@amritk/nish-x86_64-linux 0.17.0 → 0.20.0

package/std/crypto/aes.ts

@@ -57,6 +57,31 @@
  * the loops over blocks — is the discipline above and not a verified
  * property.
  *
+ * **The seams.** Four private functions do nearly all of the cipher's work,
+ * each called from exactly one place: `aesScheduleInto` (the key schedule),
+ * `aesBlockInto` (one block), `aesCtrInto` (GCTR over a run of bytes) and
+ * `ghashBlocksInto` (GHASH over a run of bytes). Each takes the arrays its
+ * caller passes, writes into them and allocates nothing the caller needs
+ * back, and its one caller checks every precondition it names first. That is
+ * what lets the compiler, natively, put each of those four calls behind a
+ * branch on the runtime's `nish_aes_hw` (`src/kernels.ts`, lowered in
+ * `src/emit.ts`): on a CPU with AES-NI and PCLMULQDQ, or the ARMv8 AES and
+ * PMULL instructions, the call goes to a kernel in `runtime/runtime-aes.c`
+ * that does no bounds checks of its own; on any other CPU, under
+ * `NISH_AES=soft`, on wasm32 and under Node, the body here runs (WP38 S5,
+ * `docs/wp38-simd.md`). The bodies are the bitsliced code, and keep their
+ * own defensive checks. The kernel keeps its own layout in a key's
+ * `roundKeys`, which a process only ever reads under the one answer
+ * `nish_aes_hw` gives it.
+ *
+ * What runs outside the seams, and so on the bitsliced code whichever way
+ * they go: `ghashLengths`, the last GHASH block of every tag, and so the end
+ * of J0's derivation for an IV that is not 12 bytes, multiplies with
+ * `ghashMultiply` on the state a seam left; and `aesGcmTag` folds E(K, J0)
+ * into it. A kernel therefore leaves the GHASH state in this module's own
+ * form, two big-endian words, and `tests/link/crypto_aes_agree` holds the two
+ * paths to the same bytes on the IVs that take that road.
+ *
  * **What is refused.** A key of any length but 16 or 32 bytes (AES-192 is out
  * of scope), a block or a sample that is not 16 bytes, an empty IV (SP 800-38D
  * §5.2.1.1 asks for at least one bit), a sealed input shorter than its tag, a
@@ -70,6 +95,8 @@
  * (`docs/wp26-stdlib.md` §3e).
  */
 
+import { wipe } from "nish:secret"
+
 /** The AES block, in bytes. */
 export const AES_BLOCK: i32 = 16
 /** GCM's tag, in bytes: this module makes and accepts only the full 128 bits. */
@@ -86,27 +113,53 @@ const AES_BATCH: i32 = 64
  * because the language has no private ones, and a key built or edited by hand
  * is not trusted: one whose shape is not what `aesKey` makes answers `null`
  * everywhere (`aesKeyUsable`), and one whose H is zero opens nothing
- * (`aesGcmOpen`).
+ * (`aesGcmOpen`). On the runtime kernels' path GHASH takes H and its powers
+ * from `roundKeys`, while `ghashLengths` and a non-12-byte IV's J0 take it
+ * from `h`; `aesKey` writes both from one schedule, so they agree. A key
+ * edited so that they disagree is outside the contract, and what it seals
+ * then depends on which path the process runs.
+ *
+ * Both are secret. A holder done with a key hands it to `aesKeyWipe`, whose
+ * volatile stores zero all of `roundKeys` (the kernels' tail of H's powers
+ * included) and `h`, and stand however dead the key is about to be.
  */
 export class AesKey {
   /** Nr: 10 for AES-128, 14 for AES-256. */
   rounds: i32 = 0
   /**
    * Round key `i` in the bitsliced layout, replicated into all four block
-   * lanes, as eight words from `8 * i`: `8 * (rounds + 1)` words in all.
+   * lanes, as eight words from `8 * i`: `8 * (rounds + 1)` words in all. In a
+   * native process that runs the runtime's AES kernels (the seams, above),
+   * the same words hold the kernels' layout instead, `runtime/runtime-aes.c`'s.
    */
   roundKeys: u64[]
-  /** H as a big-endian 128-bit number, high half. */
-  hHi: u64 = 0
-  /** H, low half. */
-  hLo: u64 = 0
+  /**
+   * H as a big-endian 128-bit number, two words: `h[0]` the high half and
+   * `h[1]` the low. An array rather than two scalar fields, so that
+   * `aesKeyWipe`'s volatile wipe reaches it.
+   */
+  h: u64[]
 
   constructor(rounds: i32, roundKeys: u64[]) {
     this.rounds = rounds
     this.roundKeys = roundKeys
+    this.h = new Array<u64>(2)
   }
 }
 
+/**
+ * Zeroes everything secret `key` holds — every word of `roundKeys`, the
+ * runtime kernels' powers of H after the schedule included, and `h` — with
+ * `wipe`'s volatile stores, which no optimiser removes however dead the key
+ * is about to be. `rounds` is not secret and stays. A wiped key seals under
+ * an all-zero schedule and, its H being zero, opens nothing (`aesGcmOpen`);
+ * `aesKeyInto` installs a new key into it.
+ */
+export const aesKeyWipe = (key: AesKey): void => {
+  wipe(key.roundKeys)
+  wipe(key.h)
+}
+
 /** A 16-bit pattern repeated into each of a word's four 16-bit lanes. */
 const aesLanes = (pattern: u64): u64 => {
   const two: u64 = pattern | (pattern << toU64(16))
@@ -439,17 +492,19 @@ export const aesBitslicedRound = (q: u64[], rk: u64[], at: i32): void => {
   aesAddRoundKey(q, rk, at)
 }
 
-/** The cipher (FIPS 197 §5.1) on the four blocks of `buf[0 .. 64)`, in place. `q` is scratch. */
-const aesEncryptBatch = (key: AesKey, buf: u8[], q: u64[]): void => {
-  const rk: u64[] = key.roundKeys
+/**
+ * The cipher (FIPS 197 §5.1) on the four blocks of `buf[0 .. 64)`, in place,
+ * under the bitsliced round keys `rk`. `q` is scratch.
+ */
+const aesEncryptBatch = (rk: u64[], rounds: i32, buf: u8[], q: u64[]): void => {
   aesPack(q, buf)
   aesAddRoundKey(q, rk, 0)
-  for (let round: i32 = 1; round < key.rounds; round++) {
+  for (let round: i32 = 1; round < rounds; round++) {
     aesBitslicedRound(q, rk, 8 * round)
   }
   aesSbox(q)
   aesShiftRows(q)
-  aesAddRoundKey(q, rk, 8 * key.rounds)
+  aesAddRoundKey(q, rk, 8 * rounds)
   aesUnpack(buf, q)
 }
 
@@ -496,12 +551,17 @@ const aesStore32 = (out: u8[], at: i32, w: u32): void => {
 }
 
 /**
- * KeyExpansion (FIPS 197 §5.2) for Nk = 4 or 8, then every round key
- * bitsliced and replicated into the four block lanes. `w` holds the words
- * big-endian, byte 0 of the key in the high byte of `w[0]`, as the standard
- * writes them. Branches only on the word number.
+ * The key-schedule seam: KeyExpansion (FIPS 197 §5.2) for Nk = 4 or 8 into
+ * `rk`, every round key bitsliced and replicated into the four block lanes.
+ * `w` holds the words big-endian, byte 0 of the key in the high byte of
+ * `w[0]`, as the standard writes them. Branches only on the word number.
+ *
+ * Its one caller, `aesKeyInto`, has checked that `key` is 16 or 32 bytes,
+ * that `rounds` is 10 or 14 to match, and that `rk` holds the
+ * `8 * (rounds + 1)` words this writes; the compiler may replace that call
+ * with a runtime kernel, which writes its own layout into the same words.
  */
-const aesExpand = (key: u8[], rounds: i32): u64[] => {
+const aesScheduleInto = (key: u8[], rounds: i32, rk: u64[]): void => {
   const nk: i32 = rounds - 6
   const total: i32 = (rounds + 1) * 4
   const w: u32[] = new Array<u32>(total)
@@ -528,8 +588,8 @@ const aesExpand = (key: u8[], rounds: i32): u64[] => {
     }
   }
   // Each round key, written into all four blocks of a batch and packed.
-  const rk: u64[] = new Array<u64>((rounds + 1) * 8)
   const buf: u8[] = new Array<u8>(AES_BATCH)
+  const rkLength: i32 = toI32(rk.length)
   for (let round: i32 = 0; round <= rounds; round++) {
     for (let k: i32 = 0; k < 4; k++) {
       for (let j: i32 = 0; j < 4; j++) {
@@ -538,10 +598,16 @@ const aesExpand = (key: u8[], rounds: i32): u64[] => {
     }
     aesPack(q, buf)
     for (let b: i32 = 0; b < 8; b++) {
-      rk[8 * round + b] = q[b]
+      const at: i32 = 8 * round + b
+      if (at < rkLength) {
+        rk[at] = q[b]
+      }
     }
   }
-  return rk
+  // The key's words, the last round key's bits and its bytes, all secret.
+  wipe(w)
+  wipe(q)
+  wipe(buf)
 }
 
 /**
@@ -583,27 +649,51 @@ const aesCopyPrefix = (dst: u8[], src: u8[], count: i32): void => {
 }
 
 /**
- * Whether `key` has the shape `aesKey` makes: 10 or 14 rounds and the
- * `(rounds + 1) * 8` round-key words the cipher reads. A key of another shape
- * could only have been built or edited by hand, and would index past its round
- * keys and panic, so every entry point answers `null` for it instead. The
- * branch is on the shape, which is not secret.
+ * Whether `key` has the shape `aesKey` makes: 10 or 14 rounds, the
+ * `(rounds + 1) * 8` round-key words the cipher reads and a two-word H. A key
+ * of another shape could only have been built or edited by hand, and would
+ * index past its arrays and panic, so every entry point answers `null` for it
+ * instead. The branch is on the shape, which is not secret.
  */
 const aesKeyUsable = (key: AesKey): boolean => {
   const rounds: i32 = key.rounds
   const words: i32 = (rounds + 1) * 8
-  return (rounds === 10 || rounds === 14) && toI32(key.roundKeys.length) === words
+  return (
+    (rounds === 10 || rounds === 14) && toI32(key.roundKeys.length) === words && toI32(key.h.length) === 2
+  )
 }
 
 /**
- * The first 16 bytes of `block` encrypted, in the first 16 bytes of a fresh
- * batch; the rest of the batch is the cipher of zeros and is not read.
+ * The single-block seam: `dst[0 .. 16) = E(K, src[0 .. 16))` under the round
+ * keys `rk`. The block goes through the first lane of a batch whose other
+ * three are zeros and not read, and the batch and the bitsliced state are
+ * wiped before they are released: the block may be H or E(K, J0).
+ *
+ * Its one caller, `aesEncryptOne`, has checked that `rk` is a schedule of
+ * `rounds` rounds and that `src` and `dst` each hold 16 bytes; the compiler
+ * may replace that call with a runtime kernel.
  */
-const aesEncryptOne = (key: AesKey, block: u8[]): u8[] => {
+const aesBlockInto = (rk: u64[], rounds: i32, src: u8[], dst: u8[]): void => {
   const buf: u8[] = new Array<u8>(AES_BATCH)
-  aesCopyPrefix(buf, block, AES_BLOCK)
-  aesEncryptBatch(key, buf, new Array<u64>(8))
-  return buf
+  const q: u64[] = new Array<u64>(8)
+  aesCopyPrefix(buf, src, AES_BLOCK)
+  aesEncryptBatch(rk, rounds, buf, q)
+  aesCopyPrefix(dst, buf, AES_BLOCK)
+  wipe(buf)
+  wipe(q)
+}
+
+/**
+ * The first 16 bytes of `src` encrypted into the first 16 of `dst`: the one
+ * call of `aesBlockInto`, so the checks its contract needs are made here. A
+ * key of the wrong shape, or a block shorter than 16 bytes, leaves `dst` as it
+ * was; no caller passes one.
+ */
+const aesEncryptOne = (key: AesKey, src: u8[], dst: u8[]): void => {
+  if (!aesKeyUsable(key) || toI32(src.length) < AES_BLOCK || toI32(dst.length) < AES_BLOCK) {
+    return
+  }
+  aesBlockInto(key.roundKeys, key.rounds, src, dst)
 }
 
 /**
@@ -617,10 +707,10 @@ export const aesKey = (key: u8[]): AesKey | null => {
     return null
   }
   const rounds: i32 = length === 16 ? 10 : 14
-  const expanded: AesKey = new AesKey(rounds, aesExpand(key, rounds))
-  const buf: u8[] = aesEncryptOne(expanded, [])
-  expanded.hHi = aesLoad64(buf, 0, 8)
-  expanded.hLo = aesLoad64(buf, 8, 16)
+  const expanded: AesKey = new AesKey(rounds, new Array<u64>((rounds + 1) * 8))
+  if (!aesKeyInto(key, expanded)) {
+    return null
+  }
   return expanded
 }
 
@@ -630,15 +720,23 @@ export const aesKey = (key: u8[]): AesKey | null => {
  * 0^128) for GCM, written into `out`, whose `roundKeys` must already be the
  * `8 * (rounds + 1)` words that key length needs (88 or 120). It answers
  * whether it did; a key of another length, or a schedule array of the wrong
- * size for it, answers `false` and leaves `out` as it was.
+ * size for it (or an `h` that is not two words), answers `false` and leaves
+ * `out` as it was.
  *
  * `aesKey` makes a fresh `AesKey` and stores its schedule into it, which no
  * arena scope may be put around; this stores numbers only, so a caller that
  * keeps one `AesKey` per connection installs every key inside a `using a =
  * arena()` block and leaves the arena where it was. The schedule and H are
- * secret: the caller wipes `out` when it is done with the key. The working
- * copy of the schedule is zeroed before it is released, by stores that stand
- * no better than `aesKey`'s own temporaries do.
+ * secret: the caller hands `out` to `aesKeyWipe` when it is done with the
+ * key. The schedule is written straight into `out.roundKeys`, and the
+ * working copies the bitsliced schedule and the block H passes through are
+ * wiped with `wipe`'s volatile stores before they are released. On a CPU
+ * that runs the runtime's kernels (the seams, in the module docs) those
+ * copies are the kernels' own, in `runtime/runtime-aes.c`, and what they
+ * leave in vector registers no wipe here reaches.
+ *
+ * `aesKey` makes its key through this, so this is the one call of
+ * `aesScheduleInto`, and the checks its contract needs are made here.
  */
 export const aesKeyInto = (key: u8[], out: AesKey): boolean => {
   const length: i32 = toI32(key.length)
@@ -647,22 +745,17 @@ export const aesKeyInto = (key: u8[], out: AesKey): boolean => {
   }
   const rounds: i32 = length === 16 ? 10 : 14
   const roundKeys: u64[] = out.roundKeys
-  const words: i32 = (rounds + 1) * 8
-  if (toI32(roundKeys.length) !== words) {
+  const hash: u64[] = out.h
+  if (toI32(roundKeys.length) !== (rounds + 1) * 8 || toI32(hash.length) !== 2) {
     return false
   }
-  const expanded: u64[] = aesExpand(key, rounds)
-  for (let i: i32 = 0; i < toI32(roundKeys.length) && i < toI32(expanded.length); i++) {
-    roundKeys[i] = expanded[i]
-    expanded[i] = 0
-  }
+  aesScheduleInto(key, rounds, roundKeys)
   out.rounds = rounds
-  const buf: u8[] = aesEncryptOne(out, [])
-  out.hHi = aesLoad64(buf, 0, 8)
-  out.hLo = aesLoad64(buf, 8, 16)
-  for (let i: i32 = 0; i < toI32(buf.length); i++) {
-    buf[i] = 0
-  }
+  const h: u8[] = new Array<u8>(AES_BLOCK)
+  aesEncryptOne(out, new Array<u8>(AES_BLOCK), h)
+  hash[0] = aesLoad64(h, 0, 8)
+  hash[1] = aesLoad64(h, 8, 16)
+  wipe(h)
   return true
 }
 
@@ -672,7 +765,7 @@ export const aesEncryptBlock = (key: AesKey, block: u8[]): u8[] | null => {
     return null
   }
   const out: u8[] = new Array<u8>(AES_BLOCK)
-  aesCopyPrefix(out, aesEncryptOne(key, block), AES_BLOCK)
+  aesEncryptOne(key, block, out)
   return out
 }
 
@@ -685,8 +778,10 @@ export const aesHeaderMask = (key: AesKey, sample: u8[]): u8[] | null => {
   if (!aesKeyUsable(key) || toI32(sample.length) !== AES_BLOCK) {
     return null
   }
+  const block: u8[] = new Array<u8>(AES_BLOCK)
+  aesEncryptOne(key, sample, block)
   const mask: u8[] = new Array<u8>(5)
-  aesCopyPrefix(mask, aesEncryptOne(key, sample), 5)
+  aesCopyPrefix(mask, block, 5)
   return mask
 }
 
@@ -798,10 +893,17 @@ export const ghashMultiply = (y: u64[], hHi: u64, hLo: u64): void => {
 }
 
 /**
- * Absorbs `data[0 .. length)` into the GHASH state `y`, 16 bytes at a time,
- * the last block padded with zeros (SP 800-38D §6.4, §7.1 step 5).
+ * The GHASH seam: absorbs `data[0 .. length)` into the GHASH state `y` under
+ * H = `hHi:hLo`, 16 bytes at a time, the last block padded with zeros
+ * (SP 800-38D §6.4, §7.1 step 5). `_rk` is the key's round keys, which this
+ * body does not read: a runtime kernel may keep powers of H after its own
+ * schedule there.
+ *
+ * Its one caller, `ghashUpdate`, has checked that `y` holds two words, that
+ * `0 <= length <= data.length` and that `_rk` is a whole schedule; the
+ * compiler may replace that call with a runtime kernel.
  */
-const ghashUpdate = (y: u64[], key: AesKey, data: u8[], length: i32): void => {
+const ghashBlocksInto = (y: u64[], hHi: u64, hLo: u64, _rk: u64[], data: u8[], length: i32): void => {
   if (toI32(y.length) < 2) {
     return
   }
@@ -812,21 +914,35 @@ const ghashUpdate = (y: u64[], key: AesKey, data: u8[], length: i32): void => {
     const at: i32 = block * 16
     y[0] = y[0] ^ aesLoad64(data, at, length)
     y[1] = y[1] ^ aesLoad64(data, at + 8, length)
-    ghashMultiply(y, key.hHi, key.hLo)
+    ghashMultiply(y, hHi, hLo)
+  }
+}
+
+/**
+ * Absorbs `data[0 .. length)` into the GHASH state `y` under `key`'s H: the
+ * one call of `ghashBlocksInto`, so the checks its contract needs are made
+ * here. A state, length or key that fails them leaves `y` as it was; no
+ * caller passes one.
+ */
+const ghashUpdate = (y: u64[], key: AesKey, data: u8[], length: i32): void => {
+  if (toI32(y.length) < 2 || length < 0 || length > toI32(data.length) || !aesKeyUsable(key)) {
+    return
   }
+  ghashBlocksInto(y, key.h[0], key.h[1], key.roundKeys, data, length)
 }
 
 /** The last GHASH block: the AAD's and the ciphertext's lengths in bits, 64 bits each. */
 const ghashLengths = (y: u64[], key: AesKey, aadLength: i32, textLength: i32): void => {
   y[0] = y[0] ^ (toU64(aadLength) << toU64(3))
   y[1] = y[1] ^ (toU64(textLength) << toU64(3))
-  ghashMultiply(y, key.hHi, key.hLo)
+  ghashMultiply(y, key.h[0], key.h[1])
 }
 
 /**
  * The pre-counter block J0 (SP 800-38D §7.1 step 2): a 12-byte IV followed by
  * the 32-bit counter 1, or for any other length GHASH of the IV padded to a
- * block and followed by its length in bits.
+ * block and followed by its length in bits. That GHASH, with the IV, says
+ * something of H, so the GHASH state is wiped here and the caller wipes J0.
  */
 const aesGcmJ0 = (key: AesKey, iv: u8[]): u8[] => {
   const length: i32 = toI32(iv.length)
@@ -841,6 +957,8 @@ const aesGcmJ0 = (key: AesKey, iv: u8[]): u8[] => {
   ghashLengths(y, key, 0, length)
   aesStore64(j0, 0, y[0])
   aesStore64(j0, 8, y[1])
+  // GHASH of the IV under H: with the IV, it says something of H.
+  wipe(y)
   return j0
 }
 
@@ -856,12 +974,20 @@ const aesGcmLengthFits = (length: i32): boolean =>
   (toI64(length) + toI64(15)) >> toI64(4) <= (toI64(1) << toI64(32)) - toI64(2)
 
 /**
- * GCTR (SP 800-38D §6.5) from inc32(J0): `dst[i] = src[i] ⊕ keystream[i]` for
- * `i` below `length`, four blocks per pass of the cipher. The counter is the
- * last four bytes of J0 as a big-endian `u32` and wraps modulo 2^32, as
- * inc32 does, while the first twelve bytes stay as they are.
+ * The GCTR seam (SP 800-38D §6.5) from inc32(J0): `dst[i] = src[i] ⊕
+ * keystream[i]` for `i` below `length`, four blocks per pass of the cipher,
+ * under the round keys `rk`. The counter is the last four bytes of J0 as a
+ * big-endian `u32` and wraps modulo 2^32, as inc32 does, while the first
+ * twelve bytes stay as they are. `dst` may be `src`: each byte is read before
+ * it is written. The batch of keystream and the bitsliced state are wiped
+ * before it returns.
+ *
+ * Its one caller, `aesGcmCtr`, has checked that `rk` is a schedule of
+ * `rounds` rounds, that `j0` is 16 bytes and that `0 <= length` and `length`
+ * is within both `src` and `dst`; the compiler may replace that call with a
+ * runtime kernel.
  */
-const aesGcmCtr = (key: AesKey, j0: u8[], src: u8[], dst: u8[], length: i32): void => {
+const aesCtrInto = (rk: u64[], rounds: i32, j0: u8[], src: u8[], dst: u8[], length: i32): void => {
   if (toI32(j0.length) < 16) {
     return
   }
@@ -870,6 +996,7 @@ const aesGcmCtr = (key: AesKey, j0: u8[], src: u8[], dst: u8[], length: i32): vo
   const q: u64[] = new Array<u64>(8)
   const srcLength: i32 = toI32(src.length)
   const dstLength: i32 = toI32(dst.length)
+  const bufLength: i32 = toI32(buf.length)
   // Counted in batches, like `ghashUpdate`'s blocks, so `base` never passes `length`.
   const batches: i32 = (length >> 6) + ((length & 63) !== 0 ? 1 : 0)
   for (let batch: i32 = 0; batch < batches; batch++) {
@@ -880,29 +1007,59 @@ const aesGcmCtr = (key: AesKey, j0: u8[], src: u8[], dst: u8[], length: i32): vo
       }
       aesStore32(buf, 16 * k + 12, counter + toU32((base >> 4) + k + 1))
     }
-    aesEncryptBatch(key, buf, q)
-    for (let j: i32 = 0; j < AES_BATCH && j < toI32(buf.length); j++) {
-      const at: i32 = base + j
-      if (at >= 0 && at < length && at < srcLength && at < dstLength) {
+    aesEncryptBatch(rk, rounds, buf, q)
+    // Every bound is in the loop's condition, where LLVM folds them into one
+    // trip count and vectorises the XOR; the same tests inside the body, once
+    // `aesGcmCtr`'s checks were inlined above them, became three compares a
+    // byte and cost seal and open 6%. The body's test is only for the bounds
+    // prover, and is always true.
+    for (let at: i32 = base; at < length && at < srcLength && at < dstLength && at - base < bufLength; at++) {
+      const j: i32 = at - base
+      if (at >= 0 && j >= 0 && j < bufLength) {
         dst[at] = src[at] ^ buf[j]
       }
     }
   }
+  // The last batch's keystream and its bitsliced state, both secret.
+  wipe(buf)
+  wipe(q)
+}
+
+/**
+ * GCTR from inc32(J0) over `src[0 .. length)` into `dst` under `key`: the one
+ * call of `aesCtrInto`, so the checks its contract needs are made here. A
+ * key, J0 or length that fails them leaves `dst` as it was; no caller passes
+ * one.
+ */
+const aesGcmCtr = (key: AesKey, j0: u8[], src: u8[], dst: u8[], length: i32): void => {
+  if (
+    !aesKeyUsable(key) ||
+    toI32(j0.length) !== AES_BLOCK ||
+    length < 0 ||
+    length > toI32(src.length) ||
+    length > toI32(dst.length)
+  ) {
+    return
+  }
+  aesCtrInto(key.roundKeys, key.rounds, j0, src, dst, length)
 }
 
 /**
  * E(K, J0) ⊕ S, GCM's tag (SP 800-38D §7.1 step 6), into `y` (zero, two
  * words) as two big-endian words: S is the GHASH of the AAD and the
- * ciphertext `text[0 .. textLength)`.
+ * ciphertext `text[0 .. textLength)`. E(K, J0)'s block is wiped once it is
+ * folded in.
  */
 const aesGcmTag = (y: u64[], key: AesKey, j0: u8[], aad: u8[], text: u8[], textLength: i32): void => {
   const aadLength: i32 = toI32(aad.length)
   ghashUpdate(y, key, aad, aadLength)
   ghashUpdate(y, key, text, textLength)
   ghashLengths(y, key, aadLength, textLength)
-  const mask: u8[] = aesEncryptOne(key, j0)
+  const mask: u8[] = new Array<u8>(AES_BLOCK)
+  aesEncryptOne(key, j0, mask)
   y[0] = y[0] ^ aesLoad64(mask, 0, 16)
   y[1] = y[1] ^ aesLoad64(mask, 8, 16)
+  wipe(mask)
 }
 
 /**
@@ -937,6 +1094,7 @@ export const aesGcmSeal = (key: AesKey, iv: u8[], aad: u8[], plaintext: u8[]): u
   aesGcmTag(tag, key, j0, aad, out, length)
   aesStore64(out, length, tag[0])
   aesStore64(out, length + 8, tag[1])
+  wipe(j0)
   return out
 }
 
@@ -972,11 +1130,15 @@ export const aesGcmOpen = (key: AesKey, iv: u8[], aad: u8[], sealed: u8[]): u8[]
   // authenticate any ciphertext and AAD. Only a key built or edited by hand
   // has it (for one from `aesKey` the chance is 2^-128), and such a key opens
   // nothing. H is secret, so this is folded into the mask, not branched on.
-  const hashKeySet: u64 = ~ctEq(key.hHi | key.hLo, toU64(0))
-  if ((same & hashKeySet) === toU64(0)) {
-    return null
+  const hashKeySet: u64 = ~ctEq(key.h[0] | key.h[1], toU64(0))
+  wipe(tag)
+  let out: u8[] | null = null
+  if ((same & hashKeySet) !== toU64(0)) {
+    const opened: u8[] = new Array<u8>(length)
+    aesGcmCtr(key, j0, sealed, opened, length)
+    out = opened
   }
-  const out: u8[] = new Array<u8>(length)
-  aesGcmCtr(key, j0, sealed, out, length)
+  // One wipe both paths reach, so the -O2 count sees it go missing.
+  wipe(j0)
   return out
 }

package/std/crypto/chacha20poly1305.ts

@@ -22,6 +22,14 @@
  * array so that the words stay in registers, and, as RFC 8439 §3 suggests,
  * the state is built once per message and only its counter moves per block.
  *
+ * **What is wiped.** Every array a call fills from the key — the ChaCha20
+ * state, the keystream block, the Poly1305 one-time key, its `r` and the
+ * accumulator, and on open the tag computed for comparison — is zeroed with
+ * `wipe`'s volatile stores before the call returns, on the refusal path too,
+ * so that no optimiser can drop the zeroing of an array about to die. The
+ * caller's own key, and the words the rounds keep in registers, are not this
+ * module's to reach.
+ *
  * **Poly1305** keeps its accumulator and its key `r` as five limbs of 26 bits
  * each in `u64`, so limb `i` holds bits `26i` to `26i + 25` of a 130-bit
  * number. RFC 8439 §3 asks for constant-time arithmetic without saying how;
@@ -54,6 +62,8 @@
  * namespace (`docs/wp26-stdlib.md` §3e).
  */
 
+import { wipe } from "nish:secret"
+
 /** The length of a ChaCha20 key in bytes (RFC 8439 §2.3). */
 export const CHACHA20_KEY_SIZE: i32 = 32
 
@@ -240,7 +250,8 @@ const chacha20Core = (state: u32[], out: u32[]): void => {
  * `dst[dstAt + i] = src[srcAt + i] ^ keystream` for `len` bytes, the keystream
  * running from `state`'s counter on, and the counter left one past the last
  * block used (RFC 8439 §2.4). The caller has checked every window and that
- * the counter does not wrap.
+ * the counter does not wrap. The last keystream block is wiped before it
+ * returns; `state` is the caller's to wipe.
  */
 const chacha20XorInto = (state: u32[], src: u8[], srcAt: i32, len: i32, dst: u8[], dstAt: i32): void => {
   const keystream: u32[] = new Array<u32>(16)
@@ -266,6 +277,7 @@ const chacha20XorInto = (state: u32[], src: u8[], srcAt: i32, len: i32, dst: u8[
     }
     done = done + take
   }
+  wipe(keystream)
 }
 
 /**
@@ -329,7 +341,9 @@ export const chacha20Block = (key: u8[], counter: u32, nonce: u8[]): u8[] | null
     return null
   }
   const out: u8[] = new Array<u8>(CHACHA20_BLOCK_SIZE)
-  chacha20XorInto(chacha20State(key, counter, nonce, 0), out, 0, CHACHA20_BLOCK_SIZE, out, 0)
+  const state: u32[] = chacha20State(key, counter, nonce, 0)
+  chacha20XorInto(state, out, 0, CHACHA20_BLOCK_SIZE, out, 0)
+  wipe(state)
   return out
 }
 
@@ -350,7 +364,9 @@ export const chacha20 = (key: u8[], counter: u32, nonce: u8[], data: u8[]): u8[]
     return null
   }
   const out: u8[] = new Array<u8>(len)
-  chacha20XorInto(chacha20State(key, counter, nonce, 0), data, 0, len, out, 0)
+  const state: u32[] = chacha20State(key, counter, nonce, 0)
+  chacha20XorInto(state, data, 0, len, out, 0)
+  wipe(state)
   return out
 }
 
@@ -566,6 +582,8 @@ export const poly1305 = (key: u8[], msg: u8[]): u8[] | null => {
   poly1305Absorb(h, r, msg, 0, toI32(msg.length), false)
   const tag: u8[] = new Array<u8>(POLY1305_TAG_SIZE)
   poly1305Finish(h, key, tag)
+  wipe(h)
+  wipe(r)
   return tag
 }
 
@@ -579,7 +597,10 @@ export const poly1305KeyGen = (key: u8[], nonce: u8[]): u8[] | null => {
   if (toI32(key.length) !== CHACHA20_KEY_SIZE || toI32(nonce.length) !== CHACHA20POLY1305_NONCE_SIZE) {
     return null
   }
-  return chacha20Poly1305Setup(chacha20State(key, 0, nonce, 0))
+  const state: u32[] = chacha20State(key, 0, nonce, 0)
+  const polyKey: u8[] = chacha20Poly1305Setup(state)
+  wipe(state)
+  return polyKey
 }
 
 /**
@@ -602,6 +623,8 @@ const chacha20Poly1305Tag = (polyKey: u8[], aad: u8[], ct: u8[], at: i32, len: i
   poly1305Block(h, r, lengths, 0, toU64(POLY1305_HIGH_BIT))
   const tag: u8[] = new Array<u8>(POLY1305_TAG_SIZE)
   poly1305Finish(h, polyKey, tag)
+  wipe(h)
+  wipe(r)
   return tag
 }
 
@@ -664,6 +687,8 @@ export const chacha20Poly1305Seal = (key: u8[], nonce: u8[], aad: u8[], plaintex
   for (let i: i32 = 0; i < toI32(tag.length); i++) {
     sealed[len + i] = tag[i]
   }
+  wipe(state)
+  wipe(polyKey)
   return sealed
 }
 
@@ -694,11 +719,18 @@ export const chacha20Poly1305Open = (key: u8[], nonce: u8[], aad: u8[], sealed:
   const tag: u8[] = chacha20Poly1305Tag(polyKey, aad, sealed, 0, len)
   // The one branch on the comparison, and it is on the answer the caller is
   // about to learn anyway.
-  if (chacha20Poly1305TagMatch(tag, sealed, len) === 0) {
-    return null
+  const match: u32 = chacha20Poly1305TagMatch(tag, sealed, len)
+  wipe(polyKey)
+  wipe(tag)
+  let plaintext: u8[] | null = null
+  if (match !== 0) {
+    const opened: u8[] = new Array<u8>(len)
+    chacha20XorInto(state, sealed, 0, len, opened, 0)
+    plaintext = opened
   }
-  const plaintext: u8[] = new Array<u8>(len)
-  chacha20XorInto(state, sealed, 0, len, plaintext, 0)
+  // One wipe both paths reach, rather than one on each, so that each is a
+  // store of its own the -O2 count can see go missing.
+  wipe(state)
   return plaintext
 }
 
@@ -714,6 +746,8 @@ export const chacha20HeaderMask = (hpKey: u8[], sample: u8[]): u8[] | null => {
     return null
   }
   const mask: u8[] = new Array<u8>(CHACHA20_HEADER_MASK_SIZE)
-  chacha20XorInto(chacha20State(hpKey, chacha20Word(sample, 0), sample, 4), mask, 0, 5, mask, 0)
+  const state: u32[] = chacha20State(hpKey, chacha20Word(sample, 0), sample, 4)
+  chacha20XorInto(state, mask, 0, 5, mask, 0)
+  wipe(state)
   return mask
 }