crypto

Documentation

Overview

Package crypto provides cryptographic primitives for the zero-knowledge vault.

This package implements key derivation (Argon2id), envelope encryption (AES-256-GCM), and key exchange (ECDH) used to protect user secrets so that neither Aileron operators nor hosting providers can access them.

Index

• Constants
• func Decrypt(ciphertext, key []byte) ([]byte, error)
• func DeriveKEK(passphrase, salt []byte) ([]byte, error)
• func DeriveKEKWithParams(passphrase, salt []byte, time, memory uint32, threads uint8) ([]byte, error)
• func DeriveSharedSecret(priv *ecdh.PrivateKey, pub *ecdh.PublicKey) ([]byte, error)
• func Encrypt(plaintext, key []byte) ([]byte, error)
• func GenerateKeyPair() (*ecdh.PrivateKey, error)
• func GenerateRandomKEK() ([]byte, error)
• func GenerateSalt() ([]byte, error)
• func MarshalPublicKey(pub *ecdh.PublicKey) []byte
• func UnmarshalPublicKey(data []byte) (*ecdh.PublicKey, error)
• func UnwrapKey(wrappedDEK, kek []byte) ([]byte, error)
• func WrapKey(dek, kek []byte) ([]byte, error)

Constants

const (
	DefaultArgon2Time    = 3
	DefaultArgon2Memory  = 64 * 1024 // 64 MB
	DefaultArgon2Threads = 4
	KEKLen               = 32 // 256-bit KEK
	SaltLen              = 16
)

Key derivation defaults. These can be overridden via DeriveKEKWithParams for testing (lower cost) or future tuning.

Functions

func Decrypt

func Decrypt(ciphertext, key []byte) ([]byte, error)

Decrypt decrypts ciphertext produced by Encrypt using AES-256-GCM. It expects the input format: nonce (12 bytes) || ciphertext || tag (16 bytes).

func DeriveKEK

func DeriveKEK(passphrase, salt []byte) ([]byte, error)

DeriveKEK derives a 256-bit Key Encryption Key from a passphrase and salt using Argon2id with default parameters.

func DeriveKEKWithParams

func DeriveKEKWithParams(passphrase, salt []byte, time, memory uint32, threads uint8) ([]byte, error)

DeriveKEKWithParams derives a KEK with explicit Argon2id parameters. Use lower values in tests to avoid slow key derivation.

func DeriveSharedSecret

func DeriveSharedSecret(priv *ecdh.PrivateKey, pub *ecdh.PublicKey) ([]byte, error)

DeriveSharedSecret performs an ECDH key exchange and returns a 256-bit shared secret derived by hashing the raw ECDH output with SHA-256. The hash step ensures uniform key material suitable for use as an encryption key.

func Encrypt

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

Encrypt encrypts plaintext using AES-256-GCM with the provided key. A random 96-bit nonce is generated and prepended to the ciphertext. The returned byte slice is: nonce (12 bytes) || ciphertext || tag (16 bytes).

func GenerateKeyPair

func GenerateKeyPair() (*ecdh.PrivateKey, error)

GenerateKeyPair generates an ephemeral ECDH key pair on the P-256 curve.

func GenerateRandomKEK

func GenerateRandomKEK() ([]byte, error)

GenerateRandomKEK returns a cryptographically random 256-bit key suitable for use as a Key Encryption Key. Used by local/dev mode where there is no user passphrase — the KEK lives only in process memory.

func GenerateSalt

func GenerateSalt() ([]byte, error)

GenerateSalt returns a cryptographically random salt for Argon2id key derivation.

func MarshalPublicKey

func MarshalPublicKey(pub *ecdh.PublicKey) []byte

MarshalPublicKey serializes an ECDH public key to its uncompressed byte representation for transmission over the wire.

func UnmarshalPublicKey

func UnmarshalPublicKey(data []byte) (*ecdh.PublicKey, error)

UnmarshalPublicKey deserializes a P-256 ECDH public key from bytes.

func UnwrapKey

func UnwrapKey(wrappedDEK, kek []byte) ([]byte, error)

UnwrapKey unwraps a Data Encryption Key using a Key Encryption Key. Semantically identical to Decrypt but named for clarity in key-wrapping contexts.

func WrapKey

func WrapKey(dek, kek []byte) ([]byte, error)

WrapKey wraps a Data Encryption Key with a Key Encryption Key. Semantically identical to Encrypt but named for clarity in key-wrapping contexts.