CMP (Certificate Management Protocol, RFC 4210)

The RFC 9810 Certificate Management Protocol producing side. pki.cmp.build assembles a PKIMessage: a PKIHeader (sender / recipient / transaction metadata), a PKIBody carrying one request or transaction (an ir / cr / kur certificate request via pki.crmf.build, a p10cr PKCS#10 via pki.csr.sign, a certConf / pollReq / genm / rr, or a nested wrapper of other PKIMessages an RA forwards), and an optional PKIProtection computed over the message. Protection is a signature under the sender key (any registry algorithm), a PBMAC1 shared-secret MAC, or a KEM-based MAC keyed by a secret the peer encapsulated to the sender's ML-KEM key. The emitted message round-trips through pki.schema.cmp.parse and its protection verifies. pki.cmp.transfer carries a message to a CMP endpoint (RFC 9811), pki.cmp.verify checks an incoming message's protection, and pki.cmp.session drives a full enrollment transaction end to end over these. Parsing lives at pki.schema.cmp.parse.

pki.cmp.build(message, opts?) -> Promise<Buffer|string>

- `key` (Buffer|CryptoKey) + `cert` (Buffer): signature protection under the sender key; `cert` is
  the signer certificate (its SPKI resolves the algorithm) and is placed in `extraCerts`.
- `mac` ({ secret, salt?, iterationCount?, prf?, keyLength? }): PBMAC1 protection from a shared secret.
- `kem` ({ key, ciphertext, kemAlgorithm, kemContext?, transactionID?, len? }): KEM-based MAC
  protection (RFC 9810 sec. 5.1.3.4), for a sender whose key establishes secrets rather than
  signing. `key` is the KEM private key as a CryptoKey (what `pki.key.generate` returns), a
  PKCS#8 DER Buffer / Uint8Array, or a PEM string. `ciphertext` is what the peer encapsulated to
  it, `kemAlgorithm` names the ML-KEM
  parameter set it was produced under, and the derived key is bound to `transactionID` (this
  message's, unless the ciphertext arrived under another) and any `kemContext`.
- `extraCerts` (array of Buffer): additional certificates to carry in `extraCerts [1]`.
- `pem` (boolean|string): return a PEM `CMP` block instead of DER.
- `pss` (boolean) / `digestAlgorithm` (string): signature-protection algorithm options.

async function example() {
  var pair = await pki.key.generate("Ed25519");
  var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
  var signerCertDer = await pki.x509.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey),
    notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  var csrDer = await pki.csr.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey) },
    { key: signerKeyPkcs8 });
  var der = await pki.cmp.build(
    { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
      body: { p10cr: csrDer } },
    { key: signerKeyPkcs8, cert: signerCertDer });
  pki.schema.cmp.parse(der).body.arm;   // "p10cr"
}
example();

pki.cmp.transfer(url, message, opts?) -> Promise<{ response, responseBytes, status, contentType, tls }>

- `transport` -- an injectable `transport(request) -> Promise<{status,headers,body}>` (default
  `pki.transport.https`, which fail-closes on a non-https URL and an unpinned server).
- `tls` -- `{ anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }` for the
  default transport (mutual-TLS `cert`/`key` is common for CMP in addition to message protection).
- `headers` -- extra request headers. The `content-type: application/pkixcmp` is always set and not
  overridable (any casing), and the request-framing headers (`content-length`, `transfer-encoding`) are
  stripped -- the transport computes Content-Length from the exact body, so a caller cannot desync framing.
- `timeout` -- ms (default 30s); `maxResponseBytes` -- streaming cap, tightenable downward only.
- `proxy` -- reach the CA through a forward HTTP proxy (`{ url, auth?, tls? }`; see pki.transport).

async function example() {
  var reqDer = await pki.cmp.build(
    { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
      body: { p10cr: csrDer } },
    { key: signerKeyPkcs8, cert: signerCertDer });
  var url = pki.cmp.wellKnownUrl("https://ca.example", { operation: "p10cr" });
  var res = await pki.cmp.transfer(url, reqDer, { transport: transport });
  res.response.body.arm;   // "ip" | "cp" | "error"
}
example();

pki.cmp.wellKnownUrl(base, opts?) -> string

- `label` -- an optional CA/RA name inserted as `.../p/<label>` (a single percent-encoded path segment).
- `operation` -- an optional operation label appended as the final path segment.

pki.cmp.wellKnownUrl("https://ca.example");                          // "https://ca.example/.well-known/cmp"
pki.cmp.wellKnownUrl("https://ca.example", { label: "myca", operation: "cr" });
//                                                                   // ".../.well-known/cmp/p/myca/cr"