elastic · michel-laterman · Jun 2, 2022 · May 31, 2022 · Jun 1, 2022
@@ -25,6 +25,7 @@ type options struct {
 	vaultPath string
 }
 
+// OptionFunc is the functional configuration type.
 type OptionFunc func(o *options)
 
 // WithVaultPath allows to specify the vault path, doesn't apply for darwin

@@ -33,6 +33,7 @@ func DisableEncryptionDarwin() {
 	}
 }
 
+// OptionFunc is the functional configuration type.
 type OptionFunc func(s *EncryptedDiskStore)
 
 // NewEncryptedDiskStore creates an encrypted disk store.
@@ -51,6 +52,7 @@ func NewEncryptedDiskStore(target string, opts ...OptionFunc) Storage {
 	return s
 }
 
+// WithVaultPath sets the path of the vault.
 func WithVaultPath(vaultPath string) OptionFunc {
 	return func(s *EncryptedDiskStore) {
 		if runtime.GOOS == darwin {
@@ -60,6 +62,7 @@ func WithVaultPath(vaultPath string) OptionFunc {
 	}
 }
 
+// Exists will check if the encrypted disk store exists.
 func (d *EncryptedDiskStore) Exists() (bool, error) {
 	_, err := os.Stat(d.target)
 	if err != nil {
@@ -82,6 +85,8 @@ func (d *EncryptedDiskStore) ensureKey() error {
 	return nil
 }
 
+// Save will write the encrypted storage to disk.
+// Specifically it will write to a .tmp file then rotate the file to the target name to ensure that an error does not corrupt the previously written file.
 func (d *EncryptedDiskStore) Save(in io.Reader) error {
 	// Ensure has agent key
 	err := d.ensureKey()
@@ -151,6 +156,7 @@ func (d *EncryptedDiskStore) Save(in io.Reader) error {
 	return nil
 }
 
+// Load returns an io.ReadCloser for the target.
 func (d *EncryptedDiskStore) Load() (rc io.ReadCloser, err error) {
 	fd, err := os.OpenFile(d.target, os.O_RDONLY, perms)
 	if err != nil {

@@ -17,6 +17,7 @@ type Store interface {
 	Save(io.Reader) error
 }
 
+// Storage interacts with on-disk data stores.
 type Storage interface {
 	Store
 
@@ -32,6 +33,8 @@ type DiskStore struct {
 	target string
 }
 
+// EncryptedDiskStore encrypts config when saving to disk.
+// When saving it will save to a temporary file then replace the target file.
 type EncryptedDiskStore struct {
 	target    string
 	vaultPath string

@@ -12,14 +12,19 @@ import (
 	"syscall"
 )
 
+// AESKeyType indicates the AES key length.
 type AESKeyType int
 
 const (
+	// AES128 represents a 128 bit key length
 	AES128 AESKeyType = 16
+	// AES192 represents a 192 bit key length
 	AES192 AESKeyType = 24
+	// AES256 represents a 256 bit key length
 	AES256 AESKeyType = 32
 )
 
+// String returns the AES key length as a string.
 func (kt AESKeyType) String() string {
 	switch kt {
 	case AES128:
@@ -86,7 +91,7 @@ func EncryptHex(key string, data []byte) (string, error) {
 	return hex.EncodeToString(enc), nil
 }
 
-// Decrypts decrypts the data with AES-GCM
+// Decrypt decrypts the data with AES-GCM
 func Decrypt(key, data []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {

@@ -28,6 +28,7 @@ import (
 	"unsafe"
 )
 
+// Vault represents encrypted storage using the Darwin keychain.
 type Vault struct {
 	name     string
 	keychain C.SecKeychainRef
@@ -112,6 +113,7 @@ func (v *Vault) Exists(key string) (bool, error) {
 	return false, statusToError(status)
 }
 
+// Remove will remove a key from the keychain.
 func (v *Vault) Remove(key string) error {
 	cname := C.CString(v.name)
 	defer C.free(unsafe.Pointer(cname))
@@ -136,6 +138,7 @@ func statusToError(status C.OSStatus) error {
 	return nil
 }
 
+// OSStatusError is an error type that can be returned by Darwin systems when interacting with the keychain.
 type OSStatusError struct {
 	status  int
 	message string

@@ -13,6 +13,8 @@ import (
 	"github.com/elastic/elastic-agent/internal/pkg/agent/vault"
 )
 
+// InitStorage prepares storage for testing.
+// disabled on Darwin.
 func InitStorage(t *testing.T) {
 	vault.DisableRootCheck()
 	storage.DisableEncryptionDarwin()