@blamejs/pki 0.5.4 → 0.5.5

package/lib/ocsp.js

@@ -57,14 +57,31 @@ var OID_EXTENDED_REVOKE = O("ocspExtendedRevoke");
 
 function _digest(wcHash, buf) { return subtle.digest(wcHash, buf).then(function (h) { return Buffer.from(h); }); }
 function _certOf(arg, what) {
-  if (arg && arg.subjectPublicKeyInfo && arg.tbsBytes) return arg;   // already parsed
-  var der;
-  if (Buffer.isBuffer(arg)) der = arg;
-  else if (arg instanceof Uint8Array) der = Buffer.from(arg);
-  else if (typeof arg === "string") { try { der = x509.pemDecode(arg); } catch (e) { throw _err("ocsp/bad-input", (what || "a certificate") + " PEM could not be decoded", e); } }
-  else throw _err("ocsp/bad-input", (what || "a certificate") + " must be a parsed certificate, a DER Buffer, or a PEM string");
-  try { return x509.parse(der); } catch (e) { throw _err("ocsp/bad-input", (what || "a certificate") + " is not a well-formed X.509 certificate", e); }
+  var label = what || "a certificate";
+  // Re-derived from the bytes its parser read, like every other certificate door. A CertID is an
+  // IDENTITY -- the issuer's name and key hashed, plus the serial -- so a certificate that names one
+  // identity while carrying another's signed bytes would have this verb ask about, or answer for,
+  // a certificate nobody issued.
+  return guard.parsed.acceptDerived(arg, "certificate", function (bytes) {
+    var der = bytes;
+    if (typeof bytes === "string") {
+      try { der = x509.pemDecode(bytes); } catch (e) { throw _err("ocsp/bad-input", label + " PEM could not be decoded", e); }
+    }
+    try { return x509.parse(der); } catch (e) { throw _err("ocsp/bad-input", label + " is not a well-formed X.509 certificate", e); }
+  }, _err, "ocsp/bad-input", label);
+}
+// The response, always parsed from the bytes the caller handed over. See verify's own comment for
+// why an object cannot be accepted here: the three parts of a signature check would come from three
+// independently-chosen properties. The claim is detected on any of the parsed-response fields, so a
+// caller who passes one is told what happened rather than getting a byte-parse fault about its type.
+var _RESPONSE_CLAIM = ["responseStatus", "basicResponse", "tbsResponseDataBytes"];
+function _responseFromBytes(response) {
+  return guard.parsed.fromTrustedSource(response, "ocspResponse", _RESPONSE_CLAIM, function (bytes) {
+    return ocspSchema.parseResponse(_toDer(bytes, "the OCSP response"));
+  }, _err, "ocsp/bad-input",
+  "the OCSP response must be its DER bytes, a PEM string, or an unmodified pki.schema.ocsp.parseResponse result: the signature, the algorithm that verifies it and the bytes it covers are separate properties of a parsed object, so a REBUILT response (Object.assign, spread, a JSON round-trip) could have the three describe different responses and is refused");
 }
+
 function _toDer(input, what) {
   if (Buffer.isBuffer(input)) return input;
   if (input instanceof Uint8Array) return Buffer.from(input);
@@ -456,13 +473,26 @@ function verify(response, opts) {
   if (opts.cert == null || opts.issuer == null) return Promise.reject(_err("ocsp/bad-input", "verify requires opts.cert and opts.issuer"));
   var parsed, cert, issuerCert, time;
   try {
-    parsed = (response && response.responseStatus) ? response : ocspSchema.parseResponse(_toDer(response, "the OCSP response"));
+    // The response is parsed from BYTES, always. A claimed-parsed response carries the signature,
+    // the algorithm that verifies it and the byte range it covers as three independent properties,
+    // so an object could pair one structure's tbsResponseDataBytes with another's signature -- and a
+    // signature the issuing CA made over a certificate it issued would verify as a ResponseData
+    // signature, returning status "good" for a certificate the responder never spoke about.
+    // Parsing here binds all three to one byte string. pki.schema.ocsp.parseResponse remains the
+    // parse-only route for a caller who wants the structure without a verdict.
+    parsed = _responseFromBytes(response);
     cert = _certOf(opts.cert, "the target certificate");
     issuerCert = _certOf(opts.issuer, "the issuer certificate");
     // The time drives the currency + responder-cert validity windows; an invalid Date fails closed
     // via _asDate (a NaN compares false against every bound, silently disabling both), never defaults.
     time = opts.time == null ? new Date() : _asDate(opts.time);
   } catch (e) { return Promise.reject(e); }
+  // The object parsed HERE goes to the verdict verb, not the caller's argument again. It carries the
+  // parser's record, so the verdict verb re-derives from the same recorded bytes -- one snapshot,
+  // read by both. Passing the caller's argument a second time would take a SECOND snapshot of it,
+  // and a shared-memory view can differ between the two: the nonce compared below would belong to
+  // one response and the signature verified to another, which is the split this whole mechanism
+  // exists to close.
   return pathValidate.verifyOcspResponse(parsed, cert, issuerCert, time, { historicalMode: opts.historicalMode === true }).then(function (verdict) {
     // A client that sent no nonce still gets the field, as null. Leaving it absent would make
     // "not requested" indistinguishable from "the field is not there yet" for a consumer reading

package/lib/path-validate.js

@@ -1178,7 +1178,10 @@ async function validate(path, opts) {
   // crypto amplification from an oversized path). Entry-point tier: throw.
   var maxCerts = guard.limits.cap(opts.maxPathCerts, "validate: opts.maxPathCerts", constants.LIMITS.PATH_MAX_CERTS, { E: E, code: "path/bad-input", min: 1 });
   if (path.length > maxCerts) throw E("path/bad-input", "validate: the certification path has " + path.length + " certificates, exceeding the maxPathCerts limit (" + maxCerts + ")");
-  var certs = path.map(function (c) { return (c && c.tbsBytes) ? c : x509.parse(c); });
+  // Through the same door `build` uses, and for the same reason: every certificate this walk decides
+  // over is re-derived from the bytes its parser read (see coerceCert), so a rebuilt object cannot
+  // present a genuine signed range alongside substituted fields.
+  var certs = path.map(function (c, ci) { return coerceCert(c, "validate: path[" + ci + "]"); });
   var n = certs.length;
   if (n < 1) throw E("path/empty-path", "validate: the certification path is empty");
   if (!opts.trustAnchor) throw E("path/bad-input", "validate: a trustAnchor is required");
@@ -1856,7 +1859,16 @@ function selectDelta(candidates) {
  *   typeof checker.check;                     // "function"
  */
 function crlChecker(crls, opts) {
-  var parsed = (crls || []).map(function (c) { return (c && c.tbsBytes) ? c : crl.parse(c); });
+  var parsed = (crls || []).map(function (c, ci) {
+    // Re-derived from the bytes the parser read, exactly as a certificate is. A CRL's answer is a
+    // verdict, and its signature covers a byte range while the revocation list and the scope
+    // extensions are separate properties of the parsed object: keep a correctly signed CRL's
+    // `tbsBytes` and signature, empty `revokedCertificates`, and the signature still verifies while
+    // a revoked certificate reports good. The scope fields fail the same way -- an emptied
+    // `crlExtensions` turns a scope-restricted CRL into one that answers for everything.
+    return guard.parsed.acceptDerived(c, "crl", crl.parse, E, "path/bad-input",
+      "crlChecker: crls[" + ci + "]");
+  });
   // RFC 5280 sec. 6.3.1(b): use-deltas is an INPUT to the algorithm. Default ON --
   // a caller holding a delta wants it used -- and turning it off never makes a
   // verdict weaker, only less determined.
@@ -2296,7 +2308,10 @@ cmsVerify.setEngine({ build: build, validate: validate, toAnchor: toAnchor,
  *   typeof checker.check;                       // "function"
  */
 function ocspChecker(responses) {
-  var parsed = (responses || []).map(function (r) { return (r && r.responseStatus) ? r : ocsp.parseResponse(r); });
+  // The same door verifyOcspResponse uses. This checker's responses reach the identical three-part
+  // signature check, so accepting a parsed object here on a truthy responseStatus would leave the
+  // door shut on one of the two ways into that check and open on the other.
+  var parsed = (responses || []).map(function (r) { return _ocspFromBytes(r); });
   return {
     check: async function (cert, issuer, ctx) {
       var time = ctx.time;
@@ -2346,14 +2361,14 @@ function ocspChecker(responses) {
 
 /**
  * @primitive  pki.path.verifyOcspResponse
- * @signature  pki.path.verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts?) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, reason }>
+ * @signature  pki.path.verifyOcspResponse(response, cert, issuerCert, time, opts?) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, reason }>
  * @since       0.2.22
  * @status      stable
  * @spec        RFC 6960
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
- * Verify a single already-parsed OCSP response for one certificate against its
- * already-parsed issuer certificate at `time` -- the lower-level primitive
+ * Verify a single OCSP response for one certificate
+ * against its already-parsed issuer certificate at `time` -- the lower-level primitive
  * `pki.ocsp.verify` composes after parsing its inputs (most callers want that
  * ergonomic entry, which also handles DER/PEM decoding and request-nonce
  * matching). It runs the EXACT SAME gates the path validator's `ocspChecker`
@@ -2374,6 +2389,16 @@ function ocspChecker(responses) {
  * `time` either way. `time` must be a valid `Date`. A malformed response's parse
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
+ * The response is its DER bytes, a PEM string, or an unmodified
+ * `pki.schema.ocsp.parseResponse` result. A REBUILT parsed response is refused. A
+ * signature check has three parts -- the signature, the algorithm that verifies it,
+ * and the bytes it covers -- and on a parsed object all three are separate properties:
+ * a genuine CA signature over a certificate that CA issued, relabelled, verifies as a
+ * ResponseData signature for a response that never existed. The parser marks what it
+ * returns, so those three are known to have been derived together from one byte
+ * string; `Object.assign`, spread and a JSON round-trip all drop the mark, which is
+ * exactly how such an object is assembled.
+ *
  * @example
  *   var ca = await pki.key.generate("Ed25519");
  *   var caKey = await pki.key.export(ca.privateKey);
@@ -2389,11 +2414,49 @@ function ocspChecker(responses) {
  *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
  *     { cert: caDer, key: caKey });
  *   var cert = pki.schema.x509.parse(leafDer), issuerCert = pki.schema.x509.parse(caDer);
- *   var resp = pki.schema.ocsp.parseResponse(der);
- *   var v = await pki.path.verifyOcspResponse(resp, cert, issuerCert, new Date());
+ *   var v = await pki.path.verifyOcspResponse(der, cert, issuerCert, new Date());
  *   v.status;   // "good" | "revoked" | "unknown"
  */
-function verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts) {
+function verifyOcspResponse(response, cert, issuerCert, time, opts) {
+  var parsedResponse, subject, issuer;
+  try {
+    parsedResponse = _ocspFromBytes(response);
+    // The two certificates go through the same door as the response, for the same reason: this
+    // verdict is about a certificate's IDENTITY -- its serial and its issuer's name and key are
+    // what the CertID is matched against, and the issuer's key is what authorizes a delegated
+    // responder. A caller-assembled certificate could name one identity while carrying another's
+    // signed bytes, so both are re-derived from the bytes their parser read.
+    subject = coerceCert(cert, "the certificate");
+    issuer = coerceCert(issuerCert, "the issuer certificate");
+  } catch (e) { return Promise.reject(e); }
+  return _verifyOcspParsed(parsedResponse, subject, issuer, time, opts);
+}
+
+// The response, always parsed from the bytes the caller handed over.
+//
+// A signature check has three parts -- the signature, the algorithm that verifies it, and the byte
+// range it covers -- and on a claimed-parsed response all three are separate properties of one
+// caller-supplied object. Pair a real CA's signature over a certificate IT issued with that
+// certificate's own tbsBytes and algorithm, label them `signature` / `tbsResponseDataBytes` /
+// `signatureAlgorithm`, and the check verifies: a genuine signature, over the bytes it was made
+// over, under the right key -- for a structure the responder never produced. Parsing binds the three
+// to one byte string, which is the only thing that makes the verdict about a response at all.
+var _OCSP_CLAIM = ["responseStatus", "basicResponse", "tbsResponseDataBytes"];
+function _ocspFromBytes(response) {
+  return guard.parsed.fromTrustedSource(response, "ocspResponse", _OCSP_CLAIM, function (bytes) {
+    if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array) && typeof bytes !== "string") {
+      throw E("path/bad-input", "verifyOcspResponse: the response must be an OCSP response DER Buffer, a PEM string, or a pki.schema.ocsp.parseResponse result");
+    }
+    return ocsp.parseResponse(bytes);
+  }, E, "path/bad-input",
+  "verifyOcspResponse: the response must be its DER bytes, a PEM string, or an unmodified pki.schema.ocsp.parseResponse result: the signature, the algorithm that verifies it and the bytes it covers are separate properties of a parsed object, so a REBUILT response (Object.assign, spread, a JSON round-trip) could have the three describe different responses and is refused");
+}
+
+// The verification over a response this module has ALREADY derived from bytes -- reached only
+// through the door above and through ocspChecker, which parses the responder's own reply. Not
+// exported: this module's export object IS pki.path, so anything on it is public surface and frozen
+// by the API snapshot, whatever a comment beside it claims.
+function _verifyOcspParsed(parsedResponse, cert, issuerCert, time, opts) {
   opts = opts || {};
   // The currency + responder-cert validity windows compare against `time`; a missing or invalid
   // check date must fail closed (a NaN compares false against every bound), never silently pass.
@@ -2451,41 +2514,22 @@ function nameMatchSoft(rdnsA, rdnsB) {
   catch (_e) { return false; }
 }
 
-// A parsed extension entry the search's findExt dereferences by .oid and, for
-// the subjectAltName, by .value (a Buffer in the identity key).
-function _isExtensionEntry(e) { return !!e && typeof e.oid === "string" && Buffer.isBuffer(e.value); }
-
-// The complete parsed-certificate shape build produces AND hands to validate --
-// every top-level field this module dereferences (grep-verified), each with the
-// type the code assumes. A claimed-parsed object satisfying this cannot throw a
-// raw TypeError anywhere in the search or the validate hand-off.
-function _isParsedCert(o) {
-  return Buffer.isBuffer(o.tbsBytes) &&
-    typeof o.serialNumberHex === "string" &&
-    !!o.signatureAlgorithm && typeof o.signatureAlgorithm.oid === "string" &&
-    !!o.signatureValue && Buffer.isBuffer(o.signatureValue.bytes) &&
-    !!o.validity && o.validity.notBefore instanceof Date && o.validity.notAfter instanceof Date &&
-    !!o.issuer && Array.isArray(o.issuer.rdns) &&
-    !!o.subject && Array.isArray(o.subject.rdns) && Buffer.isBuffer(o.subject.bytes) &&
-    !!o.subjectPublicKeyInfo && Buffer.isBuffer(o.subjectPublicKeyInfo.bytes) &&
-    !!o.subjectPublicKeyInfo.algorithm && typeof o.subjectPublicKeyInfo.algorithm.oid === "string" &&
-    !!o.subjectPublicKeyInfo.publicKey && Buffer.isBuffer(o.subjectPublicKeyInfo.publicKey.bytes) &&
-    typeof o.subjectPublicKeyInfo.publicKey.unusedBits === "number" &&
-    Array.isArray(o.extensions) && o.extensions.every(_isExtensionEntry);
-}
-
-function coerceCert(input) {
-  // An already-parsed certificate is passed through; a DER Buffer / PEM string is
-  // parsed (and its typed error normalized by the caller). A claimed-parsed object
-  // (a truthy tbsBytes) must carry the COMPLETE parsed-certificate shape build and
-  // the validate hand-off dereference -- a bare { tbsBytes } object, or any partial
-  // shape, fails closed here as a typed PathError rather than a raw TypeError deeper
-  // in the walk or inside validate.
-  if (input && typeof input === "object" && !Buffer.isBuffer(input) && input.tbsBytes !== undefined) {
-    if (!_isParsedCert(input)) throw E("path/bad-input", "build: an input has tbsBytes but is not a well-formed parsed certificate");
-    return input;
-  }
-  return x509.parse(input);
+// A certificate reaching a VERDICT is re-derived from the bytes the parser read, never trusted as
+// the object it arrives as. Completeness -- every field present with the right type -- is not enough
+// here, because a certificate's meaning is one signature over one byte range while a parsed
+// certificate presents that range, the signature, and the fields the range encodes as separate
+// properties. Keep a real CA certificate's `tbsBytes` and signature and substitute only its
+// `subjectPublicKeyInfo`, and every completeness rule passes, this walk verifies the ORIGINAL signed
+// range, and then uses the substituted key to check the next certificate -- a forged chain built out
+// of a genuine certificate. Emptying `extensions` is the same move against basicConstraints,
+// keyUsage, the name constraints and the unknown-critical rule.
+//
+// So the door takes the parser's record instead: a certificate from pki.schema.x509.parse re-parses
+// from the bytes it was read from, and anything done to that object since is discarded. One a caller
+// assembled has no record and is refused rather than silently believed.
+function coerceCert(input, label) {
+  return guard.parsed.acceptDerived(input, "certificate", x509.parse, E, "path/bad-input",
+    label || "a certificate");
 }
 
 // A trust-store entry is either a ready anchor tuple { name, publicKey,

package/lib/pkcs12-build.js

@@ -296,6 +296,24 @@ function _buildBag(bag, opts, depth) {
 }
 
 // A pre-encoded DER value (one well-formed TLV, no trailing bytes) supplied verbatim (secretValue).
+// The store, always parsed from the BYTES the caller handed over.
+//
+// Both verbs that use this decide integrity, and integrity is the one operation that must not read
+// its inputs from two independently-chosen properties. Accepting a claimed-parsed store let
+// `macedBytes` -- the range the MAC is verified over -- and `safeBags` / `encryptedSafes` -- the
+// content returned as verified -- come from different sources: verify store A's MAC, hand back store
+// B's bags. Parsing here binds them, because both are then derived from one byte string.
+//
+// `pki.schema.pkcs12.parse` remains the parse-only route for a caller who wants the structure
+// without an integrity decision.
+var _STORE_CLAIM = ["integrityMode", "mac", "macedBytes"];
+function _storeFromBytes(pfx) {
+  return guard.parsed.fromTrustedSource(pfx, "pkcs12Store", _STORE_CLAIM, function (bytes) {
+    return schemaPkcs12.parse(_coerceDer(bytes, "pfx"));
+  }, _err, "pkcs12/bad-input",
+  "pfx must be the store's DER bytes, a PEM string, or an unmodified pki.schema.pkcs12.parse result: the MAC is verified over a byte range carried on the object and the bags returned as verified are a separate property of it, so a REBUILT store (Object.assign, spread, a JSON round-trip) could have the two describe different stores and is refused");
+}
+
 function _reqDer(input, label) {
   if (input == null) throw _err("pkcs12/bad-input", label + " is required");
   var der = _bytes(input, label);
@@ -522,8 +540,10 @@ async function build(spec, opts) {
  * @defends pkcs12-mac-forgery (CWE-347)
  * @related pki.pkcs12.build, pki.schema.pkcs12.parse
  *
- * Verify a password-integrity PKCS#12 store's MAC. `pfx` is a `pki.schema.pkcs12.parse` result, a DER
- * `Buffer`, or a PEM string. The password is BMPString+NULL encoded (RFC 7292 App. B.1), the MAC is
+ * Verify a password-integrity PKCS#12 store's MAC. `pfx` is the store's DER `Buffer`, a PEM string, or an
+ * unmodified `pki.schema.pkcs12.parse` result. A REBUILT parsed store is refused: the MAC is verified over
+ * a byte range the object carries, and the parser's mark is what says that range and the store it describes
+ * came from one place. `Object.assign`, spread and a JSON round-trip drop the mark. The password is BMPString+NULL encoded (RFC 7292 App. B.1), the MAC is
  * recomputed over the store's exact AuthenticatedSafe byte range (`macedBytes`) using the store's own MAC
  * parameters -- the classic Appendix B (ID=3) HMAC or the RFC 9579 PBMAC1 -- and constant-time-compared to
  * the stored MAC value. Returns `true` / `false` for the password match; throws `Pkcs12Error` on a MAC-less
@@ -538,8 +558,14 @@ async function build(spec, opts) {
  *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
  */
 async function verifyMac(pfx, password, opts) {
+  return _verifyMacOfStore(_storeFromBytes(pfx), password, opts);
+}
+
+// The MAC computation over a store this module has ALREADY parsed from bytes. Separate from the
+// public verb so `open` can verify the store it just parsed without going back through the door --
+// the door's job is to establish that the store came from the caller's bytes, and by here it has.
+async function _verifyMacOfStore(m, password, opts) {
   opts = opts || {};
-  var m = (pfx && pfx.integrityMode !== undefined && pfx.mac !== undefined) ? pfx : schemaPkcs12.parse(_coerceDer(pfx, "pfx"));
   if (m.integrityMode !== "password" || !m.mac) throw _err("pkcs12/bad-input", "the store carries no password MAC (integrityMode " + m.integrityMode + ")");
   var expected = m.mac.macValue;
   var computed;
@@ -600,8 +626,9 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  * (public-key privacy) safe with `opts.recipientKey` (RFC 7292 sec. 3.1, via `pki.cms.decrypt`) -- returning a
  * structured bundle `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` -- each private key as PKCS#8
  * `PrivateKeyInfo` DER (re-validated), each certificate / CRL / secret as raw DER, all carrying their
- * `friendlyName` / `localKeyId` for pairing. `pfx` is a DER `Buffer`, PEM string, or a
- * `pki.schema.pkcs12.parse` result.
+ * `friendlyName` / `localKeyId` for pairing. `pfx` is the store's DER `Buffer`, a PEM string, or an
+ * unmodified `pki.schema.pkcs12.parse` result; a REBUILT parsed store is refused, since the bytes whose
+ * integrity is checked and the bags returned as checked are separate properties of it.
  *
  * A MAC-less store is refused (`pkcs12/no-integrity`) unless `opts.allowUnauthenticated` is set. A public-key
  * integrity store is verified through `pki.cms.verify` before any bag is trusted; a signature failure is
@@ -635,7 +662,7 @@ async function open(pfx, password, opts) {
   if (opts.maxIterations != null && (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations)) {
     throw _err("pkcs12/bad-input", "maxIterations must be a positive integer");
   }
-  var m = (pfx && pfx.integrityMode !== undefined && pfx.mac !== undefined) ? pfx : schemaPkcs12.parse(_coerceDer(pfx, "pfx"));
+  var m = _storeFromBytes(pfx);
   var macVerified = false;
   var signers = null;
   if (m.integrityMode === "public-key") {
@@ -649,7 +676,7 @@ async function open(pfx, password, opts) {
     if (!res.valid) throw _err("pkcs12/signature-invalid", "the PKCS#12 SignedData signature did not verify (an untrusted or tampered store)");
     signers = res.signers;
   } else if (m.integrityMode === "password") {
-    macVerified = await verifyMac(m, password, opts);
+    macVerified = await _verifyMacOfStore(m, password, opts);
     if (!macVerified) throw _err("pkcs12/mac-mismatch", "the PKCS#12 MAC did not verify (wrong password or a tampered store)");
   } else if (!opts.allowUnauthenticated) {
     throw _err("pkcs12/no-integrity", "the store carries no integrity MAC (integrityMode " + m.integrityMode + "); set opts.allowUnauthenticated to open it anyway");

package/lib/pki-build.js

@@ -395,4 +395,15 @@ function tbsNameField(cert, which) {
   return tbs.children[(hasVersion ? 1 : 0) + (which === "subject" ? 4 : 2)].bytes;
 }
 
-module.exports = { makeBuilder: makeBuilder, KU_BIT: KU_BIT, tbsNameField: tbsNameField };
+// The serialNumber of a parsed X.509 certificate, read from the SIGNED bytes rather than off the
+// object. Same tbs layout as above, and the same reason: where a producer binds an identity to an
+// existing certificate, that identity is issuer AND serial together. Deriving one from the bytes
+// and reading the other from the object lets the halves name different certificates -- a Holder
+// whose issuer is genuine and whose serial is whatever the caller wrote.
+function tbsSerialNumber(cert) {
+  var tbs = asn1.decode(cert.tbsBytes);
+  var hasVersion = tbs.children[0].tagClass === "context" && tbs.children[0].tagNumber === 0;
+  return asn1.read.integer(tbs.children[hasVersion ? 1 : 0]);
+}
+
+module.exports = { makeBuilder: makeBuilder, KU_BIT: KU_BIT, tbsNameField: tbsNameField, tbsSerialNumber: tbsSerialNumber };

package/lib/schema-crl.js

@@ -217,7 +217,13 @@ var CERTIFICATE_LIST = pkix.signedEnvelope(NS, TBS_CERTLIST, {
  *   var crl = pki.schema.crl.parse(der);
  *   crl.revokedCertificates[0].serialNumberHex;  // -> "0a3f"
  */
-var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS });
+// Recording, for the same reason the certificate parser is: a CRL is one signature over one byte
+// range, and a parsed CRL presents that range and the revocation list it encodes as separate
+// properties. Keep a correctly signed CRL's `tbsBytes` and signature and empty `revokedCertificates`
+// and the signature still verifies while the revocation answer comes from the edited list -- a
+// revoked certificate reported as good. The scope fields (`crlExtensions`, an IDP, a delta
+// indicator) fail the same way. The verdict verbs re-parse from what is recorded here.
+var parse = pkix.makeRecordingParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS }, "crl");
 
 /**
  * @primitive  pki.schema.crl.pemDecode

package/lib/schema-ocsp.js

@@ -517,7 +517,12 @@ var parseRequest = pkix.makeParser({ pemLabel: "OCSP REQUEST", PemError: PemErro
  *   res.responseStatus.name;                       // -> "successful"
  *   res.basicResponse.responses[0].certStatus.type; // -> "good" | "revoked" | "unknown"
  */
-var parseResponse = pkix.makeParser({ pemLabel: "OCSP RESPONSE", PemError: PemError, ErrorClass: OcspError, prefix: "ocsp", what: "OCSP response", topSchema: OCSP_RESPONSE, ns: NS });
+// The result records the input it was derived from. A verdict verb reads the
+// signature, the algorithm that verifies it and the bytes it covers off this object as
+// three separate properties, and re-derives all three from the recorded input rather
+// than trusting the object it was handed -- so an object rebuilt or edited after
+// parsing cannot make the three describe different responses.
+var parseResponse = pkix.makeRecordingParser({ pemLabel: "OCSP RESPONSE", PemError: PemError, ErrorClass: OcspError, prefix: "ocsp", what: "OCSP response", topSchema: OCSP_RESPONSE, ns: NS }, "ocspResponse");
 
 /**
  * @primitive  pki.schema.ocsp.pemDecode

package/lib/schema-pkcs12.js

@@ -523,10 +523,15 @@ function _buildBag(rec, state, ctx) {
  *   var store = pki.schema.pkcs12.parse(der);
  *   store.safeBags.map(function (b) { return b.type; });
  */
-var parse = pkix.makeParser({
+// The result records the input it was derived from. pki.pkcs12.verifyMac and open read
+// the MACed byte range and the bags returned as verified off this object as two
+// separate properties, and re-derive both from the recorded input rather than trusting
+// the object -- so "verify this" and "return that" cannot come to name different
+// stores, whether by rebuilding the object or by editing it after parsing.
+var parse = pkix.makeRecordingParser({
   pemLabel: "PKCS12", PemError: PemError, ErrorClass: Pkcs12Error,
   prefix: "pkcs12", what: "PFX", topSchema: PFX, ns: NS, ber: true,
-});
+}, "pkcs12Store");
 
 /**
  * @primitive  pki.schema.pkcs12.pemDecode

package/lib/schema-pkix.js

@@ -1556,6 +1556,19 @@ function makeParser(opts) {
   return function (input) { return runParse(input, opts); };
 }
 
+// makeRecordingParser(opts, kind) -> a parser that also records the bytes it read.
+//
+// The pairing is here rather than repeated per format because it is one decision, not four: a
+// structure whose parse feeds a VERDICT needs its fields bound to the byte string they came from,
+// since a parsed structure presents the signed range, the signature and the fields that range
+// encodes as separate properties -- and a caller can hand back a genuine range beside substituted
+// fields. `kind` is the tag the matching door re-derives under, so a certificate cannot be presented
+// where a CRL is expected. The record lives in guard-parsed, off the object, unreachable through it.
+function makeRecordingParser(opts, kind) {
+  return guard.parsed.recordingParser(kind, makeParser(opts), opts.ErrorClass,
+    opts.prefix + "/bad-input", "a " + opts.what);
+}
+
 // The X.509 SIGNED{ToBeSigned} macro (RFC 5280 sec. 4.1.1.3): the outer
 // SEQUENCE { toBeSigned, signatureAlgorithm AlgorithmIdentifier,
 // signatureValue BIT STRING } shared by Certificate, CertificateList and
@@ -1633,6 +1646,7 @@ module.exports = {
   pbmac1Params: pbmac1Params,
   spki: spki,
   makeParser: makeParser,
+  makeRecordingParser: makeRecordingParser,
   signedEnvelopeTbs: signedEnvelopeTbs,
   rootSequenceChildren: rootSequenceChildren,
   assertPolicyQualifiers: assertPolicyQualifiers,

package/lib/schema-x509.js

@@ -231,7 +231,20 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
  *   cert.validity.notAfter;          // Date
  *   cert.signatureAlgorithm.name;    // "Ed25519" (the algorithm the issuer signed with)
  */
-var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
+// The parser RECORDS the bytes it read, off the returned object, so a verb that computes a verdict
+// can re-derive from them instead of trusting the object it was handed.
+//
+// Completeness alone cannot carry a certificate's meaning. A certificate is one signature over one
+// byte range, but a parsed certificate presents that range (`tbsBytes`), the signature, and every
+// field the range encodes as separate properties. Keep a real CA certificate's signed bytes and
+// signature and replace only `subjectPublicKeyInfo`, and the signature check still passes over the
+// original range while the substituted key is what gets used to verify the next certificate in the
+// chain -- a forged chain out of a genuine certificate. Emptying `extensions` is the same move
+// against basicConstraints, keyUsage, name constraints, and the unknown-critical rule.
+//
+// Recording the source is what makes the object safe to accept: the verdict verbs parse it again
+// from these bytes, so anything done to the object afterwards is discarded rather than believed.
+var parse = pkix.makeRecordingParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS }, "certificate");
 
 // matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
 // share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the

package/lib/sign-scheme.js

@@ -22,6 +22,7 @@ var pkcs8 = require("./schema-pkcs8");
 var webcrypto = require("./webcrypto");
 var subtle = webcrypto.webcrypto.subtle;
 var validator = require("./validator-all");
+var guard = require("./guard-all");
 var compositeSig = require("./composite-sig");
 var b = asn1.build;
 function O(name) { return oid.byName(name); }
@@ -213,12 +214,28 @@ function _importKey(key, imp, E) {
     // signs with. One whose material this process cannot reach is refused with that as the reason.
     return webcrypto.adoptKey(key, imp, ["sign"], E, "bad-input");
   }
-  var der;
+  // A Uint8Array is copied here and a PEM string is decoded here, so both leave a SECOND copy of a
+  // private key that nothing else can reach -- wiped once the engine has imported it, which is the
+  // only thing that reads it. A caller's own Buffer is passed through untouched: they hold a live
+  // reference and will use it again, so clearing it would destroy their key.
+  var der, owned = false;
   if (Buffer.isBuffer(key)) der = key;
-  else if (key instanceof Uint8Array) der = Buffer.from(key);
-  else if (typeof key === "string") { try { der = pkcs8.pemDecode(key); } catch (e) { throw E("bad-input", "the signer PEM private key could not be decoded", e); } }
-  else throw E("bad-input", "a signer key must be a CryptoKey, a PKCS#8 DER Buffer, or a PKCS#8 PEM string");
-  return subtle.importKey("pkcs8", der, imp, false, ["sign"]);
+  else if (key instanceof Uint8Array) { der = Buffer.from(key); owned = true; }
+  else if (typeof key === "string") {
+    try { der = pkcs8.pemDecode(key); }
+    catch (e) { throw E("bad-input", "the signer PEM private key could not be decoded", e); }
+    owned = true;
+  } else throw E("bad-input", "a signer key must be a CryptoKey, a PKCS#8 DER Buffer, or a PKCS#8 PEM string");
+  var imported = subtle.importKey("pkcs8", der, imp, false, ["sign"]);
+  if (!owned) return imported;
+  // Wiped on the reject path too: a malformed key is not a way to leave the copy in memory.
+  return imported.then(function (k) {
+    guard.secret.zeroize(der, E, "bad-input", "the signer private-key copy");
+    return k;
+  }, function (e) {
+    guard.secret.zeroize(der, E, "bad-input", "the signer private-key copy");
+    throw e;
+  });
 }
 
 // signOverTbs(scheme, key, signedBytes, E) -> Promise<Buffer> the raw signature over signedBytes.

package/lib/smime.js

@@ -44,6 +44,43 @@ var SmimeError = frameworkError.SmimeError;
 
 function _err(code, msg, cause) { return new SmimeError(code, msg, cause); }
 
+// ---- the option surface each verb accepts -----------------------------------
+//
+// A misspelled option is the one input that reads as an omission rather than as a value: nothing is
+// out of range, nothing fails to parse, and the caller who asked for something stricter silently
+// gets the looser default. `protectHeaders` misspelled sends the headers a caller meant to protect
+// as ordinary display copies; `strictMicalg` misspelled accepts the mismatch it was set to reject;
+// `entity` misspelled wraps a caller's complete MIME entity inside another one.
+//
+// The tables are per VERB, not per module, because the surfaces genuinely differ -- `form` means
+// something on sign and nothing on encrypt -- and a merged table would accept each verb's options at
+// every other one, which is the same silence in a wider form. Each is the keys that verb's body and
+// the helpers it hands `opts` to actually read: the value goes through _entityBytes, _cmsSignOpts or
+// _cmsEncryptOpts as readily as it is read here, so a table built from the verb's own lines alone
+// would refuse options that work.
+var SIGN_OPTS = {
+  form: 1, entity: 1, contentType: 1, signingTime: 1, protectHeaders: 1, headers: 1, hcp: 1,
+  sid: 1, signedAttributes: 1, additionalSignedAttributes: 1,
+};
+var VERIFY_OPTS = {
+  certs: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1, strictMicalg: 1,
+  legacyHeaderProtection: 1,
+};
+var ENCRYPT_OPTS = {
+  entity: 1, contentType: 1, protectHeaders: 1, headers: 1, hcp: 1,
+  contentEncryptionAlgorithm: 1, oaepHash: 1, keyIdentifier: 1, ukm: 1,
+};
+var DECRYPT_OPTS = { recipientIndex: 1, maxIterations: 1, strictSmimeType: 1, legacyHeaderProtection: 1 };
+var COMPRESS_OPTS = { entity: 1, contentType: 1, level: 1 };
+var DECOMPRESS_OPTS = { maxOutputBytes: 1 };
+
+function _knownOpts(opts, known, verb) {
+  guard.identifier.assertKnownKeys(opts, known, _err, "smime/bad-input", function (k) {
+    return "unknown option " + JSON.stringify(k) + " for pki.smime." + verb + " -- accepted: " +
+      Object.keys(known).sort().join(", ");
+  });
+}
+
 // RFC 8551 uses application/pkcs7-<kind>; OpenSSL's legacy `smime` command emits the PKCS#7
 // application/x-pkcs7-<kind>. Accept both on the RECEIVE side (we always EMIT the RFC 8551 form).
 function _isPkcs7(type, kind) {
@@ -520,6 +557,10 @@ function _base64Body(der) {
  * @opts signingTime a `Date` for the CMS signing-time attribute, or false to omit it.
  * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`) -- inline `opts.headers` on the signed payload + the outer display headers.
  * @opts headers     the Non-Structural fields to protect + display: an object `{ Name: value }` or an array `[{ name, value }]` (Subject / From / To / Date / ...); used with `protectHeaders`.
+ * @opts hcp         the Header Confidentiality Policy applied to the OUTER display copies: `"hcp_baseline"` (default) or `"hcp_no_confidentiality"`. A signed message's payload is not encrypted, so this governs presentation, not secrecy; used with `protectHeaders`.
+ * @opts sid                       forwarded to cms.sign: the SignerIdentifier form, `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
+ * @opts signedAttributes          forwarded: `false` omits the signed-attributes set entirely (a bare-signature SignedData).
+ * @opts additionalSignedAttributes forwarded: extra signed attributes to carry, as `[{ oid, values }]`.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
@@ -529,6 +570,7 @@ function _base64Body(der) {
  */
 async function sign(content, signers, opts) {
   opts = opts || {};
+  _knownOpts(opts, SIGN_OPTS, "sign");
   // RFC 9788 header protection (opts.protectHeaders): the inner Cryptographic Payload gains hp="clear" +
   // the inlined protected fields, and the outer frame carries the display copies. Off by default => the
   // shipped path, byte-for-byte.
@@ -624,6 +666,7 @@ function _capped(msg) {
  */
 async function verify(message, opts) {
   opts = opts || {};
+  _knownOpts(opts, VERIFY_OPTS, "verify");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   // Forwarded, not re-decided here. This verb documents itself as pki.cms.verify's verdict plus the
@@ -762,6 +805,7 @@ function _cmsEncryptOpts(opts) {
  */
 async function encrypt(content, recipients, opts) {
   opts = opts || {};
+  _knownOpts(opts, ENCRYPT_OPTS, "encrypt");
   // RFC 9788 header protection (opts.protectHeaders): the inner payload carries hp="cipher" + the REAL
   // headers (inside the ciphertext); the outer frame carries only the Header-Confidentiality-Policy-processed
   // display copies (hcp_baseline obscures Subject to [...], removes Comments/Keywords). Off => shipped path.
@@ -824,6 +868,7 @@ async function encrypt(content, recipients, opts) {
  */
 async function decrypt(message, keyMaterial, opts) {
   opts = opts || {};
+  _knownOpts(opts, DECRYPT_OPTS, "decrypt");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   if (!_isPkcs7(ct.type, "mime")) throw _err("smime/unsupported-type", "not an encrypted S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");
@@ -870,6 +915,7 @@ async function decrypt(message, keyMaterial, opts) {
  */
 async function compress(content, opts) {
   opts = opts || {};
+  _knownOpts(opts, COMPRESS_OPTS, "compress");
   var entity = _entityBytes(content, opts);
   var cOpts = {};
   if (opts.level !== undefined) cOpts.level = opts.level;
@@ -903,6 +949,7 @@ async function compress(content, opts) {
  */
 async function decompress(message, opts) {
   opts = opts || {};
+  _knownOpts(opts, DECOMPRESS_OPTS, "decompress");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   if (!_isPkcs7(ct.type, "mime")) throw _err("smime/unsupported-type", "not a compressed S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");