@blamejs/pki 0.8.51 → 0.8.53

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;
@@ -35,13 +40,14 @@ function O(name) { return oid.byName(name); }
 
 var KNOWN_SIGN_OPTS = intrinsic.assign(intrinsic.create(null), {
   signedAttributes: 1, signingTime: 1, additionalSignedAttributes: 1, unsignedAttributes: 1,
+  algorithmProtection: 1,
   sid: 1, eContentType: 1, detached: 1, certificates: 1, pem: 1,
 });
 var KNOWN_SIGNER_CERT_KEYS = intrinsic.assign(intrinsic.create(null), { cert: 1, key: 1, pss: 1, digestAlgorithm: 1, combinedRsaSig: 1 });
 var KNOWN_SIGNER_KEY_ONLY_KEYS = intrinsic.assign(intrinsic.create(null), { spki: 1, keyIdentifier: 1, key: 1, pss: 1, digestAlgorithm: 1, combinedRsaSig: 1 });
 var KNOWN_COUNTERSIGN_OPTS = intrinsic.assign(intrinsic.create(null), {
   signerIndex: 1, countersignatureOf: 1, signingTime: 1, certificates: 1, pem: 1,
-  signedAttributes: 1, additionalSignedAttributes: 1, sid: 1,
+  signedAttributes: 1, additionalSignedAttributes: 1, sid: 1, algorithmProtection: 1,
 });
 var NS = pkix.makeNS("cms", CmsError, oid);
 var _b = pkiBuild.makeBuilder({
@@ -113,6 +119,12 @@ var UNSIGNED_FORBIDDEN = intrinsic.create(null);
 UNSIGNED_FORBIDDEN[O("contentType")] = "content-type";
 UNSIGNED_FORBIDDEN[O("messageDigest")] = "message-digest";
 UNSIGNED_FORBIDDEN[O("signingTime")] = "signing-time";
+/** @internal RFC 6211 sec. 2: the algorithm protection attribute "MUST NOT be an unsigned
+ *  attribute", and sec. 5 adds that one placed there "does not provide any additional security".
+ *  Both identifiers, since the two spell one attribute. The parser refuses the placement, so without
+ *  the door here this verb would emit a message its own verifier rejects. */
+UNSIGNED_FORBIDDEN[O("cmsAlgorithmProtection")] = "algorithm protection";
+UNSIGNED_FORBIDDEN[O("cmsAlgorithmProtect")] = "algorithm protection";
 
 function _buildUnsignedAttrs(list) {
   if (list == null) return null;
@@ -136,6 +148,49 @@ function _buildUnsignedAttrs(list) {
   return wire;
 }
 
+/** @internal The RFC 6211 attribute built from the very TLVs the structure's own fields are built
+ *  from. Sec. 2 says the attribute "contains a copy of the SignerInfo.digestAlgorithm field ...
+ *  including any parameters associated with it", so the copy is made from the value in hand rather
+ *  than re-derived from a registry row: a re-derivation can differ from the field it claims to copy,
+ *  and the parameters are the substitution target the attribute exists to pin.
+ *
+ *  `armTag` is 1 for a `SignerInfo` signature algorithm and 2 for an `AuthenticatedData` MAC
+ *  algorithm, which sec. 2 makes exclusive to their own placements. `attrOid` is the identifier the
+ *  caller's option resolved to, taken at the door so the pair carries the one that was asked for. */
+function _algorithmProtectionPair(attrOid, digestAlgId, armAlgId, armTag) {
+  return { type: attrOid, values: [b.sequence([digestAlgId, b.implicit(armTag, armAlgId)])] };
+}
+
+/** @internal An asked-for protection that cannot be placed is a refusal rather than a message that
+ *  silently lacks it. The attribute rides in the signed attributes, so with none there is nowhere to
+ *  put it, which is why RFC 8933 sec. 4.1 conditions its SHOULD on their presence. A caller who
+ *  names both options is asking for two things that cannot both hold.
+ *
+ *  The option is resolved FIRST, on every route, and the placement question asked second. Resolving
+ *  it inside the placement test would only read it on the route that cannot place it: a streamed
+ *  content is consumed and hashed before the attributes are built, so a misspelled value would be
+ *  refused after the stream had been read, which for a stream that cannot be replayed is a refusal
+ *  the caller cannot act on, and for one that never ends is no refusal at all.
+ *
+ *  The emitter below reads the same option again, which is sound because the options door refuses
+ *  one supplied through an accessor, own or inherited, before any value is read: two reads of a
+ *  plain field are one answer. */
+function _assertProtectionPlaceable(opts) {
+  var wanted = cms.algorithmProtectionOid(opts.algorithmProtection, _err);
+  if (opts.signedAttributes === false && wanted) {
+    throw _err("cms/bad-input", "algorithmProtection needs signed attributes to ride in, and " +
+      "signedAttributes: false signs the content directly (RFC 6211 sec. 2 places the attribute in " +
+      "SignerInfo.signedAttrs); drop one of the two");
+  }
+}
+
+/** @internal The producer door, applied to this verb's attribute records. The policy itself lives in
+ *  `schema-cms`, so the signing verbs and the authenticate verb enforce one rule rather than three
+ *  copies of it. */
+function _assertAlgorithmProtectionPairs(pairs, digestAlgId, armAlgId, armTag) {
+  cms.assertAlgorithmProtectionEmission(pairs, b.sequence([digestAlgId, b.implicit(armTag, armAlgId)]), _err);
+}
+
 function _resolveSignerContext(signer, opts) {
   var so = signer || {};
   var keyOnly = so.cert == null && so.spki != null;
@@ -161,7 +216,13 @@ async function _finishSignerInfo(rc, md, content, eContentType, opts) {
       { type: O("messageDigest"), values: [b.octetString(md)] },
     ];
     if (opts.signingTime !== false) intrinsic.push(pairs, { type: O("signingTime"), values: [_timeValue(opts.signingTime)] });
+    var apOid = cms.algorithmProtectionOid(opts.algorithmProtection, _err);
+    if (apOid) {
+      intrinsic.push(pairs, _algorithmProtectionPair(apOid,
+        rc.scheme.digestAlgId, rc.scheme.sigAlgId, 1));
+    }
     pairs = intrinsic.concat(pairs, _resolveAttrPairs(opts.additionalSignedAttributes, "a signed attribute value"));
+    _assertAlgorithmProtectionPairs(pairs, rc.scheme.digestAlgId, rc.scheme.sigAlgId, 1);
     toSign = _buildSignedAttrs(pairs);
   }
   var signedBytes = toSign.setOf ? toSign.setOf : toSign;
@@ -285,6 +346,7 @@ function _signDispatch(content, signers, opts) {
 async function _signStream(stream, signers, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.sign options");
   guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  _assertProtectionPlaceable(opts);
   if (opts.detached !== true) {
     throw _err("cms/bad-input", "a streaming (async-iterable) content requires opts.detached: true; an attached " +
       "SignedData embeds the content as a definite-length OCTET STRING, which cannot be produced without buffering it");
@@ -324,6 +386,7 @@ async function _signStream(stream, signers, opts) {
 function _sign(content, signers, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.sign options");
   guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  _assertProtectionPlaceable(opts);
   var contentBuf = _toBuf(content, "content");
   var list = Array.isArray(signers) ? _b.reqDenseArray(signers, "the signer list") : [signers];
   if (!list.length) throw _err("cms/bad-input", "pki.cms.sign requires at least one signer");
@@ -460,9 +523,15 @@ function _buildCountersignature(targetSigOctets, countersigner, opts) {
     return _digest(scheme.digest, targetSigOctets).then(function (md) {
       var pairs = [{ type: O("messageDigest"), values: [b.octetString(md)] }];
       if (opts.signingTime !== false) pairs.push({ type: O("signingTime"), values: [_timeValue(opts.signingTime)] });
+      var csApOid = cms.algorithmProtectionOid(opts.algorithmProtection, _err);
+      if (csApOid) {
+        intrinsic.push(pairs, _algorithmProtectionPair(csApOid, scheme.digestAlgId, scheme.sigAlgId, 1));
+      }
       var extra = _resolveAttrPairs(opts.additionalSignedAttributes, "a countersignature signed attribute value");
       extra.forEach(function (p) { if (p.type === O("contentType")) throw _err("cms/bad-input", "a countersignature must not carry a content-type attribute (RFC 5652 sec. 11.4)"); });
-      return _buildSignedAttrs(pairs.concat(extra));
+      var all = intrinsic.concat(pairs, extra);
+      _assertAlgorithmProtectionPairs(all, scheme.digestAlgId, scheme.sigAlgId, 1);
+      return _buildSignedAttrs(all);
     });
   }).then(function (attrs) {
     var preimage = attrs ? attrs.setOf : targetSigOctets;
@@ -554,6 +623,7 @@ function countersign(cmsInput, signers, opts) {
 function _countersign(cmsInput, signers, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.countersign options");
   guard.identifier.assertKnownKeys(opts, KNOWN_COUNTERSIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  _assertProtectionPlaceable(opts);
   var list = Array.isArray(signers) ? signers : [signers];
   if (!list.length) throw _err("cms/bad-input", "pki.cms.countersign requires at least one countersigner");
   if (opts.signingTime != null && opts.signingTime !== false) guard.time.assertEncodable(opts.signingTime, _err, "cms/bad-input", "signingTime");
@@ -628,8 +698,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,