@blamejs/pki 0.8.51 → 0.8.52

package/lib/cms-verify.js

@@ -31,6 +31,7 @@ var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
 var cms = require("./schema-cms");
+var smime = require("./schema-smime");
 var webcrypto = require("./webcrypto");
 var subtle = webcrypto.webcrypto.subtle;
 var edwardsPoint = require("./edwards-point");
@@ -46,6 +47,7 @@ var validator = require("./validator-all");
 var compositeSig = require("./composite-sig");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
+var constants = require("./constants");
 var frameworkError = require("./framework-error");
 var pkix = require("./schema-pkix");
 
@@ -69,6 +71,15 @@ function _row(o) { return guard.verdict.of(o); }
 var OID_MESSAGE_DIGEST = oid.byName("messageDigest");
 var OID_CONTENT_TYPE = oid.byName("contentType");
 var OID_COUNTERSIGNATURE = oid.byName("countersignature");
+/** @internal `id-aa-signatureTimeStampToken`, which the registry already carries under the S/MIME
+ *  authenticated-attribute arc as `timeStampToken`: `oid.byName("timeStampToken")` is
+ *  `1.2.840.113549.1.9.16.2.14`, the OID RFC 5126 clause 6.1.1 assigns. A second name for one OID
+ *  would give `oid.name()` two answers, so the existing name is used rather than a CAdES alias. */
+var OID_TIMESTAMP_TOKEN = oid.byName("timeStampToken");
+var OID_ID_DATA = oid.byName("data");
+var OID_SIGNING_CERTIFICATE = oid.byName("signingCertificate");
+var OID_SIGNING_CERTIFICATE_V2 = oid.byName("signingCertificateV2");
+var OID_SIGNING_TIME = oid.byName("signingTime");
 
 var DIGEST_HASH = intrinsic.assign(intrinsic.create(null), {
   sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512",
@@ -83,9 +94,16 @@ function _digestOidTable(named) {
   });
   return t;
 }
-var WEAK_DIGEST_OIDS = _digestOidTable([["sha1", "SHA-1"]]);
+/** @internal Both tables read the one membership list in `C.NAMES.WEAK_DIGESTS`, keyed the two ways
+ *  the two checks ask the question: by the digest OID a SignerInfo declares, and by the WebCrypto
+ *  hash name a signature algorithm resolves to. A digest added to that list reaches both. */
+var _WEAK_DIGEST_NAMES = intrinsic.map(intrinsic.keys(constants.NAMES.WEAK_DIGESTS), function (n) {
+  return [n, constants.NAMES.WEAK_DIGESTS[n]];
+});
+var WEAK_DIGEST_OIDS = _digestOidTable(_WEAK_DIGEST_NAMES);
 var UNVERIFIABLE_DIGEST_OIDS = _digestOidTable([["md5", "MD5"], ["md4", "MD4"], ["md2", "MD2"]]);
-var WEAK_SIGNATURE_HASHES = intrinsic.assign(intrinsic.create(null), { "SHA-1": 1 });
+var WEAK_SIGNATURE_HASHES = intrinsic.create(null);
+intrinsic.forEach(_WEAK_DIGEST_NAMES, function (pair) { WEAK_SIGNATURE_HASHES[pair[1]] = 1; });
 function _supportedDigest(name) { return intrinsic.hasOwn(DIGEST_HASH, name) && !!DIGEST_HASH[name]; }
 async function _computeDigest(name, content) {
   return intrinsic.bufferFrom(await subtle.digest(DIGEST_HASH[name], content));
@@ -155,6 +173,35 @@ async function _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes,
     : { ok: false, sid: sid, cert: candidates[0].der });
 }
 
+/** @internal Where a signer identifier matches several certificates, the signing-certificate
+ *  attribute is what says which of them made the signature, so one it names is tried first. A
+ *  subjectKeyIdentifier names a KEY: two certificates holding that key verify the same signature
+ *  equally, and without this the one reported as `signers[i].cert` would be whichever candidate came
+ *  first, taking with it every decision keyed to that certificate, its validity window, its key
+ *  usage, and the chain built from it. RFC 5035 clause 5.4 makes the first identifier "the
+ *  certificate used to verify the signature", which is exactly this question.
+ *
+ *  Order is all that changes: a candidate the attribute names still has to verify the signature, and
+ *  where none is named or none matches, the list is returned as it came. */
+function _preferBoundCandidate(si, candidates) {
+  if (candidates.length < 2) return candidates;
+  /** @internal The attribute is read ONCE and each candidate compared against what it read. Reading
+   *  it per candidate would multiply its size by the candidate count, and both are attacker-chosen:
+   *  a message can embed many certificates carrying one subject key identifier and a long
+   *  certificate list inside the attribute, so the work would be their product, spent before the
+   *  signature is checked. */
+  var claims = smime.certBindingClaims(si.signedAttrs || []);
+  if (!claims.present) return candidates;
+  var bound = [];
+  var rest = [];
+  intrinsic.forEach(candidates, function (c) {
+    var entry = smime.certBindingAgainst(claims.chosen, c.der);
+    var names = entry.matches === true && entry.issuerSerialMatches !== false;
+    guard.list.append(names ? bound : rest, c);
+  });
+  return bound.length ? intrinsic.concat(bound, rest) : candidates;
+}
+
 function _certSki(cert) {
   var ext = (cert.extensions || []).filter(function (e) { return e.oid === oid.byName("subjectKeyIdentifier"); })[0];
   if (!ext) return null;
@@ -295,7 +342,7 @@ async function _verifyOne(si, content, eContentType, parsedCerts, csTarget, dige
   if ((scheme.kind !== "eddsa" && scheme.kind !== "mldsa" && scheme.kind !== "slhdsa" && !sigHash) || (si.signedAttrsBytes && !_supportedDigest(si.digestAlgorithm.name))) return _pResolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported digest algorithm " + JSON.stringify(si.digestAlgorithm.name) });
   if (scheme.kind === "mldsa" && si.signedAttrsBytes && !_mldsaDigestSuitable(scheme.name, si.digestAlgorithm.name)) return _pResolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.digestAlgorithm.name + " message digest is below the security strength of " + scheme.name + " (RFC 9882 sec. 3.3)" });
   if (scheme.kind === "slhdsa" && si.signedAttrsBytes && si.digestAlgorithm.name !== scheme.digest) return _pResolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "SLH-DSA " + scheme.name + " requires the " + scheme.digest + " message digest (RFC 9814 sec. 4)" });
-  var signers = _findSignerCerts(si.sid, parsedCerts);
+  var signers = _preferBoundCandidate(si, _findSignerCerts(si.sid, parsedCerts));
   if (!signers.length) return _pResolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
 
@@ -381,7 +428,7 @@ async function _verifyComposite(si, comp, content, eContentType, parsedCerts, cs
   if (si.digestAlgorithm.name !== comp.phCms) {
     return _pResolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the SignerInfo digestAlgorithm " + JSON.stringify(si.digestAlgorithm.name) + " is not the composite " + comp.name + " pre-hash " + JSON.stringify(comp.phCms) + " (draft-ietf-lamps-cms-composite-sigs sec. 3.4)" });
   }
-  var signers = _findSignerCerts(si.sid, parsedCerts);
+  var signers = _preferBoundCandidate(si, _findSignerCerts(si.sid, parsedCerts));
   if (!signers.length) return _pResolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
   var signedBytes = await (csTarget != null ? _computeCountersigBytes(si, csTarget) : _computeSignedBytes(si, content, eContentType, digestByName));
@@ -417,6 +464,326 @@ function _surfaceSignedAttrs(si) {
   });
 }
 
+/** @internal The CAdES baseline requirements this verb decides from one SignerInfo's own signed
+ *  attributes, reported beside the signature verdict rather than folded into it: a signature can be
+ *  cryptographically sound and still not be a CAdES signature, and the two answers are separate.
+ *
+ *  `requirementsChecked` names the scope in the data, so a caller reads which requirements were
+ *  evaluated instead of taking `conformant` for a full ETSI EN 319 122-1 clause 6.3 audit. Each
+ *  finding carries the `level` of the requirement it is against, and `conformant` answers for the
+ *  shall-level ones alone, so a SHOULD the document states as guidance is reported without being
+ *  reported as non-conformance.
+ *
+ *  - requirement f, shall: "The content-type attribute shall have value id-data".
+ *  - clauses 5.2.2.2 and 5.2.2.3, shall: the signing certificate is protected by a
+ *    `signing-certificate` or `signing-certificate-v2` attribute, and the identifier it carries
+ *    names the certificate the signature resolved to. Clause 5.2.2.2 NOTE 2: "the binding
+ *    information is the digest of the certificate".
+ *  - requirement h, shall: "The ESS signing-certificate attribute shall be used if the SHA-1 hash
+ *    algorithm is used". The two attributes are defined BY their hash algorithm, clause 5.2.2.2 as
+ *    "a signing certificate attribute using the SHA-1 hash algorithm" and clause 5.2.2.3 as one
+ *    "using a hash algorithm different from SHA-1", so what the requirement reads is the digest the
+ *    identifier binds with and not the digest the signature was computed under. Its sibling
+ *    requirement i, the v2 form "when another hash algorithm than SHA-1 is used", has no verifiable
+ *    counterexample: a v1 ESSCertID carries no algorithm field, so a non-SHA-1 binding cannot be
+ *    expressed in one, and it is not claimed as checked.
+ *  - requirement g, should: "The issuerSerial field should not be included in the encoding of the
+ *    ESSCertID, ESSCertIDv2 or OtherCertID type".
+ *  - requirement j, should: "The generator should migrate to the use of ESS signing-certificate-v2
+ *    in preference to ESS signing-certificate in line with the guidance regarding limited lifetime
+ *    for the use of SHA-1", which is what a SHA-1 binding is reported against.
+ */
+var CADES_BASELINE_CHECKED = intrinsic.freeze([
+  "ETSI EN 319 122-1 clause 6.3 requirement f",
+  "ETSI EN 319 122-1 clauses 5.2.2.2 and 5.2.2.3",
+  "ETSI EN 319 122-1 clause 6.3 requirement g",
+  "ETSI EN 319 122-1 clause 6.3 requirement h",
+  "ETSI EN 319 122-1 clause 6.3 requirement j",
+]);
+
+function _cadesBaseline(si, signerCert) {
+  var attrs = si.signedAttrs || [];
+  var findings = [];
+  var contentType = null;
+  intrinsic.forEach(attrs, function (a) {
+    if (a.type !== OID_CONTENT_TYPE || contentType !== null || !a.values || a.values.length !== 1) return;
+    try { contentType = asn1.read.oid(asn1.decode(a.values[0])); }
+    // allow:swallow-unverified a content-type that does not read is reported as the unmet requirement below
+    catch (_e) { contentType = null; }
+  });
+  if (contentType !== OID_ID_DATA) {
+    guard.list.append(findings, {
+      code: "cms/cades-content-type", level: "shall",
+      message: "the content-type attribute shall have value id-data (ETSI EN 319 122-1 clause 6.3 " +
+        "requirement f), and this signature carries " +
+        (contentType === null ? "no readable content-type attribute" : (oid.name(contentType) || contentType)),
+    });
+  }
+  var v1 = null;
+  var v2 = null;
+  intrinsic.forEach(attrs, function (a) {
+    if (a.type === OID_SIGNING_CERTIFICATE && v1 === null && a.values && a.values.length === 1) v1 = a.values[0];
+    if (a.type === OID_SIGNING_CERTIFICATE_V2 && v2 === null && a.values && a.values.length === 1) v2 = a.values[0];
+  });
+  if (v1 === null && v2 === null) {
+    guard.list.append(findings, {
+      code: "cms/cades-no-signing-certificate", level: "shall",
+      message: "the signing certificate shall be protected by a signing-certificate or " +
+        "signing-certificate-v2 signed attribute (ETSI EN 319 122-1 clauses 5.2.2.2 and 5.2.2.3)",
+    });
+  } else {
+    intrinsic.forEach(_bindingFindings(attrs, signerCert), function (f) {
+      guard.list.append(findings, f);
+    });
+  }
+  return guard.verdict.of({
+    conformant: guard.list.allMatch(findings, function (f) { return f.level !== "shall"; }),
+    signingCertificateAttribute: v2 !== null ? "v2" : (v1 !== null ? "v1" : null),
+    findings: findings,
+    requirementsChecked: CADES_BASELINE_CHECKED,
+  });
+}
+
+/** @internal What the signing-certificate attribute claims, checked against the certificate this
+ *  SignerInfo selected. The requirement is that the certificate IS protected, so the attribute's
+ *  presence is not the answer: an identifier naming other bytes binds the signature to a certificate
+ *  nobody resolved it to, which is the substitution the attribute exists to prevent (RFC 5035
+ *  clause 5.4: "The first certificate identified in the sequence of certificate identifiers MUST be
+ *  the certificate used to verify the signature").
+ *
+ *  The claims are read by `pki.schema.smime.certBindingFacts`, the one implementation of "does this
+ *  identifier name that certificate", which `pki.tsp.verify` holds a timestamp token to. What differs
+ *  is the policy over the facts, not the facts: that verb refuses a token on the first failing claim,
+ *  and this one reports every claim that failed, because a conformance verdict is read to find out
+ *  what is wrong rather than to decide one thing. A superseded v1 attribute is held to the same claim
+ *  as the v2 that supersedes it, so a structure naming one certificate in each is reported rather
+ *  than resolved in favor of whichever a reader prefers. An identifier this build cannot recompute,
+ *  and a signature whose certificate was never matched, are reported as the undecided claims they
+ *  are rather than passed over. */
+function _bindingFindings(attrs, signerCert) {
+  if (signerCert == null) {
+    return [{ code: "cms/cades-signing-certificate-unverifiable", level: "shall",
+      message: "no certificate was matched for this signer, so what the signing-certificate " +
+        "attribute binds cannot be checked" }];
+  }
+  var facts = smime.certBindingFacts(attrs, signerCert);
+  var out = [];
+  var entries = [facts.chosen];
+  intrinsic.forEach(facts.superseded, function (s) { guard.list.append(entries, s); });
+  intrinsic.forEach(entries, function (e) {
+    var which = e.form === "v2" ? "signing-certificate-v2" : "signing-certificate";
+    if (!e.readable) {
+      guard.list.append(out, { code: "cms/cades-signing-certificate-unreadable", level: "shall",
+        message: "the " + which + " attribute value does not decode, so what it binds cannot be checked" });
+      return;
+    }
+    if (!e.supported) {
+      guard.list.append(out, { code: "cms/cades-signing-certificate-unreadable", level: "shall",
+        message: "the " + which + " identifier names the digest " + e.digestName +
+          ", which this build does not bind a certificate with, so what it binds cannot be checked" });
+      return;
+    }
+    /** @internal The form is held to the digest it binds with, which is what defines each of the two
+     *  attributes: a v2 identifier naming SHA-1 is the case requirement h sends to the v1 attribute.
+     *  A v1 identifier carries no algorithm field, so it is SHA-1 by the type and can never be the
+     *  wrong form for its own digest; what it draws is requirement j's migration guidance. */
+    if (e.weak && e.form === "v2") {
+      guard.list.append(out, { code: "cms/cades-signing-certificate-form", level: "shall",
+        message: "the signing-certificate attribute shall be used if the SHA-1 hash algorithm is " +
+          "used (ETSI EN 319 122-1 clause 6.3 requirement h), and this signature carries a " +
+          "signing-certificate-v2 identifier binding with " + e.digestName });
+    } else if (e.weak) {
+      guard.list.append(out, { code: "cms/cades-weak-certificate-binding", level: "should",
+        message: "the " + which + " identifier binds the certificate with " + e.digestName +
+          ", and a generator should migrate to signing-certificate-v2 in preference to " +
+          "signing-certificate given the limited lifetime for the use of SHA-1 (ETSI EN 319 122-1 " +
+          "clause 6.3 requirement j)" });
+    }
+    if (e.issuerSerialPresent) {
+      guard.list.append(out, { code: "cms/cades-issuer-serial-included", level: "should",
+        message: "the issuerSerial field should not be included in the encoding of the " +
+          (e.form === "v2" ? "ESSCertIDv2" : "ESSCertID") + " type (ETSI EN 319 122-1 clause 6.3 " +
+          "requirement g); clause 5.2.2.2 NOTE 2 has it as a hint, the binding being the digest of " +
+          "the certificate" });
+    }
+    if (e.certUnreadable) {
+      guard.list.append(out, { code: "cms/cades-signing-certificate-unverifiable", level: "shall",
+        message: "the " + which + " identifier states an issuer and serial, and the certificate " +
+          "this signer resolved to does not parse, so that claim cannot be checked" });
+    }
+    if (e.matches !== true || e.issuerSerialMatches === false) {
+      guard.list.append(out, { code: "cms/cades-signing-certificate-mismatch", level: "shall",
+        message: "the first " + which + " identifier does not name the certificate this signature " +
+          "was resolved to: " + (e.matches !== true ? "the certificate hash disagrees"
+            : "the hash agrees but the issuer and serial name another certificate") +
+          " (RFC 5035 clause 5.4), so the signing certificate is not protected (ETSI EN 319 122-1 " +
+          "clauses 5.2.2.2 and 5.2.2.3)" });
+    }
+  });
+  return out;
+}
+
+/** @internal The CAdES signature timestamps on one SignerInfo, each as its own row.
+ *
+ * `id-aa-signatureTimeStampToken` is `{ 1 2 840 113549 1 9 16 2 14 }` (RFC 5126 clause 6.1.1; ETSI
+ * EN 319 122-1 clause 5.3 and Annex D) and its imprint is "the hash value of the signature field
+ * (without the ASN.1 tag and length) within SignerInfo for which the signature-time-stamp attribute
+ * is created" (EN 319 122-1 clause 5.3).
+ *
+ * Read HERE, in the loop that already holds `targetSig`, rather than in a verb of its own. The
+ * imprint preimage is the same octets the countersignature row covers, and a separate verb would
+ * re-derive it from its own parse: two derivations of one preimage that can disagree is a silent
+ * fail-open, since the one that disagrees is the one that accepts.
+ *
+ * Plurality is the opposite of countersignature: EN 319 122-1 clause 5.3 has "exactly one component
+ * of AttributeValue type" per attribute, and RFC 5126 clause 6.1.1 allows "several instances of this
+ * attribute ... from different TSAs", so each instance is one row and an instance carrying two values
+ * is refused rather than read as two timestamps.
+ *
+ * Every failure is a ROW verdict and never a throw: a signature whose timestamp cannot be read still
+ * has its own signature verdict, and collapsing the two would lose it.
+ *
+ * `0.4.0.1733.2.4`, the archive timestamp, is NOT read here. EN 319 122-1 clause 5.5.3 contains the
+ * sentence "The archive-time-stamp-v3 attribute shall be identified by the
+ * id-aa-signatureTimeStampToken OID" and then defines `id-aa-ets-archiveTimestampV3` under the ETSI
+ * arc, as does Annex D. The ASN.1 is followed: the two attributes hash different preimages, and
+ * clause 5.5.3 step 3 has the archive timestamp cover six SignerInfo fields "including the tag,
+ * length and value octets" where this one excludes the tag and length of one of them, so a dispatcher
+ * following that sentence would hash the wrong octets for every B-T signature. */
+async function _verifySignatureTimestamps(si, targetSig, opts) {
+  var rows = [];
+  var attrs = [];
+  intrinsic.forEach(si.unsignedAttrs || [], function (a) { if (a.type === OID_TIMESTAMP_TOKEN) guard.list.append(attrs, a); });
+  if (!attrs.length) return rows;
+  /** @internal The signer's own claimed signing time and certificate window, read once here and
+   *  passed to every row, so each row answers the coherence questions against the same values. */
+  var claimed = _signingTimeOf(si);
+  for (var i = 0; i < attrs.length; i++) {
+    guard.list.append(rows, await _verifyOneTimestamp(attrs[i], targetSig, claimed, opts));
+  }
+  return rows;
+}
+
+/** @internal The signer's `signing-time` attribute as a Date, or null where it carries none. It is the
+ *  signer's own assertion and is not evidence of the real time, but it sits inside the signature, so a
+ *  timestamp that precedes it is a contradiction within one signature. */
+function _signingTimeOf(si) {
+  var found = null;
+  intrinsic.forEach(si.signedAttrs || [], function (a) {
+    if (a.type !== OID_SIGNING_TIME || found !== null || !a.values || !a.values.length) return;
+    /** @internal Read without a guard around it: `pki.schema.cms.parse` holds a signing-time
+     *  attribute's value to a Time through this same reader before any of this runs, so a value
+     *  that reaches here reads. A parser that stopped checking would surface the failure rather
+     *  than have this quietly report no claimed time. */
+    found = asn1.read.time(asn1.decode(a.values[0]));
+  });
+  return found;
+}
+
+/** @internal The instant a Date names, or null where the value is absent or names no instant. Every
+ *  ordering rule below reads its operands through this, so "no value" and "a value that cannot be
+ *  ordered" reach the comparison as the same absence rather than as a comparison that is false both
+ *  ways. */
+function _instantOrNull(value) {
+  if (!guard.time.isDate(value)) return null;
+  var at = guard.time.instantOf(value);
+  return intrinsic.numberIsNaN(at) ? null : at;
+}
+
+async function _verifyOneTimestamp(attr, targetSig, claimedSigningTime, opts) {
+  if (!attr.values || attr.values.length !== 1) {
+    return guard.verdict.of({ valid: false, trusted: false, genTime: null,
+      code: "cms/timestamp-multi-valued",
+      message: "a signature-time-stamp attribute shall contain exactly one component of AttributeValue " +
+        "type (ETSI EN 319 122-1 clause 5.3), got " + ((attr.values && attr.values.length) || 0) });
+  }
+  var tokenDer = attr.values[0];
+  tokenDer = tokenDer && tokenDer.bytes ? tokenDer.bytes : tokenDer;
+  var res;
+  try {
+    /** @internal Reached inside the function rather than at the top of the file: `tsp-sign` requires
+     *  THIS module to verify a token's own CMS signature, so a top-level require here is a cycle and
+     *  one of the two would see a half-built export object. */
+    var tspVerify = require("./tsp-sign");   // allow:inline-require -- circular load: tsp-sign requires this module
+    res = await tspVerify.verify(tokenDer, targetSig, {
+      certs: opts.timestampCerts,
+      trustAnchors: opts.timestampTrustAnchors,
+      revocationChecker: opts.timestampRevocationChecker,
+      allowWeakDigests: opts.allowWeakDigests === true,
+    });
+  } catch (e) {
+    return guard.verdict.of({ valid: false, trusted: false, genTime: null,
+      code: (e && e.code) || "cms/bad-timestamp", message: e && e.message });
+  }
+  if (res.valid !== true) {
+    return guard.verdict.of({ valid: false, trusted: res.trusted === true, genTime: res.genTime || null,
+      code: res.code === "tsp/imprint-mismatch" ? "cms/timestamp-imprint-mismatch" : res.code,
+      message: res.reason || null });
+  }
+  /** @internal Two coherence rules the token alone cannot answer, each against a value read from the
+   *  signature this attribute hangs on. The first is the signer's claimed time; the second is
+   *  EN 319 122-1 clause 6.3 requirement m, "the tokens ... shall be created before the signing
+   *  certificate has been revoked or has expired", whose expiry half is decidable from the signer
+   *  certificate alone and whose revocation half needs status this verb does not fetch.
+   *
+   *  Each instant is taken once, through the captured read, and a genTime that is not a usable
+   *  instant is refused rather than compared: an ordering test against it answers false in both
+   *  directions, so a token carrying one would pass both rules by being uncomparable. */
+  var genAt = _instantOrNull(res.genTime);
+  if (res.genTime != null && genAt === null) {
+    return guard.verdict.of({ valid: false, trusted: res.trusted === true, genTime: null,
+      code: "cms/bad-timestamp-gentime",
+      message: "the token's genTime is not a usable instant, so the times this attribute is held " +
+        "to cannot be ordered against it" });
+  }
+  var claimedAt = _instantOrNull(claimedSigningTime);
+  if (claimedAt !== null && genAt !== null && genAt < claimedAt) {
+    return guard.verdict.of({ valid: false, trusted: res.trusted === true, genTime: res.genTime,
+      code: "cms/timestamp-before-signing-time",
+      message: "the token's genTime " + guard.time.isoOf(res.genTime) + " precedes the signing-time " +
+        "the signature itself asserts, " + guard.time.isoOf(claimedSigningTime) });
+  }
+  /** @internal The upper bound is the LATEST instant the token could have been created at, not the
+   *  instant it names. Two things widen it past a `Date`: RFC 3161 clause 2.4.2 lets genTime carry a
+   *  fraction finer than a Date holds, so a time one microsecond past a notAfter truncates to the
+   *  notAfter itself, and the accuracy the token states is a window around genTime rather than a
+   *  point, so a genTime half a second inside the window with two seconds of accuracy establishes
+   *  nothing about which side of it the token was made on. Requirement m asks that the token WAS
+   *  created before the certificate expired, so a bound that cannot establish it refuses. */
+  var notAfterAt = _instantOrNull(opts.signerNotAfter);
+  var genUpper = genAt === null ? null
+    : guard.time.latestInstantOf(res.genTime, res.tstInfo && res.tstInfo.genTimeFraction, res.accuracy || null);
+  if (notAfterAt !== null && genUpper !== null && genUpper > notAfterAt) {
+    return guard.verdict.of({ valid: false, trusted: res.trusted === true, genTime: res.genTime,
+      code: "cms/timestamp-after-signer-expiry",
+      /** @internal The message names the BOUND, not just the genTime: this verdict is reached
+       *  whenever the latest instant the token could have been created at is past the notAfter, and
+       *  with a wide accuracy or a sub-millisecond fraction that is true of tokens whose stated
+       *  genTime is inside the window. Reporting the genTime alone would give an operator a reason
+       *  they can check and find false. */
+      message: "the token's genTime " + guard.time.isoOf(res.genTime) + ", with the accuracy it " +
+        "states, puts the latest it could have been created at " +
+        guard.time.isoOf(new intrinsic.Date(genUpper)) + ", past the signing certificate's notAfter " +
+        guard.time.isoOf(opts.signerNotAfter) + ", so it does not establish that the token was " +
+        "created before that certificate expired (ETSI EN 319 122-1 clause 6.3 requirement m)" });
+  }
+  return guard.verdict.of({
+    valid: true, trusted: res.trusted === true, genTime: res.genTime,
+    accuracy: res.accuracy, serialNumber: res.serialNumber, policy: res.policy,
+    revocationChecked: res.revocationChecked, tsa: res.tsa, signer: res.signer,
+  });
+}
+
+/** @internal The signing certificate's `notAfter`, where the signer row matched one. The expiry half
+ *  of EN 319 122-1 clause 6.3 requirement m is decidable from this certificate alone; the revocation
+ *  half needs status this verb does not fetch and is not claimed. */
+function _signerNotAfter(verdict) {
+  if (!verdict || !verdict.cert) return null;
+  try { return x509.parse(verdict.cert).validity.notAfter; }
+  // allow:swallow-unverified a signer certificate that does not parse already failed its own verdict
+  catch (_e) { return null; }
+}
+
 async function _verifyCountersignatures(si, parsedCerts, allowWeakDigests) {
   var targetSig = _toBuf(si.signature, "the countersigned signature");
   var values = [];
@@ -455,7 +822,7 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts, allowWeakDiges
  * Verify a CMS SignedData signature (RFC 5652 sec. 5). `input` is a PEM string, a DER
  * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, trusted, eContentType, eContent, signers }`
  * (`eContent` the encapsulated content when present, else null) where each `signers[i]` is
- * `{ ok, sid, cert, trusted, signedAttributesPresent, signedAttributes, unsignedAttrs, digestAlgorithm, countersignatures }`
+ * `{ ok, sid, cert, trusted, signedAttributesPresent, signedAttributes, unsignedAttrs, digestAlgorithm, countersignatures, signatureTimeStamps, cadesBaseline }`
  * (`cert` the matched signer certificate DER) or carries a `code` on a structural failure; `valid` is true when
  * there is at least one signer and every signer verified.
  *
@@ -480,12 +847,43 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts, allowWeakDiges
  * `subjectKeyIdentifier` names a key, and several certificates can hold it with different
  * validity windows, key usage and policies; deciding from a sibling would let an expired or
  * wrong-purpose signer certificate be reported trusted because a different certificate chained.
- * Supply the certificate you want used. RSA (PKCS#1 v1.5 and RSASSA-PSS), ECDSA, EdDSA, and the post-quantum
+ * Supply the certificate you want used. Where several candidates match the identifier and the
+ * signature carries an ESS signing-certificate attribute, the candidate that attribute names is the
+ * one selected, since RFC 5035 clause 5.4 makes its first identifier "the certificate used to verify
+ * the signature"; a named candidate must still verify the signature like any other. RSA (PKCS#1 v1.5 and RSASSA-PSS), ECDSA, EdDSA, and the post-quantum
  * ML-DSA (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814) signatures
  * are recognized, the post-quantum families in pure mode with an empty context, as is composite
  * ML-DSA (draft-ietf-lamps-cms-composite-sigs), which pairs ML-DSA with a traditional
  * RSA / ECDSA / EdDSA and verifies only when both components pass (never an AND-to-OR downgrade).
  *
+ * `signatureTimeStamps` is one row per `id-aa-signatureTimeStampToken` unsigned attribute (RFC 5126
+ * clause 6.1.1, ETSI EN 319 122-1 clause 5.3), each `{ valid, trusted, genTime, accuracy,
+ * serialNumber, policy, revocationChecked, tsa, signer }` or `{ valid: false, code, message }`. A
+ * token that does not verify is a row verdict and does not take the signer's own `ok` down: the
+ * signature and the time it was made at are separate claims. Each row's imprint is checked against
+ * the signature octets this verb just verified, and a row is refused when its `genTime` precedes the
+ * signer's own `signing-time` attribute or falls after the signing certificate's `notAfter`
+ * (EN 319 122-1 clause 6.3 requirement m).
+ *
+ * What a `valid: true` row establishes is that the token was issued over the signature octets THIS
+ * SignerInfo carries. It does not say that signature is sound, which is `signers[i].ok`, and rows are
+ * reported beside a failed signature rather than withheld, so a caller acting on a timestamp reads
+ * both. The imprint names signature octets rather than a signer, which is what EN 319 122-1
+ * clause 5.3 specifies: two certificates holding one key produce one signature value over one
+ * content, and a token over it answers for either. `pki.cms.attachTimestamp` adds such an attribute to an
+ * existing message and `pki.cms.timestampImprint` produces the imprint a TSA signs.
+ *
+ * `cadesBaseline` is a third claim, `{ conformant, signingCertificateAttribute, findings,
+ * requirementsChecked }`: a signature can be sound and still not be a CAdES signature.
+ * `requirementsChecked` lists the EN 319 122-1 requirements decided here, each unmet one carrying a
+ * `{ code, message }` finding, so `conformant` is read against that list and not as a full
+ * clause 6.3 audit. The signing-certificate requirement is the attribute's CLAIM checked against the
+ * certificate this SignerInfo selected, the one reported as `signers[i].cert`, not the attribute's
+ * presence. Like the timestamp rows it is reported beside a failed signature rather than withheld,
+ * so `conformant: true` on a signer whose `ok` is false says the CAdES attributes are in order and
+ * nothing about the signature. `pki.cms.sign` reaches `conformant: true` with a
+ * `signingCertificateV2` attribute built by `pki.schema.smime.buildSigningCertificateV2`.
+ *
  * @opts  content  The detached content when the SignedData carries no encapsulated eContent, and
  *                 required for a detached signature. A `Buffer`, or an async iterable of byte chunks
  *                 to verify a large payload without holding it in memory. The streamed form is hashed
@@ -503,6 +901,13 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts, allowWeakDiges
  *                 question from `requiredEku`, since a root distributed with NSS trust bits can be
  *                 marked untrusted for one purpose and good for another. Those bits and
  *                 `distrustAfter` are consulted only when this names a purpose.
+ * @opts  timestampCerts  Extra TSA certificates for the signature-timestamp rows, in addition to the
+ *                 ones each token embeds.
+ * @opts  timestampTrustAnchors  The roots a time-stamping authority must chain to for a timestamp row
+ *                 to report `trusted`. Named apart from `trustAnchors` because a TSA is a different
+ *                 trust decision from the signer: an operator may anchor one and not the other.
+ * @opts  timestampRevocationChecker  A revocation checker for the TSA chain, as `pki.path.validate`
+ *                 takes one. Each row reports what it established in `revocationChecked`.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var key = await pki.key.export(pair.privateKey);
@@ -540,7 +945,12 @@ async function _resolveContentDigests(parsed, streamSource) {
   return byName;
 }
 
-var _VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), { certs: 1, content: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1, allowWeakDigests: 1 });
+var _VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), { certs: 1, content: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1, allowWeakDigests: 1,
+  /** @internal The timestamp inputs are named apart from the signer's own, because a time-stamping
+   *  authority is a different trust decision from the signer's: an operator may anchor the TSA while
+   *  leaving the signer unanchored, or the reverse, and one `trustAnchors` for both would make those
+   *  two answers one. */
+  timestampCerts: 1, timestampTrustAnchors: 1, timestampRevocationChecker: 1 });
 
 function verify(input, opts) {
   return guard.async.deferred(function () { return _verify(input, opts); });
@@ -555,6 +965,7 @@ async function _verify(input, opts) {
   if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "input is not a CMS SignedData");
   var trustCfg = _snapshotTrust(opts);
   var allowWeakDigests = opts.allowWeakDigests === true;
+  var tsTrustCfg = _snapshotTimestampTrust(opts, allowWeakDigests);
   var parsedCerts = [];
   (parsed.certificates || []).forEach(function (c) { _addCert(parsedCerts, c && c.bytes ? c.bytes : c); });
   (opts.certs || []).forEach(function (c) { _addCert(parsedCerts, c); });
@@ -582,11 +993,18 @@ async function _verify(input, opts) {
     var siOne = parsed.signerInfos[_sp];
     var verdict = await _verifyOne(siOne, content, eContentType, parsedCerts, null, digestByName, allowWeakDigests);
     var counters = await _verifyCountersignatures(siOne, parsedCerts, allowWeakDigests);
+    /** @internal The timestamp rows are built from the same `signature` octets the signature verdict
+     *  above was computed over, which is why they are here and not in a verb of their own. The
+     *  signer's own certificate supplies the expiry half of EN 319 122-1 clause 6.3 requirement m. */
+    var stamps = await _verifySignatureTimestamps(siOne, _toBuf(siOne.signature, "the timestamped signature"),
+      intrinsic.assign(intrinsic.create(null), tsTrustCfg, { signerNotAfter: _signerNotAfter(verdict) }));
     guard.list.append(signers, guard.verdict.of(verdict, {
       countersignatures: counters,
+      signatureTimeStamps: stamps,
       unsignedAttrs: _surfaceUnsignedAttrs(siOne),
       signedAttributesPresent: !!siOne.signedAttrsBytes,
       signedAttributes: _surfaceSignedAttrs(siOne),
+      cadesBaseline: _cadesBaseline(siOne, verdict && verdict.cert ? verdict.cert : null),
       digestAlgorithm: siOne.digestAlgorithm.name,
       trusted: false,
     }));
@@ -640,6 +1058,30 @@ function _snapshotTrust(opts) {
   };
 }
 
+/** @internal The time-stamping authority's trust inputs, taken at the call like the signer's own and
+ *  for the same reason: they are first read inside the per-signer loop, after the signature and
+ *  countersignature checks have awaited, so an options object that changes between rows, or one
+ *  whose properties are accessors, would have two rows of one verdict judged against two different
+ *  authorities. The certificates are copied by value, since a caller holding the array could swap an
+ *  entry after the row that read it. The checker is a function and is captured as the one reference
+ *  every row calls. */
+function _snapshotTimestampTrust(opts, allowWeakDigests) {
+  var certs = opts.timestampCerts;
+  var anchors = opts.timestampTrustAnchors;
+  return {
+    timestampCerts: certs == null ? certs
+      : guard.list.copyMap(intrinsic.isArray(certs) ? certs : [certs], function (c) {
+        return _snapshotIfBytes(c, "opts.timestampCerts[]");
+      }),
+    timestampTrustAnchors: anchors == null ? anchors
+      : guard.list.copyMap(intrinsic.isArray(anchors) ? anchors : [anchors], function (a) {
+        return typeof a === "string" ? a : _cloneAnchorValue(a, 0);
+      }),
+    timestampRevocationChecker: opts.timestampRevocationChecker,
+    allowWeakDigests: allowWeakDigests,
+  };
+}
+
 /** @internal A signature over content is authorized by digitalSignature, contentCommitment or
  *  nonRepudiation alike; the shared helper carries the rest of the rule. */
 var _permitsSigning = pkix.keyUsagePermits(pkix.makeNS("cms", CmsError, oid),
@@ -817,6 +1259,12 @@ var sign = cmsSign.sign;
  */
 var countersign = cmsSign.countersign;
 
+/** @internal The two CAdES signature-timestamp verbs, re-exported here with `sign` and `countersign`
+ *  because this module is the `pki.cms` namespace's assembly point. Their documentation blocks live
+ *  with their implementations in `cms-sign.js`. */
+var timestampImprint = cmsSign.timestampImprint;
+var attachTimestamp = cmsSign.attachTimestamp;
+
 /**
  * @primitive pki.cms.encrypt
  * @signature pki.cms.encrypt(content, recipients, opts?) -> Promise<Buffer | string>
@@ -1126,4 +1574,4 @@ function isCertsOnly(input) {
 }
 
 // @internal
-module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, authenticate: authenticate, decrypt: decrypt, compress: compress, decompress: decompress, digest: cmsDigest.digest, verifyDigest: cmsDigest.verifyDigest, certsOnly: certsOnly, parseCertsOnly: parseCertsOnly, isCertsOnly: isCertsOnly, setEngine: setEngine };
+module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, authenticate: authenticate, decrypt: decrypt, compress: compress, decompress: decompress, digest: cmsDigest.digest, verifyDigest: cmsDigest.verifyDigest, certsOnly: certsOnly, parseCertsOnly: parseCertsOnly, isCertsOnly: isCertsOnly, setEngine: setEngine, timestampImprint: timestampImprint, attachTimestamp: attachTimestamp };

package/lib/constants.js

@@ -293,6 +293,21 @@ var NAMES = Object.assign(Object.create(null), {
    * this length: an OCSP CertID's issuer hashes, a timestamp's messageImprint. The XOFs (SHAKE) have
    * no single length and are absent. */
   DIGEST_OCTETS: { sha1: 20, sha256: 32, sha384: 48, sha512: 64, "sha3-256": 32, "sha3-512": 64 },
+  /** @internal The digests a verify path refuses by default and admits only under an explicit
+   *  opt-in, by the OID registry's name, with the WebCrypto hash name each maps to. A digest is weak
+   *  once a collision is reachable, which breaks the binding of every structure that carries "the
+   *  hash of X": a signature's message digest, a timestamp's messageImprint, an ESS certificate
+   *  identifier. Membership is defined once here, so a path that refuses one refuses all of them and
+   *  a path that admits them under an opt-in admits the same set. A digest no path will compute at
+   *  all is not listed; it is absent from DIGEST_HASH instead. */
+  WEAK_DIGESTS: { sha1: "SHA-1" },
+  /** @internal The digests an RFC 3161 message imprint may name in this build, by the OID registry's
+   *  name, with the node name each computes under. One table for the whole timestamp round trip: a
+   *  verb that TAKES an imprint, a verb that attaches a token over one, and the verifier that reads
+   *  it all answer from this, so none of them can produce an imprint another would refuse. SHA-1 is
+   *  listed because archived tokens carry it and the verifier admits it under an explicit opt-in;
+   *  WEAK_DIGESTS is what decides that, not absence from here. */
+  TIMESTAMP_IMPRINT_DIGESTS: { sha1: "sha1", sha256: "sha256", sha384: "sha384", sha512: "sha512" },
 });
 
 /** @internal Each inner table is looked up by a name a certificate supplies, so it answers from