@amritk/nish-x86_64-linux 0.18.0 → 0.21.0

package/std/crypto/x25519.ts

@@ -64,7 +64,14 @@
  * `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
+ * **The field is shared with Ed25519.** `nish/crypto/ed25519` works over the
+ * same GF(p), so the `f25519` functions are exported for it to import rather
+ * than written twice; they are the module's internals, with the bounds each
+ * one states, not an API for programs. Ed25519's square root needs
+ * `z^(2^252 - 3)`, which shares its first 250 bits with the inversion's
+ * exponent, so that part of the chain is `f25519Pow250`, which both call.
+ *
+ * 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).
  */
@@ -84,9 +91,9 @@ const X25519_A24: i64 = 121665
  * 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))
+export const f25519Add64 = (a: i64, b: i64): i64 => toI64(toU64(a) + toU64(b))
+export const f25519Sub64 = (a: i64, b: i64): i64 => toI64(toU64(a) - toU64(b))
+export 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 => {
@@ -98,20 +105,20 @@ const f25519Width = (i: i32): i64 => {
 const f25519LimbMask = (i: i32): i64 => f25519Sub64(toI64(1) << f25519Width(i), toI64(1))
 
 /** A fresh field element, zero. */
-const f25519Zero = (): i64[] => {
+export const f25519Zero = (): i64[] => {
   const f: i64[] = new Array<i64>(10)
   return f
 }
 
 /** A fresh field element holding the small constant `n`. */
-const f25519Small = (n: i64): i64[] => {
+export const f25519Small = (n: i64): i64[] => {
   const f: i64[] = f25519Zero()
   f[0] = n
   return f
 }
 
 /** `out = f`, limb by limb. */
-const f25519Copy = (out: i64[], f: i64[]): void => {
+export const f25519Copy = (out: i64[], f: i64[]): void => {
   if (toI32(out.length) < 10 || toI32(f.length) < 10) {
     return
   }
@@ -152,7 +159,7 @@ const f25519CarryChain = (h: i64[]): void => {
  * `h & (2^width - 1)`, which is the matching non-negative remainder for a
  * negative limb too, without shifting a negative number left.
  */
-const f25519Carry = (h: i64[]): void => {
+export const f25519Carry = (h: i64[]): void => {
   if (toI32(h.length) < 10) {
     return
   }
@@ -169,7 +176,7 @@ const f25519Carry = (h: i64[]): void => {
  * `out = f + g`, not carried. With both reduced (limbs below 2^26 in
  * magnitude) the sum's limbs are below 2^27, which `f25519Mul` accepts.
  */
-const f25519Add = (out: i64[], f: i64[], g: i64[]): void => {
+export const f25519Add = (out: i64[], f: i64[], g: i64[]): void => {
   if (toI32(out.length) < 10 || toI32(f.length) < 10 || toI32(g.length) < 10) {
     return
   }
@@ -183,7 +190,7 @@ const f25519Add = (out: i64[], f: i64[], g: i64[]): void => {
  * both reduced the difference's limbs are below 2^27 in magnitude, which
  * `f25519Mul` accepts.
  */
-const f25519Sub = (out: i64[], f: i64[], g: i64[]): void => {
+export const f25519Sub = (out: i64[], f: i64[], g: i64[]): void => {
   if (toI32(out.length) < 10 || toI32(f.length) < 10 || toI32(g.length) < 10) {
     return
   }
@@ -208,7 +215,7 @@ const f25519Sub = (out: i64[], f: i64[], g: i64[]): void => {
  * sums added again, say — breaks this bound, which is why every caller carries
  * or multiplies before it adds a second time.
  */
-const f25519Mul = (out: i64[], f: i64[], g: i64[]): void => {
+export const f25519Mul = (out: i64[], f: i64[], g: i64[]): void => {
   if (toI32(f.length) < 10 || toI32(g.length) < 10) {
     return
   }
@@ -240,12 +247,12 @@ const f25519Mul = (out: i64[], f: i64[], g: i64[]): void => {
 }
 
 /** `out = f * f`, reduced; the same bounds as `f25519Mul`. */
-const f25519Square = (out: i64[], f: i64[]): void => {
+export const f25519Square = (out: i64[], f: i64[]): void => {
   f25519Mul(out, f, f)
 }
 
 /** `out = f` squared `n` times in a row (`n` at least 1), reduced. */
-const f25519SquareTimes = (out: i64[], f: i64[], n: i32): void => {
+export const f25519SquareTimes = (out: i64[], f: i64[], n: i32): void => {
   f25519Square(out, f)
   for (let i: i32 = 1; i < n; i++) {
     f25519Square(out, out)
@@ -268,25 +275,20 @@ const f25519MulA24 = (out: i64[], f: i64[]): void => {
 }
 
 /**
- * `out = z^(p - 2)`, which is `1 / z` by Fermat's little theorem, and zero for
- * a zero `z` — what RFC 7748 §5 asks of the ladder's last step.
- *
- * p - 2 = 2^255 - 21 = (2^250 - 1) * 2^5 + 11, so the exponent is 250 ones
- * followed by `01011`. The chain builds `z^(2^n - 1)` for n = 2, 4, 5, 10, 20,
- * 40, 50, 100, 200 and 250 from the rule
- * `z^(2^(a+b) - 1) = (z^(2^a - 1))^(2^b) * z^(2^b - 1)`, then squares five
- * times and multiplies by `z^11`: 254 squarings and 11 multiplications, the
- * same for every `z`.
+ * `out = z^(2^250 - 1)` and `z11 = z^11`: the part of the exponent chain that
+ * `f25519Invert` and Ed25519's square root (`ed25519Pow22523`,
+ * `nish/crypto/ed25519`) share. The chain builds `z^(2^n - 1)` for n = 2, 4,
+ * 5, 10, 20, 40, 50, 100, 200 and 250 from the rule
+ * `z^(2^(a+b) - 1) = (z^(2^a - 1))^(2^b) * z^(2^b - 1)`: 251 squarings and 11
+ * multiplications, the same for every `z`. `out` and `z11` may not be `z`.
  */
-const f25519Invert = (out: i64[], z: i64[]): void => {
+export const f25519Pow250 = (out: i64[], z11: i64[], z: i64[]): void => {
   const z2: i64[] = f25519Zero()
-  const z11: i64[] = f25519Zero()
   const e2: i64[] = f25519Zero()
   const e5: i64[] = f25519Zero()
   const e10: i64[] = f25519Zero()
   const e50: i64[] = f25519Zero()
   const t: i64[] = f25519Zero()
-  const acc: i64[] = f25519Zero()
 
   f25519Square(z2, z)
   f25519Mul(e2, z2, z) // z^3 = z^(2^2 - 1)
@@ -300,17 +302,33 @@ const f25519Invert = (out: i64[], z: i64[]): void => {
   f25519SquareTimes(t, e5, 5)
   f25519Mul(e10, t, e5) // 2^10 - 1
   f25519SquareTimes(t, e10, 10)
-  f25519Mul(acc, t, e10) // 2^20 - 1
-  f25519SquareTimes(t, acc, 20)
-  f25519Mul(acc, t, acc) // 2^40 - 1
-  f25519SquareTimes(t, acc, 10)
+  f25519Mul(out, t, e10) // 2^20 - 1
+  f25519SquareTimes(t, out, 20)
+  f25519Mul(out, t, out) // 2^40 - 1
+  f25519SquareTimes(t, out, 10)
   f25519Mul(e50, t, e10) // 2^50 - 1
   f25519SquareTimes(t, e50, 50)
-  f25519Mul(acc, t, e50) // 2^100 - 1
-  f25519SquareTimes(t, acc, 100)
-  f25519Mul(acc, t, acc) // 2^200 - 1
-  f25519SquareTimes(t, acc, 50)
-  f25519Mul(acc, t, e50) // 2^250 - 1
+  f25519Mul(out, t, e50) // 2^100 - 1
+  f25519SquareTimes(t, out, 100)
+  f25519Mul(out, t, out) // 2^200 - 1
+  f25519SquareTimes(t, out, 50)
+  f25519Mul(out, t, e50) // 2^250 - 1
+}
+
+/**
+ * `out = z^(p - 2)`, which is `1 / z` by Fermat's little theorem, and zero for
+ * a zero `z` — what RFC 7748 §5 asks of the ladder's last step.
+ *
+ * p - 2 = 2^255 - 21 = (2^250 - 1) * 2^5 + 11, so the exponent is 250 ones
+ * followed by `01011`: `f25519Pow250`, then five squarings and a
+ * multiplication by `z^11` — 256 squarings and 12 multiplications, the same
+ * for every `z`.
+ */
+export const f25519Invert = (out: i64[], z: i64[]): void => {
+  const z11: i64[] = f25519Zero()
+  const acc: i64[] = f25519Zero()
+  const t: i64[] = f25519Zero()
+  f25519Pow250(acc, z11, z)
   f25519SquareTimes(t, acc, 5)
   f25519Mul(out, t, z11) // 2^255 - 21
 }
@@ -320,7 +338,7 @@ const f25519Invert = (out: i64[], z: i64[]): void => {
  * same instructions either way: the mask is all ones or all zeros, and the
  * swap is the masked xor of the two.
  */
-const f25519Swap = (f: i64[], g: i64[], bit: i64): void => {
+export const f25519Swap = (f: i64[], g: i64[], bit: i64): void => {
   if (toI32(f.length) < 10 || toI32(g.length) < 10) {
     return
   }
@@ -341,7 +359,7 @@ const f25519Swap = (f: i64[], g: i64[], bit: i64): void => {
  * `[p, 2^255)` is neither refused nor adjusted: §5 has it processed as its
  * residue, and the arithmetic does that by itself.
  */
-const f25519Decode = (bytes: u8[]): i64[] => {
+export const f25519Decode = (bytes: u8[]): i64[] => {
   const f: i64[] = new Array<i64>(10)
   if (toI32(bytes.length) < 32) {
     return f
@@ -382,7 +400,7 @@ const f25519Decode = (bytes: u8[]): i64[] => {
  * when the value is at least p — so the element adds `19 * q` and drops bit
  * 255, which is subtracting `p * q`.
  */
-const f25519Encode = (f: i64[]): u8[] => {
+export const f25519Encode = (f: i64[]): u8[] => {
   const h: i64[] = new Array<i64>(10)
   f25519Copy(h, f)
   f25519Carry(h)

package/std/crypto/x509-random.ts

@@ -0,0 +1,71 @@
+/**
+ * `nish/crypto/x509-random` — the private key and the serial number
+ * `nish/crypto/x509`'s `x509MintSelfSigned` needs, drawn from the operating
+ * system's CSPRNG, and the mint that draws its own serial.
+ *
+ *     import { Secret, wipe } from "nish:secret";
+ *     import { x509DrawP256Key, x509MintSelfSignedDrawn } from "nish/crypto/x509-random";
+ *
+ *     const priv: Secret<u8[]> = x509DrawP256Key();
+ *     const der: u8[] | null = x509MintSelfSignedDrawn(priv, "localhost", toI64(Date.now()), 14);
+ *     // ... present `der` and sign the handshake with `priv` ...
+ *     wipe(priv);
+ *
+ * **Native only.** Every function here reaches `crypto.getRandomValues`, so a
+ * program that imports this module does not compile for wasm32, which has no
+ * entropy to reach. That is why it is a module of its own: `nish/crypto/x509`
+ * takes the key and the serial as arguments and imports nothing from here, so
+ * a wasm32 program can still parse, verify and mint with bytes it was handed
+ * (X509-6, docs/security/crypto-x509.md).
+ */
+import { Secret, secret, wipe } from "nish:secret"
+import { P256_SCALAR_SIZE, p256PublicKey } from "nish/crypto/p256"
+import { X509_MAX_SERIAL, x509MintSelfSigned } from "nish/crypto/x509"
+
+/**
+ * A fresh P-256 private key: `P256_SCALAR_SIZE` bytes from
+ * `crypto.getRandomValues`, drawn again until they hold a scalar in [1, n),
+ * which `p256PublicKey` is the test of. Rejection rather than reduction mod n,
+ * so every key is equally likely; a draw is refused with odds below 2^-32. A
+ * refused draw is wiped before the next, and the caller wipes the one
+ * returned.
+ */
+export const x509DrawP256Key = (): Secret<u8[]> => {
+  while (true) {
+    const drawn: u8[] = new Array<u8>(P256_SCALAR_SIZE)
+    crypto.getRandomValues(drawn)
+    const key: Secret<u8[]> = secret(drawn)
+    if (p256PublicKey(key) !== null) {
+      return key
+    }
+    wipe(key)
+  }
+}
+
+/**
+ * A fresh serial number for `x509MintSelfSigned`: `X509_MAX_SERIAL` (20) bytes
+ * from `crypto.getRandomValues` with the first one's top two bits set to `01`,
+ * so the INTEGER is positive, never zero, and always twenty octets long — 158
+ * random bits, past the 64 the CA/Browser Forum asks of a serial. A serial is
+ * public, written into the certificate, so it is a plain array.
+ */
+export const x509DrawSerial = (): u8[] => {
+  const serial: u8[] = new Array<u8>(X509_MAX_SERIAL)
+  crypto.getRandomValues(serial)
+  serial[0] = (serial[0] & toU8(0x3f)) | toU8(0x40)
+  return serial
+}
+
+/**
+ * `x509MintSelfSigned(priv, commonName, notBeforeMs, days, x509DrawSerial())`:
+ * the self-signed certificate with a serial drawn here, `null` for everything
+ * the mint answers `null` for. The key stays the caller's, since the server
+ * that presents the certificate signs its handshakes with it; draw one with
+ * `x509DrawP256Key`.
+ */
+export const x509MintSelfSignedDrawn = (
+  priv: Secret<u8[]>,
+  commonName: string,
+  notBeforeMs: i64,
+  days: i32
+): u8[] | null => x509MintSelfSigned(priv, commonName, notBeforeMs, days, x509DrawSerial())

package/std/crypto/x509.ts

@@ -5,15 +5,13 @@
  * pins by its SHA-256.
  *
  *     import { x509MintSelfSigned, x509CertificateHash, derToPem } from "nish/crypto/x509";
+ *     // Native only: a program that imports this does not compile for wasm32, which has no entropy.
+ *     import { x509DrawP256Key, x509DrawSerial } from "nish/crypto/x509-random";
  *
- *     // Both secrets come from the kernel's CSPRNG; a predictable key or serial is the caller's bug.
- *     const drawn: u8[] = new Array<u8>(32);
- *     crypto.getRandomValues(drawn);
- *     const priv: Secret<u8[]> = secret(drawn); // nish:secret; p256PublicKey(priv) === null: draw again (odds 2^-32)
- *     const serial: u8[] = new Array<u8>(16);
- *     crypto.getRandomValues(serial);
- *     serial[0] = serial[0] & toU8(0x7f);   // positive, so it stays 16 octets
- *     const der: u8[] | null = x509MintSelfSigned(priv, "localhost", toI64(Date.now()), 14, serial);
+ *     // Both come from the kernel's CSPRNG; a predictable key or serial is the caller's bug.
+ *     // A wasm32 program is handed them instead, and passes them in as they are passed here.
+ *     const priv: Secret<u8[]> = x509DrawP256Key();
+ *     const der: u8[] | null = x509MintSelfSigned(priv, "localhost", toI64(Date.now()), 14, x509DrawSerial());
  *     wipe(priv);
  *     // x509CertificateHash(der) is what serverCertificateHashes names;
  *     // derToPem(der, "CERTIFICATE") is the file a TLS stack loads.
@@ -68,14 +66,16 @@
  * parameters so the golden certificate is deterministic; a caller passes
  * `Date.now()` and, for the key and the serial, bytes from
  * `crypto.getRandomValues`. This module does not draw them itself,
- * because a call to the operating system would stop it compiling for wasm32.
+ * because a call to the operating system would stop it compiling for wasm32;
+ * `nish/crypto/x509-random`, which this module does not import, draws both
+ * for a native program (X509-6).
  *
  * **Constant time.** A private key is the one secret that passes through here:
  * it is base64-decoded from PEM, lifted out of its DER, and handed to
- * `nish/crypto/p256`. Base64 maps a character to its sextet and back by
- * arithmetic on range masks, as `nish/crypto/base64url` does, and folds a bad
- * character into one word read after the whole text, so neither a branch nor a
- * table index depends on the key's bytes. PEM's framing is found by comparing
+ * `nish/crypto/p256`. Base64 is `nish/crypto/base64url`'s `base64StdPadDecode`,
+ * which maps a character to its sextet by arithmetic on range masks and folds a
+ * bad character into one word read after the whole text, so neither a branch
+ * nor a table index depends on the key's bytes. PEM's framing is found by comparing
  * the start of each line with the fixed `-----BEGIN ` and `-----END `, which no
  * base64 character matches, so those comparisons end on a line's first byte
  * whatever the key is. The DER reader branches on tags and
@@ -96,6 +96,7 @@
  * (`docs/wp26-stdlib.md` §3e).
  */
 import { Secret, secret, wipe } from "nish:secret"
+import { base64StdPadDecode, base64StdPadEncode } from "nish/crypto/base64url"
 import { p256PublicKey, p256SignSha256, p256VerifySha256 } from "nish/crypto/p256"
 import { sha256 } from "nish/crypto/sha256"
 
@@ -704,124 +705,9 @@ const x509Bytes = (text: string): u8[] => {
 }
 
 // ---------------------------------------------------------------------------
-// PEM (RFC 7468) and standard base64 (RFC 4648 §4)
+// PEM (RFC 7468), over `nish/crypto/base64url`'s padded base64
 // ---------------------------------------------------------------------------
 
-/**
- * All ones when `lo <= c <= hi`, else zero, without a branch; `c` is a byte or
- * a sextet. The subtractions are `u32`'s, which wrap by definition, rather
- * than checked `i32` ones, whose check would be a branch on a byte of what may
- * be a private key's PEM; the sign bit `>> 31` reads is the same.
- * `x509Base64CharOf` and `x509Base64SextetOf` sum in `u32` for the same reason.
- */
-const x509RangeMask = (c: i32, lo: i32, hi: i32): i32 =>
-  toI32((toU32(lo) - 1 - toU32(c)) & (toU32(c) - toU32(hi) - 1)) >> 31
-
-/**
- * The base64 character for the sextet `v`: `'A' + v`, stepped by the gap to
- * each later range it has reached — 26 lands on `a`, 52 on `0`, 62 on `+` and
- * 63 on `/`.
- */
-const x509Base64CharOf = (v: i32): i32 =>
-  toI32(
-    65 +
-      toU32(v) +
-      toU32(x509RangeMask(v, 26, 63) & 6) -
-      toU32(x509RangeMask(v, 52, 63) & 75) -
-      toU32(x509RangeMask(v, 62, 63) & 15) +
-      toU32(x509RangeMask(v, 63, 63) & 3)
-  )
-
-/** The sextet the byte `c` stands for in base64, or `-1` when it is not in the alphabet. */
-const x509Base64SextetOf = (c: i32): i32 => {
-  const upper: i32 = x509RangeMask(c, 65, 90)
-  const lower: i32 = x509RangeMask(c, 97, 122)
-  const digit: i32 = x509RangeMask(c, 48, 57)
-  const plus: i32 = x509RangeMask(c, 43, 43)
-  const slash: i32 = x509RangeMask(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 base64, as one line. */
-const x509Base64Encode = (data: u8[]): string => {
-  const parts: string[] = []
-  let acc: i32 = 0
-  let bits: i32 = 0
-  for (let k: i32 = 0; k < toI32(data.length); k++) {
-    acc = ((acc << 8) | toI32(data[k])) & 0xfff
-    bits = bits + 8
-    while (bits >= 6) {
-      bits = bits - 6
-      parts.push(String.fromCharCode(x509Base64CharOf((acc >> bits) & 63)))
-    }
-  }
-  if (bits > 0) {
-    parts.push(String.fromCharCode(x509Base64CharOf((acc << (6 - bits)) & 63)))
-  }
-  // One `=` for a final group of two bytes, two for one byte.
-  const tail: i32 = toI32(data.length) % 3
-  if (tail > 0) {
-    parts.push(tail === 1 ? "==" : "=")
-  }
-  return parts.join("")
-}
-
-/**
- * The bytes of padded 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). Where the padding is
- * depends on the length alone; the characters themselves are read by masks and
- * judged once, after the last.
- */
-const x509Base64Decode = (text: string): u8[] | null => {
-  const n: i32 = toI32(text.length)
-  if (n === 0 || (n & 3) !== 0) {
-    return null
-  }
-  let pad: i32 = 0
-  if (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
-  for (let k: i32 = 0; k < toI32(text.length); k++) {
-    // The padding is past `chars`, and is not data; which positions those are
-    // is a fact about the length.
-    if (k < chars) {
-      const v: i32 = x509Base64SextetOf(toI32(text.charCodeAt(k)))
-      bad = bad | (v >> 31)
-      acc = ((acc << 6) | (v & 63)) & 0xfff
-      bits = bits + 6
-      if (bits >= 8) {
-        bits = 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) & 0xff)
-        }
-        j = j + 1
-      }
-    }
-  }
-  bad = bad | (acc & ((1 << bits) - 1))
-  if (bad !== 0) {
-    return null
-  }
-  return out
-}
-
 /** Whether `text` starts with `prefix`. */
 const x509StartsWith = (text: string, prefix: string): boolean => {
   const n: i32 = toI32(prefix.length)
@@ -841,7 +727,7 @@ const x509EndsWith = (text: string, suffix: string): boolean => {
  * ending in a line feed.
  */
 export const derToPem = (der: u8[], label: string): string => {
-  const body: string = x509Base64Encode(der)
+  const body: string = base64StdPadEncode(der)
   const n: i32 = toI32(body.length)
   const lines: string[] = [`-----BEGIN ${label}-----`]
   for (let at: i32 = 0; at < n; at = at + 64) {
@@ -894,7 +780,10 @@ export const pemToDer = (pem: string, label: string): u8[][] | null => {
       }
       // Every block is decoded, whatever its label: a malformed block beside the
       // one asked for is refused, not skipped (docs/security/crypto-x509.md, X509-1).
-      const der: u8[] | null = x509Base64Decode(body.join(""))
+      // An empty body is refused: a block with no DER is malformed, though
+      // the empty text is base64 for no bytes.
+      const text: string = body.join("")
+      const der: u8[] | null = text.length === 0 ? null : base64StdPadDecode(text)
       if (der === null) {
         return null
       }