Added comments (#82)

* Added comments

* Update cipher/viper.go - fixed spelling

Author: kristinapathak

CHANGELOG.md

@@ -5,6 +5,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+- Added comments for godocs
 
 ## [v0.7.0]
 - Added `record_id` to index

blacklist/blacklist.go

@@ -13,30 +13,38 @@ const (
 	defaultUpdateInterval = time.Minute
 )
 
+// BlackListedItem is the regex that expresses the devices that are blacklisted
+// and the reason why.
 type BlackListedItem struct {
 	ID     string
 	Reason string
 }
 
+// TableName sets BlackListedItem's table name to be "blacklist"; for the GORM driver.
 func (BlackListedItem) TableName() string {
 	return "blacklist"
 }
 
+// List is for checking if a device id is in the blacklist.
 type List interface {
 	InList(ID string) (reason string, ok bool)
 }
 
+// SyncList is an implemention of the List interface that works synchronously.
 type SyncList struct {
 	rules    map[string]string
 	dataLock sync.RWMutex
 }
 
+// NewEmptySyncList creates a new SyncList that holds no information.
 func NewEmptySyncList() SyncList {
 	return SyncList{
 		rules: make(map[string]string),
 	}
 }
 
+// InList returns whether or not a device is on the blacklist and why, if it's
+// on the list.
 func (m *SyncList) InList(ID string) (string, bool) {
 	m.dataLock.RLock()
 	defer m.dataLock.RUnlock()
@@ -56,6 +64,8 @@ func (m *SyncList) InList(ID string) (string, bool) {
 	return "", false
 }
 
+// UpdateList takes the data given and overwrites the blacklist with the new
+// information.
 func (m *SyncList) UpdateList(data []BlackListedItem) {
 
 	newData := make(map[string]string)
@@ -68,6 +78,7 @@ func (m *SyncList) UpdateList(data []BlackListedItem) {
 	m.dataLock.Unlock()
 }
 
+// Updater is for getting the blacklist.
 type Updater interface {
 	GetBlacklist() ([]BlackListedItem, error)
 }
@@ -79,6 +90,7 @@ type listRefresher struct {
 	cache   SyncList
 }
 
+// InList checks if a specified device id is on the blacklist.
 func (d *listRefresher) InList(ID string) (string, bool) {
 	return d.cache.InList(ID)
 }
@@ -91,11 +103,14 @@ func (d *listRefresher) updateList() {
 	}
 }
 
+// RefresherConfig is the configuration specifying how often to update the list
+// and what logger to use when logging.
 type RefresherConfig struct {
 	UpdateInterval time.Duration
 	Logger         log.Logger
 }
 
+// NewListRefresher takes the given values and uses them to create a new listRefresher
 func NewListRefresher(config RefresherConfig, updater Updater, stop chan struct{}) List {
 	if config.Logger == nil {
 		config.Logger = logging.DefaultLogger()

cipher/algo_types.go

@@ -17,6 +17,7 @@
 
 package cipher
 
+// AlgorithmType is an enum used to specify which algorithm is being used.
 type AlgorithmType string
 
 const (
@@ -26,7 +27,9 @@ const (
 	RSAAsymmetric AlgorithmType = "rsa-asy"
 )
 
-func ParseAlogrithmType(algo string) AlgorithmType {
+// ParseAlgorithmType takes a string and returns an enum if one matches,
+// otherwise returns the None AlgorithmType enum.
+func ParseAlgorithmType(algo string) AlgorithmType {
 	if algo == string(Box) {
 		return Box
 	} else if algo == string(RSASymmetric) {

cipher/boxLoader.go

@@ -22,6 +22,7 @@ import (
 	"errors"
 )
 
+// BoxLoader loads the box encryption/decryption.
 type BoxLoader struct {
 	KID        string
 	PrivateKey KeyLoader
@@ -56,6 +57,7 @@ func (boxLoader *BoxLoader) getBoxPublicKey() ([32]byte, error) {
 	return publicKey, nil
 }
 
+// LoadEncrypt loads an encrypter for the box algorithm.
 func (boxLoader *BoxLoader) LoadEncrypt() (Encrypt, error) {
 	publicKey, err := boxLoader.getBoxPublicKey()
 	if err != nil {
@@ -69,6 +71,7 @@ func (boxLoader *BoxLoader) LoadEncrypt() (Encrypt, error) {
 	return NewBoxEncrypter(privateKey, publicKey, boxLoader.KID), nil
 }
 
+// LoadDecrypt loads a decrypter for the box algorithm.
 func (boxLoader *BoxLoader) LoadDecrypt() (Decrypt, error) {
 	publicKey, err := boxLoader.getBoxPublicKey()
 	if err != nil {

cipher/cipher.go

@@ -23,13 +23,14 @@ import (
 	"crypto/rand"
 	"crypto/rsa"
 	"fmt"
+	"hash"
+	"io"
+	"os"
+
 	"github.com/goph/emperror"
 	"github.com/pkg/errors"
 	"golang.org/x/crypto/blake2b"
 	"golang.org/x/crypto/nacl/box"
-	"hash"
-	"io"
-	"os"
 )
 
 func init() {
@@ -84,40 +85,48 @@ func GeneratePrivateKey(size int) *rsa.PrivateKey {
 	return privateKey
 }
 
+// DefaultCipherEncrypter returns a NOOP encrypter.
 func DefaultCipherEncrypter() Encrypt {
 	return &NOOP{}
 }
 
+// DEfaultCipherDecrypter returns a NOOP decrypter.
 func DefaultCipherDecrypter() Decrypt {
 	return &NOOP{}
 }
 
 // NOOP will just return the message
 type NOOP struct{}
 
+// GetAlgorithm returns None.
 func (*NOOP) GetAlgorithm() AlgorithmType {
 	return None
 }
 
+// GetKID returns none.
 func (*NOOP) GetKID() string {
 	return "none"
 }
 
+//EncryptMessage simply returns the message given.
 func (*NOOP) EncryptMessage(message []byte) (crypt []byte, nonce []byte, err error) {
 	return message, []byte{}, nil
 }
 
+// DecryptMessage simply returns the message given.
 func (*NOOP) DecryptMessage(cipher []byte, nonce []byte) (message []byte, err error) {
 	return cipher, nil
 }
 
+// GetAlgorithm returns the algorithm type.
 func (c *rsaEncrypterDecrypter) GetAlgorithm() AlgorithmType {
 	if c.recipientPublicKey == nil || c.senderPublicKey == nil {
 		return RSASymmetric
 	}
 	return RSAAsymmetric
 }
 
+// GetKID returns the KID.
 func (c *rsaEncrypterDecrypter) GetKID() string {
 	return c.kid
 }
@@ -132,6 +141,7 @@ type rsaEncrypterDecrypter struct {
 	label               []byte
 }
 
+// NewRSAEncrypter returns an RSA encrypter.
 func NewRSAEncrypter(hash crypto.Hash, senderPrivateKey *rsa.PrivateKey, recipientPublicKey *rsa.PublicKey, kid string) Encrypt {
 	return &rsaEncrypterDecrypter{
 		kid:                kid,
@@ -142,6 +152,7 @@ func NewRSAEncrypter(hash crypto.Hash, senderPrivateKey *rsa.PrivateKey, recipie
 	}
 }
 
+// NewRSADecrypter returns an RSA decrypter.
 func NewRSADecrypter(hash crypto.Hash, recipientPrivateKey *rsa.PrivateKey, senderPublicKey *rsa.PublicKey, kid string) Decrypt {
 	return &rsaEncrypterDecrypter{
 		kid:                 kid,
@@ -152,6 +163,7 @@ func NewRSADecrypter(hash crypto.Hash, recipientPrivateKey *rsa.PrivateKey, send
 	}
 }
 
+// EncryptMessage encrypts the message using RSA.
 func (c *rsaEncrypterDecrypter) EncryptMessage(message []byte) ([]byte, []byte, error) {
 	cipherdata, err := rsa.EncryptOAEP(
 		c.hasher.New(),
@@ -183,6 +195,7 @@ func (c *rsaEncrypterDecrypter) EncryptMessage(message []byte) ([]byte, []byte,
 	return cipherdata, signature, nil
 }
 
+// DecryptMessage decrypts the message using RSA.
 func (c *rsaEncrypterDecrypter) DecryptMessage(cipher []byte, nonce []byte) ([]byte, error) {
 	decrypted, err := rsa.DecryptOAEP(
 		c.hasher.New(),
@@ -219,14 +232,17 @@ type encryptBox struct {
 	sharedEncryptKey   *[32]byte
 }
 
+// GetAlgorithm returns the algorithm type.
 func (enBox *encryptBox) GetAlgorithm() AlgorithmType {
 	return Box
 }
 
+// GetKID returns the KID.
 func (enBox *encryptBox) GetKID() string {
 	return enBox.kid
 }
 
+// NewBoxEncrypter returns a new box encrypter.
 func NewBoxEncrypter(senderPrivateKey [32]byte, recipientPublicKey [32]byte, kid string) Encrypt {
 
 	encrypter := encryptBox{
@@ -241,6 +257,7 @@ func NewBoxEncrypter(senderPrivateKey [32]byte, recipientPublicKey [32]byte, kid
 	return &encrypter
 }
 
+// Encrypt message encrypts the message using the box algorithm.
 func (enBox *encryptBox) EncryptMessage(message []byte) ([]byte, []byte, error) {
 	var nonce [24]byte
 	if _, err := io.ReadFull(rand.Reader, nonce[:]); err != nil {
@@ -259,14 +276,17 @@ type decryptBox struct {
 	sharedDecryptKey    *[32]byte
 }
 
+// GetAlgorithm returns the algorithm type.
 func (deBox *decryptBox) GetAlgorithm() AlgorithmType {
 	return Box
 }
 
+// GetKID returns the KID.
 func (deBox *decryptBox) GetKID() string {
 	return deBox.kid
 }
 
+// NewBoxDecrypter returns a new box decrypter.
 func NewBoxDecrypter(recipientPrivateKey [32]byte, senderPublicKey [32]byte, kid string) Decrypt {
 
 	decrypter := decryptBox{
@@ -281,6 +301,7 @@ func NewBoxDecrypter(recipientPrivateKey [32]byte, senderPublicKey [32]byte, kid
 	return &decrypter
 }
 
+// DecryptMessage decrypts the message using the box algorithm.
 func (deBox *decryptBox) DecryptMessage(cipher []byte, nonce []byte) ([]byte, error) {
 	var decryptNonce [24]byte
 	copy(decryptNonce[:], nonce[:24])

cipher/key_types.go

@@ -17,6 +17,7 @@
 
 package cipher
 
+// KeyType is an enum for how the key can be used.
 type KeyType string
 
 const (

cipher/loader.go

@@ -22,11 +22,12 @@ import (
 	"crypto/rsa"
 	"crypto/x509"
 	"encoding/pem"
+	"io/ioutil"
+
 	"github.com/Comcast/webpa-common/logging"
 	"github.com/go-kit/kit/log"
 	"github.com/goph/emperror"
 	"github.com/pkg/errors"
-	"io/ioutil"
 )
 
 var (
@@ -62,20 +63,27 @@ type Config struct {
 	Keys map[KeyType]string `json:"keys,omitempty"`
 }
 
+// KeyLoader gets the bytes for a key.
 type KeyLoader interface {
 	GetBytes() ([]byte, error)
 }
+
+// EncryptLoader loads an encrypter.
 type EncryptLoader interface {
 	LoadEncrypt() (Encrypt, error)
 }
+
+//DecryptLoader loads a decrypter.
 type DecryptLoader interface {
 	LoadDecrypt() (Decrypt, error)
 }
 
+// FileLoader loads a key from a file.
 type FileLoader struct {
 	Path string
 }
 
+// GetBytes returns the bytes found at the filepath.
 func (f *FileLoader) GetBytes() ([]byte, error) {
 	return ioutil.ReadFile(f.Path)
 }
@@ -86,14 +94,17 @@ func CreateFileLoader(keys map[KeyType]string, keyType KeyType) KeyLoader {
 	}
 }
 
+// BytesLoader implements the KeyLoader.
 type BytesLoader struct {
 	Data []byte
 }
 
+// GetBytes returns the bytes stored by the BytesLoader
 func (b *BytesLoader) GetBytes() ([]byte, error) {
 	return b.Data, nil
 }
 
+// GetPrivateKey uses a keyloader to load a private key.
 func GetPrivateKey(loader KeyLoader) (*rsa.PrivateKey, error) {
 	if loader == nil {
 		return nil, errors.New("no loader")
@@ -120,6 +131,7 @@ func GetPrivateKey(loader KeyLoader) (*rsa.PrivateKey, error) {
 	}
 }
 
+// GetPublicKey uses a keyloader to load a public key.
 func GetPublicKey(loader KeyLoader) (*rsa.PublicKey, error) {
 	if loader == nil {
 		return nil, errors.New("no loader")
@@ -146,6 +158,7 @@ func GetPublicKey(loader KeyLoader) (*rsa.PublicKey, error) {
 	}
 }
 
+// LoadEncrypt uses the config to load an encrypter.
 func (config *Config) LoadEncrypt() (Encrypt, error) {
 	var err error
 	if config.Logger == nil {
@@ -197,6 +210,7 @@ func (config *Config) LoadEncrypt() (Encrypt, error) {
 	return DefaultCipherEncrypter(), emperror.Wrap(err, "failed to load custom algorithm")
 }
 
+// LoadDecrypt uses the config to load a decrypter.
 func (config *Config) LoadDecrypt() (Decrypt, error) {
 	var err error
 	if config.Logger == nil {