@blamejs/pki 0.8.51 → 0.8.52

package/lib/guard-time.js

@@ -19,17 +19,112 @@ var _dateGetUTCMinutes = require("./guard-intrinsic").uncurry(Date.prototype.get
 var _dateGetUTCSeconds = require("./guard-intrinsic").uncurry(Date.prototype.getUTCSeconds);
 var _dateGetUTCMilliseconds = require("./guard-intrinsic").uncurry(Date.prototype.getUTCMilliseconds);
 var _dateSetUTCFullYear = require("./guard-intrinsic").uncurry(Date.prototype.setUTCFullYear);
+var _dateToISOString = require("./guard-intrinsic").uncurry(Date.prototype.toISOString);
+var _charCodeAt = require("./guard-intrinsic").uncurry(String.prototype.charCodeAt);
+var _Number = require("./guard-intrinsic").Number;
+var constants = require("./constants");
+/** @internal RFC 3161 clause 2.4.2 states an Accuracy's third field in microseconds, which no
+ *  `C.TIME` scale names because no PKI structure carries a microsecond duration anywhere else. */
+var MICROS_PER_MILLISECOND = 1000;
 var _dateUTC = Date.UTC;
 var _floor = Math.floor;
 var _ceil = Math.ceil;
 /** @internal A DER GeneralizedTime carries a four-digit year and a UTCTime a narrower one, so a Date
  *  outside 0000..9999 has no PKI encoding. */
 var DER_YEAR_MIN = 0, DER_YEAR_MAX = 9999;
+/** @internal The widest accuracy a date comparison can use, the DER year range in seconds, and the
+ *  instant a wider one saturates to: the last instant a DER time can carry, which is past every
+ *  certificate date and, unlike an arbitrary ceiling, is a `Date` a verdict can render. Declared
+ *  after the range it derives from, since a `var` read above its own initializer is `undefined`. */
+var MAX_ACCURACY_SECONDS = constants.TIME.days((DER_YEAR_MAX + 1) * 366) / constants.TIME.seconds(1);
+var MAX_INSTANT = _dateUTC(DER_YEAR_MAX, 11, 31, 23, 59, 59, 999);
 
 // @enforced-by guard-shape-reinlined
 // @guard-shape \.getTime\s*\(
 function instantOf(value) { return _dateGetTime(value); }
 
+/** The instant an error message or a verdict names, rendered through the operation captured at load.
+ *  A replaced `toISOString` chooses the time a refusal reports, which is what an operator reads when
+ *  deciding whether the refusal was right, so the rendering is taken from the same place every other
+ *  read of a Date is.
+ *
+ * @enforced-by behavioral -- the live-read budget each module declares is what holds a call-time
+ * `toISOString` out of a converted file; a `@guard-shape` here would name the read in every module
+ * that renders a date and the budget already answers for those.
+ */
+function isoOf(value) { return _dateToISOString(value); }
+
+/** The instant a DER GeneralizedTime names, rounded UP to the next whole millisecond where its
+ *  fractional seconds carry a digit a `Date` cannot hold. `fraction` is the fraction's digit string;
+ *  the first three digits ARE the milliseconds, so a nonzero digit after them puts the real instant
+ *  strictly between `value` and `value + 1ms`.
+ *
+ *  An upper bound is decided against this rather than against the Date, because the Date truncates:
+ *  a time stamped at `...000000.000001Z` reads as `...000000.000Z`, which compares equal to a bound
+ *  of `...000000Z` and so passes an "after the bound" test it is on the wrong side of. The two
+ *  consumers are the timestamp verifier's own check of the authority's certificate window and the
+ *  signature-timestamp row's check of the signing certificate's expiry.
+ *
+ * @enforced-by behavioral -- a truncating comparison has no rename-proof shape; the RED vector is a
+ * token minted with a sub-millisecond fraction one tick past a certificate's notAfter.
+ */
+function ceilInstantOf(value, fraction) { return latestInstantOf(value, fraction, null); }
+
+/** @internal The part of a DER GeneralizedTime's fractional seconds a `Date` cannot hold, in whole
+ *  microseconds. The first three digits ARE the milliseconds; the next three are microseconds, and
+ *  anything finer than a microsecond counts as one, since a bound is only a bound if it is not
+ *  exceeded. Read digit by digit through the captured accessor: a fraction is caller bytes. */
+function _fractionMicros(fraction) {
+  if (typeof fraction !== "string" || fraction.length <= 3) return 0;
+  var micros = 0;
+  var finer = false;
+  for (var i = 3; i < fraction.length; i++) {
+    var c = _charCodeAt(fraction, i);
+    if (c < 48 || c > 57) break;
+    var digit = c - 48;
+    if (i === 3) micros += digit * 100;
+    else if (i === 4) micros += digit * 10;
+    else if (i === 5) micros += digit;
+    else if (digit > 0) finer = true;
+  }
+  return finer ? micros + 1 : micros;
+}
+
+/** The LATEST instant a timestamp could have been created at: its `genTime` ceiling plus the
+ *  accuracy the token states. RFC 3161 clause 2.4.2 defines accuracy as the bound on the difference
+ *  between the stated time and the real one, so a token saying it is accurate to two seconds places
+ *  its creation anywhere in a four-second window, and an upper bound that reads only `genTime`
+ *  concludes something the token does not establish. `accuracy` is the parsed `{ seconds, millis,
+ *  micros }` or null; `seconds` arrives as a BigInt, the other two as numbers, and a micros
+ *  remainder rounds up because a bound is only a bound if it is not exceeded.
+ *
+ * @enforced-by behavioral -- a bound that ignores a field has no rename-proof shape; the RED vector
+ * is a token whose genTime precedes a certificate's notAfter while its accuracy window does not.
+ */
+function latestInstantOf(value, fraction, accuracy) {
+  var at = instantOf(value);
+  var ms = 0;
+  /** @internal The sub-millisecond parts are summed and rounded ONCE. Rounding the genTime fraction
+   *  and the accuracy up separately overstates the bound by a millisecond when both carry one, which
+   *  refuses a token whose real window ends before the instant it is compared against. */
+  var micros = _fractionMicros(fraction);
+  if (accuracy !== null && typeof accuracy === "object") {
+    /** @internal An Accuracy's seconds field is an arbitrary-size INTEGER, so it is bounded BEFORE
+     *  it is scaled: a token claiming more than the DER time range can hold is saturated to the
+     *  widest instant rather than scaled into a value the scale helper refuses. The refusal would
+     *  escape the row this builds and take the whole verify call down, where what the token has
+     *  established is nothing about which side of any certificate date it falls on, which is the
+     *  answer a saturated bound gives. */
+    if (accuracy.seconds > MAX_ACCURACY_SECONDS) return MAX_INSTANT;
+    if (typeof accuracy.seconds === "bigint") ms += constants.TIME.seconds(_Number(accuracy.seconds));
+    else if (typeof accuracy.seconds === "number") ms += constants.TIME.seconds(accuracy.seconds);
+    if (typeof accuracy.millis === "number") ms += constants.TIME.milliseconds(accuracy.millis);
+    if (typeof accuracy.micros === "number") micros += accuracy.micros;
+  }
+  if (micros > 0) ms += _ceil(micros / MICROS_PER_MILLISECOND);
+  return ms > 0 ? at + ms : at;
+}
+
 // @enforced-by nan-date-comparison-unguarded
 function assertValid(value, E, code, label) {
   if (!util.types.isDate(value) || _isNaN(instantOf(value))) {
@@ -120,6 +215,9 @@ module.exports = _freeze({
   assertEncodable: assertEncodable,
   addMonths: addMonths,
   instantOf: instantOf,
+  isoOf: isoOf,
+  ceilInstantOf: ceilInstantOf,
+  latestInstantOf: latestInstantOf,
   isDate: isDate,
   toDate: toDate,
   within: within,

package/lib/schema-all.js

@@ -379,7 +379,7 @@ module.exports = {
     pemDecode: trustanchor.pemDecode, pemEncode: trustanchor.pemEncode },
   attrcert: { parse: attrcert.parse, pemDecode: attrcert.pemDecode, pemEncode: attrcert.pemEncode,
     decodeExtensions: attrcert.decodeExtensions, decodeExtension: attrcert.decodeExtension },
-  smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
+  smime: { buildSigningCertificateV2: smime.buildSigningCertificateV2, parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
   cmc: { parse: cmc.parse, parsePkiData: cmc.parsePkiData, parsePkiResponse: cmc.parsePkiResponse },
   pem: {
     decodeBundle: function (text, opts) { return pkix.pemDecodeBundle(text, opts, PemError, _detectOrNull); },

package/lib/schema-smime.js

@@ -22,6 +22,9 @@
  *   (raw), the hash algorithm (decoded for v2, or the implied SHA-1 for v1), and
  *   the optional `issuerSerial` (issuer `GeneralNames` validated + surfaced raw,
  *   serial as a BigInt + hex)) plus the optional certificate policies.
+ *   `buildSigningCertificateV2` encodes the v2 attribute value a signer attaches:
+ *   one `ESSCertIDv2` per certificate, the SHA-256 form with the DEFAULT algorithm
+ *   omitted and SHA-384 / SHA-512 with an absent parameters field.
  *   `parseSmimeCapabilities` decodes the ordered `SMIMECapabilities` list (each a
  *   capability OID + raw parameters). `decodeAttribute` takes a CMS-shaped
  *   `{ type, values }` attribute, enforces the single-`AttributeValue` rule
@@ -46,9 +49,14 @@ var schema = require("./schema-engine");
 var pkix = require("./schema-pkix");
 var oid = require("./oid");
 var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
+var intrinsic = require("./guard-intrinsic");
+var constants = require("./constants");
+var x509 = require("./schema-x509");
 
 var SmimeError = frameworkError.SmimeError;
 var PemError = frameworkError.PemError;
+var b = asn1.build;
 
 var NS = pkix.makeNS("smime", SmimeError, oid);
 var TAGS = asn1.TAGS;
@@ -61,6 +69,12 @@ var OID_SIGNING_CERTIFICATE = oid.byName("signingCertificate");
 var OID_SIGNING_CERTIFICATE_V2 = oid.byName("signingCertificateV2");
 var OID_SMIME_CAPABILITIES = oid.byName("smimeCapabilities");
 
+/** @internal The digests this module will BIND a certificate with. RFC 5035 sec. 4 leaves
+ *  `hashAlgorithm` open, and the two readers that consume the field disagree on the set they admit,
+ *  so the builder emits only what the strictest consumer accepts: SHA-1 is excluded because a
+ *  binding is an identity claim, and an identifier a verifier refuses is a token nobody can use. */
+var BIND_DIGESTS = intrinsic.assign(intrinsic.create(null), { sha256: 1, sha384: 1, sha512: 1 });
+
 var GENERAL_NAME_DIRECTORY = 4;
 var ISSUER_SERIAL = schema.seq([
   schema.field("issuer", pkix.generalNames(NS, { code: "smime/bad-general-names" })),
@@ -71,7 +85,7 @@ var ISSUER_SERIAL = schema.seq([
     return {
       issuer: m.fields.issuer.value.result,
       serialNumber: m.fields.serialNumber.value,
-      serialNumberHex: m.fields.serialNumber.node.content.toString("hex"),
+      serialNumberHex: intrinsic.bufToString(m.fields.serialNumber.node.content, "hex"),
     };
   },
 });
@@ -105,7 +119,7 @@ var POLICY_INFORMATION = schema.seq([
 });
 var POLICIES = schema.seqOf(POLICY_INFORMATION, {
   assert: "sequence", min: 0, code: "smime/bad-policies", what: "policies",
-  build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
+  build: function (m) { return intrinsic.map(m.items, function (it) { return it.value.result; }); },
 });
 
 var ESS_CERT_ID = schema.seq([
@@ -155,7 +169,7 @@ function signingCertificateSchema(essCertId, code, what) {
   ], {
     assert: "sequence", code: code, what: what,
     build: function (m, ctx) {
-      var certs = m.fields.certs.value.items.map(function (it) { return it.value.result; });
+      var certs = intrinsic.map(m.fields.certs.value.items, function (it) { return it.value.result; });
       assertSignerIssuerIsDirectoryName(certs, function (msg) { throw ctx.E("smime/bad-issuer-serial", msg); });
       return {
         certs: certs,
@@ -182,7 +196,7 @@ var SMIME_CAPABILITY = schema.seq([
 });
 var SMIME_CAPABILITIES = schema.seqOf(SMIME_CAPABILITY, {
   assert: "sequence", min: 0, code: "smime/bad-capabilities", what: "SMIMECapabilities",
-  build: function (m) { return { capabilities: m.items.map(function (it) { return it.value.result; }) }; },
+  build: function (m) { return { capabilities: intrinsic.map(m.items, function (it) { return it.value.result; }) }; },
 });
 
 /**
@@ -266,6 +280,197 @@ var parseSigningCertificateV2 = pkix.makeParser({ pemLabel: null, PemError: PemE
  */
 var parseSmimeCapabilities = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: SmimeError, prefix: "smime", what: "SMIMECapabilities", topSchema: SMIME_CAPABILITIES, ns: NS });
 
+function _err(code, message) { return new SmimeError(code, message); }
+
+/** @internal The digests a signing-certificate identifier may BIND a certificate with, on the
+ *  reading side. It is the set the builder emits, and it is narrower than the set the ESS decoder
+ *  will decode: an identifier is an identity claim, so admitting a digest nobody should bind with
+ *  would let the claim be satisfied by a certificate other than the one that signed. SHA-1 is not
+ *  here and is reported as weak by its own flag, because the v1 attribute has no algorithm field
+ *  and is SHA-1 by definition (RFC 2634), so a reader must be able to tell "weak" from "unknown". */
+var BIND_VERIFY_DIGESTS = intrinsic.assign(intrinsic.create(null), { sha256: 1, sha384: 1, sha512: 1 });
+var GENERAL_NAME = pkix.generalName(NS, { decodeValue: true, code: "smime/bad-general-names" });
+
+/** @internal What ONE signing-certificate attribute claims about `certDer`, as facts rather than a
+ *  verdict. Each claim is read and compared here so there is one implementation of "does this
+ *  identifier name that certificate", and the two consumers apply their own policy to the result:
+ *  `pki.tsp.verify` refuses a token, and `pki.cms.verify` reports a CAdES conformance finding.
+ *
+ *  An ESSCertID states the signer in two independent ways, and both are compared: the hash under
+ *  the identifier's own digest, and the issuer and serial where it carries them (RFC 5035 clause 5,
+ *  RFC 2634 clause 5.4). A hash that agrees beside an issuer and serial naming another certificate
+ *  is a contradiction, not a match. Identifiers after the first are not read: RFC 2634 clause 5.4
+ *  makes the first the signing certificate and leaves the rest as the chain. */
+function _bindingClaim(attr) {
+  var out = { form: attr.type === OID_SIGNING_CERTIFICATE_V2 ? "v2" : "v1", readable: false,
+    digestName: null, supported: false, weak: false, certHash: null, issuerSerial: null };
+  var decoded;
+  try { decoded = decodeAttribute(attr); }
+  catch (_e) { return out; }
+  var ess = decoded.certs && decoded.certs[0];
+  if (!ess) return out;
+  /** @internal The digest identifier is held to its own encoding before its NAME is read. A SHA-2
+   *  identifier carries absent or NULL parameters and nothing else (RFC 5754 clause 2, "MUST accept
+   *  SHA2 AlgorithmIdentifiers with absent parameters ... with NULL parameters"), and the same two
+   *  forms are what RFC 3370 clause 2.1 states for SHA-1. The ANY parameters field is carried
+   *  through the parse unvalidated, so an identifier naming a digest this build computes while
+   *  carrying arbitrary bytes beside it would otherwise be hashed as a well-formed binding. */
+  if (!guard.der.paramsAbsentOrNull(ess.hashAlgorithm == null ? null : ess.hashAlgorithm.parameters)) return out;
+  out.readable = true;
+  out.digestName = ess.hashAlgorithm == null ? "sha1" : ess.hashAlgorithm.name;
+  out.weak = intrinsic.hasOwn(constants.NAMES.WEAK_DIGESTS, out.digestName);
+  out.supported = out.weak || intrinsic.hasOwn(BIND_VERIFY_DIGESTS, out.digestName);
+  out.certHash = ess.certHash;
+  out.issuerSerial = ess.issuerSerial || null;
+  return out;
+}
+
+/** @internal One claim compared against one certificate. The claim is read ONCE, by
+ *  `certBindingClaims`, and this is what runs per certificate: a signer identifier can match many
+ *  candidates, and re-reading the attribute for each would multiply the attribute's size by the
+ *  candidate count before any signature is checked. Only the first identifier is ever compared, so
+ *  only it is kept.
+ *
+ * @internal
+ */
+function certBindingAgainst(claim, certDer) {
+  var out = { form: claim.form, readable: claim.readable, digestName: claim.digestName,
+    supported: claim.supported, weak: claim.weak, matches: null, certUnreadable: false,
+    issuerSerialPresent: claim.issuerSerial !== null, issuerSerialMatches: null };
+  if (!claim.readable || !claim.supported) return out;
+  /** @internal Through the captured digest and the constant-time comparison: this IS the binding
+   *  between a signature and the certificate its attribute names, so neither what the digest covers
+   *  nor how the result is compared is the caller's to choose. */
+  out.matches = guard.crypto.constantTimeEqual(guard.crypto.digest(claim.digestName, certDer), claim.certHash);
+  if (claim.issuerSerial === null) return out;
+  /** @internal A certificate that does not parse is its own fact, kept apart from an attribute that
+   *  does not decode: one says the identifier is malformed and the other says the thing it would be
+   *  compared against is, and a consumer orders the two itself. Folding them into one flag moved a
+   *  refusal from "this identifier names another certificate" to "this attribute is unreadable". */
+  var cert;
+  try { cert = x509.parse(certDer); }
+  catch (_e2) { out.certUnreadable = true; return out; }
+  if (claim.issuerSerial.serialNumber !== cert.serialNumber) { out.issuerSerialMatches = false; return out; }
+  var names = claim.issuerSerial.issuer.names || [];
+  var gn = null;
+  try {
+    if (names.length === 1) {
+      gn = schema.embeddedDer(GENERAL_NAME, names[0].bytes, NS,
+        { code: "smime/bad-general-names", what: "GeneralName" });
+    }
+  } catch (_e3) { gn = null; }
+  out.issuerSerialMatches = !!gn && gn.tagNumber === GENERAL_NAME_DIRECTORY && !!gn.value &&
+    guard.name.dnEqual(gn.value.rdns, cert.issuer.rdns, _err, "smime/bad-issuer-serial",
+      "the ESSCertID issuer");
+  return out;
+}
+
+/** @internal Every signing-certificate attribute in `signedAttrs`, read against `certDer`.
+ *  `chosen` is the v2 attribute where there is one, which supersedes v1 (RFC 5035); `superseded`
+ *  holds the rest, which a consumer still holds to the same claim, because one structure making two
+ *  incompatible statements about one fact is a contradiction rather than something to resolve in
+ *  favor of whichever attribute a reader prefers. EVERY attribute is collected rather than the first
+ *  of each type: `signedAttrs` is a DER SET OF, so which of two comes first is a function of their
+ *  encodings and a hostile producer picks it.
+ *
+ * @internal
+ */
+function certBindingClaims(signedAttrs) {
+  var found = [];
+  intrinsic.forEach(signedAttrs || [], function (a) {
+    if (a && (a.type === OID_SIGNING_CERTIFICATE || a.type === OID_SIGNING_CERTIFICATE_V2)) {
+      guard.list.append(found, a);
+    }
+  });
+  if (!found.length) return { present: false, chosen: null, superseded: [] };
+  var chosenAt = 0;
+  for (var i = 0; i < found.length; i++) {
+    if (found[i].type === OID_SIGNING_CERTIFICATE_V2) { chosenAt = i; break; }
+  }
+  var superseded = [];
+  for (var j = 0; j < found.length; j++) {
+    if (j !== chosenAt) guard.list.append(superseded, _bindingClaim(found[j]));
+  }
+  return { present: true, chosen: _bindingClaim(found[chosenAt]), superseded: superseded };
+}
+
+/** @internal The claims read and compared in one call, for a consumer holding a single certificate.
+ *  A consumer with several reads the claims once and calls `certBindingAgainst` per certificate.
+ *
+ * @internal
+ */
+function certBindingFacts(signedAttrs, certDer) {
+  var claims = certBindingClaims(signedAttrs);
+  if (!claims.present) return { present: false, chosen: null, superseded: [] };
+  return {
+    present: true,
+    chosen: certBindingAgainst(claims.chosen, certDer),
+    superseded: intrinsic.map(claims.superseded, function (c) { return certBindingAgainst(c, certDer); }),
+  };
+}
+
+var _BUILD_V2_OPTS = intrinsic.assign(intrinsic.create(null), { hashAlgorithm: 1 });
+
+/**
+ * @primitive  pki.schema.smime.buildSigningCertificateV2
+ * @signature  pki.schema.smime.buildSigningCertificateV2(certs, opts?) -> Buffer
+ * @since      0.8.52
+ * @status     stable
+ * @spec       RFC 5035, RFC 5754
+ * @related    pki.schema.smime.parseSigningCertificateV2, pki.cms.sign, pki.tsp.sign
+ *
+ * Encode an ESS `SigningCertificateV2` attribute value (RFC 5035 sec. 5.4.1), the signed attribute
+ * that binds a signature to the certificate that made it. `certs` is the signer's certificate DER,
+ * or a list of certificate DERs whose first entry is the signer's (RFC 5035 sec. 5.4); each entry
+ * becomes an `ESSCertIDv2` carrying that certificate's hash. The result is the single
+ * `AttributeValue` of a `signingCertificateV2` signed attribute, which is what CAdES requires a
+ * signature to carry (ETSI EN 319 122-1 clauses 5.2.2.2 and 5.2.2.3).
+ *
+ * `opts.hashAlgorithm` names the binding digest: `sha256` (the default), `sha384` or `sha512`. The
+ * SHA-256 form omits the `hashAlgorithm` field, which is the RFC 5035 sec. 4 DEFAULT and so must be
+ * absent (X.690 sec. 11.5); the other two emit an `AlgorithmIdentifier` with the parameters field
+ * absent, which RFC 5754 sec. 2 requires an implementation to generate. SHA-1 is refused
+ * `smime/unsupported-algorithm`: a binding is an identity claim, and `pki.tsp.verify` refuses a
+ * SHA-1 one as a weak binding.
+ *
+ * The OPTIONAL `issuerSerial` and `policies` fields are not emitted; CAdES has the issuer serial
+ * omitted (ETSI EN 319 122-1 clause 6.3 requirement g). A caller that needs either field builds the
+ * value with `pki.asn1.build`, and `parseSigningCertificateV2` reads both back.
+ *
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = 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: key });
+ *   var av = pki.schema.smime.buildSigningCertificateV2(signerCertDer);
+ *   var msg = await pki.cms.sign(Buffer.from("hello"), { cert: signerCertDer, key: key },
+ *     { additionalSignedAttributes: [{ type: "signingCertificateV2", values: [av] }] });
+ *   (await pki.cms.verify(msg, { certs: [signerCertDer] })).signers[0].cadesBaseline.conformant;   // true
+ */
+function buildSigningCertificateV2(certs, opts) {
+  guard.identifier.assertKnownKeys(opts, _BUILD_V2_OPTS, _err, "smime/bad-input",
+    "pki.schema.smime.buildSigningCertificateV2 has an unknown option ");
+  var settings = guard.identifier.pickSettings(opts, ["hashAlgorithm"]);
+  var hashName = settings.hashAlgorithm === undefined || settings.hashAlgorithm === null ? "sha256" : settings.hashAlgorithm;
+  if (typeof hashName !== "string" || !BIND_DIGESTS[guard.text.keyOf(hashName)]) {
+    throw _err("smime/unsupported-algorithm", "the ESSCertIDv2 binding digest must be sha256, sha384 or sha512, got " +
+      guard.text.showValue(hashName));
+  }
+  var list = guard.list.snapshot(intrinsic.isArray(certs) ? certs : [certs]);
+  if (!list.length) {
+    throw _err("smime/bad-input", "a SigningCertificateV2 needs at least one certificate, the signer's first (RFC 5035 sec. 5.4)");
+  }
+  var ids = [];
+  for (var i = 0; i < list.length; i++) {
+    var der = guard.bytes.view(list[i], SmimeError, "smime/bad-input", "the certificate at certs[" + i + "]");
+    var certHash = b.octetString(guard.crypto.digest(hashName, der));
+    guard.list.append(ids, hashName === "sha256"
+      ? b.sequence([certHash])
+      : b.sequence([b.sequence([b.oid(oid.byName(hashName))]), certHash]));
+  }
+  return b.sequence([b.sequence(ids)]);
+}
+
 /**
  * @primitive  pki.schema.smime.decodeAttribute
  * @signature  pki.schema.smime.decodeAttribute(attr) -> { kind, ... }
@@ -292,7 +497,7 @@ var parseSmimeCapabilities = pkix.makeParser({ pemLabel: null, PemError: PemErro
  *   got.kind;    // "signingCertificateV2"
  */
 function decodeAttribute(attr) {
-  if (!attr || typeof attr !== "object" || typeof attr.type !== "string" || !Array.isArray(attr.values)) {
+  if (!attr || typeof attr !== "object" || typeof attr.type !== "string" || !intrinsic.isArray(attr.values)) {
     throw new SmimeError("smime/bad-input", "decodeAttribute expects a CMS attribute { type, values }");
   }
   if (attr.type === OID_SIGNING_CERTIFICATE || attr.type === OID_SIGNING_CERTIFICATE_V2 || attr.type === OID_SMIME_CAPABILITIES) {
@@ -313,6 +518,11 @@ function decodeAttribute(attr) {
 }
 
 module.exports = {
+  buildSigningCertificateV2: buildSigningCertificateV2,
+  certBindingFacts: certBindingFacts,   // @internal
+  certBindingClaims: certBindingClaims,   // @internal
+  certBindingAgainst: certBindingAgainst,   // @internal
+
   parseSigningCertificate: parseSigningCertificate,
   parseSigningCertificateV2: parseSigningCertificateV2,
   parseSmimeCapabilities: parseSmimeCapabilities,