@amritk/nish-x86_64-linux 0.18.0 → 0.21.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/base64url.ts

@@ -6,6 +6,15 @@
  * text already says how many bytes the last group holds (RFC 4648 §3.2 lets a
  * specification that knows its lengths drop the padding, and RFC 7515 §2 does).
  *
+ * The module also holds RFC 4648 §4 standard base64 — `+` and `/`, padded with
+ * `=` — as `base64StdPadEncode` and `base64StdPadDecode`, for PEM
+ * (`nish/crypto/x509`) and SCRAM (`nish/net/postgres`). It is as strict and as
+ * constant-time as the URL alphabet, by the same masks, and it refuses a `=`
+ * anywhere but the last one or two characters of a text whose length is a
+ * multiple of four. They are not `nish/base64`'s `base64Encode`, which encodes
+ * only, indexes its alphabet and is for pixels; the `StdPad` names keep the two
+ * apart in the program's one namespace.
+ *
  * **Decoding is strict, so that each byte string has exactly one spelling.**
  * `base64urlDecode` answers `null` for a `=` anywhere, for any character outside
  * the alphabet (whitespace included), for a length of 1 mod 4 — six bits, not a
@@ -169,3 +178,119 @@ export const base64urlDecode = (text: string): u8[] | null => {
   }
   return out
 }
+
+// ---------------------------------------------------------------------------
+// Standard base64 (RFC 4648 §4): `+` and `/`, padded with `=`
+// ---------------------------------------------------------------------------
+
+/**
+ * The standard-alphabet character for the sextet `v`: the same steps as
+ * `base64urlCharOf` until 62, which lands on `+` and 63 on `/`.
+ */
+const base64StdPadCharOf = (v: i32): i32 =>
+  toI32(
+    65 +
+      toU32(v) +
+      toU32(base64urlRangeMask(v, 26, 63) & 6) -
+      toU32(base64urlRangeMask(v, 52, 63) & 75) -
+      toU32(base64urlRangeMask(v, 62, 63) & 15) +
+      toU32(base64urlRangeMask(v, 63, 63) & 3)
+  )
+
+/** The sextet the byte `c` stands for in standard base64, or `-1` when it is not in the alphabet. */
+const base64StdPadSextetOf = (c: i32): i32 => {
+  const upper: i32 = base64urlRangeMask(c, 65, 90)
+  const lower: i32 = base64urlRangeMask(c, 97, 122)
+  const digit: i32 = base64urlRangeMask(c, 48, 57)
+  const plus: i32 = base64urlRangeMask(c, 43, 43)
+  const slash: i32 = base64urlRangeMask(c, 47, 47)
+  const value: i32 =
+    (upper & toI32(toU32(c) - 65)) |
+    (lower & toI32(toU32(c) - 71)) |
+    (digit & toI32(toU32(c) + 4)) |
+    (plus & 62) |
+    (slash & 63)
+  return value | ~(upper | lower | digit | plus | slash)
+}
+
+/**
+ * `data` in padded standard base64, as one line: PEM's body, and SCRAM's
+ * nonces, salts and proofs (RFC 5802 §5.1). One `=` closes a final group of
+ * two bytes, two a group of one. An array longer than 2^31 - 1 bytes panics.
+ */
+export const base64StdPadEncode = (data: u8[]): string => {
+  if (data.length > 2147483647) {
+    panic("base64StdPadEncode: more than 2^31 - 1 bytes")
+  }
+  const parts: string[] = []
+  let acc: i32 = 0
+  let bits: u32 = 0
+  for (let k: i32 = 0; k < toI32(data.length); k++) {
+    acc = ((acc << 8) | toI32(data[k])) & 0xfff
+    bits += 8
+    while (bits >= 6) {
+      bits -= 6
+      parts.push(String.fromCharCode(base64StdPadCharOf((acc >> toI32(bits)) & 63)))
+    }
+  }
+  if (bits > 0) {
+    parts.push(String.fromCharCode(base64StdPadCharOf((acc << toI32(6 - bits)) & 63)))
+  }
+  const tail: i32 = toI32(data.length) % 3
+  if (tail > 0) {
+    parts.push(tail === 1 ? "==" : "=")
+  }
+  return parts.join("")
+}
+
+/**
+ * The bytes of padded standard base64 `text`, or `null` unless it is the one
+ * canonical spelling of them: a whole number of four-character groups, `=`
+ * only as the last one or two characters, every other character in the
+ * alphabet, and the bits the padding leaves over all zero (RFC 4648 §3.5).
+ * The empty text is the spelling of no bytes (RFC 4648 §10). Where the padding
+ * is depends on the length alone; the characters themselves are read by masks
+ * and judged once, after the last.
+ */
+export const base64StdPadDecode = (text: string): u8[] | null => {
+  if (text.length > 2147483647) {
+    return null
+  }
+  const n: i32 = toI32(text.length)
+  if ((n & 3) !== 0) {
+    return null
+  }
+  let pad: i32 = 0
+  if (n > 0 && toI32(text.charCodeAt(n - 1)) === 61) {
+    pad = toI32(text.charCodeAt(n - 2)) === 61 ? 2 : 1
+  }
+  const chars: i32 = n - pad
+  const out: u8[] = new Array<u8>((n >> 2) * 3 - pad)
+  const outLen: i32 = toI32(out.length)
+  let bad: i32 = 0
+  let acc: i32 = 0
+  let bits: i32 = 0
+  let j: i32 = 0
+  // The padding is past `chars` and is not data; which positions those are is
+  // a fact about the length. A `=` before them is outside the alphabet.
+  for (let k: i32 = 0; k < chars && k < toI32(text.length); k++) {
+    const v: i32 = base64StdPadSextetOf(toI32(text.charCodeAt(k)))
+    bad = bad | (v >> 31)
+    acc = ((acc << 6) | (v & 63)) & 0xfff
+    bits += 6
+    if (bits >= 8) {
+      bits -= 8
+      // Always true — `out` was sized from the same length — and written so
+      // the store keeps no bounds check.
+      if (j >= 0 && j < outLen) {
+        out[j] = toU8((acc >> bits) & 255)
+      }
+      j++
+    }
+  }
+  bad = bad | (acc & ((1 << bits) - 1))
+  if (bad !== 0) {
+    return null
+  }
+  return out
+}