@amritk/nish-x86_64-linux 0.16.0 → 0.18.0

package/std/crypto/x509.ts

@@ -7,12 +7,14 @@
  *     import { x509MintSelfSigned, x509CertificateHash, derToPem } from "nish/crypto/x509";
  *
  *     // Both secrets come from the kernel's CSPRNG; a predictable key or serial is the caller's bug.
- *     const priv: u8[] = new Array<u8>(32);
- *     crypto.getRandomValues(priv);          // p256PublicKey(priv) === null: draw again (odds 2^-32)
+ *     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);
+ *     wipe(priv);
  *     // x509CertificateHash(der) is what serverCertificateHashes names;
  *     // derToPem(der, "CERTIFICATE") is the file a TLS stack loads.
  *
@@ -31,7 +33,8 @@
  * `null`, never a panic. The reader looks at what this module uses — the
  * version, serial, algorithms, names as opaque bytes, validity, the subject
  * public key and the signature — and checks the order of what follows the key
- * (`[1]`, `[2]`, `[3]`) without parsing extensions.
+ * (`[1]`, `[2]`, `[3]`) without parsing extensions; the mint writes two of its
+ * own (below).
  *
  * **PEM is RFC 7468's strict grammar**, with standard base64 (`+` and `/`,
  * padded with `=`), not `base64url`: 64 characters a line and a shorter last
@@ -45,15 +48,26 @@
  * requirements"): X.509 v3, an ECDSA P-256 key signed with ecdsa-with-SHA256,
  * and a validity period of at most fourteen days — `notAfter - notBefore`,
  * which is what Chromium compares, so `days` is 1 to 14. Subject and issuer
- * are the same single common name, as a UTF8String. It carries **no
- * extensions**: the specification requires none, a browser checking a pinned
- * hash does no path building for basicConstraints or keyUsage to inform, and
- * every extension would be one more field whose absence is part of the
- * contract a hash pins. OpenSSL verifies it as its own trust anchor all the
- * same (`tests/link/crypto_x509`'s header has the commands). The key, the
- * serial and the time are 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,
+ * are the same single common name, as a UTF8String. It carries **two
+ * extensions, both critical and both constant**: basicConstraints with cA
+ * FALSE and keyUsage with digitalSignature alone. The W3C text requires no
+ * extension, but Chromium does: the verifier behind `serverCertificateHashes`,
+ * quiche's `WebTransportFingerprintProofVerifier`, parses the certificate
+ * with `CertificateView::ParseSingleCertificate` before it compares the hash,
+ * and that answers null when `[3] extensions` is absent
+ * (`quiche/quic/core/crypto/certificate_view.cc:395`, at the quiche revision
+ * 62826931 Chromium 141 pins), so the handshake fails with
+ * CERTIFICATE_VERIFY_FAILED. It also holds every extension to `SEQUENCE {
+ * OID, BOOLEAN OPTIONAL, OCTET STRING }` (`:413`–`:432`) and reads
+ * subjectAltName only when one is present (`:434`), so no name is needed
+ * there. The two chosen say what the certificate is, an end entity whose key
+ * only signs handshakes, so a verifier that does build a path need not fall
+ * back on its defaults; OpenSSL verifies it as its own trust anchor
+ * (`tests/link/crypto_x509`'s header has the commands; X509-9 in
+ * docs/security/crypto-x509.md). The key, the serial and the time are
+ * 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.
  *
  * **Constant time.** A private key is the one secret that passes through here:
@@ -70,10 +84,18 @@
  * public key stored beside it compares public values. None of this is under
  * the disassembly check; it is discipline.
  *
+ * **The private key is a `Secret`** (`nish:secret`, docs/LANGUAGE.md
+ * "Secrets"). `x509ParseP256PrivateKey` answers one and `x509MintSelfSigned`
+ * takes one; the scalar is copied out of its DER once, into the `Secret`, and
+ * every block decoded from the PEM is wiped before the parse returns (X509-7,
+ * docs/security/crypto-x509.md). The PEM text is the caller's string, which
+ * nothing in the language can wipe.
+ *
  * Private names carry the `x509` prefix because a `std/` module's private
  * functions share the importing program's flat symbol namespace
  * (`docs/wp26-stdlib.md` §3e).
  */
+import { Secret, secret, wipe } from "nish:secret"
 import { p256PublicKey, p256SignSha256, p256VerifySha256 } from "nish/crypto/p256"
 import { sha256 } from "nish/crypto/sha256"
 
@@ -685,8 +707,15 @@ const x509Bytes = (text: string): u8[] => {
 // PEM (RFC 7468) and standard base64 (RFC 4648 §4)
 // ---------------------------------------------------------------------------
 
-/** All ones when `lo <= c <= hi`, else zero, without a branch; `c` is a byte or a sextet. */
-const x509RangeMask = (c: i32, lo: i32, hi: i32): i32 => ((lo - 1 - c) & (c - hi - 1)) >> 31
+/**
+ * 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
@@ -694,12 +723,14 @@ const x509RangeMask = (c: i32, lo: i32, hi: i32): i32 => ((lo - 1 - c) & (c - hi
  * 63 on `/`.
  */
 const x509Base64CharOf = (v: i32): i32 =>
-  65 +
-  v +
-  (x509RangeMask(v, 26, 63) & 6) -
-  (x509RangeMask(v, 52, 63) & 75) -
-  (x509RangeMask(v, 62, 63) & 15) +
-  (x509RangeMask(v, 63, 63) & 3)
+  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 => {
@@ -708,7 +739,12 @@ const x509Base64SextetOf = (c: i32): i32 => {
   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 & (c - 65)) | (lower & (c - 71)) | (digit & (c + 4)) | (plus & 62) | (slash & 63)
+  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)
 }
 
@@ -892,7 +928,7 @@ export const pemToDer = (pem: string, label: string): u8[][] | null => {
  * optional `[1]` public key, which must be the key's own. `null` otherwise,
  * or when the scalar is 0 or not below n.
  */
-const x509Sec1Key = (der: u8[], start: i32, end: i32, needCurve: boolean): u8[] | null => {
+const x509Sec1Key = (der: u8[], start: i32, end: i32, needCurve: boolean): Secret<u8[]> | null => {
   const seq: X509DerElement | null = x509DerExpect(der, start, end, X509_TAG_SEQUENCE)
   if (seq === null || seq.end !== end) {
     return null
@@ -905,7 +941,6 @@ const x509Sec1Key = (der: u8[], start: i32, end: i32, needCurve: boolean): u8[]
   if (key === null || key.end - key.start !== 32) {
     return null
   }
-  const priv: u8[] = x509DerSlice(der, key.start, key.end)
   let at: i32 = key.end
   let curve: boolean = false
   let stored: u8[] | null = null
@@ -935,12 +970,13 @@ const x509Sec1Key = (der: u8[], start: i32, end: i32, needCurve: boolean): u8[]
   if (at !== seq.end || (needCurve && !curve)) {
     return null
   }
-  // Refuses 0 and n and above, and gives the point to hold `stored` against.
+  // The scalar is copied out of the DER only once the structure is known to
+  // be sound, straight into the `Secret` that owns it (X509-7). The check
+  // refuses 0 and n and above, and gives the point to hold `stored` against.
+  const priv: Secret<u8[]> = secret(x509DerSlice(der, key.start, key.end))
   const pub: u8[] | null = p256PublicKey(priv)
-  if (pub === null) {
-    return null
-  }
-  if (stored !== null && !x509BytesEqual(stored, pub)) {
+  if (pub === null || (stored !== null && !x509BytesEqual(stored, pub))) {
+    wipe(priv)
     return null
   }
   return priv
@@ -954,7 +990,7 @@ const x509Sec1Key = (der: u8[], start: i32, end: i32, needCurve: boolean): u8[]
  * optional `[1]` public key, which must be a BIT STRING of the key's own point
  * (X509-8 in docs/security/crypto-x509.md).
  */
-const x509Pkcs8Key = (der: u8[]): u8[] | null => {
+const x509Pkcs8Key = (der: u8[]): Secret<u8[]> | null => {
   const total: i32 = toI32(der.length)
   const seq: X509DerElement | null = x509DerExpect(der, 0, total, X509_TAG_SEQUENCE)
   if (seq === null || seq.end !== total) {
@@ -1002,34 +1038,54 @@ const x509Pkcs8Key = (der: u8[]): u8[] | null => {
   if (at !== seq.end) {
     return null
   }
-  const priv: u8[] | null = x509Sec1Key(der, key.start, key.end, false)
+  const priv: Secret<u8[]> | null = x509Sec1Key(der, key.start, key.end, false)
   if (priv === null || stored === null) {
     return priv
   }
   // The same rule as the SEC1 key's own `[1]`: the stored point is the key's.
   const pub: u8[] | null = p256PublicKey(priv)
-  return pub !== null && x509BytesEqual(stored, pub) ? priv : null
+  if (pub === null || !x509BytesEqual(stored, pub)) {
+    wipe(priv)
+    return null
+  }
+  return priv
+}
+
+/** Zero every block `pemToDer` decoded: a private key's DER is key material, refused or not. */
+const x509WipeBlocks = (blocks: u8[][] | null): void => {
+  if (blocks === null) {
+    return
+  }
+  for (const block of blocks) {
+    wipe(block)
+  }
 }
 
 /**
- * The 32-byte P-256 private key in `pem`: one `EC PRIVATE KEY` block (SEC1,
- * RFC 5915, which must name its curve) or one `PRIVATE KEY` block (unencrypted
- * PKCS#8, RFC 5208 or RFC 5958), and not both. `null` for no such block or
- * more than one, for any curve but P-256, for a scalar of 0 or n or more, for
- * a stored public key that is not the key's own, and for anything malformed.
- * An `ENCRYPTED PRIVATE KEY` is a different label, and answers `null`.
+ * The 32-byte P-256 private key in `pem`, as the `Secret` it is: one `EC
+ * PRIVATE KEY` block (SEC1, RFC 5915, which must name its curve) or one
+ * `PRIVATE KEY` block (unencrypted PKCS#8, RFC 5208 or RFC 5958), and not both.
+ * `null` for no such block or more than one, for any curve but P-256, for a
+ * scalar of 0 or n or more, for a stored public key that is not the key's own,
+ * and for anything malformed. An `ENCRYPTED PRIVATE KEY` is a different label,
+ * and answers `null`. Every block decoded from `pem` is wiped before this
+ * returns, whichever answer it gives; `pem` itself is the caller's string,
+ * which nothing can wipe (X509-7 in docs/security/crypto-x509.md).
  */
-export const x509ParseP256PrivateKey = (pem: string): u8[] | null => {
+export const x509ParseP256PrivateKey = (pem: string): Secret<u8[]> | null => {
   const sec1: u8[][] | null = pemToDer(pem, "EC PRIVATE KEY")
   const pkcs8: u8[][] | null = pemToDer(pem, "PRIVATE KEY")
+  let key: Secret<u8[]> | null = null
   if (sec1 !== null && pkcs8 === null && toI32(sec1.length) === 1) {
     const der: u8[] = sec1[0]
-    return x509Sec1Key(der, 0, toI32(der.length), true)
-  }
-  if (pkcs8 !== null && sec1 === null && toI32(pkcs8.length) === 1) {
-    return x509Pkcs8Key(pkcs8[0])
-  }
-  return null
+    key = x509Sec1Key(der, 0, toI32(der.length), true)
+  } else if (pkcs8 !== null && sec1 === null && toI32(pkcs8.length) === 1) {
+    key = x509Pkcs8Key(pkcs8[0])
+  }
+  // X509-7: the decoded DER holds the scalar too, whichever block it was.
+  x509WipeBlocks(sec1)
+  x509WipeBlocks(pkcs8)
+  return key
 }
 
 // ---------------------------------------------------------------------------
@@ -1240,12 +1296,38 @@ export const x509VerifySignature = (cert: X509Certificate, issuer: X509Certifica
   return p256VerifySha256(issuer.publicKey, cert.tbs, rs)
 }
 
+/**
+ * The minted certificate's `[3] extensions`, whole, in DER. They do not depend
+ * on the key, the name or the time, so they are one constant block rather
+ * than a tree of `x509DerWrap` calls (`tests/link/crypto_x509` pins each
+ * octet, and `x509ParseCertificate` reads the result back):
+ *
+ *     a3 20                      [3] EXPLICIT, 32 octets
+ *       30 1e                    Extensions SEQUENCE, 30 octets
+ *         30 0c                  Extension (RFC 5280 §4.2.1.9)
+ *           06 03 55 1d 13       basicConstraints, 2.5.29.19
+ *           01 01 ff             critical TRUE
+ *           04 02 30 00          OCTET STRING { SEQUENCE {} }: cA FALSE is the
+ *                                DEFAULT, so DER leaves it out (X.690 §11.5)
+ *         30 0e                  Extension (RFC 5280 §4.2.1.3)
+ *           06 03 55 1d 0f       keyUsage, 2.5.29.15
+ *           01 01 ff             critical TRUE
+ *           04 04 03 02 07 80    OCTET STRING { BIT STRING, 7 unused bits,
+ *                                bit 0 digitalSignature }: DER drops a named
+ *                                bit list's trailing zero bits (X.690 §11.2.2)
+ */
+const x509MintExtensions = (): u8[] => [
+  0xa3, 0x20, 0x30, 0x1e, 0x30, 0x0c, 0x06, 0x03, 0x55, 0x1d, 0x13, 0x01, 0x01, 0xff, 0x04, 0x02, 0x30, 0x00,
+  0x30, 0x0e, 0x06, 0x03, 0x55, 0x1d, 0x0f, 0x01, 0x01, 0xff, 0x04, 0x04, 0x03, 0x02, 0x07, 0x80,
+]
+
 /**
  * A self-signed X.509 v3 certificate, in DER, for the P-256 key `priv`: subject
  * and issuer `CN=commonName`, valid from `notBeforeMs` (milliseconds since
  * 1970, rounded down to the second) for exactly `days` days, serial number
- * `serial`, and signed with ecdsa-with-SHA256 — see the module comment for why
- * it has no extensions. `null` when `days` is below 1 or above
+ * `serial`, carrying `x509MintExtensions`' basicConstraints and keyUsage, and
+ * signed with ecdsa-with-SHA256 — see the module comment for why Chromium
+ * needs an extension at all. `null` when `days` is below 1 or above
  * `X509_MAX_DAYS`, `notBeforeMs` is negative or the validity would end after
  * 9999, `commonName` is empty, longer than 64 bytes, not UTF-8 or holds a NUL
  * (it is written as a UTF8String), `priv` is not a P-256 private key, or
@@ -1254,7 +1336,7 @@ export const x509VerifySignature = (cert: X509Certificate, issuer: X509Certifica
  * bit of 20 random bytes, or use fewer).
  */
 export const x509MintSelfSigned = (
-  priv: u8[],
+  priv: Secret<u8[]>,
   commonName: string,
   notBeforeMs: i64,
   days: i32,
@@ -1312,6 +1394,7 @@ export const x509MintSelfSigned = (
     x509DerWrap(X509_TAG_SEQUENCE, [x509DerTimeAt(start), x509DerTimeAt(end)]),
     distinguished,
     spki,
+    x509MintExtensions(),
   ])
   const rs: u8[] | null = p256SignSha256(priv, tbs)
   if (rs === null) {