@amritk/nish-x86_64-linux 0.18.0 → 0.20.0

package/std/net/tls/schedule.ts

@@ -13,6 +13,17 @@
  *     master     = HKDF-Extract(Derive-Secret(handshake, "derived", ""), 0)
  *     c/s ap traffic, exporter = Derive-Secret(master, "c ap traffic" / "s ap traffic" / "exp master", CH..server Finished)
  *
+ * A resumed handshake (RFC 8446 §2.2) starts from the ticket's PSK instead,
+ * and binds the ClientHello to it before anything else is derived:
+ *
+ *     PSK        = HKDF-Expand-Label(resumption master, "resumption", ticket_nonce, HashLen)
+ *     early      = HKDF-Extract(0, PSK)
+ *     binder key = Derive-Secret(early, "res binder", "")
+ *     binder     = HMAC(Expand-Label(binder key, "finished", "", HashLen), Hash(truncated ClientHello))
+ *     handshake  = HKDF-Extract(Derive-Secret(early, "derived", ""), ECDHE)
+ *
+ * and goes on from the handshake secret as the full handshake does.
+ *
  * Every function takes the hash length (32 or 48) rather than a suite, because
  * that is all that changes between them; `tlsSuiteHashLength` turns a suite
  * into one. The traffic key and IV are here too, because T2's record layer
@@ -25,27 +36,50 @@
  * schedule inside `using a = arena()` blocks and leave the arena where it was
  * (TLS-3 in `docs/security/tls.md`). The scratch is wiped by every step.
  *
- * **Secrets are not wiped.** Every function here answers or holds a secret as
- * plain bytes, and each stays in arena memory until that memory is reused.
- * `secureZero`, the store no optimiser removes, is on `main`, and `std/` may
- * call it once a release ships it (CLAUDE.md §Security, TLS-1 in
- * `docs/security/tls.md`).
+ * **Held.** Each step also has a `*Held` form that reads its secrets from
+ * `Secret`s the caller holds and writes the secret it derives over the bytes
+ * of one, in place, so a connection keeps each stage of the schedule in one
+ * `Secret` for its life and ratchets it: `tlsDeriveSecretHeld`,
+ * `tlsHandshakeSecretHeld`, `tlsMasterSecretHeld`, and the two that answer
+ * plain bytes, `tlsFinishedVerifyDataHeld` (`verify_data` goes on the wire)
+ * and `tlsTrafficKeysFromHeld` (the cipher reads the key and IV). Every
+ * plain intermediate is wiped before it returns.
+ *
+ * **Secrets are `Secret`s.** The one-shot functions take every secret they
+ * read (a traffic secret, the ECDHE secret, a stage of the schedule) as a
+ * `Secret<u8[]>` (`nish:secret`) and answer every secret they derive as one;
+ * each reads its key only inside `exposeWith` and wipes the intermediates it
+ * made (the "derived" salts, the `finished_key`, the zero inputs) before it
+ * returns, and HMAC wipes its key blocks. The caller owns what it is handed
+ * and wipes it. What a `Secret` cannot reach is TLS-1 in
+ * `docs/security/tls.md`. The transcript hashes, the labels and a Finished
+ * message's `verify_data` are public and stay plain.
  *
  * Written from RFC 8446, not ported from another implementation.
  */
 import {
   HkdfScratch,
+  hkdfExpandLabelHeldInto,
   hkdfExpandLabelInto,
-  hkdfExpandLabelSha256,
-  hkdfExpandLabelSha384,
+  hkdfExpandLabelSha256Held,
+  hkdfExpandLabelSha256Secret,
+  hkdfExpandLabelSha384Held,
+  hkdfExpandLabelSha384Secret,
   hkdfExtractInto,
-  hkdfExtractSha256,
-  hkdfExtractSha384,
 } from "nish/crypto/hkdf"
-import { hmacCopySha256, hmacCopySha384, hmacSha256, hmacSha384 } from "nish/crypto/hmac"
+import {
+  hmacCopySha256,
+  hmacCopySha384,
+  hmacSha256,
+  hmacSha256Secret,
+  hmacSha384,
+  hmacSha384Secret,
+} from "nish/crypto/hmac"
 import { tlsHexInto } from "nish/net/tls/codec"
+import { timingSafeEqualAt } from "nish/crypto/ct"
 import { SHA256_SIZE, Sha256, sha256 } from "nish/crypto/sha256"
 import { SHA384_SIZE, Sha384, sha384 } from "nish/crypto/sha512"
+import { Secret, expose, exposeWith, secret, wipe } from "nish:secret"
 
 /** `TLS_AES_128_GCM_SHA256` (RFC 8446 §B.4). */
 export const TLS_AES_128_GCM_SHA256: i32 = 0x1301
@@ -94,23 +128,50 @@ export const tlsSuiteKeyLength = (suite: i32): i32 => {
 
 /**
  * HKDF-Expand-Label (RFC 8446 §7.1) over the hash `hashLength` names: `length`
- * bytes from `secret`, the label (without its `"tls13 "` prefix, which is
- * added) and `context`.
+ * bytes from `prk` (RFC 8446's Secret), the label (without its `"tls13 "`
+ * prefix, which is added) and `context`, held as a `Secret`.
  */
 export const tlsExpandLabel = (
   hashLength: i32,
-  secret: u8[],
+  prk: Secret<u8[]>,
   label: string,
   context: u8[],
   length: i32
-): u8[] =>
-  hashLength === SHA384_SIZE
-    ? hkdfExpandLabelSha384(secret, label, context, length)
-    : hkdfExpandLabelSha256(secret, label, context, length)
+): Secret<u8[]> => {
+  if (hashLength === SHA384_SIZE) {
+    return hkdfExpandLabelSha384Secret(prk, label, context, length)
+  }
+  return hkdfExpandLabelSha256Secret(prk, label, context, length)
+}
+
+/** HMAC-SHA-256 keyed with the plain salt over the plain IKM, for the inner `exposeWith` of `tlsExtract` to run. */
+const tlsExtractSha256Exposed = (ikm: u8[], salt: u8[]): u8[] => hmacSha256(salt, ikm)
+
+/** HMAC-SHA-384 keyed with the plain salt over the plain IKM, as the SHA-256 one is. */
+const tlsExtractSha384Exposed = (ikm: u8[], salt: u8[]): u8[] => hmacSha384(salt, ikm)
 
-/** HKDF-Extract (RFC 5869 §2.2) over the hash `hashLength` names; an empty salt is HashLen zeros. */
-export const tlsExtract = (hashLength: i32, salt: u8[], ikm: u8[]): u8[] =>
-  hashLength === SHA384_SIZE ? hkdfExtractSha384(salt, ikm) : hkdfExtractSha256(salt, ikm)
+/** Exposes the IKM beside the already exposed salt: the outer `exposeWith` of `tlsExtract` over SHA-256. */
+const tlsExtractSha256Salted = (salt: u8[], ikm: Secret<u8[]>): u8[] =>
+  exposeWith(ikm, salt, tlsExtractSha256Exposed)
+
+/** Exposes the IKM beside the already exposed salt, as the SHA-256 one does. */
+const tlsExtractSha384Salted = (salt: u8[], ikm: Secret<u8[]>): u8[] =>
+  exposeWith(ikm, salt, tlsExtractSha384Exposed)
+
+/**
+ * HKDF-Extract (RFC 5869 §2.2) over the hash `hashLength` names, held as a
+ * `Secret`. Both inputs are `Secret`s, since the schedule salts every extract
+ * after the first with a derived secret; an empty salt keys HMAC as HashLen
+ * zeros do.
+ */
+export const tlsExtract = (hashLength: i32, salt: Secret<u8[]>, ikm: Secret<u8[]>): Secret<u8[]> => {
+  if (hashLength === SHA384_SIZE) {
+    const prk384: u8[] = exposeWith(salt, ikm, tlsExtractSha384Salted)
+    return secret(prk384)
+  }
+  const prk: u8[] = exposeWith(salt, ikm, tlsExtractSha256Salted)
+  return secret(prk)
+}
 
 /** The hash of the empty string, the transcript `Derive-Secret(., "derived", "")` hashes. */
 export const tlsEmptyHash = (hashLength: i32): u8[] => {
@@ -118,59 +179,133 @@ export const tlsEmptyHash = (hashLength: i32): u8[] => {
   return hashLength === SHA384_SIZE ? sha384(none) : sha256(none)
 }
 
-/** Derive-Secret (RFC 8446 §7.1): Expand-Label of `secret` with `label` and a transcript hash, HashLen bytes. */
-export const tlsDeriveSecret = (hashLength: i32, secret: u8[], label: string, transcriptHash: u8[]): u8[] =>
-  tlsExpandLabel(hashLength, secret, label, transcriptHash, hashLength)
+/** Derive-Secret (RFC 8446 §7.1): Expand-Label of `prk` with `label` and a transcript hash, HashLen bytes held as a `Secret`. */
+export const tlsDeriveSecret = (
+  hashLength: i32,
+  prk: Secret<u8[]>,
+  label: string,
+  transcriptHash: u8[]
+): Secret<u8[]> => tlsExpandLabel(hashLength, prk, label, transcriptHash, hashLength)
 
 /** The early secret with no PSK: HKDF-Extract of HashLen zeros under a zero salt (RFC 8446 §7.1). */
-export const tlsEarlySecret = (hashLength: i32): u8[] => {
-  const none: u8[] = []
-  return tlsExtract(hashLength, none, new Array<u8>(hashLength))
+export const tlsEarlySecret = (hashLength: i32): Secret<u8[]> => {
+  const salt: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  const ikm: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  const early: Secret<u8[]> = tlsExtract(hashLength, salt, ikm)
+  wipe(salt)
+  wipe(ikm)
+  return early
 }
 
-/** The handshake secret: HKDF-Extract of the ECDHE secret under `Derive-Secret(early, "derived", "")`. */
-export const tlsHandshakeSecret = (hashLength: i32, earlySecret: u8[], ecdhe: u8[]): u8[] =>
-  tlsExtract(hashLength, tlsDeriveSecret(hashLength, earlySecret, "derived", tlsEmptyHash(hashLength)), ecdhe)
+/**
+ * The early secret of a resumed handshake: HKDF-Extract of the PSK under a
+ * zero salt (RFC 8446 §7.1). The zero salt is wiped before it returns; the
+ * PSK is the caller's.
+ */
+export const tlsPskEarlySecret = (hashLength: i32, psk: Secret<u8[]>): Secret<u8[]> => {
+  const salt: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  const early: Secret<u8[]> = tlsExtract(hashLength, salt, psk)
+  wipe(salt)
+  return early
+}
+
+/** The binder key of a resumption PSK: `Derive-Secret(early, "res binder", "")` (RFC 8446 §7.1). */
+export const tlsBinderKey = (hashLength: i32, earlySecret: Secret<u8[]>): Secret<u8[]> =>
+  tlsDeriveSecret(hashLength, earlySecret, "res binder", tlsEmptyHash(hashLength))
+
+/**
+ * The salt the handshake secret is extracted under, `Derive-Secret(early,
+ * "derived", "")` (RFC 8446 §7.1): what `tlsHandshakeSecret` derives and
+ * wipes itself, answered for a caller that extracts in place.
+ */
+export const tlsHandshakeSalt = (hashLength: i32, earlySecret: Secret<u8[]>): Secret<u8[]> =>
+  tlsDeriveSecret(hashLength, earlySecret, "derived", tlsEmptyHash(hashLength))
+
+/**
+ * The PSK a ticket stands for: `HKDF-Expand-Label(resumption_master_secret,
+ * "resumption", ticket_nonce, HashLen)` (RFC 8446 §4.6.1).
+ */
+export const tlsResumptionPsk = (
+  hashLength: i32,
+  resumptionMasterSecret: Secret<u8[]>,
+  ticketNonce: u8[]
+): Secret<u8[]> => tlsExpandLabel(hashLength, resumptionMasterSecret, "resumption", ticketNonce, hashLength)
+
+/**
+ * The handshake secret: HKDF-Extract of the ECDHE secret under
+ * `Derive-Secret(early, "derived", "")`, which is wiped before it returns.
+ */
+export const tlsHandshakeSecret = (
+  hashLength: i32,
+  earlySecret: Secret<u8[]>,
+  ecdhe: Secret<u8[]>
+): Secret<u8[]> => {
+  const derived: Secret<u8[]> = tlsDeriveSecret(hashLength, earlySecret, "derived", tlsEmptyHash(hashLength))
+  const handshake: Secret<u8[]> = tlsExtract(hashLength, derived, ecdhe)
+  wipe(derived)
+  return handshake
+}
 
-/** The master secret: HKDF-Extract of HashLen zeros under `Derive-Secret(handshake, "derived", "")`. */
-export const tlsMasterSecret = (hashLength: i32, handshakeSecret: u8[]): u8[] =>
-  tlsExtract(
+/**
+ * The master secret: HKDF-Extract of HashLen zeros under
+ * `Derive-Secret(handshake, "derived", "")`, which is wiped before it returns.
+ */
+export const tlsMasterSecret = (hashLength: i32, handshakeSecret: Secret<u8[]>): Secret<u8[]> => {
+  const derived: Secret<u8[]> = tlsDeriveSecret(
     hashLength,
-    tlsDeriveSecret(hashLength, handshakeSecret, "derived", tlsEmptyHash(hashLength)),
-    new Array<u8>(hashLength)
+    handshakeSecret,
+    "derived",
+    tlsEmptyHash(hashLength)
   )
+  const zeros: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  const master: Secret<u8[]> = tlsExtract(hashLength, derived, zeros)
+  wipe(derived)
+  wipe(zeros)
+  return master
+}
 
 /**
  * A Finished message's `verify_data` (RFC 8446 §4.4.4): the HMAC of the
  * transcript hash under `finished_key = Expand-Label(baseKey, "finished", "",
- * HashLen)`, where `baseKey` is the sender's handshake traffic secret.
+ * HashLen)`, where `baseKey` is the sender's handshake traffic secret. The
+ * `finished_key` is wiped before it returns; `verify_data` goes on the wire,
+ * so it is plain.
  */
-export const tlsFinishedVerifyData = (hashLength: i32, baseKey: u8[], transcriptHash: u8[]): u8[] => {
+export const tlsFinishedVerifyData = (hashLength: i32, baseKey: Secret<u8[]>, transcriptHash: u8[]): u8[] => {
   const none: u8[] = []
-  const finishedKey: u8[] = tlsExpandLabel(hashLength, baseKey, "finished", none, hashLength)
-  return hashLength === SHA384_SIZE
-    ? hmacSha384(finishedKey, transcriptHash)
-    : hmacSha256(finishedKey, transcriptHash)
+  const finishedKey: Secret<u8[]> = tlsExpandLabel(hashLength, baseKey, "finished", none, hashLength)
+  const verifyData: u8[] =
+    hashLength === SHA384_SIZE
+      ? hmacSha384Secret(finishedKey, transcriptHash)
+      : hmacSha256Secret(finishedKey, transcriptHash)
+  wipe(finishedKey)
+  return verifyData
 }
 
-/** The AEAD key a traffic secret gives `suite`'s record protection (RFC 8446 §7.3); empty for a suite this module does not negotiate. */
-export const tlsTrafficKey = (suite: i32, secret: u8[]): u8[] => {
+/**
+ * The AEAD key a traffic secret gives `suite`'s record protection (RFC 8446
+ * §7.3), held as a `Secret`; empty for a suite this module does not negotiate.
+ */
+export const tlsTrafficKey = (suite: i32, trafficSecret: Secret<u8[]>): Secret<u8[]> => {
   const none: u8[] = []
   const hashLength: i32 = tlsSuiteHashLength(suite)
   if (hashLength === 0) {
-    return none
+    return secret(new Array<u8>(0))
   }
-  return tlsExpandLabel(hashLength, secret, "key", none, tlsSuiteKeyLength(suite))
+  return tlsExpandLabel(hashLength, trafficSecret, "key", none, tlsSuiteKeyLength(suite))
 }
 
-/** The 12-byte IV a traffic secret gives `suite`'s record protection (RFC 8446 §7.3); empty for a suite this module does not negotiate. */
-export const tlsTrafficIv = (suite: i32, secret: u8[]): u8[] => {
+/**
+ * The 12-byte IV a traffic secret gives `suite`'s record protection (RFC 8446
+ * §7.3), held as a `Secret`; empty for a suite this module does not negotiate.
+ */
+export const tlsTrafficIv = (suite: i32, trafficSecret: Secret<u8[]>): Secret<u8[]> => {
   const none: u8[] = []
   const hashLength: i32 = tlsSuiteHashLength(suite)
   if (hashLength === 0) {
-    return none
+    return secret(new Array<u8>(0))
   }
-  return tlsExpandLabel(hashLength, secret, "iv", none, TLS_IV_SIZE)
+  return tlsExpandLabel(hashLength, trafficSecret, "iv", none, TLS_IV_SIZE)
 }
 
 /**
@@ -288,14 +423,14 @@ const tlsEmptyHashInto = (hashLength: i32, out: u8[]): void => {
 }
 
 /**
- * `tlsDeriveSecret` in place: Derive-Secret (RFC 8446 §7.1) of `secret` with
+ * `tlsDeriveSecret` in place: Derive-Secret (RFC 8446 §7.1) of `prk` with
  * `label` and the transcript hash `transcriptHash[hashOff .. hashOff +
  * hashLength)`, its HashLen bytes written at `out[0]`.
  */
 export const tlsDeriveSecretInto = (
   kdf: HkdfScratch,
   hashLength: i32,
-  secret: u8[],
+  prk: u8[],
   label: string,
   transcriptHash: u8[],
   hashOff: i32,
@@ -304,7 +439,7 @@ export const tlsDeriveSecretInto = (
   hkdfExpandLabelInto(
     kdf,
     hashLength,
-    secret,
+    prk,
     label,
     transcriptHash,
     hashOff,
@@ -376,6 +511,98 @@ export const tlsFinishedVerifyDataInto = (
   kdf.wipe()
 }
 
+/**
+ * `tlsPskEarlySecret` in place: HKDF-Extract of `psk` under a zero salt
+ * (RFC 8446 §7.1), written at `out[0]`. The scratch is wiped; the zero salt
+ * holds nothing to wipe.
+ */
+export const tlsPskEarlySecretInto = (kdf: HkdfScratch, hashLength: i32, psk: u8[], out: u8[]): void => {
+  hkdfExtractInto(kdf, hashLength, new Array<u8>(hashLength), psk, out, TLS_SCHEDULE_FROM)
+}
+
+/** `tlsBinderKey` in place: `Derive-Secret(early, "res binder", "")`, written at `out[0]`. */
+export const tlsBinderKeyInto = (kdf: HkdfScratch, hashLength: i32, earlySecret: u8[], out: u8[]): void => {
+  const empty: u8[] = new Array<u8>(hashLength)
+  tlsEmptyHashInto(hashLength, empty)
+  tlsDeriveSecretInto(kdf, hashLength, earlySecret, "res binder", empty, TLS_SCHEDULE_FROM, out)
+}
+
+/**
+ * `tlsHandshakeSalt` in place: `Derive-Secret(early, "derived", "")`, the
+ * salt a resumed handshake extracts its handshake secret under, written at
+ * `out[0]`. The caller wipes it once the extract is done.
+ */
+export const tlsHandshakeSaltInto = (
+  kdf: HkdfScratch,
+  hashLength: i32,
+  earlySecret: u8[],
+  out: u8[]
+): void => {
+  const empty: u8[] = new Array<u8>(hashLength)
+  tlsEmptyHashInto(hashLength, empty)
+  tlsDeriveSecretInto(kdf, hashLength, earlySecret, "derived", empty, TLS_SCHEDULE_FROM, out)
+}
+
+/**
+ * `tlsResumptionPsk` in place: `HKDF-Expand-Label(resumption_master_secret,
+ * "resumption", ticketNonce[nonceOff .. nonceOff + nonceLength), HashLen)`
+ * (RFC 8446 §4.6.1), written at `out[0]`.
+ */
+export const tlsResumptionPskInto = (
+  kdf: HkdfScratch,
+  hashLength: i32,
+  resumptionMasterSecret: u8[],
+  ticketNonce: u8[],
+  nonceOff: i32,
+  nonceLength: i32,
+  out: u8[]
+): void => {
+  hkdfExpandLabelInto(
+    kdf,
+    hashLength,
+    resumptionMasterSecret,
+    "resumption",
+    ticketNonce,
+    nonceOff,
+    nonceLength,
+    out,
+    TLS_SCHEDULE_FROM,
+    hashLength
+  )
+}
+
+/**
+ * Whether `binder[binderOff .. binderOff + binderLength)` is the PSK binder
+ * RFC 8446 §4.2.11.2 asks for: the HMAC, under `finished_key =
+ * Expand-Label(binderKey, "finished", "", HashLen)`, of
+ * `truncatedHash[hashOff .. hashOff + hashLength)`, the transcript hash of
+ * the ClientHello up to its binders list. A binder that is not HashLen bytes
+ * long, or whose window is not inside `binder`, is `false` (row 9 of
+ * "Resumption" in `docs/security/tls.md`). The comparison reads every byte
+ * whatever it finds; the binder the server computed is wiped before it
+ * returns, as `tlsFinishedVerifyDataInto` wipes the finished key and the
+ * scratch.
+ */
+export const tlsBinderVerify = (
+  kdf: HkdfScratch,
+  hashLength: i32,
+  binderKey: u8[],
+  truncatedHash: u8[],
+  hashOff: i32,
+  binder: u8[],
+  binderOff: i32,
+  binderLength: i32
+): boolean => {
+  if (binderLength !== hashLength) {
+    return false
+  }
+  const expected: u8[] = new Array<u8>(hashLength)
+  tlsFinishedVerifyDataInto(kdf, hashLength, binderKey, truncatedHash, hashOff, expected, TLS_SCHEDULE_FROM)
+  const verified: boolean = timingSafeEqualAt(binder, binderOff, expected, TLS_SCHEDULE_FROM, hashLength)
+  secureZero(expected)
+  return verified
+}
+
 /**
  * `tlsTrafficKey` and `tlsTrafficIv` in place: the AEAD key a traffic secret
  * gives `suite` (RFC 8446 §7.3) written into `key`, which must be the suite's
@@ -386,7 +613,7 @@ export const tlsFinishedVerifyDataInto = (
 export const tlsTrafficKeysInto = (
   kdf: HkdfScratch,
   suite: i32,
-  secret: u8[],
+  trafficSecret: u8[],
   key: u8[],
   iv: u8[]
 ): boolean => {
@@ -395,7 +622,7 @@ export const tlsTrafficKeysInto = (
   const keyLength: i32 = tlsSuiteKeyLength(suite)
   if (
     hashLength === 0 ||
-    toI32(secret.length) !== hashLength ||
+    toI32(trafficSecret.length) !== hashLength ||
     toI32(key.length) !== keyLength ||
     toI32(iv.length) !== TLS_IV_SIZE
   ) {
@@ -404,7 +631,7 @@ export const tlsTrafficKeysInto = (
   hkdfExpandLabelInto(
     kdf,
     hashLength,
-    secret,
+    trafficSecret,
     "key",
     none,
     TLS_SCHEDULE_FROM,
@@ -416,7 +643,7 @@ export const tlsTrafficKeysInto = (
   hkdfExpandLabelInto(
     kdf,
     hashLength,
-    secret,
+    trafficSecret,
     "iv",
     none,
     TLS_SCHEDULE_FROM,
@@ -427,3 +654,185 @@ export const tlsTrafficKeysInto = (
   )
   return true
 }
+
+// ---- The schedule into held `Secret`s --------------------------------------
+
+/** The length of the bytes a `Secret` holds, which is public, for `expose` to read. */
+const tlsHeldLength = (bytes: u8[]): i32 => toI32(bytes.length)
+
+/** Overwrites the bytes a `Secret` holds with `from`, for `exposeWith` to run on the destination. */
+const tlsHeldCopy = (held: u8[], from: u8[]): void => {
+  for (let k: i32 = 0; k < toI32(held.length) && k < toI32(from.length); k++) {
+    held[k] = from[k]
+  }
+}
+
+/** `transcriptHash[hashOff .. hashOff + hashLength)` in a fresh array: the context a held form hands HKDF. */
+const tlsHeldWindow = (hashLength: i32, transcriptHash: u8[], hashOff: i32): u8[] => {
+  const window: u8[] = new Array<u8>(hashLength)
+  for (let k: i32 = 0; k < toI32(window.length); k++) {
+    window[k] = transcriptHash[hashOff + k]
+  }
+  return window
+}
+
+/**
+ * Panics naming `caller` unless `hashLength` is 32 or 48 and `held` holds
+ * `hashLength` bytes, as every secret of the schedule does.
+ */
+const tlsHeldCheck = (caller: string, hashLength: i32, held: Secret<u8[]>): void => {
+  if (hashLength !== SHA256_SIZE && hashLength !== SHA384_SIZE) {
+    panic(`${caller}: a hash length of ${hashLength}, not 32 or 48`)
+  }
+  const length: i32 = expose(held, tlsHeldLength)
+  if (length !== hashLength) {
+    panic(`${caller}: a secret of ${length} bytes, not ${hashLength}`)
+  }
+}
+
+/** HKDF-Extract of `ikm` under `salt`, both held, written over `dst`'s bytes; the plain PRK is wiped. */
+const tlsExtractHeld = (hashLength: i32, salt: Secret<u8[]>, ikm: Secret<u8[]>, dst: Secret<u8[]>): void => {
+  const prk: u8[] =
+    hashLength === SHA384_SIZE
+      ? exposeWith(salt, ikm, tlsExtractSha384Salted)
+      : exposeWith(salt, ikm, tlsExtractSha256Salted)
+  exposeWith(dst, prk, tlsHeldCopy)
+  wipe(prk)
+}
+
+/**
+ * `tlsDeriveSecret` into a held `Secret`: Derive-Secret (RFC 8446 §7.1) of
+ * `prk` with `label` and the transcript hash `transcriptHash[hashOff ..
+ * hashOff + hashLength)`, written over the HashLen bytes `dst` holds. `dst`
+ * may be `prk`. Panics unless `hashLength` is 32 or 48 and both hold
+ * HashLen bytes.
+ */
+export const tlsDeriveSecretHeld = (
+  hashLength: i32,
+  prk: Secret<u8[]>,
+  label: string,
+  transcriptHash: u8[],
+  hashOff: i32,
+  dst: Secret<u8[]>
+): void => {
+  tlsHeldCheck("tlsDeriveSecretHeld", hashLength, prk)
+  tlsHeldCheck("tlsDeriveSecretHeld", hashLength, dst)
+  const context: u8[] = tlsHeldWindow(hashLength, transcriptHash, hashOff)
+  if (hashLength === SHA384_SIZE) {
+    hkdfExpandLabelSha384Held(dst, prk, label, context)
+  } else {
+    hkdfExpandLabelSha256Held(dst, prk, label, context)
+  }
+}
+
+/**
+ * `tlsHandshakeSecret` into a held `Secret`: HKDF-Extract of `ecdhe` under
+ * `Derive-Secret(early, "derived", "")`, written over `dst`'s HashLen bytes.
+ * The salt is wiped before it returns; `dst` may be `earlySecret`.
+ */
+export const tlsHandshakeSecretHeld = (
+  hashLength: i32,
+  earlySecret: Secret<u8[]>,
+  ecdhe: Secret<u8[]>,
+  dst: Secret<u8[]>
+): void => {
+  tlsHeldCheck("tlsHandshakeSecretHeld", hashLength, dst)
+  const derived: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  tlsDeriveSecretHeld(
+    hashLength,
+    earlySecret,
+    "derived",
+    tlsEmptyHash(hashLength),
+    TLS_SCHEDULE_FROM,
+    derived
+  )
+  tlsExtractHeld(hashLength, derived, ecdhe, dst)
+  wipe(derived)
+}
+
+/**
+ * `tlsMasterSecret` into a held `Secret`: HKDF-Extract of HashLen zeros under
+ * `Derive-Secret(handshake, "derived", "")`, written over `dst`'s HashLen
+ * bytes. The salt and the zeros are wiped before it returns; `dst` may be
+ * `handshakeSecret`.
+ */
+export const tlsMasterSecretHeld = (
+  hashLength: i32,
+  handshakeSecret: Secret<u8[]>,
+  dst: Secret<u8[]>
+): void => {
+  tlsHeldCheck("tlsMasterSecretHeld", hashLength, dst)
+  const derived: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  tlsDeriveSecretHeld(
+    hashLength,
+    handshakeSecret,
+    "derived",
+    tlsEmptyHash(hashLength),
+    TLS_SCHEDULE_FROM,
+    derived
+  )
+  const zeros: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  tlsExtractHeld(hashLength, derived, zeros, dst)
+  wipe(derived)
+  wipe(zeros)
+}
+
+/**
+ * `tlsFinishedVerifyData` from a held base key and a window of a transcript:
+ * the HMAC of `transcriptHash[hashOff .. hashOff + hashLength)` under
+ * `finished_key = Expand-Label(baseKey, "finished", "", HashLen)` (RFC 8446
+ * §4.4.4). The finished key is held and wiped before it returns;
+ * `verify_data` goes on the wire, so it is plain.
+ */
+export const tlsFinishedVerifyDataHeld = (
+  hashLength: i32,
+  baseKey: Secret<u8[]>,
+  transcriptHash: u8[],
+  hashOff: i32
+): u8[] => {
+  tlsHeldCheck("tlsFinishedVerifyDataHeld", hashLength, baseKey)
+  const none: u8[] = []
+  const finishedKey: Secret<u8[]> = secret(new Array<u8>(hashLength))
+  if (hashLength === SHA384_SIZE) {
+    hkdfExpandLabelSha384Held(finishedKey, baseKey, "finished", none)
+  } else {
+    hkdfExpandLabelSha256Held(finishedKey, baseKey, "finished", none)
+  }
+  const transcript: u8[] = tlsHeldWindow(hashLength, transcriptHash, hashOff)
+  const verifyData: u8[] =
+    hashLength === SHA384_SIZE
+      ? hmacSha384Secret(finishedKey, transcript)
+      : hmacSha256Secret(finishedKey, transcript)
+  wipe(finishedKey)
+  return verifyData
+}
+
+/**
+ * `tlsTrafficKeysInto` from a held traffic secret: the AEAD key it gives
+ * `suite` (RFC 8446 §7.3) written into `key`, which must be the suite's key
+ * length, and its 12-byte IV into `iv`. Both stay plain, since the cipher
+ * reads them. `false`, writing nothing, for a suite this module does not
+ * negotiate, a secret that is not its hash's length, or a key or IV array of
+ * the wrong length.
+ */
+export const tlsTrafficKeysFromHeld = (
+  suite: i32,
+  trafficSecret: Secret<u8[]>,
+  key: u8[],
+  iv: u8[]
+): boolean => {
+  const none: u8[] = []
+  const hashLength: i32 = tlsSuiteHashLength(suite)
+  const keyLength: i32 = tlsSuiteKeyLength(suite)
+  if (
+    hashLength === 0 ||
+    expose(trafficSecret, tlsHeldLength) !== hashLength ||
+    toI32(key.length) !== keyLength ||
+    toI32(iv.length) !== TLS_IV_SIZE
+  ) {
+    return false
+  }
+  hkdfExpandLabelHeldInto(hashLength, trafficSecret, "key", none, key, TLS_SCHEDULE_FROM, keyLength)
+  hkdfExpandLabelHeldInto(hashLength, trafficSecret, "iv", none, iv, TLS_SCHEDULE_FROM, TLS_IV_SIZE)
+  return true
+}