crypto

Documentation

Overview

Package crypto provides encryption and key management operations using the age library.

This package handles:

• X25519 key generation (public/private key pairs)
• Secret encryption/decryption for secure API key storage
• Key rotation for periodic security best practices
• Atomic key replacement to prevent partial state

Thread Safety:

• Key file operations are not thread-safe (file I/O)
• Functions should not be called concurrently on same key files

Security:

• All key files use 0600 permissions (owner only)
• Temporary files are created with secure defaults
• Key rotation uses atomic operations to prevent data loss
• Private key material is never logged or printed

Memory Safety Limitation:

• Decrypted secrets are returned as strings which are immutable in Go
• This means decrypted data remains in memory until garbage collected
• For applications requiring secure memory handling, consider using DecryptSecretsBytes which returns []byte that can be explicitly zeroed

Performance:

• Key generation uses X25519 (fast, secure curve)
• Encryption uses age's efficient streaming API
• Temporary key files are cleaned up on failure

Index

• func DecryptSecrets(secretsPath, keyPath string) (string, error)
• func EncryptSecrets(secretsPath, keyPath, secrets string) error
• func EnsureKeyExists(configDir string) error
• func GenerateKey(keyPath string) error
• func RotateKey(configDir string) error
• type SecretBytes
  • func DecryptSecretsBytes(secretsPath, keyPath string) (*SecretBytes, error)
  • func (s *SecretBytes) Clear()
  • func (s *SecretBytes) Close() error
  • func (s *SecretBytes) String() string

Functions

func DecryptSecrets

func DecryptSecrets(secretsPath, keyPath string) (string, error)

DecryptSecrets decrypts the secrets file and returns the plaintext content.

func EncryptSecrets

func EncryptSecrets(secretsPath, keyPath, secrets string) error

EncryptSecrets encrypts the given secrets string using age encryption and saves to the specified path.

func EnsureKeyExists

func EnsureKeyExists(configDir string) error

EnsureKeyExists generates a new encryption key if one doesn't exist at the specified directory.

func GenerateKey

func GenerateKey(keyPath string) error

GenerateKey generates a new X25519 encryption key and saves it to the specified path.

func RotateKey

func RotateKey(configDir string) error

RotateKey generates a new encryption key and re-encrypts all secrets with it. The old key is replaced with the new key. This should be done periodically as a security best practice.

Types

type SecretBytes

type SecretBytes struct {
	// contains filtered or unexported fields
}

SecretBytes wraps decrypted secret data with automatic memory zeroization. It implements io.Closer so it can be used with defer for automatic cleanup.

Usage:

defer secrets.Close()
secrets, err := DecryptSecretsBytes(path, keyPath)

_CONTENT := secrets.String()

Close() automatically zeroizes the underlying byte slice to prevent secrets from lingering in memory. After Close() is called, the secrets are not recoverable.

func DecryptSecretsBytes

func DecryptSecretsBytes(secretsPath, keyPath string) (*SecretBytes, error)

DecryptSecretsBytes decrypts the secrets file and returns the plaintext wrapped in SecretBytes. The SecretBytes type implements io.Closer and will automatically zeroize the memory when Close() is called or when used with defer.

Usage:

defer secrets.Close()
secrets, err := DecryptSecretsBytes(path, keyPath)
if err != nil {
    return err
}
content := secrets.String()

This function provides better memory safety than DecryptSecrets for applications that need to explicitly clear sensitive data after use.

func (*SecretBytes) Clear

func (s *SecretBytes) Clear()

Clear explicitly zeroizes the secrets. Called automatically by Close().

func (*SecretBytes) Close

func (s *SecretBytes) Close() error

Close zeroizes the secrets and clears the reference. This method is safe to call multiple times.

func (*SecretBytes) String

func (s *SecretBytes) String() string

String returns the secrets as a string. The returned string is immutable in Go, so it cannot be cleared from memory. Do not use for sensitive data that requires explicit memory cleanup.