nish/crypto/hkdf

HKDF as RFC 5869 defines it, over HMAC-SHA-256 and HMAC-SHA-384.

import {
  HkdfScratch,
  hkdfExpandInto,
  hkdfExpandLabelHeldInto,
  hkdfExpandLabelInto,
  hkdfExpandLabelSha256,
  hkdfExpandLabelSha256Held,
  hkdfExpandLabelSha256Secret,
  hkdfExpandLabelSha384,
  hkdfExpandLabelSha384Held,
  hkdfExpandLabelSha384Secret,
  hkdfExpandSha256,
  hkdfExpandSha256Secret,
  hkdfExpandSha384,
  hkdfExpandSha384Secret,
  hkdfExtractInto,
  hkdfExtractSha256,
  hkdfExtractSha256Secret,
  hkdfExtractSha384,
  hkdfExtractSha384Secret,
  hkdfSha256Secret,
  hkdfSha384Secret,
} from "nish/crypto/hkdf";
import { hkdfExtractSha256, hkdfExpandSha256 } from "nish/crypto/hkdf";

const prk: u8[] = hkdfExtractSha256(salt, secret);
const okm: u8[] | null = hkdfExpandSha256(prk, info, 42);

Two steps, each its own function, because TLS 1.3 calls them separately:

PRK = HKDF-Extract(salt, IKM)  = HMAC-Hash(salt, IKM)                    (§2.2)
OKM = HKDF-Expand(PRK, info, L) = T(1) | T(2) | … truncated to L bytes   (§2.3)
T(i) = HMAC-Hash(PRK, T(i-1) | info | i),  T(0) empty,  i one byte

The counter i is one byte, so L is at most 255 × HashLen (§2.3): 8160 bytes for SHA-256 and 12240 for SHA-384. A longer L, or a negative one, answers null rather than panicking, because L usually comes from a protocol field; L = 0 answers an empty array. So does an info longer than 2^31 - 1 bytes, which toI32 would cut to a prefix under --number-mode f64, so that two infos sharing it gave one key, and a PRK shorter than HashLen, which §2.3 does not allow: an empty one is a key anybody can compute with.

HKDF-Expand-Label is TLS 1.3's wrapper around expand (RFC 8446 §7.1), and QUIC derives its packet keys with it too (RFC 9001 §5.1), so it is here once for both rather than in each:

HKDF-Expand-Label(Secret, Label, Context, Length) =
    HKDF-Expand(Secret, HkdfLabel, Length)
struct {
    uint16 length = Length;
    opaque label<7..255> = "tls13 " + Label;
    opaque context<0..255> = Context;
} HkdfLabel;

const key: u8[] = hkdfExpandLabelSha256(secret, "quic key", [], 16);

label is given without the "tls13 " prefix, which the function adds. Its arguments come from the program rather than from the peer — a label is a literal, a length a key or hash size, a context a transcript hash — so one out of range is a bug in the caller, and it panics rather than answering null: a length below 0 or above 255, a label empty or longer than 249 bytes (the struct's 7 to 255 less the prefix), a context longer than 255 bytes, and a secret shorter than HashLen.

Caller-owned scratch

The functions above make their HMAC objects and their output fresh on every call, which stores allocations no arena scope may release around them. hkdfExtractInto, hkdfExpandInto and hkdfExpandLabelInto compute the same bytes in an HkdfScratch the caller allocates once, over the hash hashLength names (32 for SHA-256, 48 for SHA-384), and write them into the caller's array, so that a loop of key derivations inside one using a = arena() block leaves the arena where it was. Each wipes the scratch before it returns, its last block and the keyed hashers of the hash it ran over, so no key material outlives the call there:

const kdf = new HkdfScratch();                         // once
hkdfExtractInto(kdf, 32, salt, ikm, prk, 0);           // 32 bytes at prk[0]
hkdfExpandLabelInto(kdf, 32, prk, "key", context, 0, 0, key, 0, 16);

They refuse what the functions above refuse, the same way: hkdfExpandInto answers false where hkdfExpandSha256 answers null, and hkdfExpandLabelInto panics where hkdfExpandLabelSha256 does. A hash length other than 32 or 48, or an output window outside its array, is the caller's bug and panics.

What the key reaches is wiped

What the key reaches is wiped (CLAUDE.md, "Security"). Every HMAC on the way wipes its key blocks and hashers (nish/crypto/hmac), and expand wipes each T(i) once the next has replaced it, and the last one before it returns. The PRK extract answers and the output expand answers are the caller's. A caller that holds its input keying material as a Secret<u8[]> (nish:secret) derives with hkdfSha256Secret or hkdfSha384Secret, which run both steps, hand the output back as a Secret and wipe the PRK between them, or with the *Secret twins of each step, HKDF-Expand-Label's among them:

const okm: Secret<u8[]> | null = hkdfSha256Secret(salt, ikm, info, 42);
const key: Secret<u8[]> = hkdfExpandLabelSha256Secret(prk, "key", context, 16);

A caller that already holds the destination — a field of a long-lived object, say, that keeps one traffic secret and ratchets it — derives into it with the *Held forms, which fill as many bytes as the Secret holds, in place, and wipe the plain output they copied from. The destination may be the PRK itself; hkdfExpandLabelHeldInto writes a plain window instead, for output that is plain by design, a record layer's AEAD key and IV:

hkdfExpandLabelSha256Held(secret, secret, "traffic upd", none);
hkdfExpandLabelHeldInto(32, secret, "key", none, key, 0, 16);

Written from RFC 5869 and RFC 8446 §7.1, not ported from another implementation.

Functions

hkdfExpandInto

HKDF-Expand (RFC 5869 §2.3) over the hash hashLength names: length bytes from prk and info, written at out[at]. false, writing nothing, where hkdfExpandSha256 answers null: a length negative or past 255 × HashLen, an info longer than 2^31 - 1 bytes, or a prk shorter than HashLen.

const hkdfExpandInto: (
  s: HkdfScratch,
  hashLength: i32,
  prk: u8[],
  info: u8[],
  out: u8[],
  at: i32,
  length: i32,
) => boolean
sHkdfScratchrequired

The scratch to compute in; what the call leaves in it is wiped.

hashLengthi32required

32 for HMAC-SHA-256, 48 for HMAC-SHA-384.

prku8[]required

The pseudorandom key, at least hashLength bytes; it is read, not kept.

infou8[]required

The public context the output is bound to; may be empty.

outu8[]required

The caller's array the output is written into.

ati32required

Where the output starts in out.

lengthi32required

How many bytes to derive, 0 to 255 × hashLength.

returnsboolean

true once the bytes are written; false, with out untouched, for bad input. A hashLength other than 32 or 48, or an output window outside out, panics instead, before anything is written.

hkdfExpandLabelHeldInto

HKDF-Expand-Label of the held prk over the hash hashLength names into a plain array: length bytes written at out[at]. This is for output that is kept plain by design, a record layer's AEAD key and IV, say, which live in the arrays the cipher reads. Panics as hkdfExpandLabelInto does.

const hkdfExpandLabelHeldInto: (
  hashLength: i32,
  prk: Secret<u8[]>,
  label: string,
  context: u8[],
  out: u8[],
  at: i32,
  length: i32,
) => void
hashLengthi32required

32 for HMAC-SHA-256, 48 for HMAC-SHA-384.

prkSecret<u8[]>required

RFC 8446's Secret, read only inside exposeWith.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, at most 255 bytes.

outu8[]required

The caller's plain array the output is written into.

ati32required

Where the output starts in out.

lengthi32required

How many bytes to derive, 0 to 255.

hkdfExpandLabelInto

HKDF-Expand-Label (RFC 8446 §7.1) over the hash hashLength names: length bytes from prk (RFC 8446's Secret), "tls13 " + label and the context context[contextOff .. contextOff + contextLen), written at out[at]. It panics where hkdfExpandLabelSha256 does — a length outside 0 to 255, a label empty or past 249 bytes, a context past 255, a secret shorter than HashLen — and on a context window outside its array.

const hkdfExpandLabelInto: (
  s: HkdfScratch,
  hashLength: i32,
  prk: u8[],
  label: string,
  context: u8[],
  contextOff: i32,
  contextLen: i32,
  out: u8[],
  at: i32,
  length: i32,
) => void
sHkdfScratchrequired

The scratch to compute in; what the call leaves in it is wiped.

hashLengthi32required

32 for HMAC-SHA-256, 48 for HMAC-SHA-384.

prku8[]required

RFC 8446's Secret, at least hashLength bytes; it is read, not kept.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The buffer holding the context.

contextOffi32required

Where the context starts in context.

contextLeni32required

The context's length, at most 255 bytes.

outu8[]required

The caller's array the output is written into.

ati32required

Where the output starts in out.

lengthi32required

How many bytes to derive, 0 to 255.

hkdfExpandLabelSha256

HKDF-Expand-Label with HMAC-SHA-256 (RFC 8446 §7.1): length bytes from prk (RFC 8446's Secret), "tls13 " + label and context. Panics on an argument out of the range the module docs give, a secret shorter than 32 bytes among them.

const hkdfExpandLabelSha256: (
  prk: u8[],
  label: string,
  context: u8[],
  length: i32,
) => u8[]
prku8[]required

RFC 8446's Secret, at least 32 bytes; it is read, not kept.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, often a transcript hash; at most 255 bytes.

lengthi32required

How many bytes to derive, 0 to 255.

returnsu8[]

A fresh array of length bytes, which the caller owns.

hkdfExpandLabelSha256Held

hkdfExpandLabelSha256Secret into dst: as many bytes as dst holds, derived from prk, the label and context and written over dst's in place. dst may be prk itself, since the output is whole before it is copied: that is a ratchet. Panics as hkdfExpandLabelSha256 does.

const hkdfExpandLabelSha256Held: (
  dst: Secret<u8[]>,
  prk: Secret<u8[]>,
  label: string,
  context: u8[],
) => void
dstSecret<u8[]>required

The Secret to overwrite; its length is the length derived. It may be prk.

prkSecret<u8[]>required

RFC 8446's Secret, read only inside exposeWith.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, often a transcript hash; at most 255 bytes.

hkdfExpandLabelSha256Secret

hkdfExpandLabelSha256 on a secret held as a Secret: the length bytes, held as one. The label is built outside expose, since the label and the context are not secret, and the PRK is read only inside it. Panics as hkdfExpandLabelSha256 does.

const hkdfExpandLabelSha256Secret: (
  prk: Secret<u8[]>,
  label: string,
  context: u8[],
  length: i32,
) => Secret<u8[]>
prkSecret<u8[]>required

RFC 8446's Secret, at least 32 bytes, read only inside exposeWith.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, often a transcript hash; at most 255 bytes.

lengthi32required

How many bytes to derive, 0 to 255.

returnsSecret<u8[]>

The length bytes, held as a Secret the caller wipes.

hkdfExpandLabelSha384

HKDF-Expand-Label with HMAC-SHA-384 (RFC 8446 §7.1): length bytes from prk (RFC 8446's Secret), "tls13 " + label and context. Panics on an argument out of the range the module docs give, a secret shorter than 48 bytes among them.

const hkdfExpandLabelSha384: (
  prk: u8[],
  label: string,
  context: u8[],
  length: i32,
) => u8[]
prku8[]required

RFC 8446's Secret, at least 48 bytes; it is read, not kept.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, often a transcript hash; at most 255 bytes.

lengthi32required

How many bytes to derive, 0 to 255.

returnsu8[]

A fresh array of length bytes, which the caller owns.

hkdfExpandLabelSha384Held

hkdfExpandLabelSha256Held with HMAC-SHA-384: panics as hkdfExpandLabelSha384 does.

const hkdfExpandLabelSha384Held: (
  dst: Secret<u8[]>,
  prk: Secret<u8[]>,
  label: string,
  context: u8[],
) => void
dstSecret<u8[]>required

The Secret to overwrite; its length is the length derived. It may be prk.

prkSecret<u8[]>required

RFC 8446's Secret, read only inside exposeWith.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, often a transcript hash; at most 255 bytes.

hkdfExpandLabelSha384Secret

hkdfExpandLabelSha256Secret with HMAC-SHA-384: panics as hkdfExpandLabelSha384 does.

const hkdfExpandLabelSha384Secret: (
  prk: Secret<u8[]>,
  label: string,
  context: u8[],
  length: i32,
) => Secret<u8[]>
prkSecret<u8[]>required

RFC 8446's Secret, at least 48 bytes, read only inside exposeWith.

labelstringrequired

The label without the "tls13 " prefix, 1 to 249 bytes.

contextu8[]required

The public context, often a transcript hash; at most 255 bytes.

lengthi32required

How many bytes to derive, 0 to 255.

returnsSecret<u8[]>

The length bytes, held as a Secret the caller wipes.

hkdfExpandSha256

HKDF-Expand with HMAC-SHA-256 (RFC 5869 §2.3): length bytes of output keying material from prk and info, or null when length is negative or past 255 × 32, when info is longer than 2^31 - 1 bytes, or when prk is shorter than 32 bytes.

const hkdfExpandSha256: (
  prk: u8[],
  info: u8[],
  length: i32,
) => u8[] | null
prku8[]required

The pseudorandom key, at least 32 bytes; it is read, not kept.

infou8[]required

The public context the output is bound to; may be empty.

lengthi32required

How many bytes to derive, 0 to 8160.

returnsu8[] | null

A fresh array of length bytes, which the caller owns and wipes, or null for bad input.

hkdfExpandSha256Secret

hkdfExpandSha256 on a PRK held as a Secret.

const hkdfExpandSha256Secret: (
  prk: Secret<u8[]>,
  info: u8[],
  length: i32,
) => Secret<u8[]> | null
prkSecret<u8[]>required

The pseudorandom key, at least 32 bytes, read only inside exposeWith.

infou8[]required

The public context the output is bound to; may be empty.

lengthi32required

How many bytes to derive, 0 to 8160.

returnsSecret<u8[]> | null

The length bytes, held as a Secret the caller wipes, or null for bad input.

hkdfExpandSha384

HKDF-Expand with HMAC-SHA-384 (RFC 5869 §2.3): length bytes of output keying material from prk and info, or null when length is negative or past 255 × 48, when info is longer than 2^31 - 1 bytes, or when prk is shorter than 48 bytes.

const hkdfExpandSha384: (
  prk: u8[],
  info: u8[],
  length: i32,
) => u8[] | null
prku8[]required

The pseudorandom key, at least 48 bytes; it is read, not kept.

infou8[]required

The public context the output is bound to; may be empty.

lengthi32required

How many bytes to derive, 0 to 12240.

returnsu8[] | null

A fresh array of length bytes, which the caller owns and wipes, or null for bad input.

hkdfExpandSha384Secret

hkdfExpandSha384 on a PRK held as a Secret.

const hkdfExpandSha384Secret: (
  prk: Secret<u8[]>,
  info: u8[],
  length: i32,
) => Secret<u8[]> | null
prkSecret<u8[]>required

The pseudorandom key, at least 48 bytes, read only inside exposeWith.

infou8[]required

The public context the output is bound to; may be empty.

lengthi32required

How many bytes to derive, 0 to 12240.

returnsSecret<u8[]> | null

The length bytes, held as a Secret the caller wipes, or null for bad input.

hkdfExtractInto

HKDF-Extract (RFC 5869 §2.2) over the hash hashLength names, the PRK's HashLen bytes written at out[at]. An empty salt keys HMAC with no bytes, which HMAC pads to the block with zeros, exactly as the HashLen zeros §2.2 asks for would be. An ikm longer than 2^31 - 1 bytes panics, as hmacSha256 does.

const hkdfExtractInto: (
  s: HkdfScratch,
  hashLength: i32,
  salt: u8[],
  ikm: u8[],
  out: u8[],
  at: i32,
) => void
sHkdfScratchrequired

The scratch to compute in; what the call leaves in it is wiped.

hashLengthi32required

32 for HMAC-SHA-256, 48 for HMAC-SHA-384.

saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmu8[]required

The input keying material; it is read, not kept.

outu8[]required

The caller's array the PRK is written into.

ati32required

Where the hashLength PRK bytes start in out.

hkdfExtractSha256

HKDF-Extract with HMAC-SHA-256 (RFC 5869 §2.2): the 32-byte PRK.

const hkdfExtractSha256: (salt: u8[], ikm: u8[]) => u8[]
saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmu8[]required

The input keying material; it is read, not kept.

returnsu8[]

A fresh 32-byte PRK, which the caller owns and wipes.

hkdfExtractSha256Secret

hkdfExtractSha256 on input keying material held as a Secret.

const hkdfExtractSha256Secret: (
  salt: u8[],
  ikm: Secret<u8[]>,
) => Secret<u8[]>
saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmSecret<u8[]>required

The input keying material, read only inside exposeWith; the caller still owns and wipes it.

returnsSecret<u8[]>

The 32-byte PRK, held as a Secret the caller wipes.

hkdfExtractSha384

HKDF-Extract with HMAC-SHA-384 (RFC 5869 §2.2): the 48-byte PRK.

const hkdfExtractSha384: (salt: u8[], ikm: u8[]) => u8[]
saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmu8[]required

The input keying material; it is read, not kept.

returnsu8[]

A fresh 48-byte PRK, which the caller owns and wipes.

hkdfExtractSha384Secret

hkdfExtractSha384 on input keying material held as a Secret.

const hkdfExtractSha384Secret: (
  salt: u8[],
  ikm: Secret<u8[]>,
) => Secret<u8[]>
saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmSecret<u8[]>required

The input keying material, read only inside exposeWith; the caller still owns and wipes it.

returnsSecret<u8[]>

The 48-byte PRK, held as a Secret the caller wipes.

hkdfSha256Secret

HKDF with HMAC-SHA-256, both steps (RFC 5869 §2): length bytes from salt, the Secret input keying material and info, held as a Secret, or null where hkdfExpandSha256 answers null. The PRK is wiped before it returns.

const hkdfSha256Secret: (
  salt: u8[],
  ikm: Secret<u8[]>,
  info: u8[],
  length: i32,
) => Secret<u8[]> | null
saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmSecret<u8[]>required

The input keying material, read only inside exposeWith; the caller still owns and wipes it.

infou8[]required

The public context the output is bound to; may be empty.

lengthi32required

How many bytes to derive, 0 to 8160.

returnsSecret<u8[]> | null

The length bytes, held as a Secret the caller wipes, or null for bad input.

hkdfSha384Secret

hkdfSha256Secret with HMAC-SHA-384: the PRK is 48 bytes, and wiped before it returns.

const hkdfSha384Secret: (
  salt: u8[],
  ikm: Secret<u8[]>,
  info: u8[],
  length: i32,
) => Secret<u8[]> | null
saltu8[]required

The public salt; an empty one stands for HashLen zero bytes (§2.2).

ikmSecret<u8[]>required

The input keying material, read only inside exposeWith; the caller still owns and wipes it.

infou8[]required

The public context the output is bound to; may be empty.

lengthi32required

How many bytes to derive, 0 to 12240.

returnsSecret<u8[]> | null

The length bytes, held as a Secret the caller wipes, or null for bad input.

Classes

HkdfScratch

What the *Into functions compute in: an HMAC scratch for each hash, the previous output block T(i - 1), and the HkdfLabel HKDF-Expand-Label builds. Allocate one per long-lived owner — a connection slot, say — and hand it to every derivation; it carries nothing from one call to the next.

class HkdfScratch
Member
new HkdfScratch() Allocates the HMAC scratch for both hashes and the buffers every derivation reuses.
previous: u8[] T(i - 1), HashLen bytes of it; wiped before every function returns.
sha256: HmacSha256Scratch The HMAC the *Into functions run when hashLength is 32; wiped before a call that ran it returns.
sha384: HmacSha384Scratch The HMAC the *Into functions run when hashLength is 48; wiped before a call that ran it returns.
wipe(): void Zeroes the key material the last derivation left: T(i - 1) and both keyed hashers.