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);
hkdfExpandInto
HKDF-Expand (RFC 5869 §2.3) over the hash hashLength names: length bytes from prk and info, written at out[at].
hkdfExpandLabelHeldInto
HKDF-Expand-Label of the held prk over the hash hashLength names into a plain array: length bytes written at out[at].
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].
hkdfExpandLabelSha256
HKDF-Expand-Label with HMAC-SHA-256 (RFC 8446 §7.1): length bytes from prk (RFC 8446's Secret), "tls13 " + label and context.
hkdfExpandLabelSha256Held
hkdfExpandLabelSha256Secret into dst: as many bytes as dst holds, derived from prk, the label and context and written over dst's in place.
hkdfExpandLabelSha256Secret
hkdfExpandLabelSha256 on a secret held as a Secret: the length bytes, held as one.
hkdfExpandLabelSha384
HKDF-Expand-Label with HMAC-SHA-384 (RFC 8446 §7.1): length bytes from prk (RFC 8446's Secret), "tls13 " + label and context.
hkdfExpandLabelSha384Held
hkdfExpandLabelSha256Held with HMAC-SHA-384: panics as hkdfExpandLabelSha384 does.
hkdfExpandLabelSha384Secret
hkdfExpandLabelSha256Secret with HMAC-SHA-384: panics as hkdfExpandLabelSha384 does.
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.
hkdfExpandSha256Secret
hkdfExpandSha256 on a PRK held as a Secret.
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.
hkdfExpandSha384Secret
hkdfExpandSha384 on a PRK held as a Secret.
hkdfExtractInto
HKDF-Extract (RFC 5869 §2.2) over the hash hashLength names, the PRK's HashLen bytes written at out[at].
hkdfExtractSha256
HKDF-Extract with HMAC-SHA-256 (RFC 5869 §2.2): the 32-byte PRK.
hkdfExtractSha256Secret
hkdfExtractSha256 on input keying material held as a Secret.
hkdfExtractSha384
HKDF-Extract with HMAC-SHA-384 (RFC 5869 §2.2): the 48-byte PRK.
hkdfExtractSha384Secret
hkdfExtractSha384 on input keying material held as a Secret.
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.
hkdfSha384Secret
hkdfSha256Secret with HMAC-SHA-384: the PRK is 48 bytes, and wiped before it returns.
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.
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
sHkdfScratchrequiredThe scratch to compute in; what the call leaves in it is wiped.
hashLengthi32required32 for HMAC-SHA-256, 48 for HMAC-SHA-384.
prku8[]required
The pseudorandom key, at least hashLength bytes; it is read, not
kept.
infou8[]requiredThe public context the output is bound to; may be empty.
outu8[]requiredThe caller's array the output is written into.
ati32requiredWhere the output starts in out.
lengthi32requiredHow 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
hashLengthi32required32 for HMAC-SHA-256, 48 for HMAC-SHA-384.
prkSecret<u8[]>requiredRFC 8446's Secret, read only inside exposeWith.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe public context, at most 255 bytes.
outu8[]requiredThe caller's plain array the output is written into.
ati32requiredWhere the output starts in out.
lengthi32requiredHow 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
sHkdfScratchrequiredThe scratch to compute in; what the call leaves in it is wiped.
hashLengthi32required32 for HMAC-SHA-256, 48 for HMAC-SHA-384.
prku8[]required
RFC 8446's Secret, at least hashLength bytes; it is read, not
kept.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe buffer holding the context.
contextOffi32requiredWhere the context starts in context.
contextLeni32requiredThe context's length, at most 255 bytes.
outu8[]requiredThe caller's array the output is written into.
ati32requiredWhere the output starts in out.
lengthi32requiredHow 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[]requiredRFC 8446's Secret, at least 32 bytes; it is read, not kept.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe public context, often a transcript hash; at most 255 bytes.
lengthi32requiredHow 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[]>requiredRFC 8446's Secret, read only inside exposeWith.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe 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.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe public context, often a transcript hash; at most 255 bytes.
lengthi32requiredHow 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[]requiredRFC 8446's Secret, at least 48 bytes; it is read, not kept.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe public context, often a transcript hash; at most 255 bytes.
lengthi32requiredHow 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[]>requiredRFC 8446's Secret, read only inside exposeWith.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe 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.
labelstringrequiredThe label without the "tls13 " prefix, 1 to 249 bytes.
contextu8[]requiredThe public context, often a transcript hash; at most 255 bytes.
lengthi32requiredHow 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[]requiredThe pseudorandom key, at least 32 bytes; it is read, not kept.
infou8[]requiredThe public context the output is bound to; may be empty.
lengthi32requiredHow 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[]requiredThe public context the output is bound to; may be empty.
lengthi32requiredHow 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[]requiredThe pseudorandom key, at least 48 bytes; it is read, not kept.
infou8[]requiredThe public context the output is bound to; may be empty.
lengthi32requiredHow 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[]requiredThe public context the output is bound to; may be empty.
lengthi32requiredHow 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
sHkdfScratchrequiredThe scratch to compute in; what the call leaves in it is wiped.
hashLengthi32required32 for HMAC-SHA-256, 48 for HMAC-SHA-384.
saltu8[]requiredThe public salt; an empty one stands for HashLen zero bytes (§2.2).
ikmu8[]requiredThe input keying material; it is read, not kept.
outu8[]requiredThe caller's array the PRK is written into.
ati32requiredWhere 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[]requiredThe public salt; an empty one stands for HashLen zero bytes (§2.2).
ikmu8[]requiredThe 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[]requiredThe 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[]requiredThe public salt; an empty one stands for HashLen zero bytes (§2.2).
ikmu8[]requiredThe 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[]requiredThe 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[]requiredThe 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[]requiredThe public context the output is bound to; may be empty.
lengthi32requiredHow 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[]requiredThe 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[]requiredThe public context the output is bound to; may be empty.
lengthi32requiredHow 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. |

