@blamejs/pki 0.5.16 → 0.5.18

package/lib/guard-secret.js

@@ -38,6 +38,10 @@ var intrinsic = require("./guard-intrinsic");
 // wiping means; reading `call` off the captured function would let them decide it again, since
 // that function is still the one sitting on the prototype (see guard-intrinsic).
 var _fill = intrinsic.uncurry(Uint8Array.prototype.fill);
+// The join that produces the buffer cipherFinish hands back. Captured for the same reason as
+// the fill: a replaced `Buffer.concat` decides what the caller receives, and it would receive it
+// while the two intermediates this module is responsible for clearing were cleared as promised.
+var _concat = intrinsic.bufferConcat;
 
 // zeroize(value, ErrorClass, code, label) -> the same object, cleared.
 //   value      : a Buffer / TypedArray the TOOLKIT allocated, or null / undefined
@@ -94,4 +98,44 @@ function zeroizeAll(list, ErrorClass, code, label) {
   return list;
 }
 
-module.exports = { zeroize: zeroize, zeroizeAll: zeroizeAll };
+// cipherFinish(transform, input, ErrorClass, code, label) -> the output, as one fresh buffer
+//   transform : a node:crypto Cipher or Decipher the CALLER built and configured (key, iv, AAD,
+//               auth tag, padding mode). This guard performs the two calls and nothing else.
+//   input     : the bytes to feed it.
+//
+// The single place this toolkit runs a configured cipher to completion, because
+// `Buffer.concat([c.update(x), c.final()])` abandons a copy on BOTH of its exits and the leak is
+// invisible at the call site.
+//
+// On a DECIPHER the abandoned copy is plaintext. `update` returns the recovered plaintext while
+// `final` is what decides whether the message was authentic at all -- a GCM tag mismatch, a CBC
+// padding failure -- so on a forged message the whole plaintext exists before anything has judged
+// it, and the `concat` never runs: that buffer becomes unreferenced garbage holding readable
+// plaintext. RFC 5083 sec. 1 requires a receiver whose integrity check fails to destroy the
+// plaintext, and withholding it from the caller is not destroying it. On the success path `concat`
+// COPIES, so the update buffer is a second full copy the caller never receives and nothing else
+// will ever clear.
+//
+// It covers the ENCRYPT direction too, where the intermediates are ciphertext and clearing them
+// buys little. That is deliberate: any rule for which of the two directions must clear is a
+// judgment made at each call site, and the sites where it is wrong are the ones nobody re-reads.
+// One shape, cleared everywhere, needs no such judgment -- and the encrypt intermediates of a
+// key-wrap are not obviously worthless to an attacker either.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape \.update\s*\([\s\S]{0,300}?\)\s*,\s*[A-Za-z_$][\w$]*\s*\.\s*final\s*\(\s*\)
+function cipherFinish(transform, input, ErrorClass, code, label) {
+  var head = null, tail = null;
+  try {
+    head = transform.update(input);
+    tail = transform.final();
+    // Always a fresh copy, never `head` itself: the returned buffer belongs to the caller and the
+    // two intermediates have to be clearable independently of it.
+    return _concat([head, tail]);
+  } finally {
+    zeroize(head, ErrorClass, code, label);
+    zeroize(tail, ErrorClass, code, label);
+  }
+}
+
+module.exports = { zeroize: zeroize, zeroizeAll: zeroizeAll, cipherFinish: cipherFinish };

package/lib/hpke.js

@@ -5,6 +5,7 @@
  * @module pki.hpke
  * @nav        Protocols
  * @title      HPKE
+ * @fullname   HPKE (Hybrid Public Key Encryption, RFC 9180)
  * @intro Hybrid Public Key Encryption (RFC 9180) -- the standard construction
  *   behind TLS Encrypted Client Hello, MLS, and OHTTP that turns a recipient KEM
  *   public key into an encapsulated key plus an AEAD-encrypting context. This is
@@ -319,7 +320,7 @@ Context.prototype.seal = function (aad, pt) {
   var nonce = this._nonce();
   var c = nodeCrypto.createCipheriv(aead.cipher, this._key, nonce, { authTagLength: aead.Nt });
   if (aad && aad.length) c.setAAD(aad);
-  var body = concat([c.update(_buf(pt)), c.final()]);
+  var body = guard.secret.cipherFinish(c, _buf(pt), HpkeError, "hpke/bad-input", "a seal intermediate");
   var ct = concat([body, c.getAuthTag()]);
   this._inc();
   return ct;
@@ -335,7 +336,10 @@ Context.prototype.open = function (aad, ct) {
   if (aad && aad.length) d.setAAD(aad);
   d.setAuthTag(ct.subarray(ct.length - aead.Nt));
   var pt;
-  try { pt = concat([d.update(ct.subarray(0, ct.length - aead.Nt)), d.final()]); }
+  // Through the shared guard so the recovered plaintext is destroyed when the AEAD tag does not
+  // check out (RFC 9180 sec. 5.2 gives open one outcome on failure, and it is not a copy left in
+  // the heap), and so the success path's abandoned intermediate is cleared too.
+  try { pt = guard.secret.cipherFinish(d, ct.subarray(0, ct.length - aead.Nt), HpkeError, "hpke/bad-input", "the recovered plaintext"); }
   catch (e) { throw _err("hpke/open-failed", "AEAD authentication failed (RFC 9180 sec. 5.2)", e); }
   this._inc();
   return pt;

package/lib/http-transport.js

@@ -5,6 +5,7 @@
  * @module     pki.transport
  * @nav        Protocols
  * @title      Transport
+ * @fullname   HTTP transport for OCSP, CRL, EST and ACME requests
  * @order      195
  * @slug       transport
  *

package/lib/inspect.js

@@ -5,6 +5,7 @@
  * @module pki.inspect
  * @nav        Tooling
  * @title      Inspect
+ * @fullname   Inspect: render any PKI structure as readable text
  * @intro Human-readable inspection of a parsed certificate: the pure-JS
  *   equivalent of `openssl x509 -text`. `certificate(input)` ingests a PEM string,
  *   a DER Buffer, or an already-parsed certificate and returns a familiar

package/lib/jose.js

@@ -5,6 +5,7 @@
  * @module     pki.jose
  * @nav        Protocols
  * @title      JOSE (JWS / JWK)
+ * @fullname   JOSE: JWS signatures and JWK keys
  * @order      10
  * @slug       jose
  *
@@ -456,7 +457,7 @@ async function verify(jws, opts) {
  *   payload: Buffer      // the raw payload octets ("" for POST-as-GET)
  *   key: CryptoKey       // the private signing key
  *   profile: string      // default "acme-outer"
- *   jwk: object          // the public JWK, when the header embeds jwk
+ *   jwk: object          // the public JWK, in kid mode (a header that embeds jwk supplies its own)
  *
  * @example
  *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
@@ -465,11 +466,38 @@ async function verify(jws, opts) {
  *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" };
  *   var jws = await pki.jose.sign({ protected: hdr, payload: Buffer.from("{}"), key: priv });
  */
+// The public JWK has two sources and the embedded one wins, so opts.jwk is read only in kid mode.
+// Supplied alongside a header that embeds its own, it selected nothing: the signature parameters
+// came from the header's key while the caller had named a different one.
 var _SIGN_KEYS = { protected: 1, payload: 1, key: 1, jwk: 1, profile: 1 };
+var _SIGN_KEYS_EMBEDDED_JWK = { protected: 1, payload: 1, key: 1, profile: 1 };
 async function sign(opts) {
   opts = opts || {};
+  // The options are checked BEFORE the header is touched. Serializing it runs the caller's own code
+  // -- a toJSON, an accessor -- and that code can delete an option from the very bag being checked,
+  // so a misspelling reached the door already removed and the message went out signed.
   guard.identifier.assertKnownKeys(opts, _SIGN_KEYS, E, "jose/bad-input", "unknown pki.jose.sign option ");
-  var header = opts.protected;
+  // The header is then serialized ONCE, and every read below comes from a snapshot of those exact
+  // bytes: the header validated, the header embedded in the JWS and the key confirmed against the
+  // produced signature are then all the same values. Read live, a caller getter answers each of
+  // those questions separately -- assertPublicJwk sees a public JWK while the bytes that ship carry
+  // the private one, and the door sees a jwk-mode header while the signer sees a kid-mode one.
+  var headerJson;
+  try { headerJson = JSON.stringify(opts.protected); }
+  catch (e) { throw E("jose/bad-header", "the protected header must be JSON-serializable", e); }
+  // Read back through the same bounded reader a received JWS goes through, so a header this side
+  // produces is held to the caps and the duplicate-member rule the other side enforces.
+  var headerBytes = headerJson === undefined ? null : Buffer.from(headerJson, "utf8");
+  var header = headerBytes === null ? opts.protected : parseJson(headerBytes);
+  // Which of the two key sources is in force is known only once the header has been read, so the
+  // narrower table runs here. It re-walks the bag, which also catches a name that code added.
+  var embedsJwk = !!(header && typeof header === "object" && header.jwk);
+  if (embedsJwk) {
+    guard.identifier.assertKnownKeys(opts, _SIGN_KEYS_EMBEDDED_JWK, E, "jose/bad-input", function (k) {
+      return "unknown pki.jose.sign option " + JSON.stringify(k) +
+        (k === "jwk" ? "; the protected header already embeds the public JWK" : "");
+    });
+  }
   var payload = opts.payload;
   if (!Buffer.isBuffer(payload)) throw E("jose/bad-input", "payload must be a Buffer (empty Buffer for POST-as-GET)");
   // Re-view before the length===0 fast-path: a DETACHED payload reads as zero-length
@@ -493,7 +521,7 @@ async function sign(opts) {
   // also PUBLISHED to the server, so it must be public-only: an accidentally exported
   // private JWK must never be serialized into the protected header.
   if (header.jwk) { _assertKeyType(checked.algRow, header.jwk); assertPublicJwk(header.jwk); }
-  var protectedB64 = b64uEncode(Buffer.from(JSON.stringify(header), "utf8"));
+  var protectedB64 = b64uEncode(headerBytes);   // the exact bytes every check above read
   var payloadB64 = payload.length === 0 ? "" : b64uEncode(payload);
   var signingInput = Buffer.from(protectedB64 + "." + payloadB64, "ascii");
   var jwk = header.jwk || opts.jwk || {};

package/lib/key.js

@@ -5,6 +5,7 @@
  * @module     pki.key
  * @nav        Signing
  * @title      Keys
+ * @fullname   Key generation, import and export (RSA, EC, EdDSA, ML-DSA)
  * @intro The key-material lifecycle: export / import a private key as PKCS#8 (`OneAsymmetricKey`,
  *   RFC 5958) or a public key as SPKI (RFC 5280 sec. 4.1.2.7), encrypt / decrypt a private key under
  *   RFC 8018 PBES2 (`EncryptedPrivateKeyInfo`, PBKDF2 + AES-CBC-Pad), and `generate` /
@@ -138,7 +139,7 @@ async function encrypt(privateKey, password, opts) {
   try { dk = nodeCrypto.pbkdf2Sync(pwK.bytes, salt, iterations, keyBits / 8, prfNode); }
   finally { if (pwK.owned) guard.secret.zeroize(pwK.bytes, KeyError, "key/bad-input", "the password encoding"); }
   try {
-    var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits);
+    var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits, KeyError, "key/bad-input");
     var epki = b.sequence([pbes2.pbes2AlgId(salt, iterations, prf, cipherName, iv), b.octetString(ciphertext)]);
     pkcs8.parseEncrypted(epki);   // self-check: the produced EncryptedPrivateKeyInfo re-parses
     return opts.pem ? pkcs8.pemEncode(epki, "ENCRYPTED PRIVATE KEY") : epki;

package/lib/lint.js

@@ -5,6 +5,7 @@
  * @module pki.lint
  * @nav        Tooling
  * @title      Lint
+ * @fullname   Certificate linting against CA/Browser Forum requirements
  * @intro The certificate LINTING engine -- the zlint / pkilint of JavaScript. It walks an
  *   ALREADY-PARSED certificate (from `pki.schema.x509.parse`, whose extension values it
  *   decodes with the shared RFC 5280 decoders) and emits graded, advisory FINDINGS: each

package/lib/merkle.js

@@ -5,6 +5,7 @@
  * @module     pki.merkle
  * @nav        Transparency
  * @title      Merkle
+ * @fullname   Merkle trees: inclusion and consistency proofs (RFC 6962)
  * @order      220
  * @slug       merkle
  *

package/lib/ocsp.js

@@ -5,6 +5,7 @@
  * @module pki.ocsp
  * @nav        Revocation
  * @title      OCSP
+ * @fullname   OCSP (Online Certificate Status Protocol) revocation checking
  * @intro The producing + client-facing half of RFC 6960 Online Certificate Status Protocol:
  *   build a status request over a certificate (`pki.ocsp.buildRequest`), build and sign a status
  *   response as an authorized responder (`pki.ocsp.sign`), emit an unsigned error response

package/lib/oid.js

@@ -5,6 +5,7 @@
  * @module     pki.oid
  * @nav        Core
  * @title      Object Identifiers
+ * @fullname   OID registry: resolve object identifiers by name or dotted form
  * @order      40
  * @slug       oid
  *

package/lib/path-validate.js

@@ -6,6 +6,7 @@
  * @module pki.path
  * @nav Path validation
  * @title Certification path validation (RFC 5280 6)
+ * @fullname Certificate chain validation (RFC 5280 sec. 6 path validation)
  * @intro
  * RFC 5280 6 certification-path validation as a pure, re-entrant algorithm
  * over already-parsed certificates. `pki.path.validate(path, opts)` runs the

package/lib/pbes2.js

@@ -133,13 +133,21 @@ function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
 
 // AES-CBC content encryption / decryption (PKCS#7 pad). decrypt's final() throws on bad pad, and the caller
 // collapses that into its uniform decrypt-failed verdict.
-function cbcEncrypt(key, iv, plaintext, keyBits) {
+// cbcEncrypt(key, iv, plaintext, keyBits, E, code) -> the ciphertext.
+// Takes the caller's typed error for the same reason cbcDecrypt does: the cipher runs through the
+// shared guard, whose one throw has to keep the calling domain's own code.
+function cbcEncrypt(key, iv, plaintext, keyBits, E, code) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([c.update(plaintext), c.final()]);
+  return guard.secret.cipherFinish(c, plaintext, E, code, "a content-encryption intermediate");
 }
-function cbcDecrypt(key, iv, ct, keyBits) {
+// cbcDecrypt(key, iv, ct, keyBits, E, code) -> the recovered plaintext.
+// Takes the caller's typed error the way rc2.cbcDecrypt does, so a refusal keeps its own domain.
+function cbcDecrypt(key, iv, ct, keyBits, E, code) {
   var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([d.update(ct), d.final()]);
+  // A wrong key fails inside final(), on the padding check, and update() has by then produced every
+  // block but the last. Through the guard so that partial plaintext is cleared on both exits rather
+  // than abandoned readable on exactly the path an attacker induces.
+  return guard.secret.cipherFinish(d, ct, E, code, "the partially recovered plaintext");
 }
 
 // Higher-level PBES2 AES-CBC encrypt: derive an AES key from PRE-FORMATTED password bytes (the caller owns
@@ -160,11 +168,11 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   // is not cleared: the caller formatted it and may still own the buffer.
   var key = nodeCrypto.pbkdf2Sync(pwBytes, salt, iterations, keyBits / 8, prfNode);
   try {
-    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits) };
+    return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits, E, prefix + "/bad-input") };
   } finally {
     // E is the caller's error FACTORY, not a class; guard-secret delegates its only throw to
-    // guard-bytes, which constructs.  yields the error the factory returns, so the
-    // currency is compatible -- and the throw is unreachable here regardless, because a freshly
+    // guard-bytes, which constructs. `new` on a factory yields the object the factory returns, so
+    // the currency is compatible -- and the throw is unreachable here regardless, because a freshly
     // allocated pbkdf2 buffer cannot be detached.
     guard.secret.zeroize(key, E, prefix + "/bad-input", "the password-derived encryption key");
   }
@@ -208,7 +216,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
     if (budget.rounds < 0) throw E(prefix + "/iteration-limit", "the aggregate PBKDF2 key-derivation work exceeds the budget (a hostile many-element input)");
   }
   var dk = nodeCrypto.pbkdf2Sync(pwBytes, pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
-  try { return cbcDecrypt(dk, iv, ciphertext, keyBits); }
+  try { return cbcDecrypt(dk, iv, ciphertext, keyBits, E, prefix + "/decrypt-failed"); }
   catch (_e) { throw E(prefix + "/decrypt-failed", "decryption failed"); }
   finally { guard.secret.zeroize(dk, E, prefix + "/bad-input", "the password-derived decryption key"); }
 }