@blamejs/pki 0.6.50 → 0.6.52

package/lib/cmp-session.js

@@ -18,6 +18,7 @@ var guard = require("./guard-all");
 var compositeSig = require("./composite-sig");
 var constants = require("./constants");
 var webcrypto = require("./webcrypto");
+var key = require("./key");
 var frameworkError = require("./framework-error");
 var sleepUtil = require("./sleep");
 var retryAfter = require("./http-retry-after");
@@ -53,6 +54,7 @@ var RESUMABLE_ARMS = Object.assign(Object.create(null), { ip: 1, cp: 1, kup: 1 }
 var RESUME_TOKEN_KEYS = Object.assign(Object.create(null), {
   transactionId: 1, recipNonce: 1, certReqId: 1, arm: 1, polls: 1, requestedSpki: 1,
   signer: 1, signerCache: 1, chain: 1, caPubs: 1, nextPollAt: 1, implicitConfirm: 1, protection: 1,
+  centralKeyGeneration: 1,
 });
 var RESUMABLE_PROTECTION = Object.assign(Object.create(null), { signature: 1, mac: 1 });
 
@@ -60,7 +62,8 @@ var KNOWN_SESSION_OPTS = Object.assign(Object.create(null), {
   url: 1, key: 1, cert: 1, mac: 1, trustAnchors: 1, intermediates: 1, recipient: 1, sender: 1,
   extraCerts: 1, implicitConfirm: 1, maxPolls: 1, maxTotalWait: 1, sleep: 1, time: 1,
   transport: 1, tls: 1, headers: 1, timeout: 1, maxResponseBytes: 1, proxy: 1, pss: 1, digestAlgorithm: 1,
-  acceptCert: 1, senderKID: 1, recipKID: 1, expectedSender: 1,
+  acceptCert: 1, senderKID: 1, recipKID: 1, expectedSender: 1, acceptCentralKeyGeneration: 1,
+  authorizedBySharedSecret: 1,
 });
 
 var TRANSCRIPT_RETAIN_RESPONSES = 2;
@@ -87,6 +90,9 @@ var KEM_CIPHERTEXT_ALGORITHMS = Object.assign(Object.create(null));
   KEM_CIPHERTEXT_ALGORITHMS[oid.byName(n)] = n;
 });
 var KNOWN_REVOKE_KEYS = Object.assign(Object.create(null), { certificate: 1, certDetails: 1, reason: 1 });
+/** @internal The keys the CRMF signature proof-of-possession arm takes, which is the only arm a
+ * session sends. A key belonging to another arm names that arm whether or not `type` says so. */
+var SESSION_POP_KEYS = Object.assign(Object.create(null), { type: 1, sender: 1 });
 var RSA_ARCS = ["rsaEncryption", "rsaSignatureWithripemd160", "id-TA-RSA-v1-5-SHA-256",
   "sigS-ISO9796-1-DFUE", "sigS-ISO9796-2Withrsa", "sigS-ISO9796-2rndWithrsa"].map(function (n) {
   return oid.toArcs(oid.byName(n)).slice(0, -1);
@@ -201,8 +207,14 @@ var CAPUBS_MAX = 2 * MAX_EXTRA_CERTS;
 var SESSION_MAX_INTERMEDIATES = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES - CAPUBS_MAX - MAX_EXTRA_CERTS;
 var SESSION_MAX_INTERMEDIATES_MAC = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES - CAPUBS_MAX;
 function _isRecoverableVerify(code) {
+  /** @internal `cmp/bad-sender-kid` belongs here for the same reason `cmp/signer-cert-not-found` does:
+   * a response whose extraCerts carry no certificate matching the declared key identifier is one this
+   * session may already hold the signer for. Retrying is safe because the fallback certificate is put
+   * through the same identifier check, so the retry can only succeed on a certificate the message
+   * actually names. */
   return code === "cmp/signer-cert-not-found" || code === "cmp/protection-failed" ||
-    code === "cmp/sender-mismatch" || code === "cmp/untrusted-signer";
+    code === "cmp/sender-mismatch" || code === "cmp/untrusted-signer" ||
+    code === "cmp/bad-sender-kid";
 }
 function _responseExtraCerts(responseBytes) {
   var extra = schemaCmp.parse(responseBytes).extraCerts;
@@ -335,8 +347,27 @@ function _certConfHash(certDer) {
  * `CertResponse` is the caller's CRMF request id (`request.ir.certReqId`, ...) when supplied, else the
  * single-request default. One transaction per session: a second or concurrent `enroll`, or a batched
  * CRMF request, is refused (a local build error leaves the session retryable). The returned `chain` is the
- * issued leaf plus any authenticated `caPubs` the CA delivered (chain material, never trust anchors); a
- * server-generated (central key generation) private key is out of scope and the grant is refused.
+ * issued leaf plus any authenticated `caPubs` the CA delivered (chain material, never trust anchors).
+ *
+ * Central key pair generation (RFC 9483 sec. 4.1.6) is available under `opts.acceptCentralKeyGeneration`,
+ * for an entity that cannot generate its own key pair. A request in the shape sec. 4.1.6 defines, a
+ * `certTemplate` with no `publicKey` or one whose `subjectPublicKey` is a zero-length BIT STRING,
+ * carries no proof of possession, since this entity holds no key to prove possession of, and goes out
+ * under `cmp2021` because the response will carry an `EnvelopedData` (RFC 9480 sec. 2.20). The session
+ * opens the delivered container with the credential it enrolled under, its private key for the key
+ * transport and key agreement techniques and its shared secret for the password technique, authorizes
+ * the key generation authority against `opts.trustAnchors` at `opts.time`, and surfaces the result on
+ * the verdict as `deliveredKey`. A PBMAC1 session may instead authorize that authority by the secret
+ * that protects its requests, which sec. 4.1.6 permits a MAC-protected exchange, and states so with
+ * `opts.authorizedBySharedSecret`; it is never inferred from an absent `trustAnchors`, since a missing
+ * option would then silently drop both the chain check and the `id-kp-cmKGA` assertion. What binds the grant is then the delivered key rather than a
+ * requested one: the issued certificate MUST certify it, and a grant whose certificate does not is
+ * refused before the `certConf` that would accept it. The package carries exactly one key, which is
+ * what sec. 4.1.6 profiles RFC 5958's `SIZE (1..MAX)` down to, because one grant certifies one key and
+ * every further key would be one the issued certificate says nothing about. Without the option, a
+ * granted `CertResponse` carrying a `privateKey` is refused, and a request that would ask for one is
+ * refused before it is sent. A `poll-timeout` on such a transaction resumes like any other; its `resumeToken` records that
+ * the grant is bound to the delivered key, and a session resuming it must set the option too.
  *
  * `revoke(request)` drives the RFC 9483 sec. 4.2 revocation exchange (`rr` -> `rp`) through the same shell.
  * The request names the certificate, either as `{ certificate }` or as `{ certDetails: { issuer,
@@ -374,6 +405,8 @@ function _certConfHash(certDer) {
  *   - `expectedSender` -- optional CA signer certificate (DER Buffer / PEM string / already-parsed `pki.schema.x509.parse` object); when set, every signed response's authenticated header sender MUST bind to it under the RFC 5280 sec. 7 subject-or-subjectAltName rule cmp.verify uses, so a re-encoded-but-equivalent DN and an empty-subject CA named only by a directoryName SAN both match. Given as bytes/PEM it also resolves a first response that omits its own extraCerts (a CA that assumes the client already holds its certificate). Absent, the session pins the first signed response's signer certificate and requires every later leg's sender to bind to it, rejecting a switch to a different trusted signer while permitting same-identity certificate/key rotation.
  *   - `implicitConfirm` -- request implicit confirmation (skip the certConf leg when the CA grants it).
  *   - `acceptCert` -- an async policy `(certDer, { status, grantedWithMods }) => boolean` consulted before the certConf; return true to accept, anything else to veto (a `grantedWithMods` certificate the CA changed). A veto sends a rejecting certConf and yields `outcome: "rejected"` with the certificate still surfaced. Incompatible with `implicitConfirm` (no reject leg exists), so the combination throws at construction.
+ *   - `acceptCentralKeyGeneration` (boolean) -- accept a key pair the authority generates on this entity's behalf (RFC 9483 sec. 4.1.6). It admits a request that names no key to certify, opens the delivered container with the credential the session enrolled under, and surfaces the result as `deliveredKey` on the issued verdict. The issued certificate must certify the delivered key. Without it, such a request and such a grant are both refused.
+ *   - `authorizedBySharedSecret` (boolean) -- authorize the key generation authority by the secret that protects this session's requests rather than by a chain, which sec. 4.1.6 permits a MAC-protected exchange. PBMAC1 sessions only, and it is the alternative to `opts.trustAnchors` for that authority rather than an addition to it: a delivered key package is authorized one way or the other, and a session accepting central key generation with neither is refused when it is built. It pairs with `opts.trustAnchors`, which on a session also path-validates the issued certificate, a job the exemption does not replace.
  *   - `transport` -- injectable `transport(request) -> Promise<{status, headers, body}>`; default pki.transport.https. It must return a promise of the response; anything else is `cmp/bad-input`.
  *   - `tls` / `headers` / `timeout` / `maxResponseBytes` -- transport config + budgets.
  *   - `proxy` -- reach the CA through a forward HTTP proxy (`{ url, auth?, tls? }`; see pki.transport).
@@ -414,6 +447,24 @@ function session(opts) {
     if (!hasAnchors) throw _err("cmp/bad-input", "signature protection requires opts.trustAnchors to authenticate the CA's response signer (RFC 9483 sec. 3.2)");
   }
   if (isMac && Array.isArray(opts.trustAnchors) && opts.trustAnchors.length === 0) opts.trustAnchors = null;
+  if (opts.acceptCentralKeyGeneration != null && typeof opts.acceptCentralKeyGeneration !== "boolean") {
+    throw _err("cmp/bad-input", "opts.acceptCentralKeyGeneration is a boolean stating that this caller accepts a key pair the authority generated (RFC 9483 sec. 4.1.6)");
+  }
+  if (opts.authorizedBySharedSecret != null && typeof opts.authorizedBySharedSecret !== "boolean") {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret is a boolean stating that this caller authorizes the key generation authority by the secret that protects its requests (RFC 9483 sec. 4.1.6)");
+  }
+  if (opts.authorizedBySharedSecret === true && !isMac) {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret authorizes the key generation authority by the secret that protected the request, so it applies only to a PBMAC1 session (RFC 9483 sec. 4.1.6)");
+  }
+  /** @internal A session that accepts a generated key pair states how it authorizes the authority
+   * that generates one, and a MAC session holding neither anchors nor the exemption states neither.
+   * Every input this needs is here, so it is refused now: the same request refused on the grant would
+   * be refused after the authority had generated and delivered the key, spending the session's one
+   * transaction slot and discarding the delivery, and the retry costs a second key generation. */
+  if (opts.acceptCentralKeyGeneration === true && isMac
+    && opts.trustAnchors == null && opts.authorizedBySharedSecret !== true) {
+    throw _err("cmp/bad-input", "accepting a centrally generated key pair needs opts.trustAnchors to chain the key generation authority, or opts.authorizedBySharedSecret to authorize it by the secret that protects this session's requests (RFC 9483 sec. 4.1.6)");
+  }
   if (opts.trustAnchors != null && _engine && _engine.toAnchor) _asCertList(opts.trustAnchors).forEach(function (a) { try { _engine.toAnchor(a); } catch (e) { throw _err("cmp/bad-input", "opts.trustAnchors: each entry must be a certificate (DER/PEM/parsed) or a { name, publicKey, algorithm } anchor tuple -- " + ((e && e.message) || e), e); } });
   if (opts.intermediates != null && _engine && _engine.coerceCert) _asCertList(opts.intermediates).forEach(function (c) { try { _engine.coerceCert(c); } catch (e) { throw _err("cmp/bad-input", "opts.intermediates: each entry must be a certificate (DER/PEM/parsed) -- " + ((e && e.message) || e), e); } });
   var _proxySnap = httpTransport.snapshotProxy(opts.proxy);
@@ -466,6 +517,10 @@ function session(opts) {
   var expectedInfoOp = null;
   var crlQuery = null;
   var requestedSpki = null;
+  /** @internal Whether the request this session sent asked the authority to generate the key pair. It
+   * decides what binds the grant: a key this entity already holds, or the delivered private key the
+   * grant arrives with (RFC 9483 sec. 4.1.6). */
+  var centralKeyGeneration = false;
   /** @internal What the request asked for, not what this session was configured with. A resumed poll
    * finishes a transaction whose confirmation was negotiated in a request an earlier process sent, so
    * the grant is confirmed the way that request asked and not the way this session's options read. */
@@ -514,6 +569,12 @@ function session(opts) {
     }
     h.sender = opts.sender != null ? opts.sender : defaultSender;
     h.recipient = opts.recipient != null ? opts.recipient : NULL_DN;
+    /** @internal RFC 9480 sec. 2.20 needs cmp2021 whenever an exchange uses EnvelopedData, "for the
+     * request being sent or for the expected response". A central key generation transaction expects
+     * one on its grant, so every message in it carries the version, not only the initial request whose
+     * body triggers it: a poll asking for that grant expects the EnvelopedData just as the request
+     * did, and a resumed poll is the same transaction in a later process. */
+    if (centralKeyGeneration) h.pvno = 3;
     if (opts.senderKID != null) h.senderKID = opts.senderKID;
     if (opts.recipKID != null) h.recipKID = opts.recipKID;
     return h;
@@ -756,6 +817,12 @@ function session(opts) {
        * this transaction has to authenticate it the way the transaction already does. */
       protection: isSig ? "signature" : "mac",
       requestedSpki: requestedSpki ? Buffer.from(requestedSpki).toString("base64") : null,
+      /** @internal What the grant is held to, when it is not a key this entity already holds. A
+       * central key generation request names no key to certify (RFC 9483 sec. 4.1.6), so the binding
+       * is the delivered private key the grant arrives with, and the resumed poll applies it the way
+       * the first process would have. Recorded so a resumed session cannot silently drop to no
+       * binding at all. */
+      centralKeyGeneration: centralKeyGeneration,
       /** @internal The identity the first process pinned on the first response it verified. Restoring it
        * is what keeps a restart from admitting a DIFFERENT trusted signer, which an uninterrupted
        * transaction refuses (RFC 9483 sec. 3.1), and it carries the certificate a responder that sent
@@ -826,7 +893,9 @@ function session(opts) {
     var ckp = resp && resp.certifiedKeyPair;
     var cert = ckp && ckp.certificate;
     if (!Buffer.isBuffer(cert)) throw _err("cmp/unexpected-arm", "a granted CertResponse carried no plain issued certificate (an encryptedCert form is out of enrollment v1 scope) (RFC 9810 sec. 5.3.4)");
-    if (ckp.privateKey != null) throw _err("cmp/unexpected-arm", "a granted CertResponse carried a server-generated privateKey (central key generation is out of enrollment v1 scope; a session enrolls a client-generated key) (RFC 9810 sec. 5.3.4)");
+    if (ckp.privateKey != null && !opts.acceptCentralKeyGeneration) {
+      throw _err("cmp/unexpected-arm", "a granted CertResponse carried a server-generated privateKey; accepting a key this entity did not generate is a decision the caller states with opts.acceptCentralKeyGeneration (RFC 9483 sec. 4.1.6)");
+    }
     var parsed;
     try { parsed = x509.parse(cert); }
     catch (e) { throw _err("cmp/bad-cert-response", "the granted CertResponse's certificate is not a valid X.509 certificate", e); }
@@ -841,6 +910,41 @@ function session(opts) {
     return cert;
   }
 
+  /** @internal The two shapes RFC 9483 sec. 4.1.6 gives a request for a centrally generated key: no
+   * publicKey at all, or one carrying an algorithm preference over a zero-length subjectPublicKey. A
+   * publicKey that is present and carries key bits is an ordinary request for a key this entity
+   * already holds. */
+  function _requestsCentralKeyGeneration(armSpec) {
+    if (!armSpec || typeof armSpec !== "object" || Buffer.isBuffer(armSpec)) return false;
+    var pk = armSpec.certTemplate ? armSpec.certTemplate.publicKey : null;
+    if (pk == null) return true;
+    if (!guard.bytes.isByteSource(pk)) return false;
+    var bits;
+    try { bits = asn1.read.bitString(asn1.decode(guard.bytes.view(pk, CmpError, "cmp/bad-input", "the certTemplate publicKey")).children[1]); }
+    catch (_e) { return false; }
+    return bits.bytes.length === 0;
+  }
+
+  /** @internal One copy of the caller's arm, and of the `certTemplate` inside it, so every check below
+   * and the message that goes on the wire read the same values. A `p10cr` arm is a byte source rather
+   * than a record, and is left to the builder's own snapshot. */
+  function _snapshotArm(armSpec) {
+    if (!_isRecord(armSpec)) return armSpec;
+    var copy = Object.assign({}, armSpec);
+    if (_isRecord(copy.certTemplate)) copy.certTemplate = Object.assign({}, copy.certTemplate);
+    /** @internal The proof of possession is copied for the same reason the template is: the session
+     * decides on `pop.type` which modes it will send, and a field answering one way to that decision
+     * and another to the builder would put a request on the wire in a mode the session refused. */
+    if (_isRecord(copy.pop)) copy.pop = Object.assign({}, copy.pop);
+    return copy;
+  }
+  /** @internal A record the session copies field by field, as opposed to a byte source, which every
+   * byte-taking door snapshots whole. A `p10cr` arm is a CertificationRequest in any of the shapes
+   * `guard.bytes` accepts, and copying one field by field would leave a plain object of indices. */
+  function _isRecord(v) {
+    return !!v && typeof v === "object" && !guard.bytes.isByteSource(v);
+  }
+
   function _extractRequestedSpki(arm, armSpec) {
     if (arm === "p10cr") {
       if (!guard.bytes.isByteSource(armSpec)) return null;
@@ -869,8 +973,97 @@ function session(opts) {
     if (!res || res.valid !== true) throw _err("cmp/bad-cert-response", "the issued certificate did not validate to a supplied trust anchor (its signature or chain is invalid) (RFC 5280 sec. 6.1)");
   }
 
+  /** @internal RFC 9483 sec. 4.1.6: the key management technique that protected the content-encryption
+   * key follows the protection of the REQUEST, so the session opens the container with the credential
+   * it enrolled under and no other. A signature session holds a private key and reaches a key
+   * transport or key agreement container (sec. 4.1.6.1, sec. 4.1.6.2); a MAC session holds the shared
+   * secret and reaches a password container (sec. 4.1.6.3). A container built for the other technique
+   * does not open, which is the rule enforcing itself. */
+  /** @internal A session certificate option takes DER, PEM, or an already-parsed certificate, and the
+   * path builder reads all three; `opts.trustAnchors` additionally takes a `{ name, publicKey,
+   * algorithm }` tuple. Both pools are forwarded to `pki.cmp.openKeyPackage`, which takes bytes, so a
+   * parsed certificate is handed on as the bytes it was parsed from rather than lost on the way: a
+   * certificate that goes missing makes the authority's chain unbuildable and reads as an unauthorized
+   * authority. An anchor tuple is passed through, since it is what the anchor form is; anything else
+   * is named here, because the certificate pool is the one place a value is dropped rather than
+   * refused. */
+  function _asOpenableCerts(v, label, allowAnchorTuple) {
+    return _asCertList(v).map(function (c, i) {
+      if (typeof c === "string" || guard.bytes.isByteSource(c)) return c;
+      var der = guard.parsed.sourceOf(c);
+      if (der != null) return der;
+      if (allowAnchorTuple && _isRecord(c)) return c;
+      throw _err("cmp/bad-input", label + "[" + i + "] is a parsed certificate this session cannot hand on as bytes; supply it as DER or PEM");
+    });
+  }
+
+  async function _openDeliveredKey(ckp) {
+    /** @internal A transaction that asked the authority to generate the key pair is bound to the key
+     * it delivers, and to nothing else: no requested public key was submitted for the grant to be
+     * held to. A grant carrying only a certificate would therefore be confirmed with nothing checked,
+     * and the entity would hold a certificate for a private key it never received. */
+    if (ckp.privateKey == null && centralKeyGeneration) {
+      throw _err("cmp/bad-cert-response", "this transaction asked the authority to generate the key pair, and the granted CertResponse carries no privateKey -- there is no key to go with the issued certificate, and nothing the grant is bound to (RFC 9483 sec. 4.1.6)");
+    }
+    if (ckp.privateKey == null) return null;
+    /** @internal The sec. 4.1.6 exemption is what the CALLER said, never what this session inferred
+     * from its own configuration. Reading it off an absent `trustAnchors` would turn a missing option
+     * into a decision to authorize the key generation authority by the shared secret alone, silently
+     * dropping both the chain check and the id-kp-cmKGA assertion. `pki.cmp.openKeyPackage` requires
+     * the statement, so a session that inferred it would admit containers the verb refuses. The verb's
+     * own door decides: one of the two rules, never neither and never both. */
+    var open = opts.mac != null
+      ? { password: opts.mac.secret, authorizedBySharedSecret: opts.authorizedBySharedSecret === true }
+      : { key: opts.key, cert: opts.cert };
+    /** @internal On a session `opts.trustAnchors` does two jobs: it authorizes the key generation
+     * authority, and it path-validates the issued certificate. The exemption replaces the first job
+     * only, so the anchors are withheld from the verb, whose door knows the first job alone and
+     * refuses the pair, and they keep the second. A caller therefore states both options to authorize
+     * the authority by the secret and still chain the certificate it was issued. */
+    if (opts.trustAnchors != null && !open.authorizedBySharedSecret) {
+      open.trustAnchors = _asOpenableCerts(opts.trustAnchors, "opts.trustAnchors", true);
+      if (opts.intermediates != null) open.intermediates = _asOpenableCerts(opts.intermediates, "opts.intermediates", false);
+    }
+    /** @internal The instant the session validates every other certificate at governs the authority's
+     * chain too, so a historical enrollment does not judge one certificate at a stated time and
+     * another at the current one. */
+    if (opts.time != null) open.time = opts.time;
+    if (ckp.privateKey.bytes == null) {
+      throw _err("cmp/bad-key-package", "a delivered key package is carried as an EnvelopedData, and this grant carries the legacy RFC 4211 EncryptedValue form (RFC 9483 sec. 4.1.6, RFC 9810 sec. 5.2.2)");
+    }
+    return cmp.openKeyPackage(ckp.privateKey.bytes, open);
+  }
+
+  /** @internal A centrally generated key and the certificate granted alongside it are one pair, and
+   * only the caller can tell: the authority's signature says the key package is authentic, and says
+   * nothing about which certificate it belongs with. An unbound pair confirms an enrollment whose
+   * certificate certifies a key this entity does not hold, so the two are compared here, before the
+   * certConf that accepts the grant (RFC 9483 sec. 4.1.6). */
+  async function _assertDeliveredKeyCertified(deliveredKey, leaf) {
+    /** @internal RFC 9483 sec. 4.1.6 gives the eContent "a sequence of one OneAsymmetricKey element",
+     * and here that count is what the grant is bound to rather than a matter of form: one grant
+     * certifies one key, so every further key in the package is one the issued certificate says
+     * nothing about and this entity would hold uncertified. The standalone `pki.cmp.openKeyPackage`
+     * surfaces a whole RFC 5958 package, which is SIZE (1..MAX), and leaves the binding to its caller;
+     * a session performs the sec. 4.1.6 enrollment, so it holds the profile's count. */
+    if (deliveredKey.keys.length !== 1) {
+      throw _err("cmp/bad-key-package", "a delivered key package carries one key, and this one carries " +
+        deliveredKey.keys.length + "; the issued certificate certifies one of them and says nothing about the rest (RFC 9483 sec. 4.1.6)");
+    }
+    var certified, pair;
+    try { certified = x509.parse(leaf).subjectPublicKeyInfo.bytes; }
+    catch (e) { throw _err("cmp/bad-cert-response", "the issued certificate's public key cannot be compared with the delivered key", e); }
+    try { pair = await key.correspondsTo(deliveredKey.keys[0], certified); }
+    catch (e) { throw _err("cmp/bad-key-package", "the delivered private key and the issued certificate could not be exercised together, so the two cannot be shown to be a pair", e); }
+    if (!pair) {
+      throw _err("cmp/bad-key-package", "the issued certificate does not certify the delivered private key -- the two are not a pair, so the certificate is unusable with the key this enrollment received (RFC 9483 sec. 4.1.6)");
+    }
+  }
+
   async function _finish(granted, header) {
     var leaf = _leafOf(granted.resp);
+    var deliveredKey = await _openDeliveredKey(granted.resp.certifiedKeyPair);
+    if (deliveredKey !== null) await _assertDeliveredKeyCertified(deliveredKey, leaf);
     var chain = [leaf], seenChain = Object.create(null);
     caPubsAccum.forEach(function (c) {
       if (!Buffer.isBuffer(c)) return;
@@ -891,13 +1084,21 @@ function session(opts) {
     return _terminal("issued", {
       certificate: certOut, chain: chainOut, status: _statusOf(granted.resp),
       confirmed: conf.confirmed, implicitConfirm: conf.implicit, polls: granted.polls || 0,
+      deliveredKey: deliveredKey,
     });
   }
 
+  /** @internal Claim the session's one transaction slot. It is claimed BEFORE the caller's request
+   * object is read, because reading one runs whatever accessors it carries and an accessor can call
+   * back into this session: a slot claimed only after validation would let the re-entrant call open a
+   * transaction that the outer call then writes its own state over. Every entry point pairs this with
+   * a `finally` that releases the slot, so a request refused during validation leaves the session
+   * retryable exactly as it did before. */
   function _assertFresh(what) {
     if (completed || inFlight) {
       throw _err("cmp/bad-input", "this pki.cmp.session transaction is already " + (completed ? "completed" : "in flight") + "; create a new session per " + what + " (RFC 9810 sec. 5.1.1: one transactionID per transaction)");
     }
+    inFlight = true;
   }
 
   async function _runOneShot(bodySpec, arm, kind) {
@@ -918,51 +1119,101 @@ function session(opts) {
 
   async function enroll(request) {
     _assertFresh("enrollment");
+    try { return await _enroll(request); }
+    finally {
+      inFlight = false;
+      completed = started;
+    }
+  }
+
+  async function _enroll(request) {
     guard.identifier.assertPlainRecord(request, _err, "cmp/bad-input", "enroll(request), a body spec { ir | cr | kur | p10cr },");
+    /** @internal The request's own door, rather than the builder's arm count downstream: the session
+     * sends the ONE arm it read out of this object, so a key the session does not recognize would
+     * otherwise be dropped silently instead of naming the caller's mistake. */
+    guard.identifier.assertKnownKeys(request, ENROLL_ARMS, _err, "cmp/bad-input", "unknown enroll request field ");
     var arms = Object.keys(request).filter(function (k) { return request[k] != null; });
     if (arms.length !== 1 || !ENROLL_ARMS[arms[0]]) {
       throw _err("cmp/bad-input", "enroll(request) must carry EXACTLY ONE enrollment arm (ir / cr / kur / p10cr)");
     }
-    var armSpec = request[arms[0]];
+    /** @internal The arm is copied out of the caller's object ONCE, and everything after this reads and
+     * sends the copy. A request object can carry accessors, so reading a field twice can get two
+     * answers: the request that goes on the wire has to be the one the checks below were applied to,
+     * or a second answer could turn a validated client-generated enrollment into a central key
+     * generation request the session never admitted. The certTemplate is copied for the same reason,
+     * since the field that decides which of the two this is lives in it. */
+    var armSpec = _snapshotArm(request[arms[0]]);
     if (armSpec && typeof armSpec === "object" && !Buffer.isBuffer(armSpec) && armSpec.messages != null) {
       throw _err("cmp/bad-input", "a batched CRMF request ({ messages: [...] }) is not supported by a session -- submit one certificate request per pki.cmp.session");
     }
     var reqSpki = _extractRequestedSpki(arms[0], armSpec);
-    if (arms[0] !== "p10cr" && reqSpki == null) {
-      throw _err("cmp/bad-input", "an ir / cr / kur enrollment must submit certTemplate.publicKey -- a session enrolls a client-generated key (a raVerified keyless request or central key generation is not supported)");
-    }
-    if (arms[0] !== "p10cr" && armSpec != null && armSpec.pop != null && armSpec.pop.type != null && armSpec.pop.type !== "signature") {
-      throw _err("cmp/bad-input", "a session ir / cr / kur proves possession by signing the CRMF proof of possession; a non-signature POP mode (" + guard.text.showValue(armSpec.pop.type) + ") is not supported (RFC 4211 sec. 4)");
+    /** @internal RFC 9483 sec. 4.1.6: an entity requesting central key generation "MUST omit the
+     * publicKey field from the certTemplate or ... fill the subjectPublicKey sub-field with a
+     * zero-length BIT STRING", and the popo "MUST be absent". A request in that shape asks the
+     * authority to generate the key, so it is admitted only when the caller has said it accepts one. */
+    var central = arms[0] !== "p10cr" && _requestsCentralKeyGeneration(armSpec);
+    if (central && !opts.acceptCentralKeyGeneration) {
+      throw _err("cmp/bad-input", "this request asks the authority to generate the key pair (RFC 9483 sec. 4.1.6: a certTemplate with no publicKey, or a zero-length subjectPublicKey); accepting a key this entity did not generate is a decision the caller states with opts.acceptCentralKeyGeneration");
+    }
+    if (arms[0] !== "p10cr" && reqSpki == null && !central) {
+      throw _err("cmp/bad-input", "an ir / cr / kur enrollment must submit certTemplate.publicKey -- a session enrolls a client-generated key unless the request asks for central key generation (RFC 9483 sec. 4.1.6) and opts.acceptCentralKeyGeneration is set");
+    }
+    if (central && armSpec.pop != null) {
+      throw _err("cmp/bad-input", "a central key generation request carries no proof of possession, since this entity holds no key to prove possession of (RFC 9483 sec. 4.1.6)");
+    }
+    /** @internal A session sends the signature proof of possession and no other, so the arm is read
+     * the way the builder reads it rather than from `type` alone. `pop: { raVerified: true }` names
+     * the raVerified arm without stating a type, and a door that asked only about `type` would pass
+     * it through to be refused downstream, after the request had been assembled. */
+    if (arms[0] !== "p10cr" && armSpec != null && _isRecord(armSpec.pop)) {
+      var popType = armSpec.pop.type;
+      if (popType != null && popType !== "signature") {
+        throw _err("cmp/bad-input", "a session ir / cr / kur proves possession by signing the CRMF proof of possession; a non-signature POP mode (" + guard.text.showValue(popType) + ") is not supported (RFC 4211 sec. 4)");
+      }
+      guard.identifier.assertKnownKeys(armSpec.pop, SESSION_POP_KEYS, _err, "cmp/bad-input",
+        "a session ir / cr / kur proves possession by signing the CRMF proof of possession, so its `pop` names the signature arm only: ");
     }
-    if (isMac && arms[0] !== "p10cr" && (armSpec == null || armSpec.key == null)) {
+    if (isMac && arms[0] !== "p10cr" && !central && (armSpec == null || armSpec.key == null)) {
       throw _err("cmp/bad-input", "a MAC-protected ir / cr / kur must carry the requested key's private half as `key` for the CRMF proof of possession -- a signature session reuses opts.key, but a PBMAC1 session has no signing key, so the request would carry no proof of possession (RFC 4211 sec. 4)");
     }
-    inFlight = true;
-    try {
-      txnKind = "enroll";
-      expectedRespArm = RESPONSE_ARM[arms[0]];
-      var cid = (typeof armSpec === "object" && !Buffer.isBuffer(armSpec)) ? armSpec.certReqId : undefined;
-      activeCertReqId = _normalizeCertReqId(cid, arms[0] === "p10cr" ? P10CR_CERT_REQ_ID : DEFAULT_CERT_REQ_ID);
-      requestedSpki = reqSpki;
-      var initial = await _send(request, arms[0]);
-      var t = _classify(initial);
-      var grantHeader = initial.header;
-      var pollCount = 0;
-      if (t.state === "waiting") {
-        var polled = await _pollLoop(t.resp);
-        pollCount = polled.polls;
-        if (polled.timeout) return _terminal("poll-timeout", { status: polled.status, polls: pollCount, resumeToken: _resumeToken(pollCount, _pollDueAt(polled.dueIn)) });
-        t = polled.done;
-        grantHeader = polled.header;
-        t.polls = pollCount;
-      }
-      if (t.state === "granted") { var r = await _finish({ resp: t.resp, polls: pollCount, code: t.code }, grantHeader); r.polls = pollCount; return r; }
-      if (t.state === "rejected") return _terminal("rejected", { status: t.status || _statusOf(t.resp), polls: pollCount });
-      throw _err("cmp/unexpected-arm", t.reason || "the enrollment transaction reached an unexpected state");
-    } finally {
-      inFlight = false;
-      completed = started;
+    /** @internal Everything this request contributes is read out of the caller's object HERE, while no
+     * session state has been written. Reading an object a caller supplied runs whatever accessors it
+     * carries, and one of those can call back into this session; a write placed among those reads
+     * would let the re-entrant call and this one interleave and leave the two variables that bind the
+     * grant, `centralKeyGeneration` and `requestedSpki`, describing different transactions. */
+    var cid = (typeof armSpec === "object" && !Buffer.isBuffer(armSpec)) ? armSpec.certReqId : undefined;
+    var certReqId = _normalizeCertReqId(cid, arms[0] === "p10cr" ? P10CR_CERT_REQ_ID : DEFAULT_CERT_REQ_ID);
+    /** @internal A central key generation request carries no proof of possession at all, so the arm
+     * names a null key to stop `pki.cmp.build` falling back to the message protection key. */
+    if (central) armSpec.key = null;
+    var sendSpec = Object.create(null);
+    sendSpec[arms[0]] = armSpec;
+
+    txnKind = "enroll";
+    expectedRespArm = RESPONSE_ARM[arms[0]];
+    activeCertReqId = certReqId;
+    /** @internal The pair is installed together, from this request alone. A session whose earlier
+     * enroll failed while building is still retryable, so a retry that submits an ordinary
+     * client-generated key must not carry the earlier request's binding into its own transaction:
+     * the zero-length subjectPublicKey form names an algorithm preference and not a key to certify,
+     * so a central request is bound to the delivered private key instead. */
+    centralKeyGeneration = central;
+    requestedSpki = central ? null : reqSpki;
+    var initial = await _send(sendSpec, arms[0]);
+    var t = _classify(initial);
+    var grantHeader = initial.header;
+    var pollCount = 0;
+    if (t.state === "waiting") {
+      var polled = await _pollLoop(t.resp);
+      pollCount = polled.polls;
+      if (polled.timeout) return _terminal("poll-timeout", { status: polled.status, polls: pollCount, resumeToken: _resumeToken(pollCount, _pollDueAt(polled.dueIn)) });
+      t = polled.done;
+      grantHeader = polled.header;
+      t.polls = pollCount;
     }
+    if (t.state === "granted") { var r = await _finish({ resp: t.resp, polls: pollCount, code: t.code }, grantHeader); r.polls = pollCount; return r; }
+    if (t.state === "rejected") return _terminal("rejected", { status: t.status || _statusOf(t.resp), polls: pollCount });
+    throw _err("cmp/unexpected-arm", t.reason || "the enrollment transaction reached an unexpected state");
   }
 
   /** @internal The state a poll-timeout handed the caller, read back. It is the caller's own record of
@@ -982,7 +1233,7 @@ function session(opts) {
       arm: token.arm, polls: token.polls, requestedSpki: token.requestedSpki, signer: token.signer,
       signerCache: token.signerCache, chain: token.chain, caPubs: token.caPubs,
       nextPollAt: token.nextPollAt, implicitConfirm: token.implicitConfirm,
-      protection: token.protection,
+      protection: token.protection, centralKeyGeneration: token.centralKeyGeneration,
     };
     var txn = _hexField(raw.transactionId, "transactionId");
     /** @internal The width a first message opens a transaction with (RFC 9483 sec. 3.1), which is the
@@ -1029,14 +1280,23 @@ function session(opts) {
      * field must not drop the check that field feeds, so the two that bind the transaction are required:
      * the key the grant is held to, and, for a signature session, the identity every response is held
      * to. A shared-secret session pins no certificate, and its secret is the binding instead. */
-    if (raw.requestedSpki == null) {
-      throw _err("cmp/bad-input", "the resumeToken requestedSpki must name the key the granted certificate certifies -- without it the grant would be bound to nothing");
+    var wasCentral = raw.centralKeyGeneration === true;
+    if (wasCentral && !opts.acceptCentralKeyGeneration) {
+      throw _err("cmp/bad-input", "the resumeToken continues a central key generation transaction, so the session resuming it must also set opts.acceptCentralKeyGeneration (RFC 9483 sec. 4.1.6)");
+    }
+    if (raw.requestedSpki == null && !wasCentral) {
+      throw _err("cmp/bad-input", "the resumeToken requestedSpki must name the key the granted certificate certifies -- without it the grant would be bound to nothing, unless the transaction requested central key generation, where the delivered key is the binding");
     }
-    var spki = _b64Field(raw.requestedSpki, "requestedSpki", CERT_MAX_BYTES);
+    if (raw.requestedSpki != null && wasCentral) {
+      throw _err("cmp/bad-input", "the resumeToken names both a requested key and central key generation; a transaction is bound one way or the other, not both");
+    }
+    var spki = wasCentral ? null : _b64Field(raw.requestedSpki, "requestedSpki", CERT_MAX_BYTES);
     /** @internal Read at the door, not when the grant arrives: stored state that is not a public key
      * would otherwise advance the exchange with the authority before it was found to be unusable. */
-    try { _spkiKeyIdentity(spki); }
-    catch (e) { throw _err("cmp/bad-input", "the resumeToken requestedSpki is not a SubjectPublicKeyInfo", e); }
+    if (spki !== null) {
+      try { _spkiKeyIdentity(spki); }
+      catch (e) { throw _err("cmp/bad-input", "the resumeToken requestedSpki is not a SubjectPublicKeyInfo", e); }
+    }
     var signer = null;
     if (raw.signer != null) signer = _certField(raw.signer, "signer", CERT_MAX_BYTES);
     else if (isSig) {
@@ -1078,7 +1338,7 @@ function session(opts) {
       throw _err("cmp/bad-input", "the resumeToken nextPollAt must be the instant the next poll is due, in milliseconds since the epoch");
     }
     return { transactionID: txn, recipNonce: nonce, certReqId: certReqId, arm: arm,
-      implicitConfirm: implicitConfirm,
+      implicitConfirm: implicitConfirm, centralKeyGeneration: wasCentral,
       polls: polls || 0, requestedSpki: spki, signer: signer, signerCache: signerCache,
       chain: chain, caPubs: caPubs,
       nextPollAt: nextPollAt != null ? nextPollAt : null };
@@ -1133,8 +1393,9 @@ function session(opts) {
    * number of processes. */
   async function resumePoll(token) {
     _assertFresh("resumed poll");
-    var t = _readResumeToken(token);
-    inFlight = true;
+    var t;
+    try { t = _readResumeToken(token); }
+    catch (e) { inFlight = false; completed = started; throw e; }
     try {
       txnKind = "enroll";
       /** @internal Installing the restored state consumes the session, whether or not a request follows:
@@ -1147,6 +1408,7 @@ function session(opts) {
       activeCertReqId = t.certReqId;
       expectedRespArm = t.arm;
       requestedSpki = t.requestedSpki;
+      centralKeyGeneration = t.centralKeyGeneration;
       requestedImplicitConfirm = t.implicitConfirm;
       /** @internal Restoring the pinned identity is what makes a restart no weaker than staying in one
        * process: the resumed responses are held to the signer the first process authenticated, and the
@@ -1242,6 +1504,14 @@ function session(opts) {
   
   async function revoke(request) {
     _assertFresh("revocation");
+    try { return await _revoke(request); }
+    finally {
+      inFlight = false;
+      completed = started;
+    }
+  }
+
+  async function _revoke(request) {
     guard.identifier.assertPlainRecord(request, _err, "cmp/bad-input", "revoke(request), an object { certificate | certDetails, reason? },");
     guard.identifier.assertKnownKeys(request, KNOWN_REVOKE_KEYS, _err, "cmp/bad-input", "unknown revoke request field ");
     if (isMac) throw _err("cmp/bad-input", "a PBMAC1 session cannot revoke: the request must be signature-protected with the certificate being revoked (RFC 9483 sec. 4.2). Use a signature session ({ key, cert }).");
@@ -1272,29 +1542,31 @@ function session(opts) {
     }
     var own = _assertRevokingOwnCertificate(certTemplateDer);
     var body = { rr: [{ certDetails: certTemplateDer, crlEntryDetails: { reason: reasonArg == null ? undefined : reasonArg } }] };
-    inFlight = true;
-    try {
-      var out = await _runOneShot(body, "rr", "revoke");
-      if (out.timeout) return _terminal("poll-timeout", { status: out.status, polls: out.polls });
-      var t = out.done;
-      if (t.state === "granted") {
-        return _terminal("revoked", {
-          status: t.status, polls: out.polls,
-          revokedCerts: _bindRevCerts(t.revCerts, own),
-          crls: (t.crls || []).map(_asCrl),
-        });
-      }
-      if (t.state === "rejected") return _terminal("rejected", { status: t.status || null, polls: out.polls });
-      throw _err("cmp/unexpected-arm", t.reason || "the revocation transaction reached an unexpected state");
-    } finally {
-      inFlight = false;
-      completed = started;
+    var out = await _runOneShot(body, "rr", "revoke");
+    if (out.timeout) return _terminal("poll-timeout", { status: out.status, polls: out.polls });
+    var t = out.done;
+    if (t.state === "granted") {
+      return _terminal("revoked", {
+        status: t.status, polls: out.polls,
+        revokedCerts: _bindRevCerts(t.revCerts, own),
+        crls: (t.crls || []).map(_asCrl),
+      });
     }
+    if (t.state === "rejected") return _terminal("rejected", { status: t.status || null, polls: out.polls });
+    throw _err("cmp/unexpected-arm", t.reason || "the revocation transaction reached an unexpected state");
   }
 
   
   async function info(request) {
     _assertFresh("support message");
+    try { return await _info(request); }
+    finally {
+      inFlight = false;
+      completed = started;
+    }
+  }
+
+  async function _info(request) {
     guard.identifier.assertPlainRecord(request, _err, "cmp/bad-input", "info(request), an object naming one support operation (caCerts / rootCaCert / certReqTemplate / crlUpdate),");
     guard.identifier.assertKnownKeys(request, INFO_OPS, _err, "cmp/bad-input", "unknown info request field ");
     var keys = Object.keys(request), names = [], values = [];
@@ -1321,31 +1593,25 @@ function session(opts) {
       crlQuery = { issuerName: built.issuerName, thisUpdate: built.thisUpdate, dpn: built.dpn };
     }
     expectedInfoOp = op;
-    inFlight = true;
-    try {
-      var out = await _runOneShot({ genm: [itav] }, "genm", "info");
-      if (out.timeout) return _terminal("poll-timeout", { operation: op.name, status: out.status, polls: out.polls });
-      var t = out.done;
-      if (t.state === "granted") {
-        var raw = t.itav.value;
-        var value = null;
-        if (raw != null) {
-          try {
-            value = schemaCmp[op.read](raw);
-          } catch (e) {
-            if (e && e.isCmpError) throw e;
-            throw _err("cmp/bad-info-value", "the " + op.name + " response value is malformed -- " + ((e && e.message) || e), e);
-          }
-          value = await _checkInfoValue(op, value, itav.infoValue);
+    var out = await _runOneShot({ genm: [itav] }, "genm", "info");
+    if (out.timeout) return _terminal("poll-timeout", { operation: op.name, status: out.status, polls: out.polls });
+    var t = out.done;
+    if (t.state === "granted") {
+      var raw = t.itav.value;
+      var value = null;
+      if (raw != null) {
+        try {
+          value = schemaCmp[op.read](raw);
+        } catch (e) {
+          if (e && e.isCmpError) throw e;
+          throw _err("cmp/bad-info-value", "the " + op.name + " response value is malformed -- " + ((e && e.message) || e), e);
         }
-        return _terminal("answered", { operation: op.name, present: raw != null, value: value, status: null, polls: out.polls });
+        value = await _checkInfoValue(op, value, itav.infoValue);
       }
-      if (t.state === "rejected") return _terminal("rejected", { operation: op.name, status: t.status || null, polls: out.polls });
-      throw _err("cmp/unexpected-arm", t.reason || "the support-message transaction reached an unexpected state");
-    } finally {
-      inFlight = false;
-      completed = started;
+      return _terminal("answered", { operation: op.name, present: raw != null, value: value, status: null, polls: out.polls });
     }
+    if (t.state === "rejected") return _terminal("rejected", { operation: op.name, status: t.status || null, polls: out.polls });
+    throw _err("cmp/unexpected-arm", t.reason || "the support-message transaction reached an unexpected state");
   }
 
   function _checkInfoValue(op, value, requestValue) {
@@ -1568,6 +1834,7 @@ module.exports = {
   transfer: cmp.transfer,
   wellKnownUrl: cmp.wellKnownUrl,
   verify: cmp.verify,
+  openKeyPackage: cmp.openKeyPackage,
   session: session,
   setEngine: setEngine,   // @internal
 };