@blamejs/pki 0.4.14 → 0.5.0

package/lib/cmp-build.js

@@ -191,12 +191,7 @@ function _encodeHeader(headerSpec, protectionAlgDer, pvno) {
 
 // A certReqId is an UNBOUNDED INTEGER (RFC 9483 -1 sentinel, no upper bound): accept a safe-integer number
 // or a bigint (a large value beyond 2^53), reject a non-integer / other type. Returns a BigInt for b.integer.
-function _reqIdInt(v, code, what) {
-  if (typeof v === "bigint") return v;
-  // Number.isSafeInteger (not isInteger): a value above 2^53 is imprecise as a Number, so it MUST be a bigint.
-  if (typeof v === "number" && Number.isSafeInteger(v)) return BigInt(v);
-  throw _err(code, what + " must be an integer (a safe-integer number, or a bigint for a large value)");
-}
+function _reqIdInt(v, code, what) { return guard.range.authoredInteger(v, _err, code, what); }
 
 // PKIFailureInfo ::= BIT STRING (named bits, RFC 9810 sec. 5.2.3) -- a minimal NamedBitList from bit names.
 function _encodeFailInfo(names, code) {
@@ -616,7 +611,7 @@ function _collectExtraCerts(opts, protCertDer) {
  * @primitive  pki.cmp.build
  * @signature  pki.cmp.build(message, opts?) -> Promise<Buffer|string>
  * @since      0.3.5
- * @status     experimental
+ * @status     stable
  * @spec       RFC 9810, RFC 9481, RFC 9579
  * @related    pki.schema.cmp.parse
  *
@@ -645,6 +640,12 @@ function _collectExtraCerts(opts, protCertDer) {
  *   - `pss` (boolean) / `digestAlgorithm` (string) -- signature-protection algorithm options.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
+ *   var csrDer = await pki.csr.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey) },
+ *     { key: signerKeyPkcs8 });
  *   var der = await pki.cmp.build(
  *     { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
  *       body: { p10cr: csrDer } },

package/lib/cmp-verify.js

@@ -665,7 +665,7 @@ async function _verify(message, opts) {
  * @primitive  pki.cmp.verify
  * @signature  pki.cmp.verify(message, opts?) -> Promise<verdict>
  * @since      0.3.26
- * @status     experimental
+ * @status     stable
  * @spec       RFC 9810, RFC 9481, RFC 9579, RFC 9483
  * @related    pki.cmp.build, pki.schema.cmp.parse
  * @defends    cmp-unverified-protection (CWE-347), cmp-mac-timing (CWE-208)
@@ -709,6 +709,16 @@ async function _verify(message, opts) {
  *   - `maxIterations` (number) -- downward-only override of the PBKDF2 iteration cap.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
+ *   var certDer = signerCertDer;   // self-signed here, so it is also its own anchor
+ *   var csrDer = await pki.csr.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey) },
+ *     { key: signerKeyPkcs8 });
+ *   var cmpDer = await pki.cmp.build(
+ *     { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
+ *       body: { p10cr: csrDer } }, { key: signerKeyPkcs8, cert: signerCertDer });
  *   var v = await pki.cmp.verify(cmpDer, { signerCert: signerCertDer, trustAnchors: [certDer] });
  *   if (v.valid && v.trusted) console.log("the response protection is authentic and the signer is trusted");
  */

package/lib/cms-sign.js

@@ -22,7 +22,7 @@ var frameworkError = require("./framework-error");
 var webcrypto = require("./webcrypto");
 var signScheme = require("./sign-scheme");
 var guard = require("./guard-all");
-var pkiBuild = require("./pki-build");
+var pkiBuild = require("./pki-build");   // the shared post-sign self-check, among other producing helpers
 var cms = require("./schema-cms");
 
 var subtle = webcrypto.webcrypto.subtle;
@@ -33,6 +33,15 @@ function _err(code, message, cause) { return new CmsError(code, message, cause);
 // cms/<kind>), so its faults keep the cms/* codes.
 function _signE(kind, message, cause) { return new CmsError("cms/" + kind, message, cause); }
 function O(name) { return oid.byName(name); }
+// The shared producing-side helpers, bound to this domain's error class. Only the
+// post-sign self-check is used here -- the same one every other signer in the
+// toolkit runs -- so a key-only signer's declared public key is bound by evidence
+// rather than by the caller's word.
+var NS = pkix.makeNS("cms", CmsError, oid);
+var _b = pkiBuild.makeBuilder({
+  ErrorClass: CmsError, prefix: "cms", O: O, NS: NS,
+  NAME_SCHEMA: pkix.name(NS), SPKI_SCHEMA: pkix.spki(NS), EXT_DECODERS: {},
+});
 
 // A digest-algorithm name -> the engine's hash name. The FIPS 202 extendable-output
 // functions are message digests here at the lengths RFC 8702 sec. 4 fixes for that use,
@@ -43,6 +52,7 @@ var DIGEST_HASH = {
 };
 
 var OID_DATA = O("data");
+var OID_PKI_DATA = O("id-cct-PKIData");   // the content type RFC 5272 sec. 3.2's signer rules govern
 var OID_SIGNED_DATA = O("signedData");
 var OID_SKI = O("subjectKeyIdentifier");
 
@@ -134,10 +144,35 @@ function _buildUnsignedAttrs(list) {
 // SignedData digestAlgorithms + certificates sets).
 function _buildSignerInfo(signer, content, eContentType, opts) {
   var so = signer || {};
-  var certDer = _normCertDer(so.cert);
-  var cert = x509.parse(certDer);
+  // A KEY-ONLY signer: `{ key, spki, keyIdentifier }` with no certificate. RFC
+  // 5272 sec. 3.2 requires exactly this when a Full PKI Request is signed with the
+  // key of a certification request it carries -- there is no certificate yet, the
+  // sid MUST be the subjectKeyIdentifier form, and its value MUST be the SKI the
+  // request itself declares. The scheme resolver only ever reads
+  // `cert.subjectPublicKeyInfo.algorithm`, so the request's own parsed SPKI stands
+  // in for the certificate that does not exist.
+  var keyOnly = so.cert == null && so.spki != null;
+  // Every field the emitted SignerInfo depends on is read ONCE, HERE, while
+  // nothing has deferred yet. The SignerIdentifier is built from the certificate
+  // or the key identifier on the lines below; the key signs, and is matched
+  // against `spki`, a promise turn later. A descriptor whose `key` and `spki`
+  // were swapped in that gap would emit a SignerInfo that names one public key
+  // and carries a signature by another -- coherent to the match check, since
+  // both halves moved together, and unverifiable to everyone else.
+  //
+  // The public bytes are COPIED, so an in-place rewrite cannot reach them
+  // either. The private key is captured by reference: copying it would put a
+  // second copy of key material in this function's hands, a secret it would then
+  // own for the rest of the call, and the reference already pins which key
+  // signs against the identifier that names it.
+  var soKey = so.key;
+  var soSpki = keyOnly ? guard.bytes.snapshotSource(so.spki, CmsError, "cms/bad-input", "a key-only signer's spki") : null;
+  var certDer = keyOnly ? null : _normCertDer(so.cert);
+  var cert = keyOnly ? _keyOnlyCertStandIn(soSpki) : x509.parse(certDer);
   var scheme = signScheme.resolveSignScheme(cert, so, opts.signedAttributes === false, _signE);
-  var sidv = _buildSid(cert, opts.sid === "ski");
+  var sidv = keyOnly
+    ? { sid: b.contextPrimitive(0, _keyOnlyKeyId(so)), version: 3 }   // [0] IMPLICIT SubjectKeyIdentifier
+    : _buildSid(cert, opts.sid === "ski");
   var sid = sidv.sid, version = sidv.version;
 
   return Promise.resolve().then(function () {
@@ -155,19 +190,60 @@ function _buildSignerInfo(signer, content, eContentType, opts) {
     });
   }).then(function (toSign) {
     var signedBytes = toSign.setOf ? toSign.setOf : toSign;   // SET-OF form for signing (sec. 5.4)
-    return signScheme.signOverTbs(scheme, so.key, signedBytes, _signE).then(function (sig) {
+    return signScheme.signOverTbs(scheme, soKey, signedBytes, _signE).then(function (sig) {
+      return _assertKeyMatchesSpki(keyOnly, soKey, soSpki, scheme, sig, signedBytes, cert).then(function () { return sig; });
+    }).then(function (sig) {
       var fields = [b.integer(BigInt(version)), sid, scheme.digestAlgId];
       if (toSign.wire) fields.push(toSign.wire);              // [0] IMPLICIT signedAttrs
       fields.push(scheme.sigAlgId, b.octetString(sig));
       var ua = _buildUnsignedAttrs(opts.unsignedAttributes);
       if (ua) fields.push(ua);                                 // [1] IMPLICIT unsignedAttrs
       return { si: b.sequence(fields), digestAlgId: scheme.digestAlgId, version: version, certDer: certDer };
+      // certDer is null for a key-only signer, and the certificates [0] embedding
+      // below filters it out -- there is nothing to embed, which is the point.
     });
   });
 }
 
 
 
+// A SignerInfo names a public key -- as `spki` when the signer is key-only, and as
+// the certificate it embeds otherwise -- while the signature comes from `key`. Two
+// different keys make a well-formed SignerInfo nobody can verify: the recipient
+// resolves the identifier to the declared key and checks a signature made by
+// another. Neither form catches that by itself, so both are checked here.
+//
+// Proven from the SIGNATURE, not from the key. Deriving the public half and
+// comparing it works only for key material this process can export, and the keys
+// this signer serves are often exactly the ones that cannot be: a non-extractable
+// CryptoKey, an HSM handle, or a composite `{ mldsa, trad }` pair that is two keys
+// rather than one. Every one of those can still be checked the direct way -- the
+// signature it just produced either verifies under the declared public key or it
+// does not -- so there is no key kind this has to take on trust.
+//
+// This is the same post-sign self-check every other signer in the toolkit runs,
+// through the same shared helper. It costs one verification per SignerInfo, which
+// is what a certificate, a CRL, a CSR and a CMP message have always paid here.
+function _assertKeyMatchesSpki(keyOnly, soKey, soSpki, scheme, sig, signedBytes, cert) {
+  var declared = keyOnly ? soSpki : (cert && cert.subjectPublicKeyInfo && cert.subjectPublicKeyInfo.bytes);
+  // A parsed certificate that does not retain its SPKI bytes cannot be checked this
+  // way. That is not a shape x509.parse produces -- and if it ever were, refusing is
+  // the answer rather than skipping, since a skip is the fail-open this prevents.
+  if (!declared) {
+    throw _signE("bad-input",
+      "a signer certificate did not surface its subjectPublicKeyInfo, so the signature it produced could " +
+      "not be checked against the key the SignerInfo declares");
+  }
+  return Promise.resolve()
+    .then(function () { return _b.assertSignatureVerifies(signedBytes, sig, declared, scheme); })
+    .then(null, function (e) {
+      if (e && typeof e.code === "string" && e.code.indexOf("cms/") === 0) throw e;
+      throw _signE("bad-input",
+        "a signer's `key` does not match the public key its SignerInfo declares (" +
+        (keyOnly ? "`spki`" : "its certificate") + "): the signature it produced does not verify under that key", e);
+    });
+}
+
 // A signing-time Time value: UTCTime before 2050, GeneralizedTime from 2050 (RFC 5652 sec. 11.3 /
 // RFC 5280 sec. 4.1.2.5). A caller Date overrides; false omits the attribute (handled above).
 function _timeValue(when) {
@@ -178,6 +254,75 @@ function _timeValue(when) {
 // Normalize a signer certificate input to its raw DER (DER Buffer / PEM string / Uint8Array).
 // The same bytes drive scheme resolution and the certificates [0] embedding, so a parsed
 // certificate (which does not retain its full DER) is rejected -- pass DER or PEM.
+// The stand-in a key-only signer resolves its signature scheme from: the parsed
+// SubjectPublicKeyInfo of the key that will sign. Only `.subjectPublicKeyInfo` is
+// read downstream, so this deliberately carries nothing else -- a fuller fake
+// would invite code to start trusting fields no certificate actually backs.
+function _keyOnlyCertStandIn(spkiDer) {
+  var alg;
+  try {
+    // SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }
+    // The WHOLE structure, not just the field this function goes on to read. For an
+    // OPAQUE key handle the derivation check downstream is deliberately skipped, so
+    // this is the ONLY thing standing between a caller's bytes and a SignerInfo that
+    // declares them: a SEQUENCE carrying an algorithm and nothing else, or a third
+    // field, would be emitted as the signer's public key and resolve to nothing for
+    // anyone trying to verify. The key VALUE is not interpreted -- only that there
+    // is one, in the field the structure reserves for it.
+    var node = asn1.decode(spkiDer);
+    if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children ||
+        node.children.length !== 2) {
+      throw _err("cms/bad-input",
+        "a key-only signer's spki is SEQUENCE { algorithm, subjectPublicKey BIT STRING } (RFC 5280 sec. 4.1.2.7)");
+    }
+    var keyNode = node.children[1];
+    if (keyNode.tagClass !== "universal" || keyNode.tagNumber !== asn1.TAGS.BIT_STRING) {
+      throw _err("cms/bad-input",
+        "a key-only signer's spki subjectPublicKey must be a BIT STRING (RFC 5280 sec. 4.1.2.7)");
+    }
+    asn1.read.bitString(keyNode);   // read, not tag-inspected: a malformed unused-bit count is refused here
+    var algNode = node.children[0];
+    if (algNode.tagClass !== "universal" || algNode.tagNumber !== asn1.TAGS.SEQUENCE ||
+        !algNode.children || !algNode.children.length || algNode.children.length > 2) {
+      throw _err("cms/bad-input",
+        "a key-only signer's spki algorithm is SEQUENCE { algorithm OID, parameters OPTIONAL } (RFC 5280 sec. 4.1.1.2)");
+    }
+    // The same shape schema-x509 surfaces: the algorithm OID plus its parameters
+    // as the RAW TLV (or null when absent) -- the resolver re-decodes those bytes
+    // for an EC named curve and for the RSASSA-PSS hash pinning, so handing it a
+    // different representation here would break exactly those two algorithms.
+    alg = {
+      oid: asn1.read.oid(algNode.children[0]),
+      parameters: algNode.children[1] ? algNode.children[1].bytes : null,
+    };
+  } catch (e) {
+    // The shape refusals above already name what is wrong; only a decode failure
+    // needs the generic message, so a precise verdict is not overwritten by it.
+    if (e && typeof e.code === "string" && e.code.indexOf("cms/") === 0) throw e;
+    throw _err("cms/bad-input", "a key-only signer's spki is not a SubjectPublicKeyInfo", e);
+  }
+  return { subjectPublicKeyInfo: { algorithm: alg } };
+}
+
+// The key identifier a key-only signer's sid carries. Required: without it there
+// is no way for a verifier to find the key, and RFC 5272 sec. 3.2 makes the value
+// the one the certification request declares.
+function _keyOnlyKeyId(so) {
+  if (so.keyIdentifier == null) {
+    throw _err("cms/bad-input",
+      "a key-only signer requires keyIdentifier -- the subjectKeyIdentifier the certification request declares (RFC 5272 sec. 3.2)");
+  }
+  // A key identifier is BYTES, so the type is checked rather than coerced. Buffer.from
+  // ACCEPTS far more than it should mean here: Buffer.from(20) allocates twenty zero
+  // octets and Buffer.from("a1b2") takes the ASCII of the text rather than the two
+  // octets a reader means by it. Either would emit a structurally valid
+  // SignerIdentifier carrying an identifier the caller never asked for, which no
+  // verifier can match back to the certification request (RFC 5272 sec. 3.2).
+  var id = guard.bytes.view(so.keyIdentifier, CmsError, "cms/bad-input", "a key-only signer's keyIdentifier");
+  if (!id.length) throw _err("cms/bad-input", "a key-only signer's keyIdentifier must not be empty");
+  return id;
+}
+
 function _normCertDer(c) {
   if (c == null) throw _err("cms/bad-input", "each signer requires a certificate (cert)");
   if (c instanceof Uint8Array && !Buffer.isBuffer(c)) c = Buffer.from(c);   // a Uint8Array -> Buffer (below)
@@ -199,6 +344,18 @@ function sign(content, signers, opts) {
   var list = Array.isArray(signers) ? signers : [signers];
   if (!list.length) throw _err("cms/bad-input", "pki.cms.sign requires at least one signer");
   var eContentType = opts.eContentType ? O(opts.eContentType) : OID_DATA;
+  // RFC 5272 sec. 3.2: "If the request key is used for signing, there MUST be only
+  // one SignerInfo in the SignedData." That clause governs a Full PKI Request, so
+  // it binds HERE only for that content type. CMS itself is happy with several
+  // SignerInfos, and a key-only signer's certificate can reach a verifier by other
+  // means -- applying the CMC rule to every content type would refuse ordinary
+  // SignedData that nothing objects to. pki.cmc.build enforces the same rule on
+  // the message it assembles, which is where the clause is really about.
+  if (eContentType === OID_PKI_DATA && list.length > 1 &&
+      list.some(function (s) { return s && s.cert == null && s.spki != null; })) {
+    throw _err("cms/bad-input",
+      "a key-only signer must be the ONLY SignerInfo in a Full PKI Request (RFC 5272 sec. 3.2)");
+  }
   // RFC 5652 sec. 5.3: signed attributes MUST be present (carrying a content-type attribute)
   // whenever the encapsulated content type is not id-data -- so signedAttributes:false is only
   // valid for id-data content. Refusing it here keeps cms.sign from emitting a non-conformant
@@ -226,8 +383,12 @@ function sign(content, signers, opts) {
     // certificates [0] IMPLICIT SET OF (the signer certs), deduped + SET-OF-ordered, when embedded.
     var sdFields = [b.integer(BigInt(version)), b.set(digestAlgs), encap];
     if (opts.certificates !== false) {
-      var certDers = _dedupe(built.map(function (x) { return x.certDer; })).sort(Buffer.compare);   // X.690 sec. 11.6
-      sdFields.push(b.contextConstructed(0, Buffer.concat(certDers)));              // [0] IMPLICIT SET OF
+      // A key-only signer contributes no certificate (certDer is null), so the
+      // set can end up EMPTY -- and an empty certificates [0] is not the same as
+      // an absent one, so the field is omitted entirely in that case.
+      var certDers = _dedupe(built.map(function (x) { return x.certDer; })
+        .filter(function (d) { return d != null; })).sort(Buffer.compare);        // X.690 sec. 11.6
+      if (certDers.length) sdFields.push(b.contextConstructed(0, Buffer.concat(certDers)));   // [0] IMPLICIT SET OF
     }
     sdFields.push(b.set(built.map(function (x) { return x.si; })));                 // signerInfos SET OF
     var signedData = b.sequence(sdFields);
@@ -276,6 +437,7 @@ function _buildCountersignature(targetSigOctets, countersigner, opts) {
   var cert = x509.parse(certDer);
   var scheme = signScheme.resolveSignScheme(cert, so, opts.signedAttributes === false, _signE);
   var sidv = _buildSid(cert, opts.sid === "ski");
+  var soKey = so.key;   // read once, here -- the SignerIdentifier above is already fixed to `cert`
   return Promise.resolve().then(function () {
     if (opts.signedAttributes === false) return null;   // sign the target signature octets directly
     return _digest(scheme.digest, targetSigOctets).then(function (md) {
@@ -286,7 +448,7 @@ function _buildCountersignature(targetSigOctets, countersigner, opts) {
       return _buildSignedAttrs(pairs.concat(extra));
     });
   }).then(function (attrs) {
-    return signScheme.signOverTbs(scheme, so.key, attrs ? attrs.setOf : targetSigOctets, _signE).then(function (sig) {
+    return signScheme.signOverTbs(scheme, soKey, attrs ? attrs.setOf : targetSigOctets, _signE).then(function (sig) {
       var fields = [b.integer(BigInt(sidv.version)), sidv.sid, scheme.digestAlgId];
       if (attrs) fields.push(attrs.wire);          // [0] IMPLICIT signedAttrs
       fields.push(scheme.sigAlgId, b.octetString(sig));

package/lib/cms-verify.js

@@ -572,7 +572,7 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * @primitive  pki.cms.verify
  * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, signers }>
  * @since      0.2.14
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5652
  * @spec       RFC 9882
  * @spec       RFC 9814
@@ -594,19 +594,55 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * @opts  certs    Extra signer certificates (an array of DER `Buffer`s) to match against, in
  *                 addition to the certificates embedded in the SignedData.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var detachedBytes = Buffer.from("hello");
+ *   var p7sDer = await pki.cms.sign(detachedBytes, { cert: cert, key: key, detached: true });
  *   var res = await pki.cms.verify(p7sDer, { content: detachedBytes });
  *   res.valid;                         // boolean
  *   res.signers[0].ok;                 // per-signer verdict
  */
+// A private copy of the input when -- and only when -- it is memory the caller can
+// still write to. Anything else (a PEM string, and whatever else the parser accepts)
+// is returned untouched so this cannot narrow the input contract of the parse it
+// feeds; the parser stays the one place that decides what an acceptable input is.
+function _snapshotIfBytes(input, label) {
+  // Every byte form the parser accepts -- an ArrayBuffer or a DataView reaches the
+  // decoder as readily as a Buffer, and leaving those aliased would reopen the
+  // window for exactly the inputs that came in by the wider door.
+  if (ArrayBuffer.isView(input) || input instanceof ArrayBuffer) {
+    return guard.bytes.snapshotSource(input, CmsError, "cms/bad-input", label);
+  }
+  return input;
+}
+
 function verify(input, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.verify options must be an object");
-  var parsed = (input && typeof input === "object" && !Buffer.isBuffer(input) && Array.isArray(input.signerInfos)) ? input : cms.parse(input);
+  // Handed MUTABLE BYTES, parse a private copy. This function decodes synchronously
+  // and checks signatures in a later promise turn, so without the copy every range
+  // the parse surfaced -- the signed content above all -- stays a view into the
+  // caller's memory across that await, and a buffer rewritten in the gap would leave
+  // the result describing one message while the signature was checked over another.
+  // Only a Buffer / Uint8Array can change underneath us: a PEM string is immutable
+  // and passes through untouched, and an already-parsed object is a lifetime the
+  // caller chose. Narrow rather than blanket, so neither input form is refused here
+  // that pki.cms.parse itself accepts.
+  var parsed = (input && typeof input === "object" && !Buffer.isBuffer(input) && Array.isArray(input.signerInfos))
+    ? input
+    : cms.parse(_snapshotIfBytes(input, "pki.cms.verify"));
   if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "input is not a CMS SignedData");
   var content = parsed.encapContentInfo.eContent;
   if (content == null) {
     if (opts.content == null) throw _err("cms/detached-content-required", "this SignedData is detached; opts.content (the external content) is required");
-    content = _toBuf(opts.content, "opts.content");
+    // Copied, not aliased: the digest over this content is computed in a later promise turn,
+    // and a detached signature's content is the whole of what the signature speaks about. A
+    // caller who rewrote the buffer in that gap would have the signature checked against the
+    // original bytes while holding the replacement, and the verdict would report a valid
+    // signature over content that was never signed.
+    content = _toBuf(_snapshotIfBytes(opts.content, "opts.content"), "opts.content");
   } else if (opts.content != null) {
     // A caller supplied external content AND the SignedData is attached. A redundant COPY that equals
     // the encapsulated content is fine; content that DIFFERS is a substitution trap -- silently
@@ -635,10 +671,15 @@ function verify(input, opts) {
 }
 // Parse a candidate cert DER and index its SKI; a cert that will not parse is skipped (it
 // simply cannot be a signer match, and a malformed embedded cert must not fail the verify).
+// The certificate bytes are copied BEFORE they are parsed, not after: the parse surfaces the
+// signed portion and the public key as VIEWS into this buffer, and both are read in a later
+// promise turn to check the signer's signature and walk the chain. Copying afterwards would
+// leave those views pointing at bytes the caller can still rewrite -- a signer certificate
+// swapped for another in that gap, with the verdict still naming the first.
 function _addCert(out, der) {
   var buf;
   try {
-    buf = _toBuf(der, "a certificate");
+    buf = _toBuf(_snapshotIfBytes(der, "a certificate"), "a certificate");
   } catch (_e) { return; }
   var cert;
   try {
@@ -663,7 +704,7 @@ function _addCert(out, der) {
  * @primitive  pki.cms.sign
  * @signature  pki.cms.sign(content, signers, opts?) -> Promise<Buffer|string>
  * @since      0.2.15
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5652
  * @spec       RFC 9882
  * @spec       RFC 9814
@@ -701,6 +742,10 @@ function _addCert(out, der) {
  *                          rejected here (RFC 5652 sec. 11). Use `pki.cms.countersign` for a
  *                          countersignature specifically.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p7 = await pki.cms.sign(Buffer.from("hello"), { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var res = await pki.cms.verify(p7);   // res.valid === true
  */
@@ -710,7 +755,7 @@ var sign = cmsSign.sign;
  * @primitive  pki.cms.countersign
  * @signature  pki.cms.countersign(cms, signers, opts?) -> Promise<Buffer|string>
  * @since      0.3.13
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5652
  * @related    pki.cms.sign, pki.cms.verify, pki.schema.cms.parse
  *
@@ -740,6 +785,10 @@ var sign = cmsSign.sign;
  * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default true.
  * @opts  pem                   Return a PEM string instead of a DER Buffer.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p7 = await pki.cms.sign(Buffer.from("hi"), { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var cs = await pki.cms.countersign(p7, { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var res = await pki.cms.verify(cs);
@@ -751,7 +800,7 @@ var countersign = cmsSign.countersign;
  * @primitive pki.cms.encrypt
  * @signature pki.cms.encrypt(content, recipients, opts?) -> Promise<Buffer | string>
  * @since 0.2.23
- * @status experimental
+ * @status stable
  * @spec RFC 5652, RFC 5083, RFC 5084, RFC 3560, RFC 5753, RFC 8418, RFC 9629, RFC 9936, RFC 3211, RFC 8018
  * @related pki.cms.decrypt, pki.schema.cms.parse
  *
@@ -775,6 +824,11 @@ var countersign = cmsSign.countersign;
  * @opts authAttrs     Authenticated attributes (SET OF Attribute) for AuthEnvelopedData.
  * @opts pem           Return a PEM string instead of a DER Buffer.
  * @example
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var pair = await pki.key.generate(rsa);
+ *   var recipientKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var recipientCertDer = await pki.x509.sign({ subject: "Recipient", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: recipientKeyPkcs8 });
  *   var env = await pki.cms.encrypt(Buffer.from("secret"), [{ cert: recipientCertDer }]);
  */
 var encrypt = cmsEncrypt.encrypt;
@@ -783,7 +837,7 @@ var encrypt = cmsEncrypt.encrypt;
  * @primitive pki.cms.authenticate
  * @signature pki.cms.authenticate(content, recipients, opts?) -> Promise<Buffer | string>
  * @since 0.3.14
- * @status experimental
+ * @status stable
  * @spec RFC 5652, RFC 2104, RFC 4231, RFC 3370
  * @related pki.cms.decrypt, pki.schema.cms.parse
  *
@@ -809,9 +863,14 @@ var encrypt = cmsEncrypt.encrypt;
  * @opts keyIdentifier `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
  * @opts pem Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
  * @example
- *   var r = pki.cms; // authenticate a message to an RSA recipient, then verify via decrypt
- *   var auth = await r.authenticate(Buffer.from("hi"), [{ cert: recipientCertDer }]);
- *   var out = await r.decrypt(auth, { key: recipientKeyPkcs8, cert: recipientCertDer });
+ *   // authenticate a message to an RSA recipient, then verify the MAC via decrypt
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var pair = await pki.key.generate(rsa);
+ *   var recipientKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var recipientCertDer = await pki.x509.sign({ subject: "Recipient", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: recipientKeyPkcs8 });
+ *   var auth = await pki.cms.authenticate(Buffer.from("hi"), [{ cert: recipientCertDer }]);
+ *   var out = await pki.cms.decrypt(auth, { key: recipientKeyPkcs8, cert: recipientCertDer });
  *   out.authenticated;   // true
  */
 var authenticate = cmsEncrypt.authenticate;
@@ -820,7 +879,7 @@ var authenticate = cmsEncrypt.authenticate;
  * @primitive pki.cms.decrypt
  * @signature pki.cms.decrypt(input, keyMaterial, opts?) -> Promise<{ content, contentType, contentTypeName, recipientType, recipientIndex, contentEncryptionAlgorithm, authenticated }>
  * @since 0.2.23
- * @status experimental
+ * @status stable
  * @spec RFC 5652, RFC 5083, RFC 5084, RFC 3560, RFC 5753, RFC 8418, RFC 9629, RFC 9936, RFC 3211, RFC 8018, RFC 3218, RFC 2104
  * @related pki.cms.encrypt, pki.cms.authenticate, pki.schema.cms.parse
  *
@@ -843,6 +902,12 @@ var authenticate = cmsEncrypt.authenticate;
  * @opts recipientIndex Explicitly select the recipient by index (overrides key-material matching).
  * @opts maxIterations  Lower the PBKDF2 iteration cap (a DoS bound; downward only).
  * @example
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var pair = await pki.key.generate(rsa);
+ *   var recipientKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var recipientCertDer = await pki.x509.sign({ subject: "Recipient", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: recipientKeyPkcs8 });
+ *   var envDer = await pki.cms.encrypt(Buffer.from("secret"), [{ cert: recipientCertDer }]);
  *   var res = await pki.cms.decrypt(envDer, { key: recipientKeyPkcs8, cert: recipientCertDer });
  *   res.content;   // the recovered plaintext Buffer
  */
@@ -852,7 +917,7 @@ var decrypt = cmsDecrypt.decrypt;
  * @primitive pki.cms.compress
  * @signature pki.cms.compress(content, opts?) -> Promise<Buffer | string>
  * @since 0.2.27
- * @status experimental
+ * @status stable
  * @spec RFC 3274, RFC 1950, RFC 1951
  * @related pki.cms.decompress, pki.schema.cms.parse
  *
@@ -875,7 +940,7 @@ var compress = cmsCompress.compress;
  * @primitive pki.cms.decompress
  * @signature pki.cms.decompress(input, opts?) -> Promise<{ content, contentType, contentTypeName, compressionAlgorithm }>
  * @since 0.2.27
- * @status experimental
+ * @status stable
  * @spec RFC 3274, RFC 1950, RFC 1951
  * @related pki.cms.compress, pki.schema.cms.parse
  *
@@ -890,6 +955,7 @@ var compress = cmsCompress.compress;
  *
  * @opts maxOutputBytes Lower the decompressed-output cap (a DoS bound; downward only).
  * @example
+ *   var compressedDer = await pki.cms.compress(Buffer.from("compress me"));
  *   var res = await pki.cms.decompress(compressedDer);
  *   res.content;   // the recovered plaintext Buffer
  */

package/lib/crl-sign.js

@@ -486,6 +486,12 @@ function _sign(spec, issuer, opts) {
  *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Issuing CA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"], subjectKeyIdentifier: true } },
+ *     { key: signerKeyPkcs8 });
  *   var der = await pki.crl.sign({
  *     thisUpdate: new Date("2026-01-01T00:00:00Z"), nextUpdate: new Date("2026-02-01T00:00:00Z"),
  *     crlNumber: 7n,
@@ -529,6 +535,14 @@ function _resolveIssuerSpki(issuer) {
  * signature only -- issuer authorization, currency, and distribution-point scope are `pki.path.crlChecker`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerSpki = await pki.key.export(pair.publicKey);
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Issuing CA", subjectPublicKey: signerSpki,
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"] } }, { key: signerKeyPkcs8 });
+ *   var crlDer = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n, revoked: [] },
+ *     { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var ok = await pki.crl.verify(crlDer, { publicKey: signerSpki });   // true / false
  */
 function verify(crl, issuer) { return Promise.resolve().then(function () { return _verify(crl, issuer); }); }
@@ -565,6 +579,14 @@ function _serialHexOf(serial) {
  * it does NOT verify the CRL signature or its currency; call `pki.crl.verify` / `pki.path.crlChecker` for that.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Issuing CA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"] } }, { key: signerKeyPkcs8 });
+ *   var crlDer = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n,
+ *     revoked: [{ serialNumber: 0x1234n, revocationDate: new Date("2026-01-15T00:00:00Z") }] },
+ *     { cert: signerCertDer, key: signerKeyPkcs8 });
  *   pki.crl.isRevoked(crlDer, 0x1234n) ? "revoked" : "not listed";
  */
 function isRevoked(crl, serialNumber) {

package/lib/crmf-sign.js

@@ -203,7 +203,7 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  * @primitive pki.crmf.build
  * @signature pki.crmf.build(spec, key?, opts?) -> Promise<Buffer|string>
  * @since 0.3.3
- * @status experimental
+ * @status stable
  * @spec RFC 4211
  * @defends forged-certificate-request (CWE-347)
  * @related pki.schema.crmf.parse, pki.csr.sign
@@ -229,6 +229,9 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerSpki = await pki.key.export(pair.publicKey);
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
  *   var msg = await pki.crmf.build(
  *     { certReqId: 0, certTemplate: { subject: "device-42", publicKey: signerSpki } },
  *     { key: signerKeyPkcs8 });
@@ -287,7 +290,7 @@ function _build(spec, key, opts) {
  * @primitive  pki.crmf.buildCertTemplate
  * @signature  pki.crmf.buildCertTemplate(template) -> Buffer
  * @since      0.3.5
- * @status     experimental
+ * @status     stable
  * @spec       RFC 4211
  * @related    pki.crmf.build
  *

package/lib/csr-sign.js

@@ -91,6 +91,9 @@ function _challengePassword(pw) {
  *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerSpki = await pki.key.export(pair.publicKey);
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
  *   var req = await pki.csr.sign(
  *     { subject: "req.example.com", subjectPublicKey: signerSpki,
  *       extensionRequest: { subjectAltName: [{ dNSName: "req.example.com" }] } },