Documentation
¶
Overview ¶
Package domain defines core cryptographic domain models for envelope encryption. Implements Master Key → KEK → DEK → Data hierarchy with AESGCM and ChaCha20 support.
Package domain defines core cryptographic domain models for envelope encryption. Implements Master Key → KEK → DEK → Data hierarchy with AESGCM and ChaCha20 support.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnsupportedAlgorithm indicates the requested encryption algorithm is not supported. ErrUnsupportedAlgorithm = errors.Wrap(errors.ErrInvalidInput, "unsupported algorithm") // ErrInvalidKeySize indicates the cryptographic key size is invalid (must be 32 bytes). ErrInvalidKeySize = errors.Wrap(errors.ErrInvalidInput, "invalid key size") // ErrDecryptionFailed indicates decryption failed due to wrong key or corrupted data. ErrDecryptionFailed = errors.Wrap(errors.ErrInvalidInput, "decryption failed") // ErrMasterKeysNotSet indicates the MASTER_KEYS environment variable is not configured. ErrMasterKeysNotSet = errors.Wrap(errors.ErrInvalidInput, "MASTER_KEYS not set") // ErrActiveMasterKeyIDNotSet indicates the ACTIVE_MASTER_KEY_ID environment variable is not configured. ErrActiveMasterKeyIDNotSet = errors.Wrap(errors.ErrInvalidInput, "ACTIVE_MASTER_KEY_ID not set") // ErrInvalidMasterKeysFormat indicates the MASTER_KEYS format is invalid. ErrInvalidMasterKeysFormat = errors.Wrap(errors.ErrInvalidInput, "invalid MASTER_KEYS format") // ErrInvalidMasterKeyBase64 indicates a master key is not valid base64. ErrInvalidMasterKeyBase64 = errors.Wrap(errors.ErrInvalidInput, "invalid master key base64") // ErrActiveMasterKeyNotFound indicates the active master key ID was not found in the keychain. ErrActiveMasterKeyNotFound = errors.Wrap(errors.ErrInvalidInput, "active master key not found") // ErrMasterKeyNotFound indicates a master key with the specified ID was not found. ErrMasterKeyNotFound = errors.Wrap(errors.ErrNotFound, "master key not found") // ErrDekNotFound indicates a DEK with the specified ID was not found. ErrDekNotFound = errors.Wrap(errors.ErrNotFound, "dek not found") // ErrKekNotFound indicates a KEK with the specified ID was not found. ErrKekNotFound = errors.Wrap(errors.ErrNotFound, "kek not found") )
Cryptographic operation errors.
Functions ¶
Types ¶
type Algorithm ¶
type Algorithm string
Algorithm represents the cryptographic algorithm used for encryption. Supported algorithms provide AEAD (Authenticated Encryption with Associated Data).
type Dek ¶
type Dek struct {
ID uuid.UUID // Unique identifier (UUIDv7)
KekID uuid.UUID // Reference to the KEK used to encrypt this DEK
Algorithm Algorithm // Encryption algorithm (AESGCM or ChaCha20)
EncryptedKey []byte // The DEK encrypted with the KEK
Nonce []byte // Unique nonce for encrypting the DEK
CreatedAt time.Time
}
Dek represents a Data Encryption Key used to encrypt application data. Encrypted with a KEK and stored alongside encrypted data. The plaintext DEK is never persisted and should be zeroed from memory immediately after use.
type Kek ¶
type Kek struct {
ID uuid.UUID // Unique identifier (UUIDv7)
MasterKeyID string // ID of the master key used to encrypt this KEK
Algorithm Algorithm // Encryption algorithm (AESGCM or ChaCha20)
EncryptedKey []byte // The KEK encrypted with the master key
Key []byte // Plaintext KEK (populated after decryption, never persisted)
Nonce []byte // Unique nonce for encrypting the KEK
Version uint // Version number for rotation tracking
CreatedAt time.Time
}
Kek represents a Key Encryption Key used to encrypt Data Encryption Keys. Encrypted with a master key and stored in the database. The Key field contains sensitive plaintext data (populated after decryption) and should be zeroed after use.
type KekChain ¶
type KekChain struct {
// contains filtered or unexported fields
}
KekChain manages a collection of Key Encryption Keys with thread-safe access. The active KEK (highest version) is used for encrypting new DEKs.
func NewKekChain ¶
NewKekChain creates a new KekChain with the first KEK as active. KEKs must be ordered by version descending (newest first) and slice must not be empty.
func (*KekChain) ActiveKekID ¶
ActiveKekID returns the UUID of the currently active Key Encryption Key.
type MasterKey ¶
type MasterKey struct {
ID string // Unique identifier for the master key
Key []byte // The raw 32-byte master key material
}
MasterKey represents a cryptographic master key used to encrypt KEKs. Must be 32 bytes (256 bits) and stored securely in KMS or environment variables. The Key field contains sensitive data and should be zeroed after use.
type MasterKeyChain ¶
type MasterKeyChain struct {
// contains filtered or unexported fields
}
MasterKeyChain manages a collection of master keys with one designated as active. Supports key rotation by maintaining multiple keys simultaneously.
func LoadMasterKeyChainFromEnv ¶
func LoadMasterKeyChainFromEnv() (*MasterKeyChain, error)
LoadMasterKeyChainFromEnv loads master keys from MASTER_KEYS and ACTIVE_MASTER_KEY_ID environment variables. Keys must be in format "id:base64key" (comma-separated) and exactly 32 bytes when decoded. Returns ErrMasterKeysNotSet, ErrActiveMasterKeyIDNotSet, ErrInvalidKeySize, or ErrActiveMasterKeyNotFound on failure.
func (*MasterKeyChain) ActiveMasterKeyID ¶
func (m *MasterKeyChain) ActiveMasterKeyID() string
ActiveMasterKeyID returns the ID of the currently active master key.
func (*MasterKeyChain) Close ¶
func (m *MasterKeyChain) Close()
Close securely clears all master keys from memory and resets the keychain.
Source Files