@amritk/nish-x86_64-linux 0.15.0 → 0.17.0

package/std/crypto/sha1.ts

@@ -0,0 +1,147 @@
+/**
+ * `nish/crypto/sha1` — SHA-1 as FIPS 180-4 §6.1 defines it, in pure Nish.
+ *
+ * **This is not for security.** SHA-1 is broken for collisions (SHAttered,
+ * 2017) and no new protocol should sign or authenticate with it. It is here
+ * for one caller: RFC 6455 §4.2.2's `Sec-WebSocket-Accept`, which is the
+ * base64 of the SHA-1 of the client's key and a fixed GUID. That value proves
+ * only that the server read the handshake as a WebSocket handshake, not who
+ * either side is, so a collision buys an attacker nothing there.
+ * `nish/net/websocket` is the importer; anything that needs a hash for its own
+ * sake takes `nish/crypto/sha256`.
+ *
+ *     import { sha1 } from "nish/crypto/sha1";
+ *
+ *     const digest: u8[] = sha1(message); // 20 bytes
+ *
+ * One shot only, because a handshake key is a few dozen bytes: there is no
+ * streaming hasher to keep in step with `Sha256`'s.
+ *
+ * Every word is a `u32`, whose arithmetic wraps, so the additions modulo 2^32
+ * are plain `+`. The only branches are on lengths, loop counters and the round
+ * number.
+ *
+ * Written from the specification, not ported from another implementation.
+ */
+
+/** The length of a digest in bytes (FIPS 180-4 §1). */
+export const SHA1_SIZE: i32 = 20
+
+/** The length of a message block in bytes (FIPS 180-4 §1). */
+export const SHA1_BLOCK: i32 = 64
+
+/** ROTL^n(x) of FIPS 180-4 §3.2: a left rotation of a 32-bit word, `0 < n < 32`. */
+const sha1Rotl = (x: u32, n: u32): u32 => (x << n) | (x >>> (32 - n))
+
+/** The big-endian word at `buf[at .. at + 4)`, as FIPS 180-4 §3.1 orders bytes in a word. */
+const sha1LoadWord = (buf: u8[], at: i32): u32 =>
+  (toU32(buf[at]) << 24) | (toU32(buf[at + 1]) << 16) | (toU32(buf[at + 2]) << 8) | toU32(buf[at + 3])
+
+/**
+ * Folds the 64-byte block at `src[at .. at + 64)` into `h`: FIPS 180-4
+ * §6.1.2, steps 1 to 4. `w` is the 80-word schedule, allocated once per call
+ * to `sha1` rather than once per block.
+ */
+const sha1Compress = (h: u32[], w: u32[], src: u8[], at: i32): void => {
+  // Written as the condition the body runs under, the shape that proves the
+  // plain `w[t]` and `h[i]` indices in range (as `sha256Compress` does).
+  if (toI32(h.length) >= 5 && toI32(w.length) >= 80 && at >= 0 && at <= toI32(src.length) - SHA1_BLOCK) {
+    // Step 1: the message schedule, big-endian words (§3.1), then (6.1.2).
+    for (let t: i32 = 0; t < 16; t += 1) {
+      w[t] = sha1LoadWord(src, at + 4 * t)
+    }
+    for (let t: i32 = 16; t < 80; t += 1) {
+      w[t] = sha1Rotl(w[t - 3] ^ w[t - 8] ^ w[t - 14] ^ w[t - 16], 1)
+    }
+    // Step 2.
+    let a: u32 = h[0]
+    let b: u32 = h[1]
+    let c: u32 = h[2]
+    let d: u32 = h[3]
+    let e: u32 = h[4]
+    // Step 3: eighty rounds, f_t and K_t of §4.1.1 and §4.2.1 by quarter.
+    for (let t: i32 = 0; t < 80; t += 1) {
+      let f: u32 = 0
+      let k: u32 = 0
+      if (t < 20) {
+        f = (b & c) ^ (~b & d)
+        k = 0x5a827999
+      } else if (t < 40) {
+        f = b ^ c ^ d
+        k = 0x6ed9eba1
+      } else if (t < 60) {
+        f = (b & c) ^ (b & d) ^ (c & d)
+        k = 0x8f1bbcdc
+      } else {
+        f = b ^ c ^ d
+        k = 0xca62c1d6
+      }
+      const temp: u32 = sha1Rotl(a, 5) + f + e + k + w[t]
+      e = d
+      d = c
+      c = sha1Rotl(b, 30)
+      b = a
+      a = temp
+    }
+    // Step 4.
+    h[0] += a
+    h[1] += b
+    h[2] += c
+    h[3] += d
+    h[4] += e
+  } else {
+    panic("sha1: a block outside its buffer")
+  }
+}
+
+/**
+ * The SHA-1 digest of all of `data`, as a fresh 20-byte array.
+ *
+ * An array longer than 2^31 - 1 bytes panics, for the reason `sha256` gives:
+ * under `--number-mode f64`, `toI32` of a longer length saturates, and the
+ * answer would be the digest of a prefix.
+ */
+export const sha1 = (data: u8[]): u8[] => {
+  if (data.length > 2147483647) {
+    panic("sha1: a message longer than 2^31 - 1 bytes")
+  }
+  const n: i32 = toI32(data.length)
+  // H^(0) of FIPS 180-4 §5.3.1.
+  const h: u32[] = new Array<u32>(5)
+  h[0] = 0x67452301
+  h[1] = 0xefcdab89
+  h[2] = 0x98badcfe
+  h[3] = 0x10325476
+  h[4] = 0xc3d2e1f0
+  const w: u32[] = new Array<u32>(80)
+  // Whole blocks straight from `data`, then the tail and its padding (§5.1.1)
+  // in one or two blocks of their own.
+  const whole: i32 = n - (n % SHA1_BLOCK)
+  for (let at: i32 = 0; at < whole; at += SHA1_BLOCK) {
+    sha1Compress(h, w, data, at)
+  }
+  const tail: i32 = n - whole
+  const tailBlocks: i32 = tail < SHA1_BLOCK - 8 ? 1 : 2
+  const last: u8[] = new Array<u8>(tailBlocks * SHA1_BLOCK)
+  const lastLength: i32 = toI32(last.length)
+  for (let k: i32 = 0; k < tail && k < lastLength; k += 1) {
+    last[k] = data[whole + k]
+  }
+  last[tail] = 0x80
+  const bits: u64 = toU64(toI64(n)) << 3
+  for (let i: i32 = 0; i < 8; i += 1) {
+    last[lastLength - 1 - i] = toU8(bits >>> toU64(8 * i))
+  }
+  for (let at: i32 = 0; at < lastLength; at += SHA1_BLOCK) {
+    sha1Compress(h, w, last, at)
+  }
+  const out: u8[] = new Array<u8>(SHA1_SIZE)
+  for (let i: i32 = 0; i < 5; i += 1) {
+    const word: u32 = h[i]
+    out[4 * i] = toU8(word >>> 24)
+    out[4 * i + 1] = toU8(word >>> 16)
+    out[4 * i + 2] = toU8(word >>> 8)
+    out[4 * i + 3] = toU8(word)
+  }
+  return out
+}

package/std/crypto/sha256.ts

@@ -215,8 +215,9 @@ const sha256Compress = (h: u32[], w: u32[], src: u8[], at: i32): void => {
   // early exit, because that is the shape that proves the plain `w[t]` and
   // `h[i]` indices in range and drops their bounds checks. The computed ones —
   // the byte reads in `sha256LoadWord` and `w[t - 2]` and its kin — keep a
-  // check each; measured, removing every check with `--unchecked-indexing`
-  // moved the 1 MiB time by less than the run-to-run noise.
+  // check each; measured, removing every check (with `--unchecked-indexing`,
+  // which no longer reaches a `nish/` module at all) moved the 1 MiB time by
+  // less than the run-to-run noise.
   if (toI32(h.length) >= 8 && toI32(w.length) >= 64 && at >= 0 && at <= toI32(src.length) - SHA256_BLOCK) {
     // Step 1: the message schedule.
     for (let t: i32 = 0; t < 16; t += 1) {
@@ -435,8 +436,19 @@ export class Sha256 {
   }
 }
 
-/** The SHA-256 digest of all of `data`, as a fresh 32-byte array. */
+/**
+ * The SHA-256 digest of all of `data`, as a fresh 32-byte array.
+ *
+ * An array longer than 2^31 - 1 bytes panics. A window's length is an `i32`,
+ * and under `--number-mode f64` `toI32` of a longer length saturates, so
+ * hashing `toI32(data.length)` bytes would answer the digest of a prefix: one
+ * digest for every message that shares its first 2^31 - 1 bytes. The length
+ * is compared as the `number` it is, before any `toI32`.
+ */
 export const sha256 = (data: u8[]): u8[] => {
+  if (data.length > 2147483647) {
+    panic("sha256: a message longer than 2^31 - 1 bytes")
+  }
   const hasher: Sha256 = new Sha256()
   const from: i32 = 0
   hasher.update(data, from, toI32(data.length))

package/std/crypto/sha512.ts

@@ -495,15 +495,29 @@ export class Sha384 {
   }
 }
 
-/** The SHA-512 digest of all of `data`, as a fresh 64-byte array. */
+/**
+ * The SHA-512 digest of all of `data`, as a fresh 64-byte array. An array
+ * longer than 2^31 - 1 bytes panics, for the reason `sha256` gives: a longer
+ * length does not survive `toI32` under `--number-mode f64`, and the digest
+ * would be of a prefix.
+ */
 export const sha512 = (data: u8[]): u8[] => {
+  if (data.length > 2147483647) {
+    panic("sha512: a message longer than 2^31 - 1 bytes")
+  }
   const hasher = new Sha512()
   hasher.update(data, OFFSET_ZERO, toI32(data.length))
   return hasher.digest()
 }
 
-/** The SHA-384 digest of all of `data`, as a fresh 48-byte array. */
+/**
+ * The SHA-384 digest of all of `data`, as a fresh 48-byte array. An array
+ * longer than 2^31 - 1 bytes panics, as in `sha512`.
+ */
 export const sha384 = (data: u8[]): u8[] => {
+  if (data.length > 2147483647) {
+    panic("sha384: a message longer than 2^31 - 1 bytes")
+  }
   const hasher = new Sha384()
   hasher.update(data, OFFSET_ZERO, toI32(data.length))
   return hasher.digest()

package/std/crypto/x25519.ts

@@ -21,9 +21,10 @@
  *   subtraction needs no bias and a carry is a floor division that works the
  *   same on a negative limb.
  *
- * Signed `i64` overflow is undefined behaviour in this language unless a
- * program is compiled with `--wrapping`, so the limb bounds below are not a
- * nicety: each function states what it accepts and what it answers, and
+ * Signed `i64` overflow is undefined behaviour in this language, and
+ * `--wrapping` does not reach a `nish/` module (only `wrappingAdd`,
+ * `wrappingSub` and `wrappingMul` from `nish:unsafe` define a wrap, at the
+ * site that calls one), so the limb bounds below are not a nicety: each function states what it accepts and what it answers, and
  * `f25519Mul` says why its sums fit.
  *
  * **Constant time, by construction, and in part by disassembly.** Nothing
@@ -57,17 +58,36 @@
  * the literal `10` or `32`, in range and drop their bounds checks. (A named
  * constant as the bound, or a `panic` as the guard, does not prove them.)
  *
+ * **Keys are `Secret`s** (`nish:secret`, docs/LANGUAGE.md "Secrets"). `x25519`
+ * takes the scalar as a `Secret<u8[]>` and answers the shared secret as one;
+ * `x25519Base` answers the public key as plain bytes. The ladder runs inside
+ * `exposeWith`, and the clamped copy and every ladder element are wiped before
+ * it returns (ECC-2, docs/security/crypto-ecc.md).
+ *
  * Private names carry the `f25519` / `x25519` prefix because a `std/` module's
  * private functions share the importing program's flat symbol namespace
  * (`docs/wp26-stdlib.md` §3e).
  */
 
+import { Secret, exposeWith, secret, wipe } from "nish:secret"
+
 /** The length in bytes of a scalar, a u-coordinate and an X25519 output. */
 export const X25519_SIZE: i32 = 32
 
 /** (A - 2) / 4 for curve25519's A = 486662 (RFC 7748 §5). */
 const X25519_A24: i64 = 121665
 
+/**
+ * `a + b`, `a - b` and `a * b` on limbs: the `u64` arithmetic, read back as
+ * `i64`. Every bound this module states keeps the true result inside `i64`,
+ * so the answer is the signed one bit for bit; the arithmetic is unsigned
+ * because signed arithmetic is checked for an overflow, and a check is a
+ * branch on a secret limb. Each is one instruction once LLVM inlines it.
+ */
+const f25519Add64 = (a: i64, b: i64): i64 => toI64(toU64(a) + toU64(b))
+const f25519Sub64 = (a: i64, b: i64): i64 => toI64(toU64(a) - toU64(b))
+const f25519Mul64 = (a: i64, b: i64): i64 => toI64(toU64(a) * toU64(b))
+
 /** The width of limb `i`: 26 bits for an even limb, 25 for an odd one. */
 const f25519Width = (i: i32): i64 => {
   const odd: i64 = toI64(i & 1)
@@ -75,7 +95,7 @@ const f25519Width = (i: i32): i64 => {
 }
 
 /** The mask of limb `i`'s bits, `2^width - 1`. */
-const f25519LimbMask = (i: i32): i64 => (toI64(1) << f25519Width(i)) - toI64(1)
+const f25519LimbMask = (i: i32): i64 => f25519Sub64(toI64(1) << f25519Width(i), toI64(1))
 
 /** A fresh field element, zero. */
 const f25519Zero = (): i64[] => {
@@ -112,7 +132,7 @@ const f25519CarryChain = (h: i64[]): void => {
   for (let i: i32 = 0; i < 9; i++) {
     const c: i64 = h[i] >> f25519Width(i)
     h[i] = h[i] & f25519LimbMask(i)
-    h[i + 1] = h[i + 1] + c
+    h[i + 1] = f25519Add64(h[i + 1], c)
   }
 }
 
@@ -139,10 +159,10 @@ const f25519Carry = (h: i64[]): void => {
   f25519CarryChain(h)
   const top: i64 = h[9] >> toI64(25)
   h[9] = h[9] & f25519LimbMask(9)
-  h[0] = h[0] + top * toI64(19)
+  h[0] = f25519Add64(h[0], f25519Mul64(top, toI64(19)))
   const c0: i64 = h[0] >> toI64(26)
   h[0] = h[0] & f25519LimbMask(0)
-  h[1] = h[1] + c0
+  h[1] = f25519Add64(h[1], c0)
 }
 
 /**
@@ -154,7 +174,7 @@ const f25519Add = (out: i64[], f: i64[], g: i64[]): void => {
     return
   }
   for (let i: i32 = 0; i < 10; i++) {
-    out[i] = f[i] + g[i]
+    out[i] = f25519Add64(f[i], g[i])
   }
 }
 
@@ -168,7 +188,7 @@ const f25519Sub = (out: i64[], f: i64[], g: i64[]): void => {
     return
   }
   for (let i: i32 = 0; i < 10; i++) {
-    out[i] = f[i] - g[i]
+    out[i] = f25519Sub64(f[i], g[i])
   }
 }
 
@@ -196,7 +216,7 @@ const f25519Mul = (out: i64[], f: i64[], g: i64[]): void => {
   // product takes `f`'s limb doubled.
   const doubled: i64[] = new Array<i64>(10)
   for (let i: i32 = 0; i < 10; i++) {
-    doubled[i] = f[i] * toI64((i & 1) + 1)
+    doubled[i] = f25519Mul64(f[i], toI64((i & 1) + 1))
   }
   // The plain product, limb `i + j` of nineteen.
   const wide: i64[] = new Array<i64>(19)
@@ -205,14 +225,14 @@ const f25519Mul = (out: i64[], f: i64[], g: i64[]): void => {
       const k: i32 = i + j
       const fi: i64 = (i & j & 1) === 1 ? doubled[i] : f[i]
       if (k >= 0 && k < 19) {
-        wide[k] = wide[k] + fi * g[j]
+        wide[k] = f25519Add64(wide[k], f25519Mul64(fi, g[j]))
       }
     }
   }
   // Limbs 10 to 18 are past bit 255, and 2^255 = 19 (mod p): fold them down.
   const h: i64[] = new Array<i64>(10)
   for (let k: i32 = 0; k < 9; k++) {
-    h[k] = wide[k] + wide[k + 10] * toI64(19)
+    h[k] = f25519Add64(wide[k], f25519Mul64(wide[k + 10], toI64(19)))
   }
   h[9] = wide[9]
   f25519Carry(h)
@@ -242,7 +262,7 @@ const f25519MulA24 = (out: i64[], f: i64[]): void => {
     return
   }
   for (let i: i32 = 0; i < 10; i++) {
-    out[i] = f[i] * X25519_A24
+    out[i] = f25519Mul64(f[i], X25519_A24)
   }
   f25519Carry(out)
 }
@@ -304,7 +324,7 @@ const f25519Swap = (f: i64[], g: i64[], bit: i64): void => {
   if (toI32(f.length) < 10 || toI32(g.length) < 10) {
     return
   }
-  const mask: i64 = toI64(0) - bit
+  const mask: i64 = f25519Sub64(toI64(0), bit)
   for (let i: i32 = 0; i < 10; i++) {
     const t: i64 = mask & (f[i] ^ g[i])
     f[i] = f[i] ^ t
@@ -368,11 +388,11 @@ const f25519Encode = (f: i64[]): u8[] => {
   f25519Carry(h)
   f25519Carry(h)
 
-  let q: i64 = (h[0] + toI64(19)) >> toI64(26)
+  let q: i64 = f25519Add64(h[0], toI64(19)) >> toI64(26)
   for (let i: i32 = 1; i < 10; i++) {
-    q = (h[i] + q) >> f25519Width(i)
+    q = f25519Add64(h[i], q) >> f25519Width(i)
   }
-  h[0] = h[0] + q * toI64(19)
+  h[0] = f25519Add64(h[0], f25519Mul64(q, toI64(19)))
   f25519CarryChain(h)
   h[9] = h[9] & f25519LimbMask(9)
 
@@ -466,25 +486,32 @@ const x25519Ladder = (k: u8[], u: i64[]): u8[] => {
 
   f25519Invert(t, z2)
   f25519Mul(x2, x2, t)
-  return f25519Encode(x2)
+  const out: u8[] = f25519Encode(x2)
+  // ECC-2: every element the scalar's bits reached is zeroed before the
+  // ladder returns, with the store `nish:secret` keeps from the optimiser.
+  wipe(x2)
+  wipe(z2)
+  wipe(x3)
+  wipe(z3)
+  wipe(a)
+  wipe(aa)
+  wipe(b)
+  wipe(bb)
+  wipe(e)
+  wipe(c)
+  wipe(d)
+  wipe(da)
+  wipe(cb)
+  wipe(t)
+  return out
 }
 
 /**
- * X25519 (RFC 7748 §5): the u-coordinate of `scalar * u` on curve25519, as 32
- * little-endian bytes.
- *
- * `scalar` is clamped as §5 says — bits 0, 1, 2 and 255 cleared, bit 254 set —
- * on a copy, so the caller's array is not changed. The top bit of `u` is
- * ignored, and a `u` of p or more is taken modulo p. The answer is always
- * canonical (below p).
- *
- * Answers `null` unless both arguments are exactly `X25519_SIZE` bytes. An
- * all-zero answer is **returned, not refused**: it is what a low-order `u`
- * gives, and RFC 7748 §6.1 leaves checking for it to the protocol, which is
- * where TLS 1.3 (WP34 T1) makes that check. A caller doing a key exchange
- * outside TLS should make it too.
+ * X25519 on the plain scalar `scalar`, for `exposeWith` to run: the clamped
+ * copy is wiped once the ladder has used it, and the answer is the shared
+ * secret's plain bytes, which `x25519` wraps again at once.
  */
-export const x25519 = (scalar: u8[], u: u8[]): u8[] | null => {
+const x25519Exposed = (scalar: u8[], u: u8[]): u8[] | null => {
   if (toI32(scalar.length) !== 32 || toI32(u.length) !== 32) {
     return null
   }
@@ -494,16 +521,42 @@ export const x25519 = (scalar: u8[], u: u8[]): u8[] | null => {
   }
   k[0] = k[0] & toU8(248)
   k[31] = (k[31] & toU8(127)) | toU8(64)
-  return x25519Ladder(k, f25519Decode(u))
+  const out: u8[] = x25519Ladder(k, f25519Decode(u))
+  wipe(k)
+  return out
+}
+
+/**
+ * X25519 (RFC 7748 §5): the u-coordinate of `scalar * u` on curve25519, as 32
+ * little-endian bytes, held as the `Secret` it is.
+ *
+ * `scalar` is clamped as §5 says — bits 0, 1, 2 and 255 cleared, bit 254 set —
+ * on a copy, which is wiped, so the caller's key is not changed. The top bit of
+ * `u` is ignored, and a `u` of p or more is taken modulo p. The answer is
+ * always canonical (below p).
+ *
+ * Answers `null` unless both arguments are exactly `X25519_SIZE` bytes. An
+ * all-zero answer is **returned, not refused**: it is what a low-order `u`
+ * gives, and RFC 7748 §6.1 leaves checking for it to the protocol. Nothing in
+ * this tree makes that check for you yet (TLS 1.3, WP34 T1, is planned to), so
+ * every caller doing a key exchange must refuse an all-zero answer itself —
+ * inside `expose`, with `timingSafeEqual` against 32 zero bytes.
+ */
+export const x25519 = (scalar: Secret<u8[]>, u: u8[]): Secret<u8[]> | null => {
+  const shared: u8[] | null = exposeWith(scalar, u, x25519Exposed)
+  if (shared === null) {
+    return null
+  }
+  return secret(shared)
 }
 
 /**
  * `x25519(scalar, 9)`: the public key for the private key `scalar`, since 9 is
- * curve25519's base point (RFC 7748 §4.1, §6.1). Answers `null` unless
- * `scalar` is `X25519_SIZE` bytes.
+ * curve25519's base point (RFC 7748 §4.1, §6.1), and public, so plain bytes.
+ * Answers `null` unless `scalar` is `X25519_SIZE` bytes.
  */
-export const x25519Base = (scalar: u8[]): u8[] | null => {
+export const x25519Base = (scalar: Secret<u8[]>): u8[] | null => {
   const base: u8[] = new Array<u8>(32)
   base[0] = toU8(9)
-  return x25519(scalar, base)
+  return exposeWith(scalar, base, x25519Exposed)
 }