@amritk/nish-x86_64-linux 0.18.0 → 0.21.0

package/std/crypto/hmac.ts

@@ -1,5 +1,6 @@
 /**
- * `nish/crypto/hmac` — HMAC as RFC 2104 defines it, over SHA-256 and SHA-384.
+ * `nish/crypto/hmac` — HMAC as RFC 2104 defines it, over SHA-256, SHA-384 and
+ * SHA-512.
  *
  *     H(K XOR opad, H(K XOR ipad, text))
  *
@@ -24,17 +25,38 @@
  * which HMAC does not keep secret; a received tag is compared with
  * `timingSafeEqual`, never `===`.
  *
+ * **What the key reaches is wiped** (CLAUDE.md, "Security"). The key block
+ * is wiped once both hashers have absorbed it, and so is the hash
+ * of a key longer than a block and the hasher that made it. `digest` wipes
+ * the inner digest and both keyed hashers (chaining value, pending block and
+ * message schedule) before it answers, so a finished `HmacSha256` holds
+ * nothing of the key. The wipes are `wipe`'s volatile stores, which `-O2`
+ * keeps (`tests/wipes/crypto.js`, "crypto_hmac crypto_hkdf: the wipes survive -O2").
+ * What no wipe here reaches is the caller's own key array, and an
+ * `HmacSha256` that is keyed and then dropped without a `digest` keeps its
+ * keyed hashers (docs/security/crypto-k1.md, K1-7).
+ *
+ * A caller that holds its key as a `Secret<u8[]>` (`nish:secret`) MACs with
+ * `hmacSha256Secret`, `hmacSha384Secret` or `hmacSha512Secret`, which read the
+ * key only inside `exposeWith`; the tag they answer is public and plain.
+ *
  * `HmacSha256Scratch` and `HmacSha384Scratch` are the same computation in
  * hashers the caller allocates once: `begin` keys them again in place and
  * `finishInto` writes the tag into the caller's array, so a loop of them
  * stores nothing of its own and an arena scope around it releases all it
  * allocated (see "Caller-owned scratch" below).
  *
- * Written from RFC 2104, not ported from another implementation.
+ * `pbkdf2HmacSha256` is PBKDF2 with HMAC-SHA-256 (RFC 8018 §5.2), the key
+ * derivation SCRAM-SHA-256 runs over a password: the password goes in as a
+ * `Secret<u8[]>` and the derived key comes out as one, and every U_j and T_i
+ * is wiped before it answers (see "PBKDF2" below).
+ *
+ * Written from RFC 2104 and RFC 8018, not ported from another implementation.
  */
-import { SHA256_BLOCK, SHA256_SIZE, Sha256, sha256 } from "nish/crypto/sha256"
-import { SHA384_SIZE, SHA512_BLOCK, Sha384, sha384 } from "nish/crypto/sha512"
+import { SHA256_BLOCK, SHA256_SIZE, Sha256 } from "nish/crypto/sha256"
+import { SHA384_SIZE, SHA512_BLOCK, SHA512_SIZE, Sha384, Sha512 } from "nish/crypto/sha512"
 import { timingSafeEqual } from "nish/crypto/ct"
+import { Secret, exposeWith, secret, wipe } from "nish:secret"
 
 /** RFC 2104 §2's `ipad`, the byte XORed into the key for the inner hash. */
 const HMAC_IPAD: i32 = 0x36
@@ -76,6 +98,141 @@ const hmacPadBlock = (key: u8[], blockSize: i32, pad: i32): u8[] => {
   return out
 }
 
+/**
+ * Zeroes everything `h` holds of the key and the message it was fed: its hash
+ * value, its pending block and its message schedule, with `wipe`'s volatile
+ * stores, which no optimiser removes however dead the hasher is about to be.
+ * The hasher is left finished, so that feeding it before it is started again
+ * panics, as feeding a spent one always has.
+ */
+const hmacWipeSha256 = (h: Sha256): void => {
+  wipe(h.state)
+  wipe(h.block)
+  wipe(h.schedule)
+  h.fill = 0
+  h.total = 0
+  h.finished = true
+}
+
+/** `hmacWipeSha256` for SHA-384. */
+const hmacWipeSha384 = (h: Sha384): void => {
+  wipe(h.engine.state)
+  wipe(h.engine.block)
+  wipe(h.engine.schedule)
+  h.engine.filled = 0
+  h.engine.count = toU64(0)
+  h.engine.finished = true
+}
+
+/** `hmacWipeSha256` for SHA-512. */
+const hmacWipeSha512 = (h: Sha512): void => {
+  wipe(h.engine.state)
+  wipe(h.engine.block)
+  wipe(h.engine.schedule)
+  h.engine.filled = 0
+  h.engine.count = toU64(0)
+  h.engine.finished = true
+}
+
+/**
+ * Panics on a key longer than 2^31 - 1 bytes, before any `toI32` of its
+ * length: under `--number-mode f64` that would saturate, and the key hashed
+ * would be a prefix, so two keys sharing it would MAC alike (K1-1).
+ */
+const hmacCheckKey = (key: u8[]): void => {
+  if (key.length > 2147483647) {
+    panic("hmac: a key longer than 2^31 - 1 bytes")
+  }
+}
+
+/**
+ * Keys `inner` with `k XOR ipad` and `outer` with `k XOR opad`, `k` no longer
+ * than SHA-256's block, in one block that is rewritten between the two and
+ * wiped once both have absorbed it.
+ */
+const hmacPadsSha256 = (inner: Sha256, outer: Sha256, k: u8[]): void => {
+  const pad: u8[] = hmacPadBlock(k, SHA256_BLOCK, HMAC_IPAD)
+  inner.update(pad, HMAC_FROM, SHA256_BLOCK)
+  hmacPadInto(pad, k, HMAC_FROM, toI32(k.length), HMAC_OPAD)
+  outer.update(pad, HMAC_FROM, SHA256_BLOCK)
+  wipe(pad)
+}
+
+/**
+ * Keys `inner` and `outer` with `key` as RFC 2104 §2 says: a key longer than
+ * the block is replaced by its hash, in a hasher of its own, and that hash
+ * and that hasher are wiped once the key blocks are absorbed.
+ */
+const hmacKeySha256 = (inner: Sha256, outer: Sha256, key: u8[]): void => {
+  hmacCheckKey(key)
+  if (toI32(key.length) <= SHA256_BLOCK) {
+    hmacPadsSha256(inner, outer, key)
+    return
+  }
+  const hasher = new Sha256()
+  hasher.update(key, HMAC_FROM, toI32(key.length))
+  const hashed: u8[] = hasher.digest()
+  hmacWipeSha256(hasher)
+  hmacPadsSha256(inner, outer, hashed)
+  wipe(hashed)
+}
+
+/** `hmacPadsSha256` for SHA-384's 128-byte block. */
+const hmacPadsSha384 = (inner: Sha384, outer: Sha384, k: u8[]): void => {
+  const pad: u8[] = hmacPadBlock(k, SHA512_BLOCK, HMAC_IPAD)
+  inner.update(pad, HMAC_FROM, SHA512_BLOCK)
+  hmacPadInto(pad, k, HMAC_FROM, toI32(k.length), HMAC_OPAD)
+  outer.update(pad, HMAC_FROM, SHA512_BLOCK)
+  wipe(pad)
+}
+
+/**
+ * Keys `inner` and `outer` with `key` as RFC 2104 §2 says: a key longer than
+ * the block is replaced by its hash, in a hasher of its own, and that hash
+ * and that hasher are wiped once the key blocks are absorbed.
+ */
+const hmacKeySha384 = (inner: Sha384, outer: Sha384, key: u8[]): void => {
+  hmacCheckKey(key)
+  if (toI32(key.length) <= SHA512_BLOCK) {
+    hmacPadsSha384(inner, outer, key)
+    return
+  }
+  const hasher = new Sha384()
+  hasher.update(key, HMAC_FROM, toI32(key.length))
+  const hashed: u8[] = hasher.digest()
+  hmacWipeSha384(hasher)
+  hmacPadsSha384(inner, outer, hashed)
+  wipe(hashed)
+}
+
+/** `hmacPadsSha256` for SHA-512's 128-byte block. */
+const hmacPadsSha512 = (inner: Sha512, outer: Sha512, k: u8[]): void => {
+  const pad: u8[] = hmacPadBlock(k, SHA512_BLOCK, HMAC_IPAD)
+  inner.update(pad, HMAC_FROM, SHA512_BLOCK)
+  hmacPadInto(pad, k, HMAC_FROM, toI32(k.length), HMAC_OPAD)
+  outer.update(pad, HMAC_FROM, SHA512_BLOCK)
+  wipe(pad)
+}
+
+/**
+ * Keys `inner` and `outer` with `key` as RFC 2104 §2 says: a key longer than
+ * the block is replaced by its hash, in a hasher of its own, and that hash
+ * and that hasher are wiped once the key blocks are absorbed.
+ */
+const hmacKeySha512 = (inner: Sha512, outer: Sha512, key: u8[]): void => {
+  hmacCheckKey(key)
+  if (toI32(key.length) <= SHA512_BLOCK) {
+    hmacPadsSha512(inner, outer, key)
+    return
+  }
+  const hasher = new Sha512()
+  hasher.update(key, HMAC_FROM, toI32(key.length))
+  const hashed: u8[] = hasher.digest()
+  hmacWipeSha512(hasher)
+  hmacPadsSha512(inner, outer, hashed)
+  wipe(hashed)
+}
+
 /**
  * HMAC-SHA-256 in progress (RFC 2104 with RFC 4231's SHA-256): feed the
  * message with `update`, as many windows as it takes, and take the 32-byte
@@ -87,13 +244,14 @@ export class HmacSha256 {
   /** H(K XOR opad, …), fed the key block in the constructor and the inner digest last. */
   outer: Sha256
 
-  /** Keys the computation. A key longer than 64 bytes is replaced by its SHA-256 (RFC 2104 §2). */
+  /**
+   * Keys the computation. A key longer than 64 bytes is replaced by its
+   * SHA-256 (RFC 2104 §2), which is wiped once used (`hmacKeySha256`).
+   */
   constructor(key: u8[]) {
-    const k: u8[] = toI32(key.length) > SHA256_BLOCK ? sha256(key) : key
     this.inner = new Sha256()
-    this.inner.update(hmacPadBlock(k, SHA256_BLOCK, HMAC_IPAD), HMAC_FROM, SHA256_BLOCK)
     this.outer = new Sha256()
-    this.outer.update(hmacPadBlock(k, SHA256_BLOCK, HMAC_OPAD), HMAC_FROM, SHA256_BLOCK)
+    hmacKeySha256(this.inner, this.outer, key)
   }
 
   /** Absorbs `data[off .. off + len)`; a window outside `data` panics in `Sha256.update`. */
@@ -101,11 +259,15 @@ export class HmacSha256 {
     this.inner.update(data, off, len)
   }
 
-  /** The 32-byte tag, in a fresh array. Ends the computation. */
+  /** The 32-byte tag, in a fresh array. Ends the computation, and wipes both hashers. */
   digest(): u8[] {
     const innerDigest: u8[] = this.inner.digest()
     this.outer.update(innerDigest, HMAC_FROM, SHA256_SIZE)
-    return this.outer.digest()
+    wipe(innerDigest)
+    const tag: u8[] = this.outer.digest()
+    hmacWipeSha256(this.inner)
+    hmacWipeSha256(this.outer)
+    return tag
   }
 }
 
@@ -121,11 +283,9 @@ export class HmacSha384 {
 
   /** Keys the computation. A key longer than 128 bytes is replaced by its SHA-384 (RFC 2104 §2). */
   constructor(key: u8[]) {
-    const k: u8[] = toI32(key.length) > SHA512_BLOCK ? sha384(key) : key
     this.inner = new Sha384()
-    this.inner.update(hmacPadBlock(k, SHA512_BLOCK, HMAC_IPAD), HMAC_FROM, SHA512_BLOCK)
     this.outer = new Sha384()
-    this.outer.update(hmacPadBlock(k, SHA512_BLOCK, HMAC_OPAD), HMAC_FROM, SHA512_BLOCK)
+    hmacKeySha384(this.inner, this.outer, key)
   }
 
   /** Absorbs `data[off .. off + len)`; a window outside `data` panics in `Sha384.update`. */
@@ -133,11 +293,49 @@ export class HmacSha384 {
     this.inner.update(data, off, len)
   }
 
-  /** The 48-byte tag, in a fresh array. Ends the computation. */
+  /** The 48-byte tag, in a fresh array. Ends the computation, and wipes both hashers. */
   digest(): u8[] {
     const innerDigest: u8[] = this.inner.digest()
     this.outer.update(innerDigest, HMAC_FROM, SHA384_SIZE)
-    return this.outer.digest()
+    wipe(innerDigest)
+    const tag: u8[] = this.outer.digest()
+    hmacWipeSha384(this.inner)
+    hmacWipeSha384(this.outer)
+    return tag
+  }
+}
+
+/**
+ * HMAC-SHA-512 in progress (RFC 2104 with RFC 4231's SHA-512), with
+ * `HmacSha256`'s methods. The block is SHA-512's 128 bytes and the tag 64.
+ */
+export class HmacSha512 {
+  /** H(K XOR ipad, …), fed the key block in the constructor and the message after. */
+  inner: Sha512
+  /** H(K XOR opad, …), fed the key block in the constructor and the inner digest last. */
+  outer: Sha512
+
+  /** Keys the computation. A key longer than 128 bytes is replaced by its SHA-512 (RFC 2104 §2). */
+  constructor(key: u8[]) {
+    this.inner = new Sha512()
+    this.outer = new Sha512()
+    hmacKeySha512(this.inner, this.outer, key)
+  }
+
+  /** Absorbs `data[off .. off + len)`; a window outside `data` panics in `Sha512.update`. */
+  update(data: u8[], off: i32, len: i32): void {
+    this.inner.update(data, off, len)
+  }
+
+  /** The 64-byte tag, in a fresh array. Ends the computation, and wipes both hashers. */
+  digest(): u8[] {
+    const innerDigest: u8[] = this.inner.digest()
+    this.outer.update(innerDigest, HMAC_FROM, SHA512_SIZE)
+    wipe(innerDigest)
+    const tag: u8[] = this.outer.digest()
+    hmacWipeSha512(this.inner)
+    hmacWipeSha512(this.outer)
+    return tag
   }
 }
 
@@ -147,7 +345,7 @@ export class HmacSha384 {
  * `data` longer than 2^31 - 1 bytes panics, as `sha256` does and for its
  * reason: under `--number-mode f64` the tag would be of a prefix, and a tag
  * that verifies every message sharing that prefix is a forgery. A key that
- * long reaches `sha256` in the constructor and panics there.
+ * long panics in the constructor for the same reason.
  */
 export const hmacSha256 = (key: u8[], data: u8[]): u8[] => {
   if (data.length > 2147483647) {
@@ -171,6 +369,31 @@ export const hmacSha384 = (key: u8[], data: u8[]): u8[] => {
   return mac.digest()
 }
 
+/**
+ * The HMAC-SHA-512 of all of `data` under `key`, as a fresh 64-byte array.
+ * `data` longer than 2^31 - 1 bytes panics, as in `hmacSha256`.
+ */
+export const hmacSha512 = (key: u8[], data: u8[]): u8[] => {
+  if (data.length > 2147483647) {
+    panic("hmacSha512: a message longer than 2^31 - 1 bytes")
+  }
+  const mac = new HmacSha512(key)
+  mac.update(data, HMAC_FROM, toI32(data.length))
+  return mac.digest()
+}
+
+/**
+ * `hmacSha256` under a key held as a `Secret`, read only inside `exposeWith`.
+ * The tag is public, so it is answered plain; the caller still wipes the key.
+ */
+export const hmacSha256Secret = (key: Secret<u8[]>, data: u8[]): u8[] => exposeWith(key, data, hmacSha256)
+
+/** `hmacSha384` under a key held as a `Secret`, as `hmacSha256Secret` is. */
+export const hmacSha384Secret = (key: Secret<u8[]>, data: u8[]): u8[] => exposeWith(key, data, hmacSha384)
+
+/** `hmacSha512` under a key held as a `Secret`, as `hmacSha256Secret` is. */
+export const hmacSha512Secret = (key: Secret<u8[]>, data: u8[]): u8[] => exposeWith(key, data, hmacSha512)
+
 /**
  * Whether `tag` is the HMAC-SHA-256 of `data` under `key`, compared by
  * `timingSafeEqual`. A tag that is not 32 bytes answers `false` without a
@@ -184,6 +407,10 @@ export const hmacSha256Verify = (key: u8[], data: u8[], tag: u8[]): boolean =>
 export const hmacSha384Verify = (key: u8[], data: u8[], tag: u8[]): boolean =>
   timingSafeEqual(hmacSha384(key, data), tag)
 
+/** Whether `tag` is the HMAC-SHA-512 of `data` under `key`, compared as `hmacSha256Verify` does. */
+export const hmacSha512Verify = (key: u8[], data: u8[], tag: u8[]): boolean =>
+  timingSafeEqual(hmacSha512(key, data), tag)
+
 // ---- Caller-owned scratch --------------------------------------------------
 //
 // `HmacSha256` makes its two hashers in its constructor, and the one-shot
@@ -241,44 +468,6 @@ export const hmacCopySha384 = (from: Sha384, to: Sha384): void => {
   to.engine.finished = from.engine.finished
 }
 
-/**
- * Zeroes everything `h` holds of the message it was fed: the pending block
- * with `secureZero`, and the hash value and message schedule, which are words
- * `secureZero` does not take, with ordinary stores. Those stand because the
- * hasher stays reachable for the next `begin`. The hasher is left finished, so
- * that feeding it before it is started again panics.
- */
-const hmacWipeSha256 = (h: Sha256): void => {
-  secureZero(h.block)
-  const state: u32[] = h.state
-  for (let i: i32 = 0; i < toI32(state.length); i += 1) {
-    state[i] = toU32(0)
-  }
-  const schedule: u32[] = h.schedule
-  for (let i: i32 = 0; i < toI32(schedule.length); i += 1) {
-    schedule[i] = toU32(0)
-  }
-  h.fill = 0
-  h.total = 0
-  h.finished = true
-}
-
-/** `hmacWipeSha256` for SHA-384. */
-const hmacWipeSha384 = (h: Sha384): void => {
-  secureZero(h.engine.block)
-  const state: u64[] = h.engine.state
-  for (let i: i32 = 0; i < toI32(state.length); i += 1) {
-    state[i] = toU64(0)
-  }
-  const schedule: u64[] = h.engine.schedule
-  for (let i: i32 = 0; i < toI32(schedule.length); i += 1) {
-    schedule[i] = toU64(0)
-  }
-  h.engine.filled = 0
-  h.engine.count = toU64(0)
-  h.engine.finished = true
-}
-
 /** Whether `[off, off + len)` is a window inside an array of `length` elements. */
 const hmacWindowFits = (length: i32, off: i32, len: i32): boolean =>
   off >= 0 && len >= 0 && off <= length - len
@@ -346,6 +535,10 @@ export class HmacSha256Scratch {
    * stored to the arena analysis.
    */
   keyBlocks(key: u8[], off: i32, len: i32): void {
+    // Starting a hasher again copies only the live part of `fresh`, so the
+    // last computation's block and schedule are wiped first (K1-7).
+    hmacWipeSha256(this.inner)
+    hmacWipeSha256(this.outer)
     hmacPadInto(this.pad, key, off, len, HMAC_IPAD)
     hmacCopySha256(this.fresh, this.inner)
     this.inner.update(this.pad, HMAC_FROM, SHA256_BLOCK)
@@ -434,6 +627,10 @@ export class HmacSha384Scratch {
    * stored to the arena analysis.
    */
   keyBlocks(key: u8[], off: i32, len: i32): void {
+    // Starting a hasher again copies only the live part of `fresh`, so the
+    // last computation's block and schedule are wiped first (K1-7).
+    hmacWipeSha384(this.inner)
+    hmacWipeSha384(this.outer)
     hmacPadInto(this.pad, key, off, len, HMAC_IPAD)
     hmacCopySha384(this.fresh, this.inner)
     this.inner.update(this.pad, HMAC_FROM, SHA512_BLOCK)
@@ -469,3 +666,134 @@ export class HmacSha384Scratch {
     hmacWipeSha384(this.outer)
   }
 }
+
+// ---- PBKDF2 ----------------------------------------------------------------
+//
+// PBKDF2 with HMAC-SHA-256 as its PRF (RFC 8018 §5.2), the key derivation
+// SCRAM-SHA-256 (RFC 7677, RFC 5802 §3 "Hi") runs over a password. The
+// password keys an inner and an outer hasher once; every U_j after that is
+// two compressions in a working hasher copied from them, so a count of 4096
+// costs 4096 HMACs and never keys one again.
+
+/** What `pbkdf2HmacSha256` passes through `exposeWith`, which carries one argument. */
+interface Pbkdf2Request {
+  /** The salt, public: SCRAM's server sends it. */
+  salt: u8[]
+  /** The iteration count `c`, at least 1. */
+  iterations: i32
+  /** The derived key's length `dkLen` in bytes, at least 1. */
+  length: i32
+}
+
+/** The length of INT(i), the big-endian block index after the salt; typed, as `HMAC_FROM` is. */
+const PBKDF2_INDEX: i32 = 4
+
+/**
+ * Ends the HMAC `work` holds, keyed as `keyedOuter` is on the outer side, and
+ * writes its 32-byte tag into `out`. Both digests `work` answers are wiped
+ * here, so they die with this call and its arena scope.
+ */
+const pbkdf2Finish = (keyedOuter: Sha256, work: Sha256, out: u8[]): void => {
+  const innerDigest: u8[] = work.digest()
+  hmacCopySha256(keyedOuter, work)
+  work.update(innerDigest, HMAC_FROM, SHA256_SIZE)
+  wipe(innerDigest)
+  const tag: u8[] = work.digest()
+  for (let i: i32 = 0; i < SHA256_SIZE && i < toI32(tag.length) && i < toI32(out.length); i += 1) {
+    out[i] = tag[i]
+  }
+  wipe(tag)
+}
+
+/** `pbkdf2HmacSha256` on the exposed password. */
+const pbkdf2HmacSha256Exposed = (password: u8[], request: Pbkdf2Request): u8[] | null => {
+  const salt: u8[] = request.salt
+  const iterations: i32 = request.iterations
+  const length: i32 = request.length
+  // Before any `toI32`, which would saturate under `--number-mode f64`.
+  if (password.length > 2147483647 || salt.length > 2147483647) {
+    return null
+  }
+  if (iterations < 1 || length < 1) {
+    return null
+  }
+  const keyedInner = new Sha256()
+  const keyedOuter = new Sha256()
+  hmacKeySha256(keyedInner, keyedOuter, password)
+  const work = new Sha256()
+  const u: u8[] = new Array<u8>(SHA256_SIZE)
+  const t: u8[] = new Array<u8>(SHA256_SIZE)
+  const index: u8[] = new Array<u8>(PBKDF2_INDEX)
+  const dk: u8[] = new Array<u8>(length)
+  // dkLen is an i32, so it never reaches RFC 8018's (2^32 - 1) * hLen bound,
+  // and the block index below never passes 2^26.
+  let block: i32 = 1
+  let done: i32 = 0
+  while (done < length) {
+    // U_1 = PRF(P, S || INT(i)), INT(i) four bytes, most significant first.
+    index[0] = toU8((block >> 24) & 0xff)
+    index[1] = toU8((block >> 16) & 0xff)
+    index[2] = toU8((block >> 8) & 0xff)
+    index[3] = toU8(block & 0xff)
+    hmacCopySha256(keyedInner, work)
+    work.update(salt, HMAC_FROM, toI32(salt.length))
+    work.update(index, HMAC_FROM, PBKDF2_INDEX)
+    pbkdf2Finish(keyedOuter, work, u)
+    for (let j: i32 = 0; j < SHA256_SIZE && j < toI32(t.length) && j < toI32(u.length); j += 1) {
+      t[j] = u[j]
+    }
+    // U_c = PRF(P, U_{c-1}); T_i = U_1 XOR ... XOR U_c.
+    for (let c: i32 = 1; c < iterations; c += 1) {
+      hmacCopySha256(keyedInner, work)
+      work.update(u, HMAC_FROM, SHA256_SIZE)
+      pbkdf2Finish(keyedOuter, work, u)
+      for (let j: i32 = 0; j < SHA256_SIZE && j < toI32(t.length) && j < toI32(u.length); j += 1) {
+        t[j] = t[j] ^ u[j]
+      }
+    }
+    const take: i32 = length - done < SHA256_SIZE ? length - done : SHA256_SIZE
+    for (let j: i32 = 0; j < take && j < toI32(t.length) && done + j < toI32(dk.length); j += 1) {
+      dk[done + j] = t[j]
+    }
+    done += take
+    block += 1
+  }
+  wipe(u)
+  wipe(t)
+  hmacWipeSha256(work)
+  hmacWipeSha256(keyedInner)
+  hmacWipeSha256(keyedOuter)
+  return dk
+}
+
+/**
+ * PBKDF2-HMAC-SHA256(P, S, c, dkLen) as RFC 8018 §5.2 defines it: the
+ * `dkLen`-byte key derived from the password `password` and the salt `salt`
+ * over `iterations` rounds, as a `Secret`.
+ *
+ *     const salted: Secret<u8[]> | null = pbkdf2HmacSha256(password, salt, 4096, 32);
+ *
+ * Bad input answers `null` and never panics: an iteration count or a length
+ * below 1, or a password or salt longer than 2^31 - 1 bytes. The password is
+ * read only inside `exposeWith`, and every U_j, every T_i, both keyed hashers
+ * and the working one are wiped before the key is answered; the digests on
+ * the way are wiped in the call that made them. The time taken depends on
+ * `iterations`, `dkLen` and the password's length past a block, all of which
+ * RFC 8018 treats as public, and on nothing of the password's bytes. The time
+ * is linear in `iterations` and nothing here bounds it, so a caller that takes
+ * the count from an untrusted peer (a SCRAM server's `i=`) must cap it first:
+ * 2^31 - 1 rounds is about 2^32 compressions.
+ */
+export const pbkdf2HmacSha256 = (
+  password: Secret<u8[]>,
+  salt: u8[],
+  iterations: i32,
+  length: i32
+): Secret<u8[]> | null => {
+  const request: Pbkdf2Request = { salt: salt, iterations: iterations, length: length }
+  const dk: u8[] | null = exposeWith(password, request, pbkdf2HmacSha256Exposed)
+  if (dk === null) {
+    return null
+  }
+  return secret(dk)
+}