@amritk/nish 0.12.0 → 0.14.0

package/std/crypto/base64url.ts

@@ -0,0 +1,145 @@
+/**
+ * `nish/crypto/base64url` — RFC 4648 §5 base64url, unpadded, as JWS and the
+ * relay's grants spell a key or a tag inside a URL or a header.
+ *
+ * The alphabet is `A-Z a-z 0-9 - _`, and there is no `=`: the length of the
+ * 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).
+ *
+ * **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
+ * byte — and for a final character whose unused low bits are not zero (RFC 4648
+ * §3.5). A lenient decoder would let `AB` and `AA` both mean `00`, and a token
+ * compared or cached by its text would then have two identities.
+ *
+ * **Neither direction indexes or branches on the data.** What is encoded here
+ * is usually a key, a nonce or a MAC, and a lookup table indexed by a secret
+ * sextet leaves its trace in the cache. So a sextet becomes a character, and a
+ * character a sextet, by arithmetic on range masks: `(lo - 1 - c) & (c - hi - 1)`
+ * is negative exactly when `lo <= c <= hi`, and an arithmetic shift by 31 turns
+ * that sign into an all-ones or all-zeros mask. A malformed character is not
+ * refused where it is found either: the verdict is ORed into one word and read
+ * once, after the whole text. The text's length is public and is tested first.
+ *
+ * Private helpers share the importing program's flat symbol namespace
+ * (`docs/wp26-stdlib.md` §3e), which is why each one carries the module's name.
+ */
+
+/**
+ * All ones when `lo <= c <= hi`, else zero, without a branch. `c` is a byte or
+ * a sextet, so neither subtraction can overflow.
+ */
+const base64urlRangeMask = (c: i32, lo: i32, hi: i32): i32 => ((lo - 1 - c) & (c - hi - 1)) >> 31
+
+/**
+ * The URL-alphabet character for the sextet `v` (`0 <= v <= 63`).
+ *
+ * It starts from `'A' + v` and adds, for each range `v` has passed, the step
+ * from the previous range's first character to this one's: 26 lands on `a`, 52
+ * on `0`, 62 on `-` and 63 on `_`.
+ */
+const base64urlCharOf = (v: i32): i32 =>
+  65 +
+  v +
+  (base64urlRangeMask(v, 26, 63) & 6) -
+  (base64urlRangeMask(v, 52, 63) & 75) -
+  (base64urlRangeMask(v, 62, 63) & 13) +
+  (base64urlRangeMask(v, 63, 63) & 49)
+
+/**
+ * The sextet the byte `c` stands for, or `-1` when `c` is not in the alphabet.
+ * Each range contributes its value under its own mask, and a byte in none of
+ * them has every bit set by the final OR.
+ */
+const base64urlSextetOf = (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 dash: i32 = base64urlRangeMask(c, 45, 45)
+  const underscore: i32 = base64urlRangeMask(c, 95, 95)
+  const value: i32 =
+    (upper & (c - 65)) | (lower & (c - 71)) | (digit & (c + 4)) | (dash & 62) | (underscore & 63)
+  return value | ~(upper | lower | digit | dash | underscore)
+}
+
+/**
+ * `data` as unpadded base64url: four characters per three bytes, and two or
+ * three for a short final group.
+ *
+ * Bytes go into a bit accumulator eight at a time and come out six at a time,
+ * so one index walks the input and the only branches are on how many bits are
+ * waiting — which depends on the position, never on the bytes.
+ */
+export const base64urlEncode = (data: u8[]): string => {
+  const parts: string[] = []
+  let acc: i32 = 0
+  let bits: i32 = 0
+  for (let k: i32 = 0; k < toI32(data.length); k++) {
+    // At most four bits wait from the bytes before, so twelve are live here;
+    // the mask keeps the accumulator from growing without bound.
+    acc = ((acc << 8) | toI32(data[k])) & 0xfff
+    bits += 8
+    while (bits >= 6) {
+      bits -= 6
+      parts.push(String.fromCharCode(base64urlCharOf((acc >> bits) & 63)))
+    }
+  }
+  // Two or four bits of a final byte are left: they go out as the high bits of
+  // one more sextet, filled out with zeros.
+  if (bits > 0) {
+    parts.push(String.fromCharCode(base64urlCharOf((acc << (6 - bits)) & 63)))
+  }
+  return parts.join("")
+}
+
+/**
+ * The bytes `text` spells in unpadded base64url, or `null` when it is not the
+ * one canonical spelling of any byte string — see the module comment for the
+ * four refusals.
+ *
+ * The same accumulator as `base64urlEncode`, run the other way: six bits in per
+ * character, eight out per byte.
+ */
+export const base64urlDecode = (text: string): u8[] | null => {
+  const n: i32 = toI32(text.length)
+  const tail: i32 = n & 3
+  // Six bits cannot finish a byte, so a single character after the last full
+  // group spells nothing.
+  if (tail === 1) {
+    return null
+  }
+  // Three bytes per full group of four, and one fewer than the characters in a
+  // short final group; `n * 3 / 4` would overflow for a text over 700 MB.
+  const out: u8[] = new Array<u8>((n >> 2) * 3 + (tail === 0 ? 0 : tail - 1))
+  const outLen: i32 = toI32(out.length)
+  // All ones once any character is outside the alphabet (its sextet of `-1`
+  // shifted right by 31), and non-zero once the text ends on a bit that
+  // encodes no byte.
+  let bad: i32 = 0
+  let acc: i32 = 0
+  let bits: i32 = 0
+  let j: i32 = 0
+  for (let k: i32 = 0; k < n; k++) {
+    const v: i32 = base64urlSextetOf(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 — but written out
+      // so that the store keeps no bounds check.
+      if (j >= 0 && j < outLen) {
+        out[j] = toU8((acc >> bits) & 255)
+      }
+      j++
+    }
+  }
+  // The two or four bits left over belong to no byte, and must be zero so that
+  // `AA` is the only spelling of a zero byte and `AB` is refused (RFC 4648 §3.5).
+  bad = bad | (acc & ((1 << bits) - 1))
+  if (bad !== 0) {
+    return null
+  }
+  return out
+}

package/std/crypto/ct.ts

@@ -0,0 +1,64 @@
+/**
+ * `nish/crypto/ct` — comparing secrets without telling the clock where they differ.
+ *
+ * An `===` loop over two MACs stops at the first differing byte, so the time it
+ * takes says how many leading bytes an attacker already guessed right, and a
+ * tag can be recovered one byte at a time. These functions read every byte of
+ * the window whatever it holds: each pair is XORed, the differences are ORed
+ * into one accumulator, and that accumulator is tested once, after the loop.
+ *
+ * What is *not* secret is checked first and may branch: the two lengths, and
+ * whether a window lies inside its array. A caller comparing a received tag
+ * against an expected one already knows both lengths, so refusing a mismatch
+ * early leaks nothing the attacker did not send.
+ *
+ * The names are `timingSafeEqual*`, after Node's `crypto.timingSafeEqual`,
+ * rather than `ctEq`: that one is reserved for the builtin WP34 N6 will add,
+ * together with the disassembly check that proves the loop stays branch-free
+ * after LLVM has seen it. Until then this is the discipline and not a proof.
+ */
+
+/**
+ * Whether `a` and `b` hold the same bytes, reading all of them.
+ *
+ * Arrays of different lengths answer `false` at once, because a length is
+ * public; arrays of one length are compared in full, with no early exit.
+ */
+export const timingSafeEqual = (a: u8[], b: u8[]): boolean => {
+  const n: i32 = toI32(a.length)
+  if (n !== toI32(b.length)) {
+    return false
+  }
+  let diff: i32 = 0
+  // Bounded by both lengths, which are equal here, so the prover drops both
+  // bounds checks rather than trusting the comparison above.
+  for (let i: i32 = 0; i < n && i < toI32(b.length); i++) {
+    diff = diff | toI32(a[i] ^ b[i])
+  }
+  return diff === 0
+}
+
+/**
+ * Whether the `len` bytes of `a` from `aOff` equal the `len` bytes of `b` from
+ * `bOff`, reading all of them.
+ *
+ * A window that does not lie inside its array — a negative offset or length,
+ * or `off + len` past the end — answers `false` instead of panicking on the
+ * first out-of-range read. That is a decision about the caller's position: a
+ * verifier handed a truncated record should say "not equal", not take the
+ * process down, and the bounds are public, so testing them first is safe.
+ */
+export const timingSafeEqualAt = (a: u8[], aOff: i32, b: u8[], bOff: i32, len: i32): boolean => {
+  const aLen: i32 = toI32(a.length)
+  const bLen: i32 = toI32(b.length)
+  // Written as `off > length - len` rather than `off + len > length`, so that
+  // a huge offset cannot wrap round to a small sum and pass.
+  if (aOff < 0 || bOff < 0 || len < 0 || aOff > aLen - len || bOff > bLen - len) {
+    return false
+  }
+  let diff: i32 = 0
+  for (let k: i32 = 0; k < len; k++) {
+    diff = diff | toI32(a[aOff + k] ^ b[bOff + k])
+  }
+  return diff === 0
+}

package/std/crypto/hkdf.ts

@@ -0,0 +1,118 @@
+/**
+ * `nish/crypto/hkdf` — HKDF as RFC 5869 defines it, over HMAC-SHA-256 and
+ * HMAC-SHA-384.
+ *
+ * Two steps, each its own function, because TLS 1.3 calls them separately:
+ *
+ *     PRK = HKDF-Extract(salt, IKM)  = HMAC-Hash(salt, IKM)                    (§2.2)
+ *     OKM = HKDF-Expand(PRK, info, L) = T(1) | T(2) | … truncated to L bytes   (§2.3)
+ *     T(i) = HMAC-Hash(PRK, T(i-1) | info | i),  T(0) empty,  i one byte
+ *
+ *     import { hkdfExtractSha256, hkdfExpandSha256 } from "nish/crypto/hkdf";
+ *
+ *     const prk: u8[] = hkdfExtractSha256(salt, secret);
+ *     const okm: u8[] | null = hkdfExpandSha256(prk, info, 42);
+ *
+ * The counter `i` is one byte, so `L` is at most 255 × HashLen (§2.3): 8160
+ * bytes for SHA-256 and 12240 for SHA-384. A longer `L`, or a negative one,
+ * answers `null` rather than panicking, because `L` usually comes from a
+ * protocol field; `L = 0` answers an empty array.
+ *
+ * HKDF-Expand-Label, TLS 1.3's wrapper around `expand`, belongs with TLS and is
+ * not here. Written from RFC 5869, not ported from another implementation.
+ */
+import { HmacSha256, HmacSha384, hmacSha256, hmacSha384 } from "nish/crypto/hmac"
+import { SHA256_SIZE } from "nish/crypto/sha256"
+import { SHA384_SIZE } from "nish/crypto/sha512"
+
+/** The largest block counter, and so the most blocks `expand` can make (RFC 5869 §2.3). */
+const HKDF_MAX_BLOCKS: i32 = 255
+
+/** A typed zero for the offsets below: a bare literal is an `f64` under `--number-mode f64`. */
+const HKDF_FROM: i32 = 0
+
+/**
+ * The salt `extract` keys HMAC with: `salt` itself, or HashLen zero bytes when
+ * it is empty (RFC 5869 §2.2, "if not provided"). HMAC zero-pads a short key to
+ * a block anyway, so the two give one PRK; the zeros are written out so the
+ * code says what the RFC says.
+ */
+const hkdfSalt = (salt: u8[], hashLen: i32): u8[] =>
+  toI32(salt.length) === 0 ? new Array<u8>(hashLen) : salt
+
+/**
+ * Copies `block[0 .. n)` to `out[at .. at + n)`, where `n` is as much of the
+ * block as `out` still has room for. Answers the new fill of `out`.
+ */
+const hkdfAppend = (out: u8[], at: i32, block: u8[]): i32 => {
+  const outLength: i32 = toI32(out.length)
+  const blockLength: i32 = toI32(block.length)
+  let k: i32 = 0
+  while (k < blockLength && at + k < outLength) {
+    out[at + k] = block[k]
+    k += 1
+  }
+  return at + k
+}
+
+/** HKDF-Extract with HMAC-SHA-256 (RFC 5869 §2.2): the 32-byte PRK. */
+export const hkdfExtractSha256 = (salt: u8[], ikm: u8[]): u8[] => hmacSha256(hkdfSalt(salt, SHA256_SIZE), ikm)
+
+/** HKDF-Extract with HMAC-SHA-384 (RFC 5869 §2.2): the 48-byte PRK. */
+export const hkdfExtractSha384 = (salt: u8[], ikm: u8[]): u8[] => hmacSha384(hkdfSalt(salt, SHA384_SIZE), ikm)
+
+/**
+ * HKDF-Expand with HMAC-SHA-256 (RFC 5869 §2.3): `length` bytes of output
+ * keying material from `prk` and `info`, or `null` when `length` is negative
+ * or past 255 × 32.
+ */
+export const hkdfExpandSha256 = (prk: u8[], info: u8[], length: i32): u8[] | null => {
+  if (length < 0 || length > HKDF_MAX_BLOCKS * SHA256_SIZE) {
+    return null
+  }
+  const out: u8[] = new Array<u8>(length)
+  const counter: u8[] = new Array<u8>(1)
+  const counterLength: i32 = 1
+  let previous: u8[] = []
+  let at: i32 = 0
+  let i: i32 = 1
+  while (at < length) {
+    const mac = new HmacSha256(prk)
+    mac.update(previous, HKDF_FROM, toI32(previous.length))
+    mac.update(info, HKDF_FROM, toI32(info.length))
+    counter[0] = toU8(i)
+    mac.update(counter, HKDF_FROM, counterLength)
+    previous = mac.digest()
+    at = hkdfAppend(out, at, previous)
+    i += 1
+  }
+  return out
+}
+
+/**
+ * HKDF-Expand with HMAC-SHA-384 (RFC 5869 §2.3): `length` bytes of output
+ * keying material from `prk` and `info`, or `null` when `length` is negative
+ * or past 255 × 48.
+ */
+export const hkdfExpandSha384 = (prk: u8[], info: u8[], length: i32): u8[] | null => {
+  if (length < 0 || length > HKDF_MAX_BLOCKS * SHA384_SIZE) {
+    return null
+  }
+  const out: u8[] = new Array<u8>(length)
+  const counter: u8[] = new Array<u8>(1)
+  const counterLength: i32 = 1
+  let previous: u8[] = []
+  let at: i32 = 0
+  let i: i32 = 1
+  while (at < length) {
+    const mac = new HmacSha384(prk)
+    mac.update(previous, HKDF_FROM, toI32(previous.length))
+    mac.update(info, HKDF_FROM, toI32(info.length))
+    counter[0] = toU8(i)
+    mac.update(counter, HKDF_FROM, counterLength)
+    previous = mac.digest()
+    at = hkdfAppend(out, at, previous)
+    i += 1
+  }
+  return out
+}

package/std/crypto/hmac.ts

@@ -0,0 +1,155 @@
+/**
+ * `nish/crypto/hmac` — HMAC as RFC 2104 defines it, over SHA-256 and SHA-384.
+ *
+ *     H(K XOR opad, H(K XOR ipad, text))
+ *
+ * `K` is the key zero-padded to the hash's block size, or first hashed when it
+ * is longer than a block (RFC 2104 §2); `ipad` is the byte 0x36 and `opad` the
+ * byte 0x5c, repeated a block long. The key is absorbed into both hashers in
+ * the constructor, so a `HmacSha256` is a keyed inner hash waiting for the
+ * message and a keyed outer hash waiting for the inner digest.
+ *
+ *     import { HmacSha256, hmacSha256, hmacSha256Verify } from "nish/crypto/hmac";
+ *
+ *     const tag: u8[] = hmacSha256(key, message);
+ *     const ok: boolean = hmacSha256Verify(key, message, received);
+ *
+ *     const mac = new HmacSha256(key);
+ *     mac.update(record, off, len);
+ *     const tag2: u8[] = mac.digest();
+ *
+ * Like the hashers underneath, a `digest` ends the computation: a later
+ * `update` or a second `digest` panics in the hasher it reaches, and so does
+ * a window outside its buffer. The only branch on the key is on its length,
+ * which HMAC does not keep secret; a received tag is compared with
+ * `timingSafeEqual`, never `===`.
+ *
+ * Written from RFC 2104, 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 { timingSafeEqual } from "nish/crypto/ct"
+
+/** RFC 2104 §2's `ipad`, the byte XORed into the key for the inner hash. */
+const HMAC_IPAD: i32 = 0x36
+
+/** RFC 2104 §2's `opad`, the byte XORed into the key for the outer hash. */
+const HMAC_OPAD: i32 = 0x5c
+
+/** A typed zero for the offsets below: a bare literal is an `f64` under `--number-mode f64`. */
+const HMAC_FROM: i32 = 0
+
+/**
+ * `key XOR pad` over a whole block of `blockSize` bytes, with `key` already no
+ * longer than a block: the key's bytes XOR `pad`, then `pad` alone where the
+ * zero padding of RFC 2104 §2 step (1) would be.
+ */
+const hmacPadBlock = (key: u8[], blockSize: i32, pad: i32): u8[] => {
+  const padByte: u8 = toU8(pad)
+  const out: u8[] = new Array<u8>(blockSize)
+  const outLength: i32 = toI32(out.length)
+  const keyLength: i32 = toI32(key.length)
+  // Bounded by both lengths, so both indices are proved in range.
+  let i: i32 = 0
+  while (i < keyLength && i < outLength) {
+    out[i] = key[i] ^ padByte
+    i += 1
+  }
+  while (i < outLength) {
+    out[i] = padByte
+    i += 1
+  }
+  return out
+}
+
+/**
+ * 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
+ * tag with `digest`.
+ */
+export class HmacSha256 {
+  /** H(K XOR ipad, …), fed the key block in the constructor and the message after. */
+  inner: Sha256
+  /** 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). */
+  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)
+  }
+
+  /** Absorbs `data[off .. off + len)`; a window outside `data` panics in `Sha256.update`. */
+  update(data: u8[], off: i32, len: i32): void {
+    this.inner.update(data, off, len)
+  }
+
+  /** The 32-byte tag, in a fresh array. Ends the computation. */
+  digest(): u8[] {
+    const innerDigest: u8[] = this.inner.digest()
+    this.outer.update(innerDigest, HMAC_FROM, SHA256_SIZE)
+    return this.outer.digest()
+  }
+}
+
+/**
+ * HMAC-SHA-384 in progress (RFC 2104 with RFC 4231's SHA-384), with
+ * `HmacSha256`'s methods. The block is SHA-384's 128 bytes and the tag 48.
+ */
+export class HmacSha384 {
+  /** H(K XOR ipad, …), fed the key block in the constructor and the message after. */
+  inner: Sha384
+  /** H(K XOR opad, …), fed the key block in the constructor and the inner digest last. */
+  outer: Sha384
+
+  /** 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)
+  }
+
+  /** Absorbs `data[off .. off + len)`; a window outside `data` panics in `Sha384.update`. */
+  update(data: u8[], off: i32, len: i32): void {
+    this.inner.update(data, off, len)
+  }
+
+  /** The 48-byte tag, in a fresh array. Ends the computation. */
+  digest(): u8[] {
+    const innerDigest: u8[] = this.inner.digest()
+    this.outer.update(innerDigest, HMAC_FROM, SHA384_SIZE)
+    return this.outer.digest()
+  }
+}
+
+/** The HMAC-SHA-256 of all of `data` under `key`, as a fresh 32-byte array. */
+export const hmacSha256 = (key: u8[], data: u8[]): u8[] => {
+  const mac = new HmacSha256(key)
+  mac.update(data, HMAC_FROM, toI32(data.length))
+  return mac.digest()
+}
+
+/** The HMAC-SHA-384 of all of `data` under `key`, as a fresh 48-byte array. */
+export const hmacSha384 = (key: u8[], data: u8[]): u8[] => {
+  const mac = new HmacSha384(key)
+  mac.update(data, HMAC_FROM, toI32(data.length))
+  return mac.digest()
+}
+
+/**
+ * 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
+ * byte compare, since its length is public; one that is is compared in full,
+ * so the time taken does not say how many leading bytes were right.
+ */
+export const hmacSha256Verify = (key: u8[], data: u8[], tag: u8[]): boolean =>
+  timingSafeEqual(hmacSha256(key, data), tag)
+
+/** Whether `tag` is the HMAC-SHA-384 of `data` under `key`, compared as `hmacSha256Verify` does. */
+export const hmacSha384Verify = (key: u8[], data: u8[], tag: u8[]): boolean =>
+  timingSafeEqual(hmacSha384(key, data), tag)