Documentation
¶
Overview ¶
Package crypt defines pluggable encryption and key-derivation interfaces. Implementations can swap in NACL, AES-GCM (FIPS 140), or any AEAD primitive without touching keeper internals.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrDecrypt = errors.New("decryption failed")
ErrDecrypt is returned when authenticated decryption fails.
Functions ¶
This section is empty.
Types ¶
type AES256GCMCipher ¶ added in v0.0.2
type AES256GCMCipher struct {
// contains filtered or unexported fields
}
AES256GCMCipher implements Cipher using AES-256-GCM.
AES-256-GCM is approved under FIPS 140-2 / FIPS 140-3 when used with a FIPS-validated cryptographic module. Use this cipher (paired with PBKDF2SHA256KDF) when operating in a FIPS-restricted environment.
Key size must be exactly 32 bytes (256 bits). Nonce size is 12 bytes (96 bits) as recommended by NIST SP 800-38D.
func NewAES256GCMCipher ¶ added in v0.0.2
func NewAES256GCMCipher(key []byte) (*AES256GCMCipher, error)
NewAES256GCMCipher creates an AES256GCMCipher from a 32-byte key. Returns an error if key is not exactly 32 bytes.
func (*AES256GCMCipher) Decrypt ¶ added in v0.0.2
func (c *AES256GCMCipher) Decrypt(ciphertext []byte) ([]byte, error)
Decrypt implements Cipher. Returns ErrDecrypt on authentication failure, truncation, or any other decryption error.
func (*AES256GCMCipher) Encrypt ¶ added in v0.0.2
func (c *AES256GCMCipher) Encrypt(plaintext []byte) ([]byte, error)
Encrypt implements Cipher. A random 12-byte nonce is prepended to the ciphertext. The nonce is generated using crypto/rand.
func (*AES256GCMCipher) KeySize ¶ added in v0.0.2
func (c *AES256GCMCipher) KeySize() int
KeySize implements Cipher. AES-256-GCM requires a 32-byte (256-bit) key.
type Argon2KDF ¶
Argon2KDF implements KDF using Argon2id — the recommended password-hashing algorithm for new systems (winner of the Password Hashing Competition).
To meet FIPS 140 requirements swap this for a PBKDF2-SHA-256 implementation that satisfies the same KDF interface.
func DefaultArgon2KDF ¶
func DefaultArgon2KDF() *Argon2KDF
DefaultArgon2KDF returns a KDF with sensible interactive defaults. Tune for your threat model: higher Time/Memory → slower but stronger.
type Cipher ¶
type Cipher interface {
// Encrypt returns authenticated ciphertext for plaintext.
// The implementation is responsible for generating and prepending a nonce.
Encrypt(plaintext []byte) ([]byte, error)
// Decrypt recovers plaintext from ciphertext produced by Encrypt.
// Returns ErrDecrypt on authentication failure or truncation.
Decrypt(ciphertext []byte) ([]byte, error)
// KeySize returns the number of bytes this cipher requires for its key.
// Used by key-derivation paths to produce correctly-sized keys without
// hard-coding algorithm-specific constants (e.g. 32 for XChaCha20-Poly1305
// and AES-256-GCM, 16 for AES-128-GCM).
KeySize() int
}
Cipher is the encryption contract used throughout keeper. Any authenticated-encryption scheme (XChaCha20-Poly1305, AES-256-GCM, NaCl secretbox, …) must satisfy this interface.
type KDF ¶
type KDF interface {
// DeriveKey derives a key of keyLen bytes from password and salt.
DeriveKey(password, salt []byte, keyLen int) ([]byte, error)
}
KDF is the key-derivation contract. Swap between scrypt, Argon2id, PBKDF2, or an HSM-backed KDF without changing caller code.
type PBKDF2SHA256KDF ¶ added in v0.0.2
type PBKDF2SHA256KDF struct {
// Iterations is the PBKDF2 iteration count.
// Must be ≥ 1. Higher values increase resistance to brute-force attacks.
Iterations int
}
PBKDF2SHA256KDF implements KDF using PBKDF2 with HMAC-SHA-256.
PBKDF2-SHA-256 is approved under FIPS 140-2 / FIPS 140-3. Pair this with AES256GCMCipher when FIPS compliance is required.
NIST SP 800-132 recommends a minimum of 1000 iterations; for interactive authentication use at least 210,000 (OWASP 2023 recommendation). DefaultPBKDF2KDF uses 600,000 iterations as a conservative default.
For non-FIPS deployments prefer DefaultArgon2KDF — it provides stronger memory-hardness guarantees against GPU/ASIC attacks.
func DefaultPBKDF2KDF ¶ added in v0.0.2
func DefaultPBKDF2KDF() *PBKDF2SHA256KDF
DefaultPBKDF2KDF returns a PBKDF2SHA256KDF with 600,000 iterations — the OWASP-recommended minimum as of 2023 for PBKDF2-HMAC-SHA256.
type ScryptKDF ¶
type ScryptKDF struct {
// N is the CPU/memory cost parameter. Must be a power of 2 (≥2).
N int
// R is the block size parameter.
R int
// P is the parallelisation parameter.
P int
}
ScryptKDF implements KDF using scrypt. It exists solely for backward compatibility with databases that were created with scrypt-derived keys. New deployments should use DefaultArgon2KDF instead.
Recommended migration path: Open the existing database with a ScryptKDF in Config.KDF. Call Rotate with the same passphrase — this re-derives with Argon2id and
re-encrypts all secrets in one atomic operation.
Replace ScryptKDF with DefaultArgon2KDF in your Config going forward.
func DefaultScryptKDF ¶
func DefaultScryptKDF() *ScryptKDF
DefaultScryptKDF returns a ScryptKDF with the same defaults that the old keeper hard-coded (N=32768, r=8, p=1).
type XChacha20Cipher ¶
type XChacha20Cipher struct {
// contains filtered or unexported fields
}
XChacha20Cipher implements Cipher using XChaCha20-Poly1305. It is the default cipher for keeper.
func NewCipher ¶
func NewCipher(secret string) (*XChacha20Cipher, error)
NewCipher creates an XChacha20Cipher from a human-readable secret. It first tries to decode secret as standard Base64; if that fails or the decoded key is not exactly 32 bytes it hashes the string with SHA-256 to produce a 32-byte key.
func NewCipherFromKey ¶
func NewCipherFromKey(key []byte) (*XChacha20Cipher, error)
NewCipherFromKey creates an XChacha20Cipher directly from a 32-byte key.
func (*XChacha20Cipher) Decrypt ¶
func (c *XChacha20Cipher) Decrypt(ciphertext []byte) ([]byte, error)
Decrypt implements Cipher.
func (*XChacha20Cipher) Encrypt ¶
func (c *XChacha20Cipher) Encrypt(plaintext []byte) ([]byte, error)
Encrypt implements Cipher. A random nonce is prepended to the ciphertext.
func (*XChacha20Cipher) KeySize ¶ added in v0.0.2
func (c *XChacha20Cipher) KeySize() int
KeySize implements Cipher. XChaCha20-Poly1305 requires a 32-byte key.
Source Files