kdf - Key Derivation Functions #

Warning. This is a work-in-progress experimental fork of kdf. Do not use it in production; use kdf instead.

Key derivation functions in OCaml.

A protocol rarely uses its secret as a key directly. A TLS or QUIC stack expands one shared secret into several keys, and a password store stretches a weak password into a key that is slow to guess. nox-kdf provides the standard functions for both, each in its own library:

nox-kdf.hkdf: HKDF (RFC 5869), with the HKDF-Expand-Label of TLS 1.3;
nox-kdf.concat: the single-step Concat KDF of NIST SP 800-56A;
nox-kdf.kmac: KMAC128 and KMAC256 of NIST SP 800-185, the PRF of the KMAC-based KDF of NIST SP 800-108r1;
nox-kdf.pbkdf: PBKDF1 and PBKDF2 from PKCS #5 (RFC 2898);
nox-kdf.scrypt: scrypt (RFC 7914).

HKDF and PBKDF2 can also write their output into a caller's buffer, or into a Secret.t, so a key can be erased once it is no longer needed.

Installation #

Install with opam:

$ opam install nox-kdf

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-kdf

Example #

Derive protocol-specific keys with HKDF or password-derived keys with PBKDF2/scrypt, depending on the secret material you start with. HKDF works in two steps (RFC 5869, section 2). Hkdf.extract computes a pseudorandom key, prk = HMAC-SHA256(salt, ikm), from the input key material ikm, which may be unevenly random, such as a Diffie-Hellman shared secret. Hkdf.expand stretches prk to the length asked for, here 32 bytes, as T(1) || T(2) || ... with T(i) = HMAC-SHA256(prk, T(i − 1) || info || i). The info string is a label, so keys derived for different purposes are independent:

let salt = "deployment-2026"
let ikm = "shared input key material"

let key =
  let prk = Hkdf.extract ~hash:`SHA256 ~salt ikm in
  Hkdf.expand ~hash:`SHA256 ~prk ~info:"api-token" 32