@amritk/nish-x86_64-linux 0.17.0 → 0.20.0

package/std/crypto/hkdf.ts

@@ -65,6 +65,29 @@
  * 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** (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.
  */
@@ -78,6 +101,7 @@ import {
 } from "nish/crypto/hmac"
 import { SHA256_SIZE } from "nish/crypto/sha256"
 import { SHA384_SIZE } from "nish/crypto/sha512"
+import { Secret, expose, exposeWith, secret, wipe } from "nish:secret"
 
 /** The largest block counter, and so the most blocks `expand` can make (RFC 5869 §2.3). */
 const HKDF_MAX_BLOCKS: i32 = 255
@@ -145,10 +169,13 @@ export const hkdfExpandSha256 = (prk: u8[], info: u8[], length: i32): u8[] | nul
     mac.update(info, HKDF_FROM, toI32(info.length))
     counter[0] = toU8(i)
     mac.update(counter, HKDF_FROM, counterLength)
-    previous = mac.digest()
+    const block: u8[] = mac.digest()
+    wipe(previous)
+    previous = block
     at = hkdfAppend(out, at, previous)
     i += 1
   }
+  wipe(previous)
   return out
 }
 
@@ -179,13 +206,115 @@ export const hkdfExpandSha384 = (prk: u8[], info: u8[], length: i32): u8[] | nul
     mac.update(info, HKDF_FROM, toI32(info.length))
     counter[0] = toU8(i)
     mac.update(counter, HKDF_FROM, counterLength)
-    previous = mac.digest()
+    const block: u8[] = mac.digest()
+    wipe(previous)
+    previous = block
     at = hkdfAppend(out, at, previous)
     i += 1
   }
+  wipe(previous)
   return out
 }
 
+// ---- Keys held as `Secret`s ------------------------------------------------
+//
+// The `*Secret` functions the module docs name: each reads its key only inside
+// `exposeWith`, and hands the PRK and the output back as `Secret`s.
+
+/** What `expand` needs besides the PRK, as one argument, since `exposeWith` hands on only one. */
+interface HkdfExpandRequest {
+  info: u8[]
+  length: i32
+}
+
+/**
+ * HKDF-Extract with HMAC-SHA-256 on the plain IKM, for `exposeWith` to run.
+ * It keys HMAC with `salt` itself rather than through `hkdfSalt`, whose answer
+ * may be `salt`, because the checker does not credit that path with leaving
+ * `salt` unwritten (NL2450). The PRK is the same: an empty salt is padded to
+ * the block with zeros, as the HashLen zeros of §2.2 would be.
+ */
+const hkdfExtractSha256Exposed = (ikm: u8[], salt: u8[]): u8[] => hmacSha256(salt, ikm)
+
+/** HKDF-Extract with HMAC-SHA-384 on the plain IKM, for `exposeWith` to run, as the SHA-256 one is. */
+const hkdfExtractSha384Exposed = (ikm: u8[], salt: u8[]): u8[] => hmacSha384(salt, ikm)
+
+/** HKDF-Expand with HMAC-SHA-256 on the plain PRK, for `exposeWith` to run. */
+const hkdfExpandSha256Exposed = (prk: u8[], request: HkdfExpandRequest): u8[] | null =>
+  hkdfExpandSha256(prk, request.info, request.length)
+
+/** HKDF-Expand with HMAC-SHA-384 on the plain PRK, for `exposeWith` to run. */
+const hkdfExpandSha384Exposed = (prk: u8[], request: HkdfExpandRequest): u8[] | null =>
+  hkdfExpandSha384(prk, request.info, request.length)
+
+/** `hkdfExtractSha256` on input keying material held as a `Secret`: the 32-byte PRK, held as one. */
+export const hkdfExtractSha256Secret = (salt: u8[], ikm: Secret<u8[]>): Secret<u8[]> => {
+  const prk: u8[] = exposeWith(ikm, salt, hkdfExtractSha256Exposed)
+  return secret(prk)
+}
+
+/** `hkdfExtractSha384` on input keying material held as a `Secret`: the 48-byte PRK, held as one. */
+export const hkdfExtractSha384Secret = (salt: u8[], ikm: Secret<u8[]>): Secret<u8[]> => {
+  const prk: u8[] = exposeWith(ikm, salt, hkdfExtractSha384Exposed)
+  return secret(prk)
+}
+
+/**
+ * `hkdfExpandSha256` on a PRK held as a `Secret`: the output keying material,
+ * held as one, or `null` where `hkdfExpandSha256` answers `null`.
+ */
+export const hkdfExpandSha256Secret = (prk: Secret<u8[]>, info: u8[], length: i32): Secret<u8[]> | null => {
+  const request: HkdfExpandRequest = { info: info, length: length }
+  const okm: u8[] | null = exposeWith(prk, request, hkdfExpandSha256Exposed)
+  if (okm === null) {
+    return null
+  }
+  return secret(okm)
+}
+
+/**
+ * `hkdfExpandSha384` on a PRK held as a `Secret`: the output keying material,
+ * held as one, or `null` where `hkdfExpandSha384` answers `null`.
+ */
+export const hkdfExpandSha384Secret = (prk: Secret<u8[]>, info: u8[], length: i32): Secret<u8[]> | null => {
+  const request: HkdfExpandRequest = { info: info, length: length }
+  const okm: u8[] | null = exposeWith(prk, request, hkdfExpandSha384Exposed)
+  if (okm === null) {
+    return null
+  }
+  return secret(okm)
+}
+
+/**
+ * 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.
+ */
+export const hkdfSha256Secret = (
+  salt: u8[],
+  ikm: Secret<u8[]>,
+  info: u8[],
+  length: i32
+): Secret<u8[]> | null => {
+  const prk: Secret<u8[]> = hkdfExtractSha256Secret(salt, ikm)
+  const okm: Secret<u8[]> | null = hkdfExpandSha256Secret(prk, info, length)
+  wipe(prk)
+  return okm
+}
+
+/** `hkdfSha256Secret` with HMAC-SHA-384: the PRK is 48 bytes, and wiped before it returns. */
+export const hkdfSha384Secret = (
+  salt: u8[],
+  ikm: Secret<u8[]>,
+  info: u8[],
+  length: i32
+): Secret<u8[]> | null => {
+  const prk: Secret<u8[]> = hkdfExtractSha384Secret(salt, ikm)
+  const okm: Secret<u8[]> | null = hkdfExpandSha384Secret(prk, info, length)
+  wipe(prk)
+  return okm
+}
+
 /**
  * The `HkdfLabel` struct of RFC 8446 §7.1, the `info` HKDF-Expand-Label hands
  * to `expand`, or a panic naming `caller` when `length`, `label` or `context`
@@ -212,6 +341,13 @@ const hkdfLabel = (caller: string, label: string, context: u8[], length: i32): u
   out[1] = toU8(length & 0xff)
   out[2] = toU8(fullLength)
   for (let k: i32 = 0; k < fullLength; k += 1) {
+    // `out` is longer than `3 + fullLength`, but the proof cannot read that
+    // off the sum it was allocated with; this test is what proves the store.
+    // It sits in the body rather than the loop condition, which stays the
+    // plain `k < fullLength` the attribute pass counts as a bounded loop.
+    if (3 + k >= toI32(out.length)) {
+      panic("hkdfLabel: the label overran its buffer")
+    }
     out[3 + k] = toU8(toI32(full.charCodeAt(k)))
   }
   out[3 + fullLength] = toU8(contextLength)
@@ -221,12 +357,12 @@ const hkdfLabel = (caller: string, label: string, context: u8[], length: i32): u
 
 /**
  * HKDF-Expand-Label with HMAC-SHA-256 (RFC 8446 §7.1): `length` bytes from
- * `secret`, `"tls13 " + label` and `context`. Panics on an argument out of the
+ * `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.
  */
-export const hkdfExpandLabelSha256 = (secret: u8[], label: string, context: u8[], length: i32): u8[] => {
+export const hkdfExpandLabelSha256 = (prk: u8[], label: string, context: u8[], length: i32): u8[] => {
   const okm: u8[] | null = hkdfExpandSha256(
-    secret,
+    prk,
     hkdfLabel("hkdfExpandLabelSha256", label, context, length),
     length
   )
@@ -238,12 +374,12 @@ export const hkdfExpandLabelSha256 = (secret: u8[], label: string, context: u8[]
 
 /**
  * HKDF-Expand-Label with HMAC-SHA-384 (RFC 8446 §7.1): `length` bytes from
- * `secret`, `"tls13 " + label` and `context`. Panics on an argument out of the
+ * `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.
  */
-export const hkdfExpandLabelSha384 = (secret: u8[], label: string, context: u8[], length: i32): u8[] => {
+export const hkdfExpandLabelSha384 = (prk: u8[], label: string, context: u8[], length: i32): u8[] => {
   const okm: u8[] | null = hkdfExpandSha384(
-    secret,
+    prk,
     hkdfLabel("hkdfExpandLabelSha384", label, context, length),
     length
   )
@@ -253,6 +389,47 @@ export const hkdfExpandLabelSha384 = (secret: u8[], label: string, context: u8[]
   return okm
 }
 
+/**
+ * `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.
+ */
+export const hkdfExpandLabelSha256Secret = (
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[],
+  length: i32
+): Secret<u8[]> => {
+  const okm: Secret<u8[]> | null = hkdfExpandSha256Secret(
+    prk,
+    hkdfLabel("hkdfExpandLabelSha256Secret", label, context, length),
+    length
+  )
+  if (okm === null) {
+    panic("hkdfExpandLabelSha256Secret: a secret shorter than 32 bytes")
+  }
+  return okm
+}
+
+/** `hkdfExpandLabelSha256Secret` with HMAC-SHA-384: panics as `hkdfExpandLabelSha384` does. */
+export const hkdfExpandLabelSha384Secret = (
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[],
+  length: i32
+): Secret<u8[]> => {
+  const okm: Secret<u8[]> | null = hkdfExpandSha384Secret(
+    prk,
+    hkdfLabel("hkdfExpandLabelSha384Secret", label, context, length),
+    length
+  )
+  if (okm === null) {
+    panic("hkdfExpandLabelSha384Secret: a secret shorter than 48 bytes")
+  }
+  return okm
+}
+
 // ---- Caller-owned scratch ----------------------------------------------------
 
 /** The longest `HkdfLabel`: two length bytes, `label<7..255>` and `context<0..255>`, each with its length byte. */
@@ -435,7 +612,7 @@ export const hkdfExpandInto = (
 
 /**
  * HKDF-Expand-Label (RFC 8446 §7.1) over the hash `hashLength` names: `length`
- * bytes from `secret`, `"tls13 " + label` and the context
+ * 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
@@ -444,7 +621,7 @@ export const hkdfExpandInto = (
 export const hkdfExpandLabelInto = (
   s: HkdfScratch,
   hashLength: i32,
-  secret: u8[],
+  prk: u8[],
   label: string,
   context: u8[],
   contextOff: i32,
@@ -468,7 +645,7 @@ export const hkdfExpandLabelInto = (
   ) {
     panic("hkdfExpandLabelInto: the context window is outside its array or longer than 255 bytes")
   }
-  if (toI32(secret.length) < hashLength) {
+  if (toI32(prk.length) < hashLength) {
     panic("hkdfExpandLabelInto: a secret shorter than HashLen")
   }
   hkdfCheckOutput("hkdfExpandLabelInto", out, at, length)
@@ -491,5 +668,120 @@ export const hkdfExpandLabelInto = (
   for (let k: i32 = 0; k < contextLen && contextAt + 1 + k < toI32(info.length); k += 1) {
     info[contextAt + 1 + k] = context[contextOff + k]
   }
-  hkdfExpandWindow(s, hashLength, secret, info, contextAt + 1 + contextLen, out, at, length)
+  hkdfExpandWindow(s, hashLength, prk, info, contextAt + 1 + contextLen, out, at, length)
+}
+
+// ---- From and into a held `Secret` -----------------------------------------
+//
+// The `*Held` forms derive from a `Secret<u8[]>` the caller already holds, and
+// into one, overwriting its bytes in place, so a key that lives in one place
+// for a connection's life is never handed out as a fresh `Secret`. The output
+// is derived plain inside `exposeWith` of the PRK, by the function the
+// `*Secret` forms run, copied where it goes, and wiped. None of this opens a
+// `using arena()` block: every hasher's constructor stores the arrays it
+// allocates into its fields, which the block refuses (NL2424), and a scratch
+// made before the block could be neither written nor wiped inside `exposeWith`
+// (NL2450, and `secureZero` is C). The function's own scope reclaims the
+// temporaries instead.
+
+/** The length of the bytes a `Secret` holds, which is public, for `expose` to read. */
+const hkdfHeldLength = (bytes: u8[]): i32 => toI32(bytes.length)
+
+/**
+ * HKDF-Expand-Label of the held `prk` over the hash `hashLength` names: the
+ * `length` bytes, plain, for the caller to copy and wipe. Panics naming
+ * `caller` where `hkdfExpandLabelSha256` does.
+ */
+const hkdfHeldDerive = (
+  caller: string,
+  hashLength: i32,
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[],
+  length: i32
+): u8[] => {
+  hkdfCheckHash(caller, hashLength)
+  const request: HkdfExpandRequest = { info: hkdfLabel(caller, label, context, length), length: length }
+  const okm: u8[] | null =
+    hashLength === SHA256_SIZE
+      ? exposeWith(prk, request, hkdfExpandSha256Exposed)
+      : exposeWith(prk, request, hkdfExpandSha384Exposed)
+  if (okm === null) {
+    panic(
+      `${caller}: a secret shorter than ${hashLength} bytes, or more than ${255 * hashLength} bytes asked`
+    )
+  }
+  return okm
+}
+
+/**
+ * Overwrites the bytes a `Secret` holds with `okm`, for `exposeWith` to run on
+ * the destination: it writes the value it is shown, never its argument.
+ */
+const hkdfHeldCopy = (held: u8[], okm: u8[]): void => {
+  for (let k: i32 = 0; k < toI32(held.length) && k < toI32(okm.length); k++) {
+    held[k] = okm[k]
+  }
+}
+
+/** Derives into `dst`, as many bytes as it holds, for the two exported forms. */
+const hkdfHeld = (
+  caller: string,
+  hashLength: i32,
+  dst: Secret<u8[]>,
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[]
+): void => {
+  const okm: u8[] = hkdfHeldDerive(caller, hashLength, prk, label, context, expose(dst, hkdfHeldLength))
+  exposeWith(dst, okm, hkdfHeldCopy)
+  wipe(okm)
+}
+
+/**
+ * `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.
+ */
+export const hkdfExpandLabelSha256Held = (
+  dst: Secret<u8[]>,
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[]
+): void => {
+  hkdfHeld("hkdfExpandLabelSha256Held", SHA256_SIZE, dst, prk, label, context)
+}
+
+/** `hkdfExpandLabelSha256Held` with HMAC-SHA-384: panics as `hkdfExpandLabelSha384` does. */
+export const hkdfExpandLabelSha384Held = (
+  dst: Secret<u8[]>,
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[]
+): void => {
+  hkdfHeld("hkdfExpandLabelSha384Held", SHA384_SIZE, dst, prk, label, context)
+}
+
+/**
+ * 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.
+ */
+export const hkdfExpandLabelHeldInto = (
+  hashLength: i32,
+  prk: Secret<u8[]>,
+  label: string,
+  context: u8[],
+  out: u8[],
+  at: i32,
+  length: i32
+): void => {
+  hkdfCheckOutput("hkdfExpandLabelHeldInto", out, at, length)
+  const okm: u8[] = hkdfHeldDerive("hkdfExpandLabelHeldInto", hashLength, prk, label, context, length)
+  for (let k: i32 = 0; k < length && k < toI32(okm.length); k++) {
+    out[at + k] = okm[k]
+  }
+  wipe(okm)
 }