@blamejs/pki 0.8.50 → 0.8.52

package/lib/cms-sign.js

@@ -25,6 +25,11 @@ var _promiseResolve = intrinsic.uncurry(intrinsic.promiseResolve);
 var _promiseAll = intrinsic.uncurry(intrinsic.promiseAll);
 var pkiBuild = require("./pki-build");
 var cms = require("./schema-cms");
+var constants = require("./constants");
+/** @internal The RFC 3161 structural layer, for the one thing this module asks of a token: which
+ *  octets its message imprint claims to cover. `schema-tsp` reaches only the schema modules, so this
+ *  is not the signing module's own cycle back through `tsp-sign`. */
+var tsp = require("./schema-tsp");
 
 var subtle = webcrypto.webcrypto.subtle;
 var CmsError = frameworkError.CmsError;
@@ -628,8 +633,257 @@ function _countersign(cmsInput, signers, opts) {
   });
 }
 
+/** @internal One Attribute appended to a SignerInfo's `[1] unsignedAttrs`, with every attribute
+ *  already there kept byte for byte and the SET OF re-sorted. A NEW attribute member rather than a
+ *  value merged into an existing one of the same type: ETSI EN 319 122-1 clause 5.3 reads "The
+ *  signature-time-stamp attribute shall contain exactly one component of AttributeValue type", while
+ *  RFC 5126 clause 6.1.1 has "Several instances of this attribute may occur with an electronic
+ *  signature, from different TSAs", so n timestamps are n attribute instances each carrying a
+ *  one-element SET. That is the opposite of the countersignature above, where RFC 5652 clause 11.4
+ *  puts n signatures in one attribute's values, which is why the two do not share this helper.
+ *
+ *  `build.set` sorts with the same comparison the parser's `derSetOrder` check applies, so the
+ *  rebuilt SET OF cannot be in an order the reader refuses. The `0x31` to `0xA1` re-tag is sound
+ *  because both identifiers are a single octet, leaving the length encoding untouched. */
+function _appendUnsignedAttr(siNode, attrDer) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var hasUa = last.tagClass === "context" && last.tagNumber === 1;
+  var base = intrinsic.map((hasUa ? intrinsic.arraySlice(kids, 0, kids.length - 1) : kids), function (k) { return k.bytes; });
+  var existing = hasUa ? intrinsic.map(last.children, function (a) { return a.bytes; }) : [];
+  var setOf = b.set(intrinsic.concat(existing, [attrDer]));
+  var wire = intrinsic.bufferFrom(setOf); wire[0] = 0xA1;
+  intrinsic.push(base, wire);
+  return b.sequence(base);
+}
+
+/** @internal The SignerInfo node a verb is targeting, with the index checked against what the message
+ *  carries rather than against a caller's assertion. */
+function _timestampTarget(der, signerIndex, who) {
+  var parsed = cms.parse(der);
+  if (!intrinsic.isArray(parsed.signerInfos)) throw _err("cms/bad-input", who + " input is not a CMS SignedData");
+  var idx = signerIndex == null ? 0 : signerIndex;
+  if (typeof idx !== "number" || !intrinsic.isInteger(idx) || idx < 0 || idx >= parsed.signerInfos.length) {
+    throw _err("cms/bad-input", who + " signerIndex out of range: " + guard.text.showValue(signerIndex) +
+      " (the message carries " + parsed.signerInfos.length + " signer" + (parsed.signerInfos.length === 1 ? "" : "s") + ")");
+  }
+  var root = asn1.decode(der);
+  var sd = root.children[1].children[0];
+  var siSet = sd.children[sd.children.length - 1];
+  return { parsed: parsed, root: root, sd: sd, siSet: siSet, idx: idx, siNode: siSet.children[idx] };
+}
+
+var KNOWN_IMPRINT_OPTS = intrinsic.assign(intrinsic.create(null), { signerIndex: 1, digestAlgorithm: 1 });
+
+/**
+ * @primitive pki.cms.timestampImprint
+ * @signature  pki.cms.timestampImprint(input, opts?) -> Promise<{ imprint, signerIndex }>
+ * @since      0.8.52
+ * @status     stable
+ * @spec       ETSI EN 319 122-1 clause 5.3, RFC 5126 clause 6.1.1, RFC 3161 clause 2.4.1
+ * @related    pki.cms.attachTimestamp, pki.tsp.request, pki.tsp.verify, pki.cms.verify
+ *
+ * The message imprint a time-stamping authority is asked to sign over, for the CAdES
+ * signature-time-stamp attribute. EN 319 122-1 clause 5.3 fixes what it covers: "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". So this is a digest of the contents octets of
+ * `SignerInfo.signature`, with the tag and length excluded, which is the same octet rule RFC 5652
+ * clause 11.4 states for a countersignature.
+ *
+ * `input` is the SignedData as a DER `Buffer` or a PEM `CMS` string, the same input
+ * `pki.cms.countersign` takes and for the same reason: the imprint covers exact octets of the
+ * message as it stands, so this reads the wire bytes rather than a representation of them. The
+ * result is `{ imprint, signerIndex }`: `imprint` is `{ hashAlgorithm, hashedMessage }`, the
+ * argument `pki.tsp.request` and `pki.tsp.sign` take, so a third-party authority can be driven
+ * without this package signing anything, and `signerIndex` is the signer it was taken for, which is
+ * what `pki.cms.attachTimestamp` is given when the token comes back.
+ *
+ * @opts  signerIndex      which signer to take the imprint for (default 0).
+ * @opts  digestAlgorithm  the digest to take (default `"sha256"`). MD5 is refused: EN 319 122-1
+ *                         clause 6.2.1 reads "In addition, MD5 algorithm shall not be used as digest
+ *                         algorithm".
+ * @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 signedDer = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key });
+ *   var taken = await pki.cms.timestampImprint(signedDer);
+ *   var req = pki.tsp.request(taken.imprint, { certReq: true });
+ *   taken.imprint.hashAlgorithm;   // "sha256"
+ */
+function timestampImprint(input, opts) {
+  return guard.bytes.fixedCall(CmsError, "cms/bad-input", [
+    [input, "the CMS message"], [opts, "pki.cms.timestampImprint options"],
+  ], _timestampImprint);
+}
+
+function _timestampImprint(input, opts) {
+  opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.timestampImprint options");
+  guard.identifier.assertKnownKeys(opts, KNOWN_IMPRINT_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  var name = opts.digestAlgorithm == null ? "sha256" : opts.digestAlgorithm;
+  /** @internal MD5 is answered before the build's own digest table, which does not carry it either:
+   *  asked for by name, it gets the clause that forbids it rather than the generic "this build does
+   *  not have that digest", which is a different thing to tell an operator. */
+  if (name === "md5") throw _err("cms/bad-input", "MD5 shall not be used as a digest algorithm (ETSI EN 319 122-1 clause 6.2.1)");
+  /** @internal Admitted against the digests a timestamp VERIFIER reads an imprint under, not the
+   *  build's general digest table: a digest outside that set produces an imprint whose token every
+   *  verifier here refuses, so taking one would hand an operator a request for an unusable token. */
+  if (typeof name !== "string" || !intrinsic.hasOwn(constants.NAMES.TIMESTAMP_IMPRINT_DIGESTS, name)) {
+    throw _err("cms/bad-input", "digestAlgorithm must name a digest a signature timestamp is read " +
+      "under (sha256, sha384 or sha512), got " + guard.text.showValue(opts.digestAlgorithm));
+  }
+  /** @internal A weak digest is refused outright here, with no opt-in beside it. `attachTimestamp`
+   *  has one because a token that already exists may be archived under a digest that was current
+   *  when it was made; a token this imprint would be sent for does not exist yet, so the only thing
+   *  the option could buy is a request for a token this verb's own sibling then refuses. */
+  if (intrinsic.hasOwn(constants.NAMES.WEAK_DIGESTS, name)) {
+    throw _err("cms/bad-input", "the imprint digest " + name + " is one a signature timestamp is " +
+      "refused for, so a token taken over it could not be attached or verified");
+  }
+  var der = pkix.coerceToDer(input, { pemLabel: null, PemError: frameworkError.PemError, ErrorClass: CmsError, prefix: "cms" });
+  var t = _timestampTarget(der, opts.signerIndex, "pki.cms.timestampImprint");
+  /** @internal `imprint` is nested rather than spread across the result, so the object this returns
+   *  is the one `pki.tsp.request` and `pki.tsp.sign` take: their message-imprint door admits
+   *  `hashAlgorithm` and `hashedMessage` and refuses any other field, which a flat result carrying
+   *  the signer index would trip. The index is what `pki.cms.attachTimestamp` is then given, so it
+   *  is reported beside the imprint instead of inside it. */
+  return guard.verdict.of({
+    imprint: guard.verdict.of({
+      hashAlgorithm: name,
+      hashedMessage: guard.crypto.digest(name, _signatureOctets(t.siNode)),
+    }),
+    signerIndex: t.idx,
+  });
+}
+
+var KNOWN_ATTACH_OPTS = intrinsic.assign(intrinsic.create(null), { signerIndex: 1, pem: 1, allowWeakDigests: 1 });
+
+/**
+ * @primitive pki.cms.attachTimestamp
+ * @signature pki.cms.attachTimestamp(input, token, opts?) -> Promise<Buffer>
+ * @since      0.8.52
+ * @status     stable
+ * @spec       ETSI EN 319 122-1 clause 5.3, RFC 5126 clause 6.1.1, RFC 3161
+ * @related    pki.cms.timestampImprint, pki.cms.verify, pki.tsp.sign, pki.cms.countersign
+ *
+ * Attach an RFC 3161 `TimeStampToken` to a signature as the CAdES signature-time-stamp unsigned
+ * attribute `{ 1 2 840 113549 1 9 16 2 14 }`, taking a `SignedData` to the EN 319 122-1 B-T level.
+ * `input` is that SignedData as a DER `Buffer` or a PEM `CMS` string and `token` the token a
+ * time-stamping authority returned for the imprint `pki.cms.timestampImprint` produced, as DER or
+ * PEM. Both are read as wire bytes rather than as a parsed representation, because this verb
+ * rewrites the message's own octets.
+ *
+ * It SPLICES rather than re-signs. Re-signing produces a different signature value, so a token taken
+ * over the first one would no longer match it, which is measured and not reasoned: with ECDSA the
+ * second signature differs every time. What is preserved byte for byte is therefore everything the
+ * four signature inputs cover: the encapsulated content and its type, and per signer the `version`,
+ * `sid`, `digestAlgorithm`, `[0] signedAttrs`, `signatureAlgorithm` and `signature` TLVs, plus every
+ * embedded certificate, every revocation entry, and every attribute already in `unsignedAttrs`. What
+ * is re-encoded is the targeted signer's `[1] unsignedAttrs` SET OF and the five enclosing lengths,
+ * none of which appears in any signature input.
+ *
+ * Several instances may be attached, one per authority, which is what RFC 5126 clause 6.1.1 permits
+ * and EN 319 122-1 clause 5.3 shapes: each is its own attribute carrying exactly one value.
+ *
+ * `signerIndex` names a signer of the INPUT. `signerInfos` is a SET OF, whose members are emitted in
+ * DER order, so giving one member an attribute changes its encoding and can change its position:
+ * identify a signer of the OUTPUT by its signature value or its certificate, not by the index it
+ * held on the way in.
+ *
+ * The imprint is checked before anything is written, so this verb cannot produce a message its own
+ * verifier would reject: the token's imprint must be the hash of the targeted signer's signature
+ * value, and its digest must be one the verifier admits. Nothing else about the token is judged
+ * here; `pki.cms.verify` does that.
+ *
+ * @opts  signerIndex  which signer to attach to (default 0).
+ * @opts  pem          return a PEM `CMS` block rather than DER.
+ * @opts  allowWeakDigests  attach a token whose imprint is a weak digest, which both this verb and
+ *                   `pki.cms.verify` refuse by default. This is the archived-token path, and the
+ *                   same option is needed again at verification.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var spki = await pki.key.export(pair.publicKey);
+ *   var nb = new Date("2026-01-01T00:00:00Z"), na = new Date("2036-01-01T00:00:00Z");
+ *   var cert = await pki.x509.sign({ subject: "Signer", subjectPublicKey: spki, notBefore: nb, notAfter: na }, { key: key });
+ *   // RFC 3161 sec. 2.3: a TSA certificate's extendedKeyUsage MUST be critical and name timeStamping alone
+ *   var tsaCert = await pki.x509.sign({ subject: "Example TSA", subjectPublicKey: spki, notBefore: nb, notAfter: na,
+ *     extensions: { keyUsage: ["digitalSignature"], extendedKeyUsage: ["timeStamping"], extendedKeyUsageCritical: true } },
+ *     { key: key });
+ *   var signedDer = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key });
+ *   var taken = await pki.cms.timestampImprint(signedDer);
+ *   var token = await pki.tsp.sign(taken.imprint, { cert: tsaCert, key: key },
+ *     { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
+ *   var bT = await pki.cms.attachTimestamp(signedDer, token, { signerIndex: taken.signerIndex });
+ *   (await pki.cms.verify(bT, { certs: [cert] })).signers[0].signatureTimeStamps[0].valid;   // true
+ */
+function attachTimestamp(input, token, opts) {
+  return guard.async.deferred(function () {
+    return guard.bytes.fixedCall(CmsError, "cms/bad-input", [
+      [input, "the CMS message"], [token, "the time-stamp token"], [opts, "pki.cms.attachTimestamp options"],
+    ], _attachTimestamp);
+  });
+}
+
+function _attachTimestamp(input, token, opts) {
+  opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.attachTimestamp options");
+  guard.identifier.assertKnownKeys(opts, KNOWN_ATTACH_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  var der = pkix.coerceToDer(input, { pemLabel: null, PemError: frameworkError.PemError, ErrorClass: CmsError, prefix: "cms" });
+  var tokenDer = pkix.coerceToDer(token, { pemLabel: null, PemError: frameworkError.PemError, ErrorClass: CmsError, prefix: "cms" });
+  var t = _timestampTarget(der, opts.signerIndex, "pki.cms.attachTimestamp");
+
+  /** @internal The imprint is checked HERE, before a byte is written, against the signature this
+   *  attribute will hang on. A verb that wrote first would produce a message `pki.cms.verify` refuses
+   *  on the row it just created, and the caller would have no way to tell a mis-addressed token from
+   *  a corrupt one. The token's own structure, its authority's certificate and its chain are not
+   *  judged here: those are the verifier's, and judging them twice in two places is two answers. */
+  var tst = tsp.parseToken(tokenDer);
+  var want = tst.tstInfo.messageImprint;
+  var name = want.hashAlgorithm && want.hashAlgorithm.name;
+  if (!name || !intrinsic.hasOwn(constants.NAMES.TIMESTAMP_IMPRINT_DIGESTS, name)) {
+    throw _err("cms/bad-input", "the token's message imprint names a digest a signature timestamp " +
+      "is not read under: " + guard.text.showValue(name || (want.hashAlgorithm && want.hashAlgorithm.oid)));
+  }
+  /** @internal The identifier is held to its own encoding as well as to its name: a digest
+   *  AlgorithmIdentifier carries absent or DER NULL parameters (RFC 5754 clause 2), and the ANY
+   *  field is carried through the parse unvalidated, so one naming sha256 beside arbitrary bytes
+   *  would otherwise be hashed as a well-formed imprint. */
+  if (!guard.der.paramsAbsentOrNull(want.hashAlgorithm.parameters)) {
+    throw _err("cms/bad-input", "the token's message imprint algorithm identifier carries " +
+      "parameters other than DER NULL, which a digest identifier does not (RFC 5754 clause 2)");
+  }
+  /** @internal The same digest posture the verifier holds this attribute to, read from the one
+   *  membership list: a token whose imprint is a weak digest is refused here too, under the option
+   *  that admits it there, so the verb does not write an attribute whose row `pki.cms.verify` then
+   *  refuses by default. The imprint carries the whole binding between the token and the signature,
+   *  and a collision in it substitutes one signature under a genuine token. */
+  if (opts.allowWeakDigests !== true && intrinsic.hasOwn(constants.NAMES.WEAK_DIGESTS, name)) {
+    throw _err("cms/weak-timestamp-imprint", "the token's message imprint is a " + name + " digest, " +
+      "which a signature timestamp is refused for by default; pass allowWeakDigests: true to attach " +
+      "an archived token under it");
+  }
+  var have = guard.crypto.digest(name, _signatureOctets(t.siNode));
+  if (!guard.crypto.constantTimeEqual(have, want.hashedMessage)) {
+    throw _err("cms/timestamp-imprint-mismatch", "the token's message imprint is not the hash of this " +
+      "signer's signature value, so attaching it would produce a signature timestamp that does not " +
+      "verify (ETSI EN 319 122-1 clause 5.3)");
+  }
+
+  var attr = b.sequence([b.oid(O("timeStampToken")), b.set([tokenDer])]);
+  var newSiSet = b.set(intrinsic.map(t.siSet.children, function (siNode, i) {
+    return i === t.idx ? _appendUnsignedAttr(siNode, attr) : siNode.bytes;
+  }));
+  var sdKids = t.sd.children;
+  var newSdFields = intrinsic.map(intrinsic.arraySlice(sdKids, 0, sdKids.length - 1), function (k) { return k.bytes; });
+  intrinsic.push(newSdFields, newSiSet);
+  var out = b.sequence([t.root.children[0].bytes, b.explicit(0, b.sequence(newSdFields))]);
+  return opts.pem ? pkix.pemEncode(out, "CMS", frameworkError.PemError) : out;
+}
+
 module.exports = {
   sign: sign, countersign: countersign, certsOnly: certsOnly,
+  timestampImprint: timestampImprint, attachTimestamp: attachTimestamp,
   // @internal
   KNOWN_SIGNER_CERT_KEYS: KNOWN_SIGNER_CERT_KEYS,
   KNOWN_SIGNER_KEY_ONLY_KEYS: KNOWN_SIGNER_KEY_ONLY_KEYS,