kdf

Documentation

Overview

Package kdf is the Scrinium key-derivation primitive.

Derive turns a passphrase plus a stored set of Argon2id parameters into a 32-byte key-encryption key (KEK), suitable for AES-256-GCM wrapping of the data-encryption key (DEK).

The package owns three concerns:

• parameter defaults and the minimum-validity check enforced across InitStore / Unlock / RotateKEK;
• cryptographically-secure salt generation;
• the Argon2id derivation itself.

Everything else — DEK lifecycle, descriptor wrapping, recovery kit shape — lives outside this package. The boundary is narrow on purpose: this is the cryptographic kernel, and it should be auditable in isolation.

DAG: kdf depends on domain (for KDFParams shape), errs (for sentinel errors), and golang.org/x/crypto/argon2. It does not import core, driver, plugin, or anything else.

Index

• Constants
• func Default() domain.KDFParams
• func Derive(passphrase, salt []byte, time, memory uint32, threads uint8) []byte
• func NewSalt() ([]byte, error)
• func Validate(p domain.KDFParams) error

Constants

const (
	MinTime    uint32 = 1
	MinMemory  uint32 = 19456 // KiB ≈ 19 MiB; OWASP 2024 floor
	MinThreads uint8  = 1
)

Minimum bounds enforced by Validate. Mirror the comment on errs.ErrInvalidKDFParams.

const Algorithm = "argon2id"

Algorithm is the only KDF algorithm currently supported.

const KEKLen = 32

KEKLen is the length of the derived key in bytes. 32 — the key size of AES-256-GCM, the AEAD used to wrap the DEK.

const SaltLen = 16

SaltLen is the length of the salt in bytes. Fixed at 16 per RFC 9106 §4 recommendation; not configurable by callers.

Functions

func Default

func Default() domain.KDFParams

Default returns the cost parameters applied when InitStore is called without an explicit StoreConfig.KDFParams override.

The returned struct is the *client-facing* shape — three cost fields, no salt, no algorithm. The salt is generated separately at InitStore time via NewSalt; the algorithm is fixed by this package.

func Derive

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

Derive computes the KEK from a passphrase using Argon2id with the supplied parameters. The output is exactly KEKLen (32) bytes.

This is the algorithmic kernel: it takes raw inputs and runs the cipher. Higher layers are responsible for assembling these inputs from the client-supplied domain.KDFParams plus a freshly-generated or descriptor-restored salt.

The passphrase byte slice is NOT zeroed by this function — callers are responsible for wiping their own buffers after the derived KEK is no longer needed.

func NewSalt

func NewSalt() ([]byte, error)

NewSalt returns SaltLen bytes from crypto/rand. A failure here indicates a broken OS RNG and is not retried.

func Validate

func Validate(p domain.KDFParams) error

Validate runs the minimum-validity check on a client-supplied parameter set. Only the three cost fields are inspected; salt and algorithm are not part of the client surface.

Returns a wrapped errs.ErrInvalidKDFParams with a concrete reason; errors.Is against ErrInvalidKDFParams matches every shape of failure.