@blamejs/pki 0.5.16 → 0.5.18

package/lib/cms-encrypt.js

@@ -351,10 +351,10 @@ function _pwriWrapIv(kek, cek, iv) {
   var wk = _pwriFormat(cek);
   try {
     var c1 = nodeCrypto.createCipheriv("aes-256-cbc", kek, iv); c1.setAutoPadding(false);
-    var pass1 = Buffer.concat([c1.update(wk), c1.final()]);
+    var pass1 = guard.secret.cipherFinish(c1, wk, CmsError, "cms/bad-input", "the PWRI first-pass ciphertext");
     var iv2 = pass1.subarray(pass1.length - 16);
     var c2 = nodeCrypto.createCipheriv("aes-256-cbc", kek, iv2); c2.setAutoPadding(false);
-    return Buffer.concat([c2.update(pass1), c2.final()]);
+    return guard.secret.cipherFinish(c2, pass1, CmsError, "cms/bad-input", "the PWRI wrapped key");
   } finally {
     guard.secret.zeroize(wk, CmsError, "cms/bad-input", "the PWRI plaintext block");
   }
@@ -364,22 +364,91 @@ var PRF_HASH = { hmacWithSHA1: "SHA-1", hmacWithSHA256: "SHA-256", hmacWithSHA38
 function _prfHash(prf) { if (!PRF_HASH[prf]) throw _err("cms/bad-input", "unsupported pwri prf " + JSON.stringify(prf)); return PRF_HASH[prf]; }
 
 // ---- recipient dispatch ----------------------------------------------------
-async function _buildRecipient(cek, desc, opts) {
+// The fields a recipient descriptor carries, PER ARM. Each arm reads a disjoint set, and every
+// field beyond the selector is optional with a default, so an unrecognized name is missed by
+// nothing and the recipient is built with the shipped parameters instead: `oaepHsh` for `oaepHash`
+// encrypts the content key under the default SHA-256 OAEP, and a misspelled `iterations`, `salt`
+// or `prf` on a password recipient derives the key at the default work factor. A union table would
+// admit another arm's fields, which the chosen arm never reads.
+var _PWRI_KEYS = { password: 1, iterations: 1, prf: 1, salt: 1 };
+var _KEKRI_KEYS = { kek: 1, kekId: 1 };
+// A certificate recipient dispatches on the certificate's KEY ALGORITHM, and the arms read
+// different fields: ktri (RSA) reads oaepHash and never ukm; kari (ECDH / X25519 / X448) and kemri
+// (ML-KEM) read ukm and never oaepHash. One table across all three accepted `oaepHash` on an EC
+// certificate, where nothing reads it, so the content key was wrapped under the arm's own defaults
+// while the caller had named a hash. Checked after the key algorithm resolves, since that is what
+// selects the arm.
+var _KTRI_RECIPIENT_KEYS = { cert: 1, oaepHash: 1, keyIdentifier: 1 };
+var _AGREE_RECIPIENT_KEYS = { cert: 1, keyIdentifier: 1, ukm: 1 };
+
+// The three top-level options that are per-recipient DEFAULTS rather than message-wide settings.
+// Which of them any given message actually consumes depends on the recipient arms it selects, so
+// they are checked against the arms after those resolve, not against a fixed list.
+var _RECIPIENT_DEFAULTS = ["oaepHash", "keyIdentifier", "ukm"];
+
+function _assertRecipientKeys(desc, known, arm) {
+  guard.identifier.assertKnownKeys(desc, known, _err, "cms/bad-input", function (k) {
+    return "unknown field " + JSON.stringify(k) + " on a " + arm +
+      " recipient; that field is not read for this recipient type";
+  });
+}
+
+// A default no selected recipient reads is discarded exactly as a misspelling would be: `oaepHash`
+// on a message whose only recipient is a password recipient names a wrapping the message does not
+// perform. Run after every recipient's arm has resolved and BEFORE anything is emitted.
+function _assertDefaultsConsumed(opts, consumed) {
+  for (var i = 0; i < _RECIPIENT_DEFAULTS.length; i++) {
+    var name = _RECIPIENT_DEFAULTS[i];
+    if (opts[name] != null && !consumed[name]) {
+      throw _err("cms/bad-input", "opts." + name + " is a per-recipient default and no recipient of this message reads it" +
+        (name === "oaepHash" ? " (only an RSA certificate recipient does)"
+          : name === "ukm" ? " (only a key-agreement or KEM certificate recipient does)"
+            : " (only a certificate recipient does)"));
+    }
+  }
+}
+
+async function _buildRecipient(cek, desc, opts, consumed) {
   if (desc == null || typeof desc !== "object") throw _err("cms/bad-input", "each recipient must be a descriptor object");
-  if (desc.password != null) return _buildPwri(cek, desc);
-  if (desc.kek != null) return _buildKekri(cek, desc);
+  // Checked per arm, on the same selector the dispatch below uses, so the table that runs is the
+  // one belonging to the arm that will build. `consumed` records which top-level defaults the
+  // selected arms read, so a default no recipient consumes can be refused once they all resolve.
+  if (desc.password != null) { _assertRecipientKeys(desc, _PWRI_KEYS, "password"); return _buildPwri(cek, desc); }
+  if (desc.kek != null) { _assertRecipientKeys(desc, _KEKRI_KEYS, "KEK"); return _buildKekri(cek, desc); }
   if (desc.cert != null) {
     var cert = x509.parse(_normCertDer(desc.cert, "a recipient certificate"));
     var keyOid = cert.subjectPublicKeyInfo.algorithm.oid;
-    if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) return _buildKtri(cek, cert, mergeOpts(opts, desc));
-    if (keyOid === O("ecPublicKey") || MONT_KA[keyOid]) return _buildKari(cek, cert, mergeOpts(opts, desc));
-    if (KEM_WC[keyOid]) return _buildKemri(cek, cert, mergeOpts(opts, desc));
+    if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) {
+      _assertRecipientKeys(desc, _KTRI_RECIPIENT_KEYS, "RSA certificate");
+      return _buildKtri(cek, cert, mergeOpts(opts, desc, _KTRI_RECIPIENT_KEYS, consumed));
+    }
+    if (keyOid === O("ecPublicKey") || MONT_KA[keyOid]) {
+      _assertRecipientKeys(desc, _AGREE_RECIPIENT_KEYS, "key-agreement certificate");
+      return _buildKari(cek, cert, mergeOpts(opts, desc, _AGREE_RECIPIENT_KEYS, consumed));
+    }
+    if (KEM_WC[keyOid]) {
+      _assertRecipientKeys(desc, _AGREE_RECIPIENT_KEYS, "KEM certificate");
+      return _buildKemri(cek, cert, mergeOpts(opts, desc, _AGREE_RECIPIENT_KEYS, consumed));
+    }
     throw _err("cms/unsupported-algorithm", "unsupported recipient certificate key algorithm " + keyOid);
   }
   throw _err("cms/bad-input", "a recipient needs { cert }, { password }, or { kek, kekId }");
 }
-function mergeOpts(opts, desc) {
-  return { oaepHash: desc.oaepHash || opts.oaepHash, keyIdentifier: desc.keyIdentifier || opts.keyIdentifier, ukm: desc.ukm != null ? desc.ukm : opts.ukm };
+// Each default is taken from the descriptor when it supplies one and from the top-level options
+// otherwise. That one choice is also the record of which top-level defaults the recipient CONSUMED:
+// an arm that does not read the name never consumes it, and neither does one whose descriptor
+// overrode it, so recording it from the arm's table alone would accept a value nothing read.
+function _pickDefault(desc, opts, name, known, consumed, nullish) {
+  var supplied = desc[name], fromDesc = nullish ? supplied != null : !!supplied;
+  if (!fromDesc && known[name] && consumed && opts[name] != null) consumed[name] = 1;
+  return fromDesc ? supplied : opts[name];
+}
+function mergeOpts(opts, desc, known, consumed) {
+  return {
+    oaepHash: _pickDefault(desc, opts, "oaepHash", known, consumed, false),
+    keyIdentifier: _pickDefault(desc, opts, "keyIdentifier", known, consumed, false),
+    ukm: _pickDefault(desc, opts, "ukm", known, consumed, true),
+  };
 }
 // RecipientInfo CHOICE: ktri untagged; kari [1], kekri [2], pwri [3], ori [4], all IMPLICIT,
 // so the arm's SEQUENCE tag is replaced by the context tag.
@@ -397,12 +466,46 @@ function _envelopedVersion(recips, hasUnprotected) {
   return forcesTwo ? 2 : 0;
 }
 
+// The two exported verbs have DISJOINT option sets, so they get separate tables: one shared table
+// would admit every other verb's keys, which is the hole rather than the door. Each is the union of
+// what the verb reads THROUGH ITS DELEGATIONS -- encrypt never names oaepHash, keyIdentifier or ukm
+// itself, but hands opts to the per-recipient builders that do, and to _emit for pem.
+// Authenticated attributes live in an AuthEnvelopedData, which only an AEAD content algorithm
+// produces: a CBC algorithm selects EnvelopedData, which has no field for them and is not handed
+// opts at all. Requested there, they named a protection the message does not carry.
+var _ENCRYPT_OPTS_AEAD = {
+  contentEncryptionAlgorithm: 1, contentType: 1, authAttrs: 1, oaepHash: 1, keyIdentifier: 1,
+  ukm: 1, pem: 1,
+};
+var _ENCRYPT_OPTS_CBC = {
+  contentEncryptionAlgorithm: 1, contentType: 1, oaepHash: 1, keyIdentifier: 1, ukm: 1, pem: 1,
+};
+// authenticatedAttributes: false MACs the content octets directly, and the attribute set is what
+// carries the digest: neither the digest algorithm nor any extra attribute is read on that branch.
+var _AUTHENTICATE_OPTS_ATTRS = {
+  macAlgorithm: 1, digestAlgorithm: 1, authenticatedAttributes: 1, authAttrs: 1, contentType: 1,
+  keyIdentifier: 1, oaepHash: 1, ukm: 1, pem: 1,
+};
+var _AUTHENTICATE_OPTS_BARE = {
+  macAlgorithm: 1, authenticatedAttributes: 1, contentType: 1,
+  keyIdentifier: 1, oaepHash: 1, ukm: 1, pem: 1,
+};
+
 async function encrypt(content, recipients, opts) {
   opts = opts || {};
-  var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
+  // The content algorithm selects the structure, so it is resolved before the door and the table
+  // that runs is the one belonging to the structure this call will emit.
   var algName = opts.contentEncryptionAlgorithm || "aes-256-gcm";
   var ca = CONTENT_ALGS[algName];
   if (!ca) throw _err("cms/bad-input", "unsupported contentEncryptionAlgorithm " + JSON.stringify(algName));
+  guard.identifier.assertKnownKeys(opts, ca.aead ? _ENCRYPT_OPTS_AEAD : _ENCRYPT_OPTS_CBC, _err, "cms/bad-input",
+    function (k) {
+      return "pki.cms.encrypt has an unknown option " + JSON.stringify(k) +
+        (!ca.aead && k === "authAttrs"
+          ? " for a CBC content algorithm; authenticated attributes are carried only by an AuthEnvelopedData, which an AEAD algorithm produces"
+          : "");
+    });
+  var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
   var contentType = opts.contentType || "data";
   var cek = nodeCrypto.randomBytes(ca.keyBits / 8);
 
@@ -415,7 +518,9 @@ async function encrypt(content, recipients, opts) {
 
     if (!recipients.length) throw _err("cms/bad-input", "at least one recipient is required (RFC 5652 sec. 6.1)");
     var recips = [];
-    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(cek, recipients[i], opts));
+    var consumed = {};
+    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(cek, recipients[i], opts, consumed));
+    _assertDefaultsConsumed(opts, consumed);
     var riNodes = recips.map(_taggedRecipient);
 
     if (ca.aead) return _emit(_authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, recips), "authEnvelopedData", opts);
@@ -432,11 +537,48 @@ function _emit(inner, ctName, opts) {
 
 function _envelopedData(contentBytes, cek, ca, contentType, riNodes, recips) {
   var iv = nodeCrypto.randomBytes(16);
-  var enc = pbes2.cbcEncrypt(cek, iv, contentBytes, ca.keyBits);
+  var enc = pbes2.cbcEncrypt(cek, iv, contentBytes, ca.keyBits, CmsError, "cms/bad-input");
   var eci = b.sequence([b.oid(O(contentType)), b.sequence([b.oid(O(ca.oid)), b.octetString(iv)]), b.contextPrimitive(0, enc)]);
   return b.sequence([b.integer(BigInt(_envelopedVersion(recips, false))), b.setOf(riNodes), eci]);
 }
 
+// Every authenticated attribute this module MACs -- auto-built or caller-supplied, in either content
+// type that carries them -- MUST be a well-formed Attribute SEQUENCE { type OBJECT IDENTIFIER,
+// non-empty SET OF value } with no repeated type (RFC 5652 sec. 5.3). Rejecting here means a
+// malformed attribute never reaches the wire; leaving it to the wire means the operator learns from
+// a peer's parser that the message they built is unreadable, with the MAC already computed over it.
+//
+// `forbidden` names an attribute type this particular content type must not emit, with the clause
+// that says so. It is a parameter rather than a constant because the same attribute is required in
+// one content type and discouraged in the other: AuthenticatedData MACs its own message-digest by
+// design (RFC 5652 sec. 9.2), while for AuthEnvelopedData that value is the unencrypted hash of a
+// plaintext the message exists to conceal (RFC 5083 sec. 2.1 / sec. 5).
+function _assertAuthAttrs(pairs, forbidden) {
+  var seenTypes = {};
+  pairs.forEach(function (p) {
+    var node;
+    try { node = asn1.decode(p); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute is not well-formed DER", e); }
+    if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children || node.children.length !== 2 ||
+      node.children[1].tagClass !== "universal" || node.children[1].tagNumber !== asn1.TAGS.SET ||
+      !node.children[1].children || node.children[1].children.length < 1) {
+      throw _err("cms/bad-input", "an authenticated attribute must be an Attribute SEQUENCE { type, non-empty SET OF value } (RFC 5652)");
+    }
+    var t;
+    try { t = asn1.read.oid(node.children[0]); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute type is not an OBJECT IDENTIFIER", e); }
+    if (guard.intrinsic.hasOwn(seenTypes, t)) throw _err("cms/bad-input", "authenticated attributes must not repeat an attribute type (RFC 5652): " + t);
+    seenTypes[t] = 1;
+    if (forbidden && t === forbidden.oid) throw _err("cms/bad-input", forbidden.why);
+  });
+}
+
+// The one attribute AuthEnvelopedData declines to emit. Its value is the unencrypted one-way hash of
+// the plaintext, so disclosing it enables content tracking and confirms a guessed plaintext against
+// a message that was encrypted to prevent exactly that.
+var AUTH_ENVELOPED_FORBIDDEN = {
+  oid: O("messageDigest"),
+  why: "authAttrs must not carry the message-digest attribute in an AuthEnvelopedData: its value is the unencrypted hash of the plaintext, which enables content tracking and confirmation of a guessed plaintext (RFC 5083 sec. 2.1, sec. 5)",
+};
+
 function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, recips) {
   var nonce = nodeCrypto.randomBytes(12);
   var authAttrsDer = null, aad = Buffer.alloc(0);
@@ -446,6 +588,7 @@ function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, r
     throw _err("cms/bad-input", "AuthEnvelopedData with a non-data contentType requires authAttrs (RFC 5083 sec. 2.1)");
   }
   if (opts.authAttrs && opts.authAttrs.length) {
+    _assertAuthAttrs(opts.authAttrs, AUTH_ENVELOPED_FORBIDDEN);
     // authAttrs are transmitted [1] IMPLICIT but MACed under the EXPLICIT SET OF tag (RFC 5083 sec. 2.2).
     var setOf = b.setOf(opts.authAttrs);
     aad = setOf; authAttrsDer = b.contextConstructed(1, setOf.subarray(_tlvHeaderLen(setOf)));
@@ -462,8 +605,31 @@ function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, r
   return b.sequence(kids);
 }
 
+// The single descriptor an EncryptedData takes, PER ARM. `cek` and `password` select the arm and
+// the arms read disjoint sets, so a union would admit the other arm's fields: `{ cek, iterations }`
+// supplies a work factor to a branch that derives nothing, and the caller's parameter is discarded
+// exactly as a misspelling would be. `pem` is read after both arms, so it belongs to each.
+// pem selects the output encoding of the whole call and is an OPTION, the third argument, on every
+// other verb here. A second spelling on the descriptor was read by the password arm alone, so the
+// cek arm accepted it and returned DER; there is now one place to ask for PEM.
+var _ENCRYPTED_DATA_CEK_KEYS = { cek: 1 };
+var _ENCRYPTED_DATA_PW_KEYS = { password: 1, iterations: 1, salt: 1, prf: 1 };
+
 function _encryptedData(contentBytes, desc, ca, contentType, opts, cek) {
   if (ca.aead) throw _err("cms/bad-input", "EncryptedData supports only CBC content encryption");
+  // An EncryptedData carries no RecipientInfos at all, so nothing here reads a per-recipient
+  // default. This branch returns before the recipient loop, so it answers for them itself.
+  _assertDefaultsConsumed(opts, {});
+  // Checked per arm, on the same selector the dispatch below uses, so the table that runs belongs
+  // to the branch that will encrypt.
+  if (desc != null && typeof desc === "object") {
+    var edKeys = desc.cek != null ? _ENCRYPTED_DATA_CEK_KEYS : _ENCRYPTED_DATA_PW_KEYS;
+    var edArm = desc.cek != null ? "cek" : "password";
+    guard.identifier.assertKnownKeys(desc, edKeys, _err, "cms/bad-input", function (k) {
+      return "unknown field " + JSON.stringify(k) + " on a " + edArm +
+        " EncryptedData descriptor; that field is not read for this arm";
+    });
+  }
   var iv = nodeCrypto.randomBytes(16);
   var contentAlgNode, encKey;
   if (desc && desc.cek != null) {
@@ -475,7 +641,7 @@ function _encryptedData(contentBytes, desc, ca, contentType, opts, cek) {
   } else {
     throw _err("cms/bad-input", "EncryptedData needs a single { cek } or { password } descriptor");
   }
-  var enc = pbes2.cbcEncrypt(encKey, iv, contentBytes, ca.keyBits);
+  var enc = pbes2.cbcEncrypt(encKey, iv, contentBytes, ca.keyBits, CmsError, "cms/bad-input");
   var eci = b.sequence([b.oid(O(contentType)), contentAlgNode, b.contextPrimitive(0, enc)]);
   var inner = b.sequence([b.integer(0n), eci]);
   return _emit(inner, "encryptedData", opts);
@@ -495,11 +661,11 @@ function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
   var key = nodeCrypto.pbkdf2Sync(password, salt, iterations, ca.keyBits / 8, pbes2.prfNodeByName(prf, _err, "cms"));
   if (pwOwn2.owned) guard.secret.zeroize(password, CmsError, "cms/bad-input", "the password encoding");
   try {
-    var enc = pbes2.cbcEncrypt(key, iv, contentBytes, ca.keyBits);
+    var enc = pbes2.cbcEncrypt(key, iv, contentBytes, ca.keyBits, CmsError, "cms/bad-input");
     var contentAlg = pbes2.pbes2AlgId(salt, iterations, prf, ca.oid, iv);
     var eci = b.sequence([b.oid(O(contentType)), contentAlg, b.contextPrimitive(0, enc)]);
     var inner = b.sequence([b.integer(0n), eci]);
-    return _emit(inner, "encryptedData", { pem: opts && opts.pem != null ? opts.pem : desc.pem });
+    return _emit(inner, "encryptedData", opts);
   } finally {
     guard.secret.zeroize(key, CmsError, "cms/bad-input", "the password-derived content-encryption key");
   }
@@ -509,7 +675,7 @@ function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
 function _gcmEncrypt(key, nonce, plaintext, aad, keyBits, tagLen) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-gcm", key, nonce, { authTagLength: tagLen });
   if (aad && aad.length) c.setAAD(aad);
-  var ct = Buffer.concat([c.update(plaintext), c.final()]);
+  var ct = guard.secret.cipherFinish(c, plaintext, CmsError, "cms/bad-input", "a content-encryption intermediate");
   return { ct: ct, tag: c.getAuthTag() };
 }
 
@@ -543,13 +709,22 @@ var SUPPORTED_DIGEST = { sha256: 1, sha384: 1, sha512: 1 };
 
 async function authenticate(content, recipients, opts) {
   opts = opts || {};
+  // The attribute branch is selected once, and the door and the MAC below both act on that one
+  // decision, so the table that runs belongs to the branch that will compute the MAC.
+  var withAttrs = opts.authenticatedAttributes !== false;
+  guard.identifier.assertKnownKeys(opts, withAttrs ? _AUTHENTICATE_OPTS_ATTRS : _AUTHENTICATE_OPTS_BARE,
+    _err, "cms/bad-input", function (k) {
+      return "pki.cms.authenticate has an unknown option " + JSON.stringify(k) +
+        (!withAttrs && (k === "digestAlgorithm" || k === "authAttrs")
+          ? " with authenticatedAttributes: false; the MAC then covers the content octets directly and no attribute set is built"
+          : "");
+    });
   var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
   var macName = opts.macAlgorithm || "hmac-sha256";
   var mac = MAC_ALGS[macName];
   if (!mac) throw _err("cms/bad-input", "unsupported macAlgorithm " + JSON.stringify(macName) + " (hmac-sha256/384/512)");
   if (!Array.isArray(recipients) || !recipients.length) throw _err("cms/bad-input", "at least one recipient is required (RFC 5652 sec. 9.1)");
   var contentType = opts.contentType || "data";
-  var withAttrs = opts.authenticatedAttributes !== false;
   // RFC 5652 sec. 9.1: authAttrs MUST be present when the eContentType is not id-data.
   if (contentType !== "data" && !withAttrs) throw _err("cms/bad-input", "AuthenticatedData with a non-data contentType requires authenticated attributes (RFC 5652 sec. 9.1)");
 
@@ -558,12 +733,16 @@ async function authenticate(content, recipients, opts) {
   var macKey = nodeCrypto.randomBytes(MAC_KEY_OCTETS);
   try {
     var recips = [];
-    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(macKey, recipients[i], opts));
+    var consumedAuth = {};
+    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(macKey, recipients[i], opts, consumedAuth));
+    _assertDefaultsConsumed(opts, consumedAuth);
     var riNodes = recips.map(_taggedRecipient);
 
-    var digestName = opts.digestAlgorithm || mac.node;
     var digestAlgTagged = null, authAttrsDer = null, preimage;
     if (withAttrs) {
+      // Inside the branch that uses it: the attribute set is what carries the digest, so on the
+      // other branch there is no digest to name and opts.digestAlgorithm is refused at the door.
+      var digestName = opts.digestAlgorithm || mac.node;
       if (!SUPPORTED_DIGEST[digestName]) throw _err("cms/bad-input", "unsupported digestAlgorithm " + JSON.stringify(digestName) + " (sha256/384/512)");
       // sec. 9.2: content-type (== eContentType) + message-digest (== digest(content)) attributes,
       // SET-OF-sorted, MACed under the EXPLICIT SET OF tag (0x31) but transmitted [2] IMPLICIT (0xA2).
@@ -573,24 +752,7 @@ async function authenticate(content, recipients, opts) {
         b.sequence([b.oid(O("messageDigest")), b.setOf([b.octetString(mdDigest)])]),
       ];
       if (opts.authAttrs && opts.authAttrs.length) pairs = pairs.concat(opts.authAttrs);
-      // Every authAttr (auto-built or caller-supplied) MUST be a well-formed Attribute SEQUENCE
-      // { type OBJECT IDENTIFIER, values SET OF } and each type appears at most once (RFC 5652), so a
-      // malformed or duplicate caller attribute is rejected before it is MACed and emitted, never left to
-      // fail an operator's parser downstream.
-      var seenTypes = {};
-      pairs.forEach(function (p) {
-        var node;
-        try { node = asn1.decode(p); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute is not well-formed DER", e); }
-        if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children || node.children.length !== 2 ||
-          node.children[1].tagClass !== "universal" || node.children[1].tagNumber !== asn1.TAGS.SET ||
-          !node.children[1].children || node.children[1].children.length < 1) {
-          throw _err("cms/bad-input", "an authenticated attribute must be an Attribute SEQUENCE { type, non-empty SET OF value } (RFC 5652)");
-        }
-        var t;
-        try { t = asn1.read.oid(node.children[0]); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute type is not an OBJECT IDENTIFIER", e); }
-        if (seenTypes[t]) throw _err("cms/bad-input", "authenticated attributes must not repeat an attribute type (RFC 5652): " + t);
-        seenTypes[t] = 1;
-      });
+      _assertAuthAttrs(pairs, null);
       var setOf = b.setOf(pairs);
       preimage = setOf;                                                            // MAC over the 0x31 SET OF
       authAttrsDer = b.contextConstructed(2, setOf.subarray(_tlvHeaderLen(setOf)));   // [2] IMPLICIT on the wire

package/lib/cms-sign.js

@@ -43,6 +43,14 @@ var KNOWN_SIGN_OPTS = {
   signedAttributes: 1, signingTime: 1, additionalSignedAttributes: 1, unsignedAttributes: 1,
   sid: 1, eContentType: 1, detached: 1, certificates: 1, pem: 1,
 };
+// The SIGNER descriptor has two forms, and every field it reads is named here so a caller that
+// authors one can be held to the form it selects: a certificate signer, and the key-only signer
+// RFC 5272 sec. 3.2 requires for a Full PKI Request, whose identity comes from `spki` +
+// `keyIdentifier` instead. The signature parameters are read by both. Exported for the verbs that
+// take signer descriptors as AUTHORING input and gate them at their own door -- pki.cms.sign takes
+// them straight from its caller, where a bag carrying extra handles is an ordinary shape.
+var KNOWN_SIGNER_CERT_KEYS = { cert: 1, key: 1, pss: 1, digestAlgorithm: 1, combinedRsaSig: 1 };
+var KNOWN_SIGNER_KEY_ONLY_KEYS = { spki: 1, keyIdentifier: 1, key: 1, pss: 1, digestAlgorithm: 1, combinedRsaSig: 1 };
 // Countersign has its own set: it takes signerIndex and countersignatureOf to SELECT which
 // signature it attaches to, and has no content of its own, so eContentType, detached and
 // unsignedAttributes are not among the options it reads.
@@ -109,7 +117,7 @@ function _buildSid(cert, useSki) {
 function _buildSignedAttrs(pairs) {
   var seenTypes = {};
   var attrs = pairs.map(function (p) {
-    if (seenTypes[p.type]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    if (guard.intrinsic.hasOwn(seenTypes, p.type)) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
     seenTypes[p.type] = 1;
     return b.sequence([b.oid(p.type), b.set(p.values)]);
   });
@@ -147,8 +155,8 @@ function _buildUnsignedAttrs(list) {
   var pairs = _resolveAttrPairs(list, "an unsigned attribute value");
   var seen = {};
   pairs.forEach(function (p) {
-    if (UNSIGNED_FORBIDDEN[p.type]) throw _err("cms/bad-input", "the " + UNSIGNED_FORBIDDEN[p.type] + " attribute must not appear as an unsigned attribute (RFC 5652 sec. 11)");
-    if (seen[p.type]) throw _err("cms/bad-input", "unsignedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    if (guard.intrinsic.hasOwn(UNSIGNED_FORBIDDEN, p.type)) throw _err("cms/bad-input", "the " + UNSIGNED_FORBIDDEN[p.type] + " attribute must not appear as an unsigned attribute (RFC 5652 sec. 11)");
+    if (guard.intrinsic.hasOwn(seen, p.type)) throw _err("cms/bad-input", "unsignedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
     seen[p.type] = 1;
   });
   var setOf = b.set(pairs.map(function (p) { return b.sequence([b.oid(p.type), b.set(p.values)]); }));
@@ -658,4 +666,10 @@ function _countersign(cmsInput, signers, opts) {
 //     belt-and-suspenders against a future caller reordering the two.
 //   * the `crls [1]` preservation branches in `countersign`. pki.cms.sign never emits a crls field,
 //     so a store this producer countersigns never carries one to preserve.
-module.exports = { sign: sign, countersign: countersign };
+module.exports = {
+  sign: sign, countersign: countersign,
+  // @internal -- the signer-descriptor field tables, for a verb that AUTHORS signer descriptors
+  // from its own caller's options and gates them at its own door.
+  KNOWN_SIGNER_CERT_KEYS: KNOWN_SIGNER_CERT_KEYS,
+  KNOWN_SIGNER_KEY_ONLY_KEYS: KNOWN_SIGNER_KEY_ONLY_KEYS,
+};

package/lib/cms-verify.js

@@ -5,6 +5,7 @@
  * @module pki.cms
  * @nav        Verification
  * @title      CMS
+ * @fullname   CMS (Cryptographic Message Syntax) signing and verification
  * @intro Verify a CMS SignedData signature (RFC 5652 sec. 5) -- the structure S/MIME signed
  *   mail, RFC 3161 timestamp tokens, and code-signing all rest on. `verify(cms, opts)` parses
  *   the SignedData (over the strict `pki.schema.cms` codec), locates each SignerInfo's signer
@@ -1118,7 +1119,10 @@ var countersign = cmsSign.countersign;
  * @opts oaepHash      The RSAES-OAEP hash for ktri recipients: `"sha256"` (default) / `"sha384"` / `"sha512"`.
  * @opts keyIdentifier The recipient identifier form: `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
  * @opts ukm           User keying material (a Buffer) for kari / kemri recipients.
- * @opts authAttrs     Authenticated attributes (SET OF Attribute) for AuthEnvelopedData.
+ * @opts authAttrs     Authenticated attributes (SET OF Attribute) for AuthEnvelopedData. Each must be a
+ *   well-formed `Attribute SEQUENCE { type, non-empty SET OF value }` and no type may repeat (RFC 5652
+ *   sec. 5.3). `message-digest` is refused: its value is the unencrypted hash of the plaintext, which
+ *   enables content tracking and confirms a guessed plaintext (RFC 5083 sec. 2.1, sec. 5).
  * @opts pem           Return a PEM string instead of a DER Buffer.
  * @example
  *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };

package/lib/constants.js

@@ -5,6 +5,7 @@
  * @module     pki.C
  * @nav        Core
  * @title      Constants
+ * @fullname   Constants: size caps, time units and named bounds
  * @order      10
  * @featured   true
  * @slug       constants

package/lib/crl-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.crl
  * @nav        Signing
  * @title      CRLs
+ * @fullname   CRLs (certificate revocation lists): read, sign and shard
  * @intro The X.509 CRL producing side. `pki.crl.sign` builds a `TBSCertList`, signs it, and emits a
  *   `CertificateList` (RFC 5280 sec. 5) that `pki.schema.crl.parse`, `pki.path.crlChecker`, and OpenSSL
  *   all accept -- over any signature algorithm the toolkit registry resolves: RSA (PKCS#1 v1.5 / PSS),
@@ -71,8 +72,38 @@ var REASON_BY_NAME = {};
 Object.keys(CRL_REASON).forEach(function (v) { REASON_BY_NAME[CRL_REASON[v]] = Number(v); });
 
 var KNOWN_CRL_EXT_KEYS = { authorityKeyIdentifier: 1, issuingDistributionPoint: 1, deltaCRLIndicator: 1, freshestCRL: 1, authorityInfoAccess: 1 };
+// The three caller-owned objects pki.crl.sign reads. `crlNumber` and `extensions` are read by
+// _buildCrlExtensions, which _sign hands the whole spec to, so they belong here even though _sign
+// never names them -- the table is derived from what the call ACTUALLY reads, including through
+// its delegations, not from the doc block.
+var KNOWN_SPEC_KEYS = {
+  issuer: 1, thisUpdate: 1, nextUpdate: 1, revoked: 1, crlNumber: 1, extensions: 1,
+};
+// spec.issuer is the third place an issuer distinguished name can come from, and it is read only
+// when neither issuer.cert nor issuer.name supplies one: both of those win outright. A spec naming
+// one issuer beside a certificate for another was signed under the certificate's.
+var KNOWN_SPEC_KEYS_ISSUER_NAMED = {
+  thisUpdate: 1, nextUpdate: 1, revoked: 1, crlNumber: 1, extensions: 1,
+};
+// Two FORMS, exactly as x509-sign has: when `issuer.cert` is present the builder takes the DN and
+// the public key from it and never reads `name` or `publicKey`, so a union signed under the
+// certificate's identity while discarding the one the caller wrote out.
+var KNOWN_ISSUER_CERT_KEYS = { key: 1, cert: 1 };
+var KNOWN_ISSUER_EXPLICIT_KEYS = { key: 1, name: 1, publicKey: 1 };
+var KNOWN_SIGN_OPTS = { digestAlgorithm: 1, pem: 1, pss: 1 };
+
 var KNOWN_IDP_KEYS = { fullName: 1, onlyContainsUserCerts: 1, onlyContainsCACerts: 1, onlyContainsAttributeCerts: 1, indirectCRL: 1 };
 
+// The fields ONE revoked-certificate entry carries. Every optional one is encoded only when
+// present, so a misspelling is missed by nothing and the entry is signed without it: `reson` for
+// `reason` lists the certificate as revoked with no reasonCode at all, and a relying party reading
+// the CRL cannot tell a caller who meant keyCompromise from one who gave no reason. The entry is
+// where this bites hardest, because the CRL as a whole still verifies. `certificateIssuer` is
+// listed because the builder DOES read it -- to refuse it with its own message.
+var KNOWN_REVOKED_KEYS = {
+  serialNumber: 1, revocationDate: 1, reason: 1, invalidityDate: 1, certificateIssuer: 1, extensions: 1,
+};
+
 // RFC 5280 sec. 5.2 -- the profile-fixed criticality of each recognized CRL extension. cRLNumber (5.2.3),
 // authorityKeyIdentifier (5.2.1), freshestCRL (5.2.6), and authorityInfoAccess (5.2.7) MUST be non-critical;
 // issuingDistributionPoint (5.2.5) and deltaCRLIndicator (5.2.4) MUST be critical. Enforced on the object
@@ -311,6 +342,12 @@ function _buildRevoked(entryList, isDelta) {
   var anyExt = false, seenSerials = {};
   var entries = entryList.map(function (e, idx) {
     if (!e || typeof e !== "object" || Buffer.isBuffer(e)) throw _err("crl/bad-input", "each revoked entry must be an object");
+    // Before any field of the entry is encoded, so an unrecognized name is a refusal rather than an
+    // entry signed without what it asked for.
+    guard.identifier.assertKnownKeys(e, KNOWN_REVOKED_KEYS, _err, "crl/bad-input", function (k) {
+      return "unknown field " + JSON.stringify(k) + " in revoked entry [" + idx +
+        "]; an entry is { serialNumber, revocationDate, reason?, invalidityDate?, extensions? }";
+    });
     if (e.serialNumber == null) throw _err("crl/bad-input", "revoked entry [" + idx + "] requires a serialNumber");
     var serialTlv = _serialInteger(e.serialNumber);
     // RFC 5280 sec. 5.1.2.6 -- a serial number identifies a certificate uniquely, so a CRL MUST NOT list the
@@ -398,11 +435,34 @@ function _sign(spec, issuer, opts) {
   opts = opts || {};
   if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("crl/bad-input", "the CRL spec must be an object");
   issuer = issuer || {};
+  // Before any field is read. A dropped key here is worse than elsewhere in the toolkit: a CRL
+  // asserts what is revoked, so the failure is a correctly signed, structurally valid CRL saying
+  // NOTHING is revoked. `revokedCertificates` earns its own hint because it is the name the parser
+  // uses for the same list -- a caller round-tripping a parsed CRL back into sign reaches for it
+  // first, and got a signed empty list.
+  // The issuer form is settled once, before either door, so the spec table matches the source the
+  // distinguished name will actually come from.
+  var byCert = issuer.cert != null, byName = issuer.name != null;
+  guard.identifier.assertKnownKeys(spec, byCert || byName ? KNOWN_SPEC_KEYS_ISSUER_NAMED : KNOWN_SPEC_KEYS,
+    _err, "crl/bad-input", function (k) {
+      return "unknown CRL spec field " + JSON.stringify(k) +
+        (k === "revokedCertificates" ? "; the producer reads `revoked` (the parser reports the same list as `revokedCertificates`)"
+          : k === "issuer" ? "; the issuer argument already names one, through " + (byCert ? "issuer.cert" : "issuer.name") +
+            ", and that is the name the CRL is signed under"
+            : "");
+    });
+  guard.identifier.assertKnownKeys(issuer, byCert ? KNOWN_ISSUER_CERT_KEYS : KNOWN_ISSUER_EXPLICIT_KEYS,
+    _err, "crl/bad-input", function (k) {
+      return "unknown issuer field " + JSON.stringify(k) + " for the " + (byCert
+        ? "certificate form; issuer.cert supplies the name and the public key, so they are not read here"
+        : "explicit form; the issuer takes { key, name, publicKey }, or { key, cert } to take both from a certificate");
+    });
+  guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "crl/bad-input", "pki.crl.sign has an unknown option ");
   if (issuer.key == null) throw _err("crl/bad-input", "a signing key (issuer.key, a PKCS#8 private key) is required");
 
   // Resolve the issuer name + signing-key SPKI. `{ cert }` supplies both; else `{ name|spec.issuer, publicKey }`.
   var issuerDer, issuerSpki, issuerCert = null;
-  if (issuer.cert != null) {
+  if (byCert) {
     issuerCert = _parseIssuerCert(issuer.cert);
     _assertIssuerCanSignCrl(issuerCert);
     issuerDer = pkiBuild.tbsNameField(issuerCert, "subject");
@@ -410,7 +470,7 @@ function _sign(spec, issuer, opts) {
   } else {
     issuerSpki = _reqDer(issuer.publicKey, "issuer.publicKey (the issuer SPKI DER)");
     _assertValidSpki(issuerSpki, "issuer.publicKey");
-    var dnSource = issuer.name != null ? issuer.name : spec.issuer;
+    var dnSource = byName ? issuer.name : spec.issuer;
     if (dnSource == null) throw _err("crl/bad-issuer", "an issuer distinguished name is required (issuer.name or spec.issuer) when no issuer.cert is given");
     issuerDer = _encodeName(dnSource);
   }

package/lib/crmf-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.crmf
  * @nav        Signing
  * @title      Certificate request messages
+ * @fullname   CRMF (Certificate Request Message Format, RFC 4211)
  * @intro The RFC 4211 certificate-request-message producing side. `pki.crmf.build` assembles a
  *   `CertReqMessages` -- one or more `CertReqMsg`, each a `CertRequest` (a `CertTemplate` of the requested
  *   certificate fields plus optional controls) paired with a proof of possession. The common proof is a

package/lib/csr-sign.js

@@ -6,6 +6,7 @@
  * @module     pki.csr
  * @nav        Signing
  * @title      Certification requests
+ * @fullname   CSRs (PKCS#10 certification requests): build, sign and verify
  * @intro The PKCS#10 certification-request producing side. `pki.csr.sign` builds a
  *   `CertificationRequestInfo`, signs it with the subject's own private key (proof of possession, since
  *   a CSR has no issuer), and emits a `CertificationRequest` (RFC 2986) that `pki.schema.csr.parse`,

package/lib/ct.js

@@ -5,6 +5,7 @@
  * @module     pki.ct
  * @nav        Transparency
  * @title      CT
+ * @fullname   Certificate Transparency (CT) logs and SCTs
  * @order      210
  * @slug       ct
  *

package/lib/est.js

@@ -5,6 +5,7 @@
  * @module     pki.est
  * @nav        Schema
  * @title      EST
+ * @fullname   EST (Enrollment over Secure Transport, RFC 7030)
  * @order      190
  * @slug       est
  *

package/lib/framework-error.js

@@ -5,6 +5,7 @@
  * @module     pki.errors
  * @nav        Core
  * @title      Errors
+ * @fullname   Error classes and the stable domain/reason codes they carry
  * @order      20
  * @slug       errors
  *