crypto

func Decrypt ¶

func Decrypt(encryptedText string, key []byte) (string, error)

Decrypt decrypts a base64-encoded ciphertext string using AES-256-GCM authenticated decryption.

This is a convenience wrapper around DecryptBytes that works with strings. The function verifies the authenticity of the ciphertext using the embedded authentication tag. If the ciphertext has been tampered with, the function will return an error.

Parameters:

• encryptedText: The base64-encoded encrypted string (cannot be empty)
• key: The 32-byte decryption key (must be exactly KeySize bytes)

Returns:

• The decrypted plaintext string
• An error if decryption fails (authentication failure, corruption, or invalid input)

Example:

key, _ := crypto.GenerateKey()
ciphertext, _ := crypto.Encrypt("sensitive data", key)
plaintext, err := crypto.Decrypt(ciphertext, key)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Decrypted:", plaintext) // Output: sensitive data

The function will return an error if:

• The key size is incorrect
• The encrypted text is empty
• The base64 decoding fails
• The ciphertext is too short
• Authentication fails (tampering detected)

func DecryptBytes ¶

func DecryptBytes(encryptedText string, key []byte) ([]byte, error)

DecryptBytes decrypts a base64-encoded ciphertext string using AES-256-GCM authenticated decryption.

The function verifies the authenticity of the ciphertext using the embedded authentication tag. If the ciphertext has been tampered with, the function will return an error. This is the core decryption function that returns binary data with buffer pooling optimization.

Parameters:

• encryptedText: The base64-encoded encrypted string (cannot be empty)
• key: The 32-byte decryption key (must be exactly KeySize bytes)

Returns:

• The decrypted plaintext as a byte slice
• An error if decryption fails (authentication failure, corruption, or invalid input)

Example:

key, _ := crypto.GenerateKey()
data := []byte("sensitive binary data")
ciphertext, _ := crypto.EncryptBytes(data, key)
plaintext, err := crypto.DecryptBytes(ciphertext, key)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Decrypted:", string(plaintext)) // Output: sensitive binary data

The function will return an error if:

• The key size is incorrect
• The encrypted text is empty
• The base64 decoding fails
• The ciphertext is too short
• Authentication fails (tampering detected)

func DecryptBytesWithAAD ¶

func DecryptBytesWithAAD(encryptedText string, key []byte, aad []byte) ([]byte, error)

DecryptBytesWithAAD decrypts a base64-encoded ciphertext string using AES-256-GCM with Additional Authenticated Data.

This function verifies both the ciphertext authenticity and the AAD integrity. If either the ciphertext or AAD has been tampered with, the function will return an error. This is designed for NEMESIS vault requirements with metadata authentication.

Parameters:

• encryptedText: The base64-encoded encrypted string (cannot be empty)
• key: The 32-byte decryption key (must be exactly KeySize bytes)
• aad: Additional Authenticated Data (must match encryption AAD)

Returns:

• The decrypted plaintext as a byte slice
• An error if decryption or AAD verification fails

Example for NEMESIS:

aad := []byte(`{"tenant":"app","path":"/db/pass","version":1,"keyID":"kek_abc123"}`)
decrypted, err := crypto.DecryptBytesWithAAD(ciphertext, key, aad)

func DecryptWithAAD ¶

func DecryptWithAAD(encryptedText string, key []byte, aad string) (string, error)

DecryptWithAAD decrypts a base64-encoded ciphertext string using AES-256-GCM with Additional Authenticated Data.

This is a convenience wrapper around DecryptBytesWithAAD that works with strings. Verifies both ciphertext authenticity and AAD integrity for NEMESIS requirements.

Parameters:

• encryptedText: The base64-encoded encrypted string (cannot be empty)
• key: The 32-byte decryption key (must be exactly KeySize bytes)
• aad: Additional Authenticated Data as string (must match encryption AAD)

Returns:

• The decrypted plaintext string
• An error if decryption or AAD verification fails

Example for NEMESIS:

aad := `{"tenant":"app","path":"/db/pass","version":1,"keyID":"kek_abc123"}`
plaintext, err := crypto.DecryptWithAAD(ciphertext, key, aad)

func DeriveKey ¶

func DeriveKey(password, salt []byte, keyLen int, params *KDFParams) ([]byte, error)

DeriveKey derives a key from a password and salt using Argon2id (the recommended variant).

Argon2id is the recommended variant of Argon2, providing resistance against both side-channel attacks and time-memory trade-off attacks. It uses secure default parameters that provide strong protection against both CPU and memory-based attacks.

Parameters:

• password: The password to derive the key from (cannot be empty)
• salt: The salt to use for key derivation (cannot be empty, should be random)
• keyLen: The desired length of the derived key in bytes (must be positive)
• params: Custom Argon2id parameters (nil to use secure defaults)

Returns:

• The derived key as a byte slice
• An error if key derivation fails

Example:

password := []byte("my-secure-password")
salt := []byte("random-salt-123")

// Use secure defaults
key, err := crypto.DeriveKey(password, salt, 32, nil)
if err != nil {
	log.Fatal(err)
}

// Use custom parameters
params := &crypto.KDFParams{
	Time:    4,
	Memory:  128,
	Threads: 2,
}
key, err := crypto.DeriveKey(password, salt, 32, params)

If params is nil, secure defaults are used (Time: 3, Memory: 64MB, Threads: 4).

func DeriveKeyDefault ¶

func DeriveKeyDefault(password, salt []byte, keyLen int) ([]byte, error)

DeriveKeyDefault derives a key using Argon2id with secure default parameters.

This is a convenience function for when you don't need custom parameters. It's equivalent to calling DeriveKey with params set to nil.

Parameters:

• password: The password to derive the key from (cannot be empty)
• salt: The salt to use for key derivation (cannot be empty, should be random)
• keyLen: The desired length of the derived key in bytes (must be positive)

Returns:

• The derived key as a byte slice
• An error if key derivation fails

Example:

password := []byte("my-secure-password")
salt := []byte("random-salt-123")
key, err := crypto.DeriveKeyDefault(password, salt, 32)
if err != nil {
	log.Fatal(err)
}

func DeriveKeyHKDF ¶

func DeriveKeyHKDF(masterKey, salt, info []byte, keyLen int) ([]byte, error)

DeriveKeyHKDF derives a key using HKDF-SHA256 (RFC 5869). This is ideal for envelope encryption where you need to derive multiple keys from a single master key (e.g., KEK → DEK derivation in NEMESIS).

Parameters:

• masterKey: The input keying material (IKM), typically 32 bytes
• salt: Optional salt value (can be nil), used for key strengthening
• info: Optional context/application info (can be nil), prevents key reuse across contexts
• keyLen: Length of output key in bytes (typically 32 for AES-256)

Example:

masterKey := []byte("my-32-byte-master-key-for-nemesis")
dek, err := crypto.DeriveKeyHKDF(masterKey, nil, []byte("nemesis-dek-v1"), 32)
if err != nil {
    log.Fatal(err)
}

Security: HKDF is designed for high-entropy inputs (like randomly generated keys). For password-based key derivation, use DeriveKey() with Argon2id instead.

func DeriveKeyHKDFDefault ¶

func DeriveKeyHKDFDefault(masterKey []byte, keyLen int) ([]byte, error)

DeriveKeyHKDFDefault derives a key using HKDF-SHA256 with sensible defaults. Uses empty salt and info, suitable for simple key derivation scenarios.

Parameters:

• masterKey: The input keying material (32+ bytes recommended)
• keyLen: Length of output key in bytes (typically 32)

Example:

dek, err := crypto.DeriveKeyHKDFDefault(kek, 32)

func DeriveKeyWithParams ¶

func DeriveKeyWithParams(password, salt []byte, time, memoryMB, threads, keyLen int) ([]byte, error)

DeriveKeyWithParams derives a key from a password and salt using Argon2id with custom parameters.

This is a legacy function that provides direct parameter control. For new code, consider using DeriveKey with a KDFParams struct for better readability and maintainability.

Parameters:

• password: The password to derive the key from (cannot be empty)
• salt: The salt to use for key derivation (cannot be empty, should be random)
• time: The number of iterations (must be positive)
• memoryMB: The memory usage in MB (must be positive)
• threads: The number of threads (must be positive)
• keyLen: The desired length of the derived key in bytes (must be positive)

Returns:

• The derived key as a byte slice
• An error if key derivation fails

Example:

password := []byte("my-secure-password")
salt := []byte("random-salt-123")
key, err := crypto.DeriveKeyWithParams(password, salt, 4, 128, 2, 32)
if err != nil {
	log.Fatal(err)
}

Use this function only if you need to customize the parameters for specific requirements.

func Encrypt ¶

func Encrypt(plaintext string, key []byte) (string, error)

Encrypt encrypts a plaintext string using AES-256-GCM authenticated encryption.

This is a convenience wrapper around EncryptBytes that works with strings. The function uses AES-256 in GCM mode, which provides both confidentiality and authenticity. The returned string is base64-encoded and contains the nonce, ciphertext, and authentication tag.

Parameters:

• plaintext: The string to encrypt (can be empty)
• key: The 32-byte encryption key (must be exactly KeySize bytes)

Returns:

• A base64-encoded string containing the encrypted data
• An error if encryption fails

Example:

key, _ := crypto.GenerateKey()
ciphertext, err := crypto.Encrypt("sensitive data", key)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Encrypted:", ciphertext)

Empty plaintext is supported and will result in a valid ciphertext containing only the nonce and authentication tag.

func EncryptBytes ¶

func EncryptBytes(plaintext []byte, key []byte) (string, error)

EncryptBytes encrypts a plaintext byte slice using AES-256-GCM authenticated encryption.

The function uses AES-256 in GCM mode, which provides both confidentiality and authenticity. The returned string is base64-encoded and contains the nonce, ciphertext, and authentication tag. This is the core encryption function that works with binary data with buffer pooling optimization.

Parameters:

• plaintext: The byte slice to encrypt (can be empty)
• key: The 32-byte encryption key (must be exactly KeySize bytes)

Returns:

• A base64-encoded string containing the encrypted data
• An error if encryption fails

Example:

key, _ := crypto.GenerateKey()
data := []byte("sensitive binary data")
ciphertext, err := crypto.EncryptBytes(data, key)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Encrypted:", ciphertext)

Empty plaintext is supported and will result in a valid ciphertext containing only the nonce and authentication tag.

func EncryptBytesWithAAD ¶

func EncryptBytesWithAAD(plaintext []byte, key []byte, aad []byte) (string, error)

EncryptBytesWithAAD encrypts a plaintext byte slice using AES-256-GCM with Additional Authenticated Data.

This function is designed for NEMESIS vault requirements where AAD contains metadata like {tenant, path, version, KeyID} for authenticated encryption with context binding.

Parameters:

• plaintext: The byte slice to encrypt (can be empty)
• key: The 32-byte encryption key (must be exactly KeySize bytes)
• aad: Additional Authenticated Data (authenticated but not encrypted)

Returns:

• A base64-encoded string containing the encrypted data
• An error if encryption fails

Example for NEMESIS:

key, _ := crypto.GenerateKey()
aad := []byte(`{"tenant":"app","path":"/db/pass","version":1,"keyID":"kek_abc123"}`)
ciphertext, err := crypto.EncryptBytesWithAAD(secretData, key, aad)

func EncryptWithAAD ¶

func EncryptWithAAD(plaintext string, key []byte, aad string) (string, error)

EncryptWithAAD encrypts a plaintext string using AES-256-GCM with Additional Authenticated Data.

This is a convenience wrapper around EncryptBytesWithAAD that works with strings. Designed for NEMESIS vault requirements where AAD contains metadata for context binding.

Parameters:

• plaintext: The string to encrypt (can be empty)
• key: The 32-byte encryption key (must be exactly KeySize bytes)
• aad: Additional Authenticated Data as string (authenticated but not encrypted)

Returns:

• A base64-encoded string containing the encrypted data
• An error if encryption fails

Example for NEMESIS:

key, _ := crypto.GenerateKey()
aad := `{"tenant":"app","path":"/db/pass","version":1,"keyID":"kek_abc123"}`
ciphertext, err := crypto.EncryptWithAAD("secret-password", key, aad)

func GenerateKey ¶

func GenerateKey() ([]byte, error)

GenerateKey generates a cryptographically secure random key of KeySize bytes.

This function creates a new 32-byte (256-bit) key suitable for AES-256 encryption. The key is generated using the cryptographically secure random number generator provided by the operating system.

Returns:

• A 32-byte key as a byte slice
• An error if key generation fails

Example:

key, err := crypto.GenerateKey()
if err != nil {
	log.Fatal(err)
}
fmt.Println("Generated key length:", len(key)) // Output: 32

The generated key is suitable for use with Encrypt and Decrypt functions.

func GenerateNonce ¶

func GenerateNonce(size int) ([]byte, error)

GenerateNonce generates a cryptographically secure random nonce of the given size.

A nonce (number used once) is a random value that should be used only once for each encryption operation. This function generates a cryptographically secure random nonce suitable for use with AES-GCM encryption.

Parameters:

• size: The desired size of the nonce in bytes (must be positive)

Returns:

• A byte slice containing the random nonce
• An error if nonce generation fails

Example:

nonce, err := crypto.GenerateNonce(12) // 12 bytes is standard for AES-GCM
if err != nil {
	log.Fatal(err)
}
fmt.Println("Generated nonce length:", len(nonce)) // Output: 12

For AES-GCM, a 12-byte nonce is recommended for optimal security and performance.

func GetKeyFingerprint ¶

func GetKeyFingerprint(key []byte) string

GetKeyFingerprint generates a fingerprint for a key (non-cryptographic).

This function creates a short, human-readable identifier for a key by computing the SHA-256 hash and taking the first 8 bytes. This provides better collision resistance than using just the first few bytes of the key while maintaining speed.

The fingerprint is useful for logging, debugging, and identifying keys without exposing the actual key material.

Parameters:

• key: The key to generate a fingerprint for

Returns:

• A 16-character hexadecimal string representing the fingerprint
• An empty string if the key is empty

Example:

key, _ := crypto.GenerateKey()
fingerprint := crypto.GetKeyFingerprint(key)
fmt.Println("Key fingerprint:", fingerprint) // e.g., "a1b2c3d4e5f67890"

Uses the first 8 bytes of SHA-256 for better collision resistance while maintaining speed.

func KeyFromBase64 ¶

func KeyFromBase64(s string) ([]byte, error)

KeyFromBase64 decodes a base64 string to a key.

This function is the inverse of KeyToBase64 and is useful for loading keys from text-based storage formats like JSON or configuration files.

Parameters:

• s: The base64-encoded string to decode

Returns:

• The decoded key as a byte slice
• An error if the base64 decoding fails

Example:

base64Key := "dGVzdC1rZXktZGF0YS0xMjM0NTY3ODkwYWJjZGVm"
key, err := crypto.KeyFromBase64(base64Key)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Decoded key length:", len(key))

func KeyFromHex ¶

func KeyFromHex(s string) ([]byte, error)

KeyFromHex decodes a hexadecimal string to a key.

This function is the inverse of KeyToHex and is useful for loading keys from hexadecimal representations. The input string can contain both uppercase and lowercase hexadecimal characters.

Parameters:

• s: The hexadecimal string to decode

Returns:

• The decoded key as a byte slice
• An error if the hexadecimal decoding fails

Example:

hexKey := "746573742d6b65792d646174612d31323334353637383930616263646566"
key, err := crypto.KeyFromHex(hexKey)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Decoded key length:", len(key))

func KeyToBase64 ¶

func KeyToBase64(key []byte) string

KeyToBase64 encodes a key as a base64 string.

This function is useful for storing keys in text-based formats like JSON or configuration files. The returned string is safe to use in URLs and other text contexts.

Parameters:

• key: The key to encode (can be any byte slice)

Returns:

• A base64-encoded string representation of the key

Example:

key, _ := crypto.GenerateKey()
base64Key := crypto.KeyToBase64(key)
fmt.Println("Base64 key:", base64Key)

func KeyToHex ¶

func KeyToHex(key []byte) string

KeyToHex encodes a key as a hexadecimal string.

This function is useful for displaying keys in a human-readable format or storing them in text-based formats. The returned string contains only lowercase hexadecimal characters (0-9, a-f).

Parameters:

• key: The key to encode (can be any byte slice)

Returns:

• A hexadecimal string representation of the key

Example:

key, _ := crypto.GenerateKey()
hexKey := crypto.KeyToHex(key)
fmt.Println("Hex key:", hexKey)

func ValidateKey ¶

func ValidateKey(key []byte) error

ValidateKey checks that a key has the correct size for AES-256.

This function verifies that the provided key is exactly 32 bytes (256 bits), which is required for AES-256 encryption. It's useful for validating keys before using them with the Encrypt and Decrypt functions.

Parameters:

• key: The key to validate

Returns:

• An error if the key size is incorrect, nil if valid

Example:

key, _ := crypto.GenerateKey()
err := crypto.ValidateKey(key)
if err != nil {
	log.Fatal("Invalid key:", err)
}
fmt.Println("Key is valid for AES-256")

The function will return an error if the key is not exactly 32 bytes.

func WarmupPools ¶

func WarmupPools(count int)

WarmupPools pre allocates buffers in the pools to reduce cold latency

func Zeroize ¶

func Zeroize(b []byte)

Zeroize securely wipes a byte slice from memory.

This function overwrites all bytes in the slice with zeros to prevent sensitive data from remaining in memory after use. This is important for security when dealing with cryptographic keys and other sensitive data.

Note: This function modifies the original slice in place.

Parameters:

• b: The byte slice to zeroize

Example:

key, _ := crypto.GenerateKey()
// Use the key for encryption/decryption
ciphertext, _ := crypto.Encrypt("data", key)
// Securely wipe the key from memory
crypto.Zeroize(key)