@blamejs/pki 0.6.47 → 0.6.49

package/lib/cmc-build.js

@@ -15,9 +15,18 @@ var crmf = require("./schema-crmf");
 var cmcFmt = require("./schema-cmc");
 var oid = require("./oid");
 var cmsSign = require("./cms-sign");
+var cmsEncrypt = require("./cms-encrypt");
+var cmsDecrypt = require("./cms-decrypt");
+var key = require("./key");
+var _createPublicKey = nodeCrypto.createPublicKey;
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
 var _hasOwn = intrinsic.hasOwn;
+var _isArray = intrinsic.isArray;
+var _isBuffer = intrinsic.isBuffer;
+var _bufferFrom = intrinsic.bufferFrom;
+var _bufferConcat = intrinsic.bufferConcat;
+var _subarray = intrinsic.subarray;
 var frameworkError = require("./framework-error");
 
 var CmcError = frameworkError.CmcError;
@@ -27,6 +36,7 @@ function O(name) { return oid.byName(name); }
 
 var OID_IDENTITY_PROOF_V2 = O("id-cmc-identityProofV2");
 var OID_POP_LINK_RANDOM = O("id-cmc-popLinkRandom");
+var OID_DECRYPTED_POP = O("id-cmc-decryptedPOP");
 var OID_IDENTIFICATION = O("id-cmc-identification");
 var OID_SHA256 = O("sha256");
 var OID_HMAC_SHA256 = O("hmacWithSHA256");
@@ -42,7 +52,7 @@ var POP_LINK_RANDOM_BYTES = 64;
 
 var KNOWN_SPEC_KEYS = intrinsic.assign(intrinsic.create(null), {
   requests: 1, controls: 1, cmsSequence: 1, otherMsgSequence: 1,
-  identityProof: 1, popLink: 1, renewal: 1,
+  identityProof: 1, popLink: 1, renewal: 1, popChallenge: 1,
   transactionId: 1, senderNonce: 1, dataReturn: 1,
 });
 
@@ -100,6 +110,61 @@ var KNOWN_REQUEST_KEYS = intrinsic.assign(intrinsic.create(null), { tcr: 1, crm:
 var KNOWN_CONTROL_KEYS = intrinsic.assign(intrinsic.create(null), { type: 1, value: 1 });
 var KNOWN_IDENTITY_PROOF_KEYS = intrinsic.assign(intrinsic.create(null), { identity: 1, secret: 1 });
 var KNOWN_POP_LINK_KEYS = intrinsic.assign(intrinsic.create(null), { secret: 1 });
+var KNOWN_MAC_KEYS = intrinsic.assign(intrinsic.create(null), { identifier: 1, secret: 1 });
+var KNOWN_MAC_CARRIER_KEYS = intrinsic.assign(intrinsic.create(null), { mac: 1 });
+var UTF8_STRING_TAG = 12;
+
+/** @internal Whether two caller-supplied secrets are the same secret, comparing the bytes each spells
+ * out so a string and the same bytes are not read as two different credentials. Compared in constant
+ * time: the two values come from one caller here, but the primitive is the one this toolkit compares
+ * secret-derived bytes with everywhere. */
+function _sameSecret(a, byIdentity) {
+  var ab = null, bb = null;
+  try {
+    ab = _secretCopy(a, "the shared secret");
+    bb = _secretCopy(byIdentity, "the identityProof secret");
+    return ab !== null && bb !== null && ab.length === bb.length && guard.crypto.constantTimeEqual(ab, bb);
+  } finally {
+    /** @internal Both copies, on every exit: one input being unusable is the path that leaves the other
+     * one allocated, and a comparison that refuses is still a comparison that copied. */
+    var made = [];
+    if (ab) guard.list.append(made, ab);
+    if (bb) guard.list.append(made, bb);
+    if (made.length) guard.secret.zeroizeAll(made, CmcError, "cmc/bad-input", "the compared shared-secret copies");
+  }
+}
+function _secretCopy(v, what) {
+  if (typeof v === "string") return _bufferFrom(v, "utf8");
+  if (guard.bytes.isByteSource(v)) return guard.bytes.snapshotSource(v, CmcError, "cmc/bad-input", what);
+  return null;
+}
+
+/** @internal The key a shared-secret carrier derives its MAC key from: the identifier encoded as UTF-8
+ * followed by the shared secret (RFC 5272 sec. 3.2(c)). Both halves of the toolkit read this one
+ * function, so a request it builds and a message it authenticates derive the same bytes. The caller
+ * owns the returned buffer and wipes it. */
+function macPassword(mac) {
+  if (!mac || typeof mac !== "object" || _isArray(mac) || _isBuffer(mac)) {
+    throw E("cmc/bad-input", "a shared-secret carrier is { identifier, secret } (RFC 5272 sec. 3.2)");
+  }
+  guard.identifier.assertKnownKeys(mac, KNOWN_MAC_KEYS, E, "cmc/bad-input", "unknown shared-secret field ");
+  if (typeof mac.identifier !== "string" || mac.identifier.length === 0) {
+    throw E("cmc/bad-input", "a shared-secret carrier needs the identifier the authority knows the client by, as a non-empty string (RFC 5272 sec. 3.2)");
+  }
+  if (typeof mac.secret !== "string" && !guard.bytes.isByteSource(mac.secret)) {
+    throw E("cmc/bad-input", "a shared-secret carrier needs the secret as a string or bytes (RFC 5272 sec. 3.2)");
+  }
+  var secretBytes = typeof mac.secret === "string" ? _bufferFrom(mac.secret, "utf8")
+    : guard.bytes.snapshotSource(mac.secret, CmcError, "cmc/bad-input", "the shared secret");
+  if (secretBytes.length === 0) {
+    guard.secret.zeroize(secretBytes, CmcError, "cmc/bad-input", "the shared secret");
+    throw E("cmc/bad-input", "a shared-secret carrier needs a non-empty secret (RFC 5272 sec. 3.2)");
+  }
+  var idBytes = _bufferFrom(mac.identifier, "utf8");
+  var joined = _bufferConcat([idBytes, secretBytes]);
+  guard.secret.zeroizeAll([idBytes, secretBytes], CmcError, "cmc/bad-input", "the shared-secret encoding");
+  return joined;
+}
 
 function fixedRequestId(req, index) {
   if (!req || typeof req !== "object") throw E("cmc/bad-input", "each request must be an object");
@@ -125,13 +190,59 @@ function fixedRequestId(req, index) {
   return req.bodyPartID == null ? null : req.bodyPartID;
 }
 
-async function _assertTcrPops(requests) {
+async function _assertTcrPops(requests, popProvenRequest) {
   for (var i = 0; i < requests.length; i++) {
-    if (requests[i] && requests[i].tcr != null) await _assertOneTcrPop(requests[i].tcr, i);
+    if (requests[i] && requests[i].tcr != null) await _assertOneTcrPop(requests[i].tcr, i, popProvenRequest);
   }
 }
-async function _assertOneTcrPop(tcr, i) {
-  var parsed = csr.parse(_der(tcr, "a tcr certificationRequest"));
+/** @internal The parameters an algorithm identifier carries, which for these four are absent or NULL. */
+function _assertNoAlgorithmParameters(algId, what) {
+  var params = algId.parameters;
+  if (params == null) return;
+  if (params.length === 2 && params[0] === 0x05 && params[1] === 0x00) return;
+  throw E("cmc/bad-pop-challenge",
+    "the challenge's " + what + " carries a parameter value, and the algorithms RFC 5274 sec. 4.2 " +
+    "names take none: they are encoded with the parameters absent or NULL");
+}
+
+/** @internal Whether these bytes are one DER OCTET STRING and nothing else. */
+function _isNoSignatureValue(bytes) {
+  if (!bytes || !bytes.length) return false;
+  var node;
+  try { node = asn1.decode(bytes); }
+  catch (_e) { return false; } // allow:swallow-unverified bytes that do not decode are not a NoSignatureValue
+  return node.tagClass === "universal" && node.tagNumber === asn1.TAGS.OCTET_STRING && !node.constructed;
+}
+
+/** @internal A key that can only decrypt cannot sign the request that asks for its certificate, so RFC
+ * 5272 App. C.1 gives it a signature algorithm that carries no proof and sends the proof through the
+ * sec. 6.7 challenge instead. A request in that form is accepted here only when this message answers a
+ * challenge for that same request; without one it carries no proof of possession at all. */
+async function _assertOneTcrPop(tcr, i, popProvenRequest) {
+  var der = _der(tcr, "a tcr certificationRequest");
+  var parsed = csr.parse(der);
+  if (parsed.signatureAlgorithm.oid === O("id-alg-noSignature")) {
+    var params = parsed.signatureAlgorithm.parameters;
+    if (!params || params.length !== 2 || params[0] !== 0x05 || params[1] !== 0x00) {
+      throw E("cmc/bad-popo", "a tcr request [" + i + "] uses id-alg-noSignature, whose parameters must be " +
+        "present and encoded as NULL (RFC 5272 App. C.1)");
+    }
+    /** @internal "NoSignatureValue ::= OCTET STRING" (App. C.1), carried in the signature BIT STRING.
+     * The section says it holds the hash of the request but names no algorithm, so the encoding is what
+     * can be checked here; a value that is not one is a request an authority would reject. */
+    var sig = parsed.signatureValue;
+    if (!sig || sig.unusedBits !== 0 || !_isNoSignatureValue(sig.bytes)) {
+      throw E("cmc/bad-popo", "a tcr request [" + i + "] uses id-alg-noSignature, whose signature is a " +
+        "NoSignatureValue OCTET STRING (RFC 5272 App. C.1)");
+    }
+    if (!popProvenRequest || popProvenRequest.length !== der.length ||
+        !guard.crypto.constantTimeEqual(popProvenRequest, der)) {
+      throw E("cmc/bad-popo", "a tcr request [" + i + "] is signed with id-alg-noSignature, which proves " +
+        "nothing about the key; such a request carries its proof of possession in an answered " +
+        "challenge, so pass the one the authority sent as popChallenge (RFC 5272 App. C.1, sec. 6.7)");
+    }
+    return;
+  }
   if (!(await csrVerify.verifyCsrSignature(parsed))) {
     throw E("cmc/bad-popo", "a tcr request [" + i + "] failed its proof-of-possession: the PKCS#10 signature does not verify under the request's own subject public key (RFC 5272 sec. 6.3), so a CA would reject it -- refusing it here rather than signing it");
   }
@@ -225,10 +336,58 @@ var BINDING_TYPE_NAME = intrinsic.assign(intrinsic.create(null), {
   dataReturn: "an OCTET STRING (RFC 5272 sec. 6.4)",
 });
 
+/** @internal Controls the builder computes for itself from a spec field. Their value is a proof, so a
+ * second one arriving hand-encoded cannot be reconciled with the computed one the way an Identification
+ * name can: the two would both be emitted, and a message carrying two proofs of the same thing is one an
+ * authority has no rule for. Naming the spec field that produces it says which of the two to drop. */
+var GENERATED_BY_OID = intrinsic.create(null);
+GENERATED_BY_OID[O("id-cmc-identityProofV2")] = { field: "identityProof" };
+GENERATED_BY_OID[O("id-cmc-popLinkWitnessV2")] = { field: "popLink" };
+GENERATED_BY_OID[O("id-cmc-popLinkRandom")] = { field: "popLink" };
+GENERATED_BY_OID[O("id-cmc-decryptedPOP")] = { field: "popChallenge", perTarget: true };
+
+/** @internal The bodyPartID a Decrypted POP names, which is the request its proof covers. Several may
+ * ride in one message, one per request, so it is the target that has to be unique rather than the
+ * control. A value that will not read as one is treated as naming nothing, and a second such control is
+ * refused because there is no target to tell the two apart by. */
+function _decryptedPopTarget(controlValue) {
+  try {
+    var node = asn1.decode(controlValue);
+    return intrinsic.bigIntToString(asn1.read.integer(node.children[0]), 10);
+  } catch (_e) { return null; } // allow:swallow-unverified an unreadable control names no request
+}
+
+function _assertNotAlsoComputed(controlType, controlValue, seen, spec) {
+  var generated = GENERATED_BY_OID[controlType];
+  if (!generated) return;
+  /** @internal Tested the way the producer tests it. A field this reads as present but the emitting
+   * code skips would refuse a message that carries one control, not two. */
+  if (spec[generated.field]) {
+    throw E("cmc/bad-input",
+      "spec." + generated.field + " computes this control, and spec.controls carries one as well; a " +
+      "request carries one or the other, since a message with two leaves the authority no proof to " +
+      "check (RFC 5272 sec. 6.2.1 / 6.3.1 / 6.7)");
+  }
+  var target = generated.perTarget ? _decryptedPopTarget(controlValue) : null;
+  var slot = generated.perTarget ? controlType + ":" + (target === null ? "?" : target) : controlType;
+  if (seen[guard.text.keyOf(slot)]) {
+    throw E("cmc/bad-input",
+      "spec.controls carries two " + (oid.name(controlType) || controlType) + " controls" +
+      (generated.perTarget
+        ? (target === null
+          ? " that name no readable certification request, so nothing tells the two proofs apart"
+          : " naming certification request " + target + ", so the authority has two proofs of one request")
+        : "") +
+      "; a message with two leaves the authority no proof to check (RFC 5272 sec. 6.2.1 / 6.3.1 / 6.7)");
+  }
+  seen[guard.text.keyOf(slot)] = true;
+}
+
 function _assertNoDuplicateBinding(callerControls, spec) {
   var seen = intrinsic.create(null);
   callerControls.forEach(function (c) {
-    var field = BINDING_BY_OID[_oidOf(c.type)];
+    var controlOid = _oidOf(c.type);
+    var field = BINDING_BY_OID[controlOid];
     if (!field) return;
     try { BINDING_READER[field](asn1.decode(_der(c.value, "a control value"))); }
     catch (e) {
@@ -314,6 +473,175 @@ function identityProofV2(secret, reqSequenceBytes, identity) {
   }
 }
 
+/** @internal RFC 5274 sec. 4.2 names what a conforming client implements for this exchange: SHA-1 MUST
+ * and SHA-256 SHOULD for the witness, HMAC-SHA1 MUST and HMAC-SHA256 SHOULD for the proof. Both MUSTs
+ * are legacy algorithms and are accepted because the profile requires them of a client answering a
+ * challenge, which is a server's choice to make rather than this side's. Anything else is refused: a
+ * proof computed under an algorithm the server did not ask for is not an answer. */
+var POP_WITNESS_HASH = intrinsic.create(null);
+POP_WITNESS_HASH[O("sha1")] = "sha1";
+POP_WITNESS_HASH[O("sha256")] = "sha256";
+var POP_MAC_HASH = intrinsic.create(null);
+POP_MAC_HASH[O("hmacWithSHA1")] = "sha1";
+POP_MAC_HASH[O("hmacWithSHA256")] = "sha256";
+var POP_MAC_KEY_MAX_BYTES = 64;
+var KNOWN_POP_CHALLENGE_KEYS = intrinsic.assign(intrinsic.create(null),
+  { challenge: 1, recipient: 1 });
+
+/** @internal The key this challenge is addressed to is the one being certified, which by definition has
+ * no certificate yet, so the recipient cannot be selected by matching one. Sec. 6.7 says the identifier
+ * "SHOULD be the SKI" of the request, and that an issuerAndSerialNumber form carries a NULL issuer with
+ * the request's bodyPartID as the serial: neither names a certificate this caller holds. So each
+ * recipient is tried with the key, and the WITNESS decides which attempt recovered the right value,
+ * which is the check the section already requires and the only one that can answer the question. A
+ * caller who does hold the certificate can still pass it and select the ordinary way. */
+var POP_MAX_RECIPIENTS = 8;
+
+/** @internal The CMS recipient kinds that identify a key. A password or a key-encryption key opens the
+ * envelope without saying whose it is, so a decryption through one proves possession of no key. */
+var ASYMMETRIC_RECIPIENT = intrinsic.assign(intrinsic.create(null), { ktri: 1, kari: 1, ori: 1 });
+
+/** @internal What identifies a request within its arm, which is everything a TaggedRequest carries
+ * except the body part identifier the new message is entitled to renumber. Defined once, so the two
+ * sides of the comparison below cannot read different things: the other-message arm is identified by
+ * its type together with its value, since a value alone could belong to another type. */
+function _requestIdentity(parsed) {
+  if (!parsed) return null;
+  if (parsed.arm === "tcr") return { arm: "tcr", bytes: parsed.certificationRequestBytes };
+  if (parsed.arm === "crm") return { arm: "crm", bytes: parsed.certReqMsgBytes };
+  if (parsed.arm === "orm" && parsed.requestMessageType) {
+    return { arm: "orm",
+      bytes: _bufferConcat([b.oid(parsed.requestMessageType), parsed.requestMessageValueBytes]) };
+  }
+  return null;
+}
+
+/** @internal Whether the key that opened the challenge is the key the request asks to have certified.
+ * Only a tcr is answered this way: a crm request carries its own proof-of-possession field. */
+function _provesRequestKey(openingKey, outgoing) {
+  if (!openingKey || !outgoing || !outgoing.certificationRequestBytes) return false;
+  var requested;
+  /** @internal Compared as keys rather than as encodings: an elliptic-curve point written in compressed
+   * form and the same point written uncompressed are different bytes and the same key, and it is the key
+   * the section is about. */
+  try {
+    requested = _createPublicKey({
+      key: csr.parse(outgoing.certificationRequestBytes).subjectPublicKeyInfo.bytes,
+      format: "der", type: "spki",
+    });
+  } catch (_e) { return false; } // allow:swallow-unverified a key this runtime cannot read proves nothing here
+  return intrinsic.keyEquals(requested, openingKey);
+}
+
+/** @internal The public half of the key that OPENED the challenge. The recipient kind comes from the
+ * decryption that succeeded rather than from the caller's object, so key material the envelope never
+ * exercised is not read as the key that answered it. A key whose public half this runtime cannot derive
+ * yields null, and the request is then refused rather than accepted on an unproven key. */
+async function _openingPublicKey(recipient, recipientType) {
+  if (!ASYMMETRIC_RECIPIENT[recipientType]) return null;
+  try {
+    return _createPublicKey({
+      key: await key.publicFromPrivate(recipient.key), format: "der", type: "spki",
+    });
+  } catch (_e) { return null; } // allow:swallow-unverified a key whose public half cannot be derived proves nothing here
+}
+
+async function _recoverProofValue(decoded, recipient, witnessHash) {
+  /** @internal The count is read off the parse rather than re-walked here, so the structure the parser
+   * accepted and the structure this loop iterates cannot disagree. */
+  var count = decoded.cmsRecipientCount;
+  if (count > POP_MAX_RECIPIENTS) {
+    throw E("cmc/bad-pop-challenge",
+      "the challenge's enveloped proof value names " + count + " recipients; a challenge is addressed to " +
+      "the key being certified, and at most " + POP_MAX_RECIPIENTS + " are tried (RFC 5272 sec. 6.7)");
+  }
+  for (var i = 0; i < count; i++) {
+    var opened;
+    try {
+      opened = await cmsDecrypt.decrypt(decoded.cms, recipient, { recipientIndex: i });
+    } catch (_e) {
+      continue;   // allow:swallow-unverified this recipient is not addressed to the supplied key; the witness decides
+    }
+    var candidate = opened.content;
+    var computed = nodeCrypto.createHash(witnessHash).update(candidate).digest();
+    var matches = computed.length === decoded.witness.length &&
+      guard.crypto.constantTimeEqual(computed, decoded.witness);
+    guard.secret.zeroize(computed, CmcError, "cmc/bad-input", "the computed witness");
+    /** @internal The kind of recipient that actually opened it travels with the value, so what proved
+     * possession is decided by the decryption that happened rather than by the caller's object. */
+    if (matches) return { value: candidate, recipientType: opened.recipientType };
+    guard.secret.zeroize(candidate, CmcError, "cmc/bad-input", "a rejected proof value");
+  }
+  throw E("cmc/pop-failed",
+    "no recipient of the challenge yielded a proof value hashing to the witness it carries, so this " +
+    "client cannot prove possession and the enrollment is abandoned (RFC 5272 sec. 6.7 step 3)");
+}
+
+/** @internal The client half of RFC 5272 sec. 6.7: decrypt the challenge, confirm it is the value the
+ * server hashed into the witness, and answer with a MAC over the request it carried. The witness check
+ * is not separable from the answer, because a client that cannot confirm the value "MUST abort the
+ * enrollment process" rather than prove possession of something it could not read. */
+async function answerPopChallenge(popChallenge, ids) {
+  if (!popChallenge || typeof popChallenge !== "object" || _isArray(popChallenge) || _isBuffer(popChallenge)) {
+    throw E("cmc/bad-input", "popChallenge is { challenge, recipient } (RFC 5272 sec. 6.7)");
+  }
+  guard.identifier.assertKnownKeys(popChallenge, KNOWN_POP_CHALLENGE_KEYS, E, "cmc/bad-input",
+    "unknown popChallenge field ");
+  var recipient = popChallenge.recipient;
+  if (!recipient || typeof recipient !== "object" || _isArray(recipient) || _isBuffer(recipient)) {
+    throw E("cmc/bad-input",
+      "popChallenge.recipient is the CMS key material that opens the challenge, in the shape " +
+      "pki.cms.decrypt takes (RFC 5272 sec. 6.7)");
+  }
+  /** @internal The challenge arrives from the authority, so bytes that are not DER at all are a
+   * malformed challenge like any other and carry the same code rather than the codec's. */
+  var challengeBytes = _der(popChallenge.challenge, "the popChallenge challenge");
+  var challengeNode;
+  try { challengeNode = asn1.decode(challengeBytes); }
+  catch (e) {
+    throw E("cmc/bad-pop-challenge",
+      "the popChallenge challenge is the DER of an EncryptedPOP control value: " +
+      ((e && e.message) || "malformed") + " (RFC 5272 sec. 6.7)", e);
+  }
+  var decoded = cmcFmt.parseEncryptedPop(challengeNode);
+  var witnessHash = POP_WITNESS_HASH[guard.text.keyOf(decoded.witnessAlgID.oid)];
+  var macHash = POP_MAC_HASH[guard.text.keyOf(decoded.thePOPAlgID.oid)];
+  if (!witnessHash || !macHash) {
+    throw E("cmc/bad-pop-challenge",
+      "the challenge names an algorithm this client does not answer under: RFC 5274 sec. 4.2 requires " +
+      "SHA-1 or SHA-256 for the witness and HMAC-SHA1 or HMAC-SHA256 for the proof, got " +
+      decoded.witnessAlgID.oid + " and " + decoded.thePOPAlgID.oid);
+  }
+  /** @internal These four algorithms take no parameters: a SHA-2 identifier carries them absent or as
+   * NULL (RFC 5754 sec. 2), and the SHA-1 and HMAC identifiers carry NULL. A parameter value that is
+   * neither is not one of the algorithms named, and copying it into the answer would send the authority
+   * an identifier it cannot read. */
+  _assertNoAlgorithmParameters(decoded.witnessAlgID, "witnessAlgID");
+  _assertNoAlgorithmParameters(decoded.thePOPAlgID, "thePOPAlgID");
+
+  var proofValue = null, macKey = null;
+  try {
+    var recovered = await _recoverProofValue(decoded, recipient, witnessHash);
+    proofValue = recovered.value;
+    /** @internal "The POP Proof Value is used as the secret value in the HMAC algorithm and the request
+     * is used as the data. If the POP Proof Value is greater than 64 bytes, only the first 64 bytes of
+     * the POP Proof Value is used as the secret." The data is the TaggedRequest exactly as the
+     * challenge carried it, which is the copy the server holds and the reason sec. 6.7 puts the request
+     * in the challenge at all: neither side re-encodes it. */
+    macKey = _bufferFrom(proofValue.length > POP_MAC_KEY_MAX_BYTES
+      ? _subarray(proofValue, 0, POP_MAC_KEY_MAX_BYTES) : proofValue);
+    var thePOP = nodeCrypto.createHmac(macHash, macKey).update(decoded.requestBytes).digest();
+    return { algBytes: decoded.thePOPAlgID.bytes, thePOP: thePOP, ids: ids,
+      recipientSpki: await _openingPublicKey(recipient, recovered.recipientType),
+      challengedRequest: _requestIdentity(decoded.request) };
+  } finally {
+    var owned = [];
+    if (proofValue && _isBuffer(proofValue)) guard.list.append(owned, proofValue);
+    if (macKey) guard.list.append(owned, macKey);
+    if (owned.length) guard.secret.zeroizeAll(owned, CmcError, "cmc/bad-input", "the POP proof value");
+  }
+}
+
 function popLinkWitnessV2(secret, R) {
   _assertSecret(secret, "a POP Link Witness V2 control");
   var key = nodeCrypto.createHash("sha256").update(secret, "utf8").digest();
@@ -373,7 +701,17 @@ async function _build(spec, signer, opts) {
           "a renewal request carries no " + forbidden + " control (RFC 5272 sec. 3.2 (a))");
       }
     }
-    var renewalSigners = Array.isArray(signer) ? signer : [signer];
+    /** @internal A renewal carries no Identification or Identity Proof control because, in sec. 3.2(a)'s
+     * words, "the same information is provided by the use of an existing certificate from a CA when
+     * signing the PKI Request". A shared secret authenticates the message without naming any
+     * certificate, so a renewal carried that way would assert an identity by nothing at all. */
+    if (signer && typeof signer === "object" && !_isArray(signer) && signer.mac != null) {
+      throw E("cmc/bad-signer",
+        "a renewal request is signed with the certificate being renewed, which is what carries the " +
+        "original identity in place of the Identification and Identity Proof controls (RFC 5272 sec. 3.2 (a)); " +
+        "a shared secret names no certificate, so it cannot renew");
+    }
+    var renewalSigners = _isArray(signer) ? signer : [signer];
     for (var si = 0; si < renewalSigners.length; si++) {
       var rs = renewalSigners[si];
       if (rs && rs.cert == null && rs.spki != null) {
@@ -385,6 +723,12 @@ async function _build(spec, signer, opts) {
   }
 
   var controls = [];
+  /** @internal The names a caller-written Identification control gives this client, collected as those
+   * controls are encoded so the name checked is the name carried (RFC 5272 sec. 6.2.3). */
+  var controlIdentifiers = [], controlIdentificationCount = 0, controlIdentifierUnreadable = false;
+  /** @internal Which of the controls the builder computes have already arrived hand-encoded, checked
+   * against the bytes being encoded rather than a second read of the caller's object. */
+  var generatedSeen = intrinsic.create(null);
   callerControls.forEach(function (c) {
     if (!c || typeof c !== "object" || c.type == null || c.value == null) {
       throw E("cmc/bad-input", "each control is { type, value }");
@@ -393,7 +737,27 @@ async function _build(spec, signer, opts) {
       return "unknown field " + JSON.stringify(k) + " on a control -- a control is { type, value }, " +
         "and its bodyPartID is allocated by the builder";
     });
-    controls.push(encodeControl(_oidOf(c.type), [_der(c.value, "a control value")], ids));
+    /** @internal Taken once. A control is a caller object, so reading `type` or `value` a second time
+     * can answer differently than it did here, and what this request is checked against has to be what
+     * it carries. The Identification name below is read off THESE bytes for the same reason. */
+    var controlType = _oidOf(c.type);
+    var controlValue = _der(c.value, "a control value");
+    _assertNotAlsoComputed(controlType, controlValue, generatedSeen, spec);
+    if (controlType === OID_IDENTIFICATION) {
+      controlIdentificationCount += 1;
+      var idNode;
+      try { idNode = asn1.decode(controlValue); }
+      catch (_e) { controlIdentifierUnreadable = true; }
+      /** @internal The control is a UTF8String (RFC 5272 sec. 6.2.3). Another string type carrying the
+       * same characters is a different value on the wire, so it cannot stand in for the control this
+       * request needs while a strict authority refuses the message. */
+      if (idNode && idNode.tagClass === "universal" && idNode.tagNumber === UTF8_STRING_TAG) {
+        guard.list.append(controlIdentifiers, asn1.read.string(idNode));
+      } else {
+        controlIdentifierUnreadable = true;
+      }
+    }
+    guard.list.append(controls, encodeControl(controlType, [controlValue], ids));
   });
 
   _assertNoDuplicateBinding(callerControls, spec);
@@ -410,6 +774,22 @@ async function _build(spec, signer, opts) {
       [b.octetString(_der(spec.dataReturn, "spec.dataReturn"))], ids));
   }
 
+  /** @internal The name the request gives the authority for this client, from whichever of the two
+   * places names it. Read before either control is emitted, so the pair can be compared. */
+  var macIdentifier = signer && typeof signer === "object" && !_isArray(signer) && signer.mac != null &&
+    typeof signer.mac === "object" && typeof signer.mac.identifier === "string" ? signer.mac.identifier : null;
+  var identityIdentifier = spec.identityProof && typeof spec.identityProof.identity === "string"
+    ? spec.identityProof.identity : null;
+
+  /** @internal Settled BEFORE the Identity Proof witness is computed, because the presence of an
+   * Identification control changes how that witness is derived: with one, the hash is over the secret
+   * and the identity together rather than the secret alone (RFC 5272 sec. 6.2.3). A name reaching the
+   * request from anywhere therefore has to be known here, or the witness is derived one way and the
+   * request carries the control that demands the other. */
+  var carriedIdentity = identityIdentifier;
+  if (carriedIdentity == null && controlIdentifiers.length > 0) carriedIdentity = controlIdentifiers[0];
+  if (carriedIdentity == null) carriedIdentity = macIdentifier;
+
   if (spec.identityProof) {
     guard.identifier.assertKnownKeys(spec.identityProof, KNOWN_IDENTITY_PROOF_KEYS, E, "cmc/bad-input",
       function (k) { return "unknown field " + JSON.stringify(k) + " on identityProof -- it is { secret, identity? }"; });
@@ -419,7 +799,88 @@ async function _build(spec, signer, opts) {
     }
     if (identity != null) controls.push(encodeControl(OID_IDENTIFICATION, [b.utf8(identity)], ids));
     controls.push(encodeControl(OID_IDENTITY_PROOF_V2,
-      [identityProofV2(spec.identityProof.secret, reqSequenceBytes, identity)], ids));
+      [identityProofV2(spec.identityProof.secret, reqSequenceBytes, carriedIdentity)], ids));
+  }
+
+  /** @internal A PasswordRecipientInfo names no recipient, so an authority holding secrets for many
+   * clients has nothing in the carrier to select one by. The Identification control is what carries
+   * that name: it "assists the server in locating the shared-secret" (RFC 5272 sec. 6.2.3), so a
+   * request authenticated by a secret says whose secret it is. Two names for one client is refused
+   * rather than picked between. */
+  if (macIdentifier != null) {
+    var named = [];
+    for (var nc = 0; nc < controlIdentifiers.length; nc++) guard.list.append(named, controlIdentifiers[nc]);
+    if (identityIdentifier != null) guard.list.append(named, identityIdentifier);
+    for (var ni = 0; ni < named.length; ni++) {
+      if (named[ni] !== macIdentifier) {
+        throw E("cmc/bad-input",
+          "the shared-secret identifier and the Identification the request already carries name the same " +
+          "client to the authority, so a request cannot carry two different ones (RFC 5272 sec. 6.2.3)");
+      }
+    }
+    if (controlIdentifierUnreadable) {
+      throw E("cmc/bad-input",
+        "the Identification control this request carries does not read as the UTF8String the client is " +
+        "named by, so it cannot be confirmed to name the client whose secret authenticates the request (RFC 5272 sec. 6.2.3)");
+    }
+    /** @internal One client, one shared secret. The carrier's MAC and an Identity Proof witness are both
+     * keyed from "the shared-secret" (RFC 5272 sec. 3.2 and 6.2.1), so two different ones would leave an
+     * authority able to check one and not the other, and unable to tell which credential is the client's. */
+    if (spec.identityProof && !_sameSecret(signer.mac.secret, spec.identityProof.secret)) {
+      throw E("cmc/bad-input",
+        "the shared secret that authenticates this request and the one its Identity Proof is computed " +
+        "from are the same secret, so a request cannot carry two different ones (RFC 5272 sec. 3.2 / 6.2.1)");
+    }
+    /** @internal One request names one client once. Two controls saying the same thing still leave an
+     * authority choosing between them, so the request carries exactly one however it was assembled. */
+    var alreadyNamed = controlIdentificationCount + (identityIdentifier == null ? 0 : 1);
+    if (alreadyNamed > 1) {
+      throw E("cmc/bad-input",
+        "a request names its client once, and this one carries " + alreadyNamed + " Identification controls " +
+        "(RFC 5272 sec. 6.2.3)");
+    }
+    if (alreadyNamed === 0) {
+      guard.list.append(controls, encodeControl(OID_IDENTIFICATION, [b.utf8(macIdentifier)], ids));
+    }
+  }
+
+  /** @internal The answer to a challenge-response proof of possession (RFC 5272 sec. 6.7 step 4). Its
+   * bodyPartID names the certification request in THIS request, not the one the challenge quoted, so
+   * the server can tie the proof to what is being asked for now. With more than one request there is
+   * no single answer to give, and guessing which one the proof covers is not this side's call. */
+  var popProvenRequest = null;
+  if (spec.popChallenge) {
+    if (encodedRequests.length !== 1) {
+      throw E("cmc/bad-input",
+        "a challenge-response proof of possession answers for one certification request, and this " +
+        "request carries " + encodedRequests.length + " (RFC 5272 sec. 6.7)");
+    }
+    var answered = await answerPopChallenge(spec.popChallenge, ids);
+    /** @internal The proof covers the request the CHALLENGE carried, and the control names the request
+     * in THIS message. If those are not the same certification request, the message proves possession
+     * of a key for a request it does not contain, so the two are compared on everything but the body
+     * part identifier, which the new message is entitled to renumber. */
+    var outgoing = cmcFmt.parseTaggedRequest(asn1.decode(encodedRequests[0].der));
+    var outgoingId = _requestIdentity(outgoing);
+    if (!answered.challengedRequest || !outgoingId ||
+        answered.challengedRequest.arm !== outgoingId.arm ||
+        answered.challengedRequest.bytes.length !== outgoingId.bytes.length ||
+        !guard.crypto.constantTimeEqual(answered.challengedRequest.bytes, outgoingId.bytes)) {
+      throw E("cmc/bad-input",
+        "the challenge answers for a different certification request than this message carries, so the " +
+        "proof would not cover the request it names (RFC 5272 sec. 6.7 step 4)");
+    }
+    /** @internal What the challenge proved possession of. A request signed with id-alg-noSignature has
+     * no signature to prove it, and App. C.1 sends exactly that case here, so this is the request that
+     * is then allowed to carry one. Opening the challenge shows possession of the key it was encrypted
+     * to, which sec. 6.7 says is the key in the request; a challenge opened by any other key says
+     * nothing about the key being certified, so it does not stand in for the missing signature. */
+    popProvenRequest = _provesRequestKey(answered.recipientSpki, outgoing) ? outgoingId.bytes : null;
+    guard.list.append(controls, encodeControl(OID_DECRYPTED_POP, [b.sequence([
+      b.integer(BigInt(encodedRequests[0].bodyPartID)),
+      b.raw(answered.algBytes),
+      b.octetString(answered.thePOP),
+    ])], ids));
   }
 
   if (spec.popLink) {
@@ -450,6 +911,27 @@ async function _build(spec, signer, opts) {
       (e && e.message ? e.message : "malformed"), e);
   }
 
+  /** @internal RFC 5272 sec. 3.2 gives a Full PKI Request two carriers, and a request uses one: a
+   * SignedData signed by a key, or an AuthenticatedData whose MAC a shared secret keys. A client
+   * enrolling under a secret has no key to sign with, so naming both is a contradiction rather than a
+   * preference. */
+  if (signer && typeof signer === "object" && !_isArray(signer) && signer.mac != null) {
+    if (signer.key != null || signer.cert != null || signer.spki != null || signer.keyIdentifier != null) {
+      throw E("cmc/bad-input", "a request is carried by a signature or by a shared secret, not both (RFC 5272 sec. 3.2)");
+    }
+    guard.identifier.assertKnownKeys(signer, KNOWN_MAC_CARRIER_KEYS, E, "cmc/bad-input", "unknown shared-secret carrier field ");
+    var macBytes = macPassword(signer.mac);
+    try {
+      await _assertTcrPops(requests, popProvenRequest);
+      /** @internal The Password Recipient Info option, which sec. 3.2(a) requires, is what the CMS
+       * producer selects for a password recipient, and it generates the MAC key sec. 3.2(b) calls for. */
+      return await cmsEncrypt.authenticate(pkiData, [{ password: macBytes }],
+        { contentType: "id-cct-PKIData", pem: opts.pem });
+    } finally {
+      guard.secret.zeroize(macBytes, CmcError, "cmc/bad-input", "the derived shared-secret key");
+    }
+  }
+
   _assertKeyOnlySigner(signer, requests);
 
   var ownedKeyBytes = [];
@@ -459,7 +941,7 @@ async function _build(spec, signer, opts) {
     ownedKeyBytes.length = 0;
   }
   try {
-    await _assertTcrPops(requests);
+    await _assertTcrPops(requests, popProvenRequest);
     return await cmsSign.sign(pkiData, copiedSigner, { eContentType: "id-cct-PKIData", pem: opts.pem });
   } finally {
     _wipeOwnedKeys();
@@ -582,4 +1064,4 @@ function _csrKeyIdentity(csrDer) {
   return { ski: found, spki: (spki && spki.bytes) || null };
 }
 
-module.exports = { build: build };
+module.exports = { build: build, macPassword: macPassword };