@blamejs/pki 0.2.20 → 0.2.22

package/lib/path-validate.js

@@ -38,6 +38,7 @@ var schema = require("./schema-engine");
 var x509 = require("./schema-x509");
 var crl = require("./schema-crl");
 var ocsp = require("./schema-ocsp");
+var ocspVerify = require("./ocsp-verify");
 var guard = require("./guard-all");
 var constants = require("./constants");
 var validator = require("./validator-all");
@@ -331,6 +332,32 @@ function compositeKeyUsageCheck(cert) {
   return { ok: true };
 }
 
+// The ML-KEM SubjectPublicKeyInfo OIDs (RFC 9935 / FIPS 203). A certificate carrying one of
+// these keys is a KEM key-establishment certificate: it can neither sign nor agree.
+var ML_KEM_OIDS = {};
+["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n) { ML_KEM_OIDS[oid.byName(n)] = true; });
+
+// RFC 9935 sec. 5: a certificate whose SubjectPublicKeyInfo carries an id-ml-kem-* OID, IF it
+// has a keyUsage extension, MUST assert keyEncipherment as the ONLY key usage set -- an ML-KEM
+// key is a key-establishment-only key (it cannot sign or agree, so no other bit is legitimate,
+// and an unnamed/reserved bit set alongside keyEncipherment is equally forbidden). The caller
+// invokes this only for an ML-KEM-keyed certificate; an absent keyUsage places no restriction
+// (RFC 5280 sec. 4.2.1.3). This also makes an ML-KEM "CA" (keyCertSign) an explicit reject.
+function kemKeyUsageCheck(cert) {
+  var ku;
+  try { ku = decodeExt(cert, OID.keyUsage); }
+  catch (e) { return { ok: false, code: "path/kem-key-usage", error: e }; }
+  if (!ku) return { ok: true };
+  var v = ku.value;
+  var others = v.digitalSignature || v.nonRepudiation || v.dataEncipherment || v.keyAgreement ||
+    v.keyCertSign || v.cRLSign || v.encipherOnly || v.decipherOnly || (v.reservedBitsSet === true);
+  if (!v.keyEncipherment || others) {
+    return { ok: false, code: "path/kem-key-usage",
+      error: E("path/kem-key-usage", "an ML-KEM key's keyUsage must assert keyEncipherment as the only bit (RFC 9935 sec. 5)") };
+  }
+  return { ok: true };
+}
+
 // Import a descriptor's verification key, validating an EdDSA point FIRST: node/OpenSSL import a
 // low-order (e.g. identity or all-zeroes) Ed25519/Ed448 SPKI without complaint and such a key
 // verifies a forged signature. This is the ONE seam both the certificate path and the revocation
@@ -1215,6 +1242,14 @@ async function validate(path, opts) {
       if (!cku.ok) failed = true;
     }
 
+    // RFC 9935 sec. 5: an ML-KEM-keyed certificate's keyUsage must be keyEncipherment-only.
+    // Runs for the target AND every intermediate whose own subject key is ML-KEM.
+    if (ML_KEM_OIDS[cert.subjectPublicKeyInfo.algorithm.oid]) {
+      var kku = kemKeyUsageCheck(cert);
+      checks.push({ name: "kemKeyUsage", ok: kku.ok, code: kku.ok ? undefined : kku.code });
+      if (!kku.ok) failed = true;
+    }
+
     // 6.1.3(a)(2) validity window.
     var t = opts.time;
     var vOk = true, vCode;
@@ -1805,163 +1840,19 @@ function verifyCrlSignature(theCrl, issuer) {
 
 // ---- the OCSP revocation checker (RFC 6960) -------------------------------
 
-// CertID identity-hash algorithms (RFC 6960 sec. 4.1.1). Kept SEPARATE from the
-// signature SIG_ALGS/HASH_BY_OID set (which omits SHA-1 -- a SHA-1 *signature* is
-// refused, SHAttered): a CertID hash is an identity binding of an already-known
-// issuer, not a signature, so collision resistance is irrelevant to the lookup
-// and RFC 6960's default SHA-1 CertID MUST interoperate. A hash OID outside this
-// set cannot be reproduced -> no CertID match (fail closed), never an assumption.
-var OCSP_CERTID_HASHES = {};
-OCSP_CERTID_HASHES[oid.byName("sha1")] = "SHA-1";
-OCSP_CERTID_HASHES[oid.byName("sha256")] = "SHA-256";
-OCSP_CERTID_HASHES[oid.byName("sha384")] = "SHA-384";
-OCSP_CERTID_HASHES[oid.byName("sha512")] = "SHA-512";
-var OID_OCSP_SIGNING = oid.byName("ocspSigning");
-var OID_OCSP_NOCHECK = oid.byName("ocspNoCheck");
-
-// The subjectPublicKey BIT STRING VALUE (excluding the unused-bits octet) of an
-// SPKI DER -- the exact bytes an OCSP CertID issuerKeyHash / byKey KeyHash hash
-// over (RFC 6960 sec. 4.1.1). Throws on a malformed SPKI; the caller fails closed.
-function ocspKeyValue(spkiDer) {
-  return asn1.read.bitString(asn1.decode(spkiDer).children[1]).bytes;
-}
-
-// The delegate responder's importable SPKI. If its key omits algorithm parameters
-// and inherits them from the issuing CA (same key algorithm -- an EC public key
-// whose SPKI omits the namedCurve, RFC 5280 sec. 4.1.2.7), splice the issuer's
-// parameters in so importKey("spki", ...) has a complete key; otherwise a valid
-// response would verify as unknown. Mirrors updateWorkingKey's inheritance.
-function ocspResponderSpki(rc, issuer) {
-  var keyAlg = rc.subjectPublicKeyInfo.algorithm;
-  if (!isNullOrAbsentParams(keyAlg.parameters)) return rc.subjectPublicKeyInfo.bytes;
-  var issuerOid, issuerParams;
-  // Coverage residual -- the catch is unreachable: this function runs only after the
-  // delegate's signature verified under issuer.workingPublicKey, so that SPKI already
-  // imported and decodes cleanly here. (The children[1] ? : null false side IS covered.)
-  try {
-    var alg = asn1.decode(issuer.workingPublicKey).children[0];
-    issuerOid = asn1.read.oid(alg.children[0]);
-    issuerParams = alg.children[1] ? alg.children[1].bytes : null;
-  } catch (_e) { return rc.subjectPublicKeyInfo.bytes; }
-  if (issuerOid === keyAlg.oid && !isNullOrAbsentParams(issuerParams)) {
-    return spliceSpkiParameters(rc.subjectPublicKeyInfo, keyAlg.oid, issuerParams);
-  }
-  return rc.subjectPublicKeyInfo.bytes;
-}
-function ocspDigest(alg, buf) { return subtle.digest(alg, buf).then(function (h) { return Buffer.from(h); }); }
-
-// The checker implements NO OCSP response-extension semantics (the nonce is the
-// live client's, RFC 6960 sec. 4.4.1; CRL References / Archive Cutoff / Service
-// Locator are not consulted), so a CRITICAL responseExtension / singleExtension
-// may change a response's meaning in a way this code cannot honor -- treat it as
-// unusable (RFC 6960 sec. 4.4 / the RFC 5280 critical-extension contract, the OCSP
-// analogue of the crlChecker unhandled-critical skip). Returns true if `extList`
-// carries any critical extension.
-function ocspHasCriticalExtension(extList) {
-  if (!extList) return false;
-  for (var i = 0; i < extList.length; i++) if (extList[i].critical) return true;
-  return false;
-}
-
-// A SingleResponse's CertID names the target cert IFF its serial equals the
-// target's AND issuerNameHash + issuerKeyHash, recomputed under the CertID's OWN
-// hashAlgorithm, match the issuer (RFC 6960 sec. 4.1.1). A serial-only match would
-// let a "good" for issuer A serial N answer a query for issuer B serial N
-// (cross-CA substitution), so BOTH issuer hashes must match under the responder's
-// chosen algorithm -- never an assumed SHA-1.
-//
-// `issuerNameCandidates` is every byte encoding of the (name-chaining-validated)
-// issuer DN to try: the checked cert's issuer field (RFC 6960 sec. 4.1.1) plus,
-// when available, the issuer certificate's own subject encoding. These are RFC
-// 5280 sec. 7.1-equal (they chained) but MAY differ in DER -- case, whitespace, a
-// PrintableString-vs-UTF8String DirectoryString choice -- and a responder MAY have
-// hashed any of them; matching the CertID against any is still the SAME validated
-// issuer, because the issuerKeyHash + serial + authorized signature carry the
-// binding. The key (raw octets, no encoding variance) is matched once.
-async function ocspCertIdMatches(certID, cert, issuerNameCandidates, issuerKeyBits) {
-  if (certID.serialNumberHex !== cert.serialNumberHex) return false;
-  var hashName = OCSP_CERTID_HASHES[certID.hashAlgorithm.oid];
-  if (!hashName) return false;   // an unreproducible hash -> the match cannot be confirmed
-  var keyHash = await ocspDigest(hashName, issuerKeyBits);
-  if (!certID.issuerKeyHash.equals(keyHash)) return false;
-  for (var i = 0; i < issuerNameCandidates.length; i++) {
-    if (certID.issuerNameHash.equals(await ocspDigest(hashName, issuerNameCandidates[i]))) return true;
-  }
-  return false;
-}
-
-// Resolve the signer of a BasicOCSPResponse to an AUTHORIZED responder's SPKI DER,
-// or null when none is authorized (RFC 6960 sec. 4.2.2.2). Two models: the issuing
-// CA signing directly (responderID identifies the issuer), or a CA-delegated
-// responder -- a certificate in `certs` issued by the SAME CA, valid at `time`,
-// bearing id-kp-OCSPSigning in its extendedKeyUsage. anyExtendedKeyUsage and an
-// ABSENT EKU do NOT authorize an OCSP delegate (the opposite of the path-validation
-// EKU default), so an ordinary leaf the CA issued cannot forge revocation status.
-// Fails closed at every branch (a malformed delegate, a control-byte DN, an
-// unreadable EKU -> skip that candidate).
-async function ocspAuthorizeResponder(basicResponse, cert, issuer, issuerKeyBits, time) {
-  var rid = basicResponse.responderID;
-  var matchesIssuer = false;
-  try {
-    if (rid.byName) matchesIssuer = dnEqual(rid.byName.rdns, cert.issuer.rdns);
-    else if (rid.byKey) matchesIssuer = rid.byKey.equals(await ocspDigest("SHA-1", issuerKeyBits));
-  } catch (_e) { matchesIssuer = false; }
-  if (matchesIssuer) return issuer.workingPublicKey;
-
-  for (var i = 0; i < basicResponse.certs.length; i++) {
-    var rc;
-    try { rc = x509.parse(basicResponse.certs[i]); }
-    catch (_e) { continue; }
-    var identifies = false;
-    try {
-      if (rid.byName) identifies = dnEqual(rid.byName.rdns, rc.subject.rdns);
-      else if (rid.byKey) identifies = rid.byKey.equals(await ocspDigest("SHA-1", ocspKeyValue(rc.subjectPublicKeyInfo.bytes)));
-    } catch (_e) { identifies = false; }
-    if (!identifies) continue;
-    // The delegate MUST be issued directly by the CA that issued the target.
-    var issuedByCa;
-    try { issuedByCa = dnEqual(rc.issuer.rdns, cert.issuer.rdns); }
-    catch (_e) { continue; }
-    if (!issuedByCa) continue;
-    if (!guard.crypto.isOctetAligned(rc.signatureValue)) continue;
-    if (!(await _verifyWithSpki(rc.signatureAlgorithm, rc.signatureValue.bytes, issuer.workingPublicKey, rc.tbsBytes))) continue;
-    // The delegate certificate MUST itself be valid at the validation instant.
-    if (time < rc.validity.notBefore || time > rc.validity.notAfter) continue;
-    // The delegate MUST assert id-kp-OCSPSigning; anyEKU / an absent EKU do not.
-    var eku;
-    try { eku = decodeExt(rc, OID.extKeyUsage); }
-    catch (_e) { continue; }
-    if (!eku || eku.value.indexOf(OID_OCSP_SIGNING) === -1) continue;
-    // A delegate asserting keyUsage MUST permit digitalSignature -- signing an OCSP
-    // response is a digitalSignature operation (RFC 5280 sec. 4.2.1.3); an absent
-    // keyUsage is unrestricted, an unreadable one is not authoritative.
-    var ku;
-    try { ku = decodeExt(rc, OID.keyUsage); }
-    catch (_e) { continue; }
-    if (ku && ku.value.digitalSignature !== true) continue;
-    // A delegate carrying a critical extension this code does not process is
-    // unusable, the same fail-closed rule the path validator applies to any cert
-    // (RFC 5280 sec. 6.1.4(o)) -- an unknown critical constraint must not be ignored
-    // while its key is trusted to authenticate revocation status. A RECOGNIZED
-    // critical extension whose value is malformed is likewise rejected via the
-    // shared structure validation, exactly as the path validator rejects it.
-    if (unrecognizedCriticalExtension(rc, false)) continue;
-    if (validateCriticalExtensionStructure(rc)) continue;
-    // The delegate MUST carry id-pkix-ocsp-nocheck (RFC 6960 sec. 4.2.2.2.1): a
-    // transport-free checker cannot otherwise confirm the responder certificate has
-    // not itself been revoked, and a revoked OCSP-signing certificate would keep
-    // signing "good" until its notAfter. A deployment that instead supplies the
-    // responder's own status opts in through a future checker; absent nocheck, fail
-    // closed (unknown) rather than trust an unvalidated responder.
-    if (!findExt(rc, OID_OCSP_NOCHECK)) continue;
-    // A composite-keyed delegate is an out-of-path signer cert and gets the same
-    // composite keyUsage gate the path certificates do (draft sec. 5.2): a dual-usage
-    // composite responder key (a forbidden encryption bit set) is not authorized.
-    if (compositeSig.COMPOSITE_ALGS[rc.subjectPublicKeyInfo.algorithm.oid] && !compositeKeyUsageCheck(rc).ok) continue;
-    return ocspResponderSpki(rc, issuer);
-  }
-  return null;
-}
+// The OCSP response-verification core (responder authorization + CertID binding + currency +
+// status) lives ONCE in lib/ocsp-verify.js, composed here by pki.path.ocspChecker AND by
+// pki.ocsp.verify -- there is no second, weaker OCSP verify path. This binds the path-validate-
+// owned signature engine + RFC 5280 cert-profile gates into that shared core.
+var ocspCore = ocspVerify.makeOcspVerify({
+  verifyWithSpki: _verifyWithSpki,
+  decodeExt: decodeExt, findExt: findExt,
+  unrecognizedCriticalExtension: unrecognizedCriticalExtension,
+  validateCriticalExtensionStructure: validateCriticalExtensionStructure,
+  compositeKeyUsageCheck: compositeKeyUsageCheck,
+  isNullOrAbsentParams: isNullOrAbsentParams, spliceSpkiParameters: spliceSpkiParameters,
+  dnEqual: dnEqual,
+});
 
 /**
  * @primitive  pki.path.ocspChecker
@@ -2009,57 +1900,26 @@ function ocspChecker(responses) {
       if (issuer.issuerCert) addNameCandidate(issuer.issuerCert.subject);
       addNameCandidate(issuer.workingIssuerName);
       var issuerKeyBits;
-      try { issuerKeyBits = ocspKeyValue(issuer.workingPublicKey); }
+      try { issuerKeyBits = ocspVerify.ocspKeyValue(issuer.workingPublicKey); }
       catch (_e) { return { status: "unknown", reason: "the issuer public key could not be read to recompute the OCSP CertID" }; }
 
       // A serial is revoked if ANY authoritative, verified, current response says
       // so -- a clean response must never shadow a revoking one (the crlChecker
       // fail-closed law). "good" needs at least one authoritative match; every
-      // other outcome is undetermined.
+      // other outcome is undetermined. The shared verify core evaluates each
+      // response (responder authorization + signature + CertID + currency +
+      // status) and returns a per-response summary this aggregates.
       var revokedResult = null;
       var sawGood = false;
       var sawUnknownStatus = false;
 
       for (var k = 0; k < parsed.length; k++) {
-        var resp = parsed[k];
-        if (resp.responseStatus.code !== 0) continue;   // non-successful -> conveys no status
-        var br = resp.basicResponse;
-        // Coverage residual -- unreachable for a parsed response: schema-ocsp enforces
-        // the successful-status <-> responseBytes biconditional, so a code-0 response
-        // always carries a basicResponse. Backstop for a hand-built object.
-        if (!br) continue;
-        var signerSpki = await ocspAuthorizeResponder(br, cert, issuer, issuerKeyBits, time);
-        if (!signerSpki) continue;                       // unauthorized responder
-        if (!(await _verifyWithSpki(br.signatureAlgorithm, br.signature, signerSpki, br.tbsResponseDataBytes))) continue;
-        // A critical responseExtension changes the meaning of the WHOLE response
-        // and this code processes none -> the response is unusable.
-        if (ocspHasCriticalExtension(br.responseExtensions)) continue;
-        for (var s = 0; s < br.responses.length; s++) {
-          var sr = br.responses[s];
-          if (!(await ocspCertIdMatches(sr.certID, cert, issuerNameCandidates, issuerKeyBits))) continue;   // not about this cert
-          if (ocspHasCriticalExtension(sr.singleExtensions)) continue;   // a critical per-response extension this code cannot process -> skip
-          if (sr.thisUpdate > time) continue;                    // not yet valid
-          if (!sr.nextUpdate || sr.nextUpdate < time) continue;  // no bounded validity / stale -> fail closed
-          var st = sr.certStatus;
-          if (st.type === "revoked") {
-            // A revocation is effective as of its revocationTime. Present-time
-            // validation revokes regardless (a future revocationTime is
-            // post-dating/skew, never "good"); only an EXPLICIT historical
-            // validation defers a strictly-future revocation.
-            if (historical && st.revocationTime instanceof Date && st.revocationTime.getTime() > time.getTime()) { sawGood = true; }
-            else {
-              revokedResult = {
-                status: "revoked",
-                revocationReason: st.revocationReason || null,
-                reason: "certificate reported revoked by an authorized OCSP responder" + (st.revocationReason ? " (" + st.revocationReason + ")" : ""),
-              };
-            }
-          } else if (st.type === "good") {
-            sawGood = true;
-          } else {
-            sawUnknownStatus = true;   // an explicit responder "unknown"
-          }
+        var v = await ocspCore.evaluateResponse(parsed[k], cert, issuer, issuerKeyBits, issuerNameCandidates, time, historical);
+        if (v.revoked && !revokedResult) {
+          revokedResult = { status: "revoked", revocationReason: v.revoked.revocationReason, reason: v.revoked.reason };
         }
+        if (v.sawGood) sawGood = true;
+        if (v.sawUnknownStatus) sawUnknownStatus = true;
       }
       if (revokedResult) return revokedResult;
       if (sawGood) return { status: "good" };
@@ -2073,8 +1933,82 @@ 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 }>
+ * @since       0.2.22
+ * @status      experimental
+ * @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
+ * `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`
+ * does: it locates the SingleResponse whose CertID binds this cert's serial to
+ * its issuer (recomputing `issuerNameHash`/`issuerKeyHash` under the CertID's
+ * own hashAlgorithm), confirms the responder is authorized (the issuing CA
+ * directly, or a CA-issued delegate bearing both id-kp-OCSPSigning and
+ * id-pkix-ocsp-nocheck and passing the full out-of-path certificate gates),
+ * verifies the response signature over `tbsResponseDataBytes`, and checks
+ * currency (`thisUpdate`/`nextUpdate`) -- there is no weaker second OCSP verify
+ * path. It is fail-closed and never throws on an unauthorized, stale, or
+ * unverifiable response: those yield `{ status: "unknown" }` with the granular
+ * `responderAuthorized`/`signatureValid`/`matched` flags and a `reason`; a
+ * `revoked` status surfaces its `revocationReason`. Setting `opts.historicalMode`
+ * treats a revocation whose `revocationTime` is strictly after `time` as not-yet-
+ * revoked (`good`) -- for validating a signature as of a past `time`, before the
+ * certificate was later revoked; the responder certificate is still validated at
+ * `time` either way. `time` must be a valid `Date`. A malformed response's parse
+ * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
+ *
+ * @example
+ *   var resp = pki.schema.ocsp.parseResponse(der);
+ *   var v = await pki.path.verifyOcspResponse(resp, cert, issuerCert, new Date());
+ *   v.status;   // "good" | "revoked" | "unknown"
+ */
+function verifyOcspResponse(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.
+  if (!(time instanceof Date) || isNaN(time.getTime())) {
+    return Promise.reject(E("path/bad-input", "verifyOcspResponse: time must be a valid Date (the currency + responder-validity check date)"));
+  }
+  // Bind the supplied issuer certificate to the target: the target's issuer DN must equal the
+  // issuer cert's subject DN AND the target's signature must verify under the issuer's key. A
+  // direct-CA responder is authorized by exactly this issuer identity and the CertID is recomputed
+  // under the issuer's key, so without the cryptographic binding a rogue certificate sharing the
+  // issuer's subject DN (but a different key) could recompute a matching CertID and sign a "good"
+  // response for a certificate that CA never issued. ocspChecker gets an issuer already chained by
+  // the path validator; the standalone entry must establish the binding itself. Fail closed.
+  function unbound(reason) { return { status: "unknown", responderAuthorized: false, signatureValid: false, matched: false, reason: reason }; }
+  var boundName;
+  try { boundName = dnEqual(cert.issuer.rdns, issuerCert.subject.rdns); }
+  catch (e) { return Promise.reject(e); }   // an embedded control byte in a DN -> path/name-chaining
+  if (!boundName) {
+    return Promise.resolve(unbound("the supplied issuer certificate's subject does not match the target certificate's issuer"));
+  }
+  return builtinVerify({ workingPublicKey: issuerCert.subjectPublicKeyInfo.bytes }, cert).then(function (sig) {
+    if (!sig.ok) return unbound("the target certificate's signature does not verify under the supplied issuer certificate's key");
+    var issuerCtx = { workingPublicKey: issuerCert.subjectPublicKeyInfo.bytes, workingIssuerName: issuerCert.subject, issuerCert: issuerCert };
+    var issuerNameCandidates = [cert.issuer.bytes];
+    function add(nm) { if (nm && nm.bytes && !issuerNameCandidates.some(function (e) { return e.equals(nm.bytes); })) issuerNameCandidates.push(nm.bytes); }
+    add(issuerCert.subject);
+    var issuerKeyBits;
+    try { issuerKeyBits = ocspVerify.ocspKeyValue(issuerCert.subjectPublicKeyInfo.bytes); }
+    catch (_e) { return unbound("the issuer public key could not be read to recompute the OCSP CertID"); }
+    return ocspCore.evaluateResponse(parsedResponse, cert, issuerCtx, issuerKeyBits, issuerNameCandidates, time, opts.historicalMode === true).then(function (v) {
+      if (v.revoked) return { status: "revoked", responderAuthorized: true, signatureValid: true, matched: true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, revocationReason: v.revoked.revocationReason, reason: v.revoked.reason };
+      if (v.sawGood) return { status: "good", responderAuthorized: true, signatureValid: true, matched: true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, reason: "good" };
+      return { status: "unknown", responderAuthorized: v.responderAuthorized === true, signatureValid: v.signatureValid === true, matched: v.matched === true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, reason: v.reason };
+    });
+  });
+}
+
 module.exports = {
   validate: validate,
   crlChecker: crlChecker,
   ocspChecker: ocspChecker,
+  verifyOcspResponse: verifyOcspResponse,
 };

package/lib/schema-pkix.js

@@ -660,6 +660,14 @@ function certExtensionDecoders(ns) {
       var byte = bit >> 3, mask = 0x80 >> (bit & 7);
       out[nm] = byte < bs.bytes.length && (bs.bytes[byte] & mask) !== 0;
     });
+    // Any bit beyond the 9 named positions is a reserved/unknown usage. RFC 5280 tolerates it,
+    // but a "MUST be the ONLY bit" rule (e.g. RFC 9935 sec. 5 ML-KEM keyEncipherment-only) needs
+    // to see it -- so surface it rather than silently drop bits >= 9.
+    var reserved = false;
+    for (var bit2 = KU_BITS.length; bit2 < bs.bytes.length * 8 && !reserved; bit2++) {
+      if ((bs.bytes[bit2 >> 3] & (0x80 >> (bit2 & 7))) !== 0) reserved = true;
+    }
+    out.reservedBitsSet = reserved;
     return out;
   }
 

package/lib/sign-scheme.js

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The signature-scheme resolver + signer shared by
+// every producer that signs a raw preimage with a certificate's key: pki.cms.sign (SignerInfo),
+// pki.ocsp.sign (BasicOCSPResponse), and future X.509 / CRL issuance. It owns the ONE key ->
+// { signatureAlgorithm, WebCrypto import/sign params } dispatch across the whole algorithm set
+// (RSA-PKCS1 / RSA-PSS / ECDSA P-256/384/521 / Ed25519 / Ed448 / ML-DSA / SLH-DSA / composite
+// ML-DSA), so a new signer surface inherits the full registry -- PQC included -- instead of
+// re-deriving a partial, drifting copy (Hard rule #2: registry not switch; and no second signer).
+//
+// Error-parameterized like the guard / validator families: the caller passes its typed error
+// factory `E(kind, message, cause)` where kind is "bad-input" | "unsupported-algorithm", so every
+// domain keeps its own code (cms/bad-input vs ocsp/bad-input). The digest choice (a CMS
+// digestAlgorithm concern) is surfaced as `scheme.digest`; the caller that has a digestAlgorithm
+// field (CMS) builds it, the caller that signs raw bytes (OCSP) ignores it.
+
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var pkcs8 = require("./schema-pkcs8");
+var webcrypto = require("./webcrypto");
+var subtle = webcrypto.webcrypto.subtle;
+var validator = require("./validator-all");
+var compositeSig = require("./composite-sig");
+var b = asn1.build;
+function O(name) { return oid.byName(name); }
+
+var HASH = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
+var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", shake128: "shake128", shake256: "shake256" };
+var PSS_SALT = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };
+var ECDSA_ALG = { sha256: "ecdsaWithSHA256", sha384: "ecdsaWithSHA384", sha512: "ecdsaWithSHA512" };
+// RSA-PKCS1 signatures fold the digest into a combined signature OID when there is NO separate
+// digestAlgorithm field to carry it (X.509 / CRL / OCSP -- RFC 5280 sec. 4.1.1.2, RFC 6960). CMS
+// SignerInfo has that field, so it signs under the bare rsaEncryption key OID instead.
+var RSA_PKCS1_SIG = { sha256: "sha256WithRSAEncryption", sha384: "sha384WithRSAEncryption", sha512: "sha512WithRSAEncryption" };
+var HASH_NAME_BY_OID = {};
+HASH_NAME_BY_OID[O("sha256")] = "sha256";
+HASH_NAME_BY_OID[O("sha384")] = "sha384";
+HASH_NAME_BY_OID[O("sha512")] = "sha512";
+var EC_BY_CURVE_OID = {};
+EC_BY_CURVE_OID[O("prime256v1")] = { curve: "P-256", coordLen: 32 };
+EC_BY_CURVE_OID[O("secp384r1")] = { curve: "P-384", coordLen: 48 };
+EC_BY_CURVE_OID[O("secp521r1")] = { curve: "P-521", coordLen: 66 };
+var MLDSA_BY_OID = {};
+MLDSA_BY_OID[O("id-ml-dsa-44")] = "ML-DSA-44";
+MLDSA_BY_OID[O("id-ml-dsa-65")] = "ML-DSA-65";
+MLDSA_BY_OID[O("id-ml-dsa-87")] = "ML-DSA-87";
+var MLDSA_SUITABLE_DIGEST = {
+  "ML-DSA-44": { sha256: 1, sha384: 1, sha512: 1, shake256: 1 },
+  "ML-DSA-65": { sha384: 1, sha512: 1, shake256: 1 },
+  "ML-DSA-87": { sha512: 1, shake256: 1 },
+};
+var SLHDSA_BY_OID = {};
+[["sha2-128s", "sha256"], ["sha2-128f", "sha256"], ["sha2-192s", "sha512"], ["sha2-192f", "sha512"],
+ ["sha2-256s", "sha512"], ["sha2-256f", "sha512"], ["shake-128s", "shake128"], ["shake-128f", "shake128"],
+ ["shake-192s", "shake256"], ["shake-192f", "shake256"], ["shake-256s", "shake256"], ["shake-256f", "shake256"]
+].forEach(function (r) { SLHDSA_BY_OID[O("id-slh-dsa-" + r[0])] = { wc: "SLH-DSA-" + r[0].toUpperCase(), digest: r[1] }; });
+
+// An AlgorithmIdentifier { OID } (absent parameters) or { OID, NULL }.
+function _algId(name, shape) { return shape === "null" ? b.sequence([b.oid(O(name)), b.nullValue()]) : b.sequence([b.oid(O(name))]); }
+// The RSASSA-PSS AlgorithmIdentifier: explicit SHA-2 hash, MGF1 keyed to it, hash-length salt,
+// default trailerField omitted (RFC 4055).
+function _pssAlgId(digestName) {
+  var hashAlg = b.sequence([b.oid(O(digestName)), b.nullValue()]);
+  var mgf = b.sequence([b.oid(O("mgf1")), hashAlg]);
+  var params = b.sequence([b.explicit(0, hashAlg), b.explicit(1, mgf), b.explicit(2, b.integer(BigInt(PSS_SALT[HASH[digestName]])))]);
+  return b.sequence([b.oid(O("rsassaPss")), params]);
+}
+// An id-RSASSA-PSS SPKI MAY pin its permitted hash in the params (RFC 4055 sec. 1.2 / 3.1). Read
+// it so signing honors the restriction; absent params or an unrecognized hash returns null.
+function _pssHashFromSpki(cert, E) {
+  var params = cert.subjectPublicKeyInfo.algorithm.parameters;
+  if (params == null) return null;
+  var node = asn1.decode(params);
+  if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children) return null;
+  var hashField = node.children.filter(function (c) { return c.tagClass === "context" && c.tagNumber === 0; })[0];
+  if (!hashField || !hashField.children || !hashField.children[0] || !hashField.children[0].children) return null;
+  var oidNode = hashField.children[0].children[0];
+  if (!oidNode || oidNode.tagClass !== "universal" || oidNode.tagNumber !== asn1.TAGS.OBJECT_IDENTIFIER) return null;
+  var pinnedOid = asn1.read.oid(oidNode);
+  var name = HASH_NAME_BY_OID[pinnedOid];
+  if (!name) throw E("unsupported-algorithm", "the id-RSASSA-PSS signer key pins an unsupported hash algorithm (" + pinnedOid + ")");
+  return name;
+}
+
+// resolveSignScheme(cert, so, noSignedAttrs, E) -> the signature scheme from the signer cert's
+// public-key algorithm + per-signer opts (so.digestAlgorithm / so.pss / so.combinedRsaSig -- the
+// last folds the digest into a combined RSA signature OID for a caller with no digestAlgorithm
+// field). Returns
+// { composite?, digest, digestAlgId, sigAlgId, imp?, sign?, ecdsaDer?, coordLen? }. `digest`/
+// `digestAlgId` matter only to a caller with a CMS digestAlgorithm field; OCSP ignores them.
+function resolveSignScheme(cert, so, noSignedAttrs, E) {
+  so = so || {};
+  var alg = cert.subjectPublicKeyInfo.algorithm;
+  var keyOid = alg.oid;
+  var comp = compositeSig.COMPOSITE_ALGS[keyOid];
+  if (comp) {
+    if (comp.trad.unsupported) throw E("unsupported-algorithm", "composite " + comp.name + ": " + comp.trad.unsupported);
+    if (so.digestAlgorithm && so.digestAlgorithm !== comp.phCms) throw E("bad-input", "composite " + comp.name + " fixes the digestAlgorithm to " + comp.phCms + " (draft-ietf-lamps-cms-composite-sigs sec. 3.4); " + JSON.stringify(so.digestAlgorithm) + " conflicts");
+    return { composite: comp, digest: comp.phCms, digestAlgId: _algId(comp.phCms, "absent"), sigAlgId: _algId(comp.name, "absent") };
+  }
+  if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) {
+    var isPssKey = keyOid === O("rsassaPss");
+    var pinned = isPssKey ? _pssHashFromSpki(cert, E) : null;
+    if (pinned && so.digestAlgorithm && so.digestAlgorithm !== pinned) throw E("bad-input", "the signer key restricts the RSASSA-PSS digest to " + pinned + ", but digestAlgorithm " + JSON.stringify(so.digestAlgorithm) + " was requested");
+    var d = so.digestAlgorithm || pinned || "sha256";
+    if (!HASH[d]) throw E("unsupported-algorithm", "unsupported RSA digest algorithm " + JSON.stringify(d));
+    if (so.pss || isPssKey) return { digest: d, digestAlgId: _algId(d, "absent"), sigAlgId: _pssAlgId(d), imp: { name: "RSA-PSS", hash: HASH[d] }, sign: { name: "RSA-PSS", saltLength: PSS_SALT[HASH[d]] }, ecdsaDer: false };
+    var rsaSigAlgId = so.combinedRsaSig ? _algId(RSA_PKCS1_SIG[d], "null") : _algId("rsaEncryption", "null");
+    return { digest: d, digestAlgId: _algId(d, "absent"), sigAlgId: rsaSigAlgId, imp: { name: "RSASSA-PKCS1-v1_5", hash: HASH[d] }, sign: { name: "RSASSA-PKCS1-v1_5" }, ecdsaDer: false };
+  }
+  if (keyOid === O("ecPublicKey")) {
+    var curveOid;
+    try { curveOid = asn1.read.oid(asn1.decode(alg.parameters)); }
+    catch (e) { throw E("unsupported-algorithm", "the signer EC key parameters are not a named-curve OID", e); }
+    var ec = EC_BY_CURVE_OID[curveOid];
+    if (!ec) throw E("unsupported-algorithm", "the signer key is on an unsupported EC curve");
+    var de = so.digestAlgorithm || "sha256";
+    if (!HASH[de]) throw E("unsupported-algorithm", "unsupported ECDSA digest algorithm " + JSON.stringify(de));
+    return { digest: de, digestAlgId: _algId(de, "absent"), sigAlgId: _algId(ECDSA_ALG[de], "absent"), imp: { name: "ECDSA", namedCurve: ec.curve }, sign: { name: "ECDSA", hash: HASH[de] }, ecdsaDer: true, coordLen: ec.coordLen };
+  }
+  if (keyOid === O("Ed25519") || keyOid === O("Ed448")) {
+    var name = keyOid === O("Ed25519") ? "Ed25519" : "Ed448";
+    var dd = so.digestAlgorithm || (name === "Ed25519" ? "sha512" : "shake256");
+    if (!NODE_DIGEST[dd]) throw E("unsupported-algorithm", "unsupported " + name + " digest algorithm " + JSON.stringify(dd));
+    return { digest: dd, digestAlgId: _algId(dd, "absent"), sigAlgId: _algId(name, "absent"), imp: { name: name }, sign: { name: name }, ecdsaDer: false };
+  }
+  if (MLDSA_BY_OID[keyOid]) {
+    var mlName = MLDSA_BY_OID[keyOid];
+    var md;
+    if (noSignedAttrs) {
+      md = "sha512";
+    } else {
+      md = so.digestAlgorithm || "sha512";
+      if (!NODE_DIGEST[md]) throw E("unsupported-algorithm", "unsupported ML-DSA message digest " + JSON.stringify(md));
+      if (!MLDSA_SUITABLE_DIGEST[mlName][md]) throw E("unsupported-algorithm", "the " + md + " message digest is below the security strength of " + mlName + " (RFC 9882 sec. 3.3)");
+    }
+    return { digest: md, digestAlgId: _algId(md, "absent"), sigAlgId: _algId(oid.name(keyOid), "absent"), imp: { name: mlName }, sign: { name: mlName }, ecdsaDer: false };
+  }
+  if (SLHDSA_BY_OID[keyOid]) {
+    var slh = SLHDSA_BY_OID[keyOid];
+    if (so.digestAlgorithm && so.digestAlgorithm !== slh.digest) throw E("bad-input", "SLH-DSA " + slh.wc + " requires the " + slh.digest + " message digest (RFC 9814 sec. 4); digestAlgorithm " + JSON.stringify(so.digestAlgorithm) + " conflicts");
+    return { digest: slh.digest, digestAlgId: _algId(slh.digest, "absent"), sigAlgId: _algId(oid.name(keyOid), "absent"), imp: { name: slh.wc }, sign: { name: slh.wc }, ecdsaDer: false };
+  }
+  throw E("unsupported-algorithm", "unsupported signer key algorithm " + keyOid);
+}
+
+// A CryptoKey's algorithm must match the resolved scheme (name / hash / curve).
+function _assertKeyMatchesScheme(key, imp, E) {
+  var ka = key.algorithm || {};
+  if (ka.name !== imp.name) throw E("bad-input", "the signer CryptoKey algorithm (" + ka.name + ") does not match the certificate's key algorithm (" + imp.name + ")");
+  if (imp.hash && (!ka.hash || ka.hash.name !== imp.hash)) throw E("bad-input", "the signer CryptoKey hash (" + (ka.hash && ka.hash.name) + ") does not match the signing digest (" + imp.hash + ")");
+  if (imp.namedCurve && ka.namedCurve !== imp.namedCurve) throw E("bad-input", "the signer CryptoKey curve (" + ka.namedCurve + ") does not match the certificate curve (" + imp.namedCurve + ")");
+}
+function _normPkcs8(k, label, E) {
+  if (Buffer.isBuffer(k)) return k;
+  if (k instanceof Uint8Array) return Buffer.from(k);
+  if (typeof k === "string") { try { return pkcs8.pemDecode(k); } catch (e) { throw E("bad-input", label + " PEM could not be decoded", e); } }
+  throw E("bad-input", label + " must be a PKCS#8 DER Buffer, Uint8Array, or PEM string");
+}
+function _normCompositeKeys(key, comp, E) {
+  if (!key || typeof key !== "object" || Buffer.isBuffer(key) || key instanceof Uint8Array || key.mldsa == null || key.trad == null) {
+    throw E("bad-input", "a composite " + comp.name + " signer key must be { mldsa: <PKCS#8>, trad: <PKCS#8> }");
+  }
+  return { mldsa: _normPkcs8(key.mldsa, "the composite ML-DSA component key", E), trad: _normPkcs8(key.trad, "the composite traditional component key", E) };
+}
+function _importKey(key, imp, E) {
+  if (key && typeof key === "object" && !Buffer.isBuffer(key) && !(key instanceof Uint8Array) && key.type === "private") {
+    _assertKeyMatchesScheme(key, imp, E);
+    return Promise.resolve(key);
+  }
+  var der;
+  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"]);
+}
+
+// signOverTbs(scheme, key, signedBytes, E) -> Promise<Buffer> the raw signature over signedBytes.
+// The classical path imports the key + signs (re-encoding ECDSA to canonical DER); the composite
+// path signs BOTH component keys and returns mldsaSig || tradSig (composite-sig.js owns it).
+function signOverTbs(scheme, key, signedBytes, E) {
+  if (scheme.composite) {
+    return compositeSig.compositeSign(scheme.composite, _normCompositeKeys(key, scheme.composite, E), signedBytes).then(function (sig) { return Buffer.from(sig); });
+  }
+  return _importKey(key, scheme.imp, E).then(function (priv) {
+    return subtle.sign(scheme.sign, priv, signedBytes).then(function (sigRaw) {
+      var sig = Buffer.from(sigRaw);
+      if (scheme.ecdsaDer) sig = validator.sig.rawToEcdsaDer(sig, scheme.coordLen);
+      return sig;
+    });
+  });
+}
+
+// MLDSA_SUITABLE_DIGEST + SLHDSA_BY_OID are the RFC 9882 sec. 3.3 / RFC 9814 sec. 4 per-parameter-
+// set digest policy, exported so the VERIFY side (cms-verify) shares the EXACT same table this
+// resolver signs under -- a digest accepted on sign is precisely the set accepted on verify, with
+// no drift between the two.
+module.exports = {
+  resolveSignScheme: resolveSignScheme,
+  signOverTbs: signOverTbs,
+  MLDSA_SUITABLE_DIGEST: MLDSA_SUITABLE_DIGEST,
+  SLHDSA_BY_OID: SLHDSA_BY_OID,
+};