@blamejs/pki 0.7.39 → 0.7.41

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.7.41 — 2026-09-12
+
+A delivered or archived private key is proven the private half of its certificate with the key itself.
+
+### Fixed
+
+- pki.est.serverkeygen proves a cleartext server-generated private key is the private half of the returned certificate it binds it to (a signature, an agreement, or an encapsulation the key completes), and refuses with est/key-cert-mismatch a key whose stated public half matches the certificate while its private material cannot use it. The selection of the certificate by public-key match and the ambiguity refusal are unchanged, and a finite-field Diffie-Hellman key, whose private structure carries the exponent alone, is still bound by the value it derives, at any width the runtime reads.
+- pki.crmf.build proves the key enclosed in an encryptedKey proof of possession is the private half of certTemplate.publicKey with the key itself, and refuses with crmf/bad-popo an RSA, EC, EdDSA, ML-DSA, ML-KEM or composite key that only states the template's public components; a key the toolkit cannot read stays crmf/bad-input. A finite-field Diffie-Hellman key, whose private structure carries the exponent alone, keeps the derived comparison at any width, so the archival path still accepts a key wider than any group the toolkit agrees over.
+
+## v0.7.40 — 2026-09-12
+
+A PKCS#12 store links a certificate only to its own key.
+
+### Changed
+
+- pki.pkcs12.build refuses, with pkcs12/bad-input, a { key, cert } pair whose key is not the private half of the certificate's public key, and a key bag and a certificate bag sharing a localKeyId (PKCS #9 sec. 5.5.2) whose key is not that certificate's, across every safe and nested safe of the store. The pair is proven with the private material (a signature, an agreement, or for a composite ML-KEM key an encapsulation to the certificate's key decapsulated under the private key), never by the public components a private key carries about itself. A localKeyId names one private key, so a store carrying one localKeyId on two key bags is refused with pkcs12/bad-input; several certificate bags under one key's localKeyId are each held to that key, at most 1024 across the store. A store of more than 1024 safes is refused before any safe is built. Bags with different or absent localKeyIds are not a pair and are unaffected; a key-only or certificate-only store is unaffected.
+- The toolkit proves a finite-field Diffie-Hellman key pair by the public value the exponent generates (a DH PrivateKeyInfo carries the exponent alone), in either encoding of the key: the PKCS #3 form a generated key is written in and the X9.42 form a certificate names it in (RFC 3279 sec. 2.3.3); a key in either encoding is held to the largest group the toolkit agrees over (4096 bits) and to a group whose modulus and stated order are prime, so a malformed DH certificate is refused rather than paired. Proving a DH pair costs those primality proofs, so a store links at most 8 finite-field DH pairs. So pki.pkcs12.build stores a DH key with its certificate and a CMP session confirms a centrally generated DH key the issued certificate certifies; a DH key under another key's certificate is refused as before.
+
 ## v0.7.39 — 2026-09-12
 
 An OCSP CertID's issuer hashes are held to the length of the digest they name.

package/README.md

@@ -238,7 +238,7 @@ comment blocks, is at [pkijs.com](https://pkijs.com).
 | `pki.cmp` | CMP message building, transfer, and verification (RFC 9810). `build(message, opts)` assembles a protected `PKIMessage`. `message.header` carries the `sender` and `recipient` GeneralNames (including the anonymous NULL-DN) plus optional transaction metadata; `message.body` is a single-key object naming the arm — request-side `ir`, `cr`, `kur`, `krr` (key recovery, §5.3.7), `ccr` (cross-certification, §5.3.11: a `CertReqMessages` at the normative floor, where the requesting CA keeps its private key so a private-key-transport encryptedKey proof-of-possession is refused, and the optional App. D.6 single-request cardinality is not enforced), `p10cr`, `certConf`, `pollReq`, `genm`, `rr`, responder-side `ip`, `cp`, `kup`, `ccp`, `rp`, `genp`, `error`, `pollRep`, `krp`, `pkiconf`, and the registration-authority `nested` wrapper of complete PKIMessages (RFC 9810 §5.1.3.5). Protection is exactly one of `opts.{ key, cert }`, a signature under the sender key with the algorithm resolved from the signer certificate so RSA (PKCS#1 v1.5 / PSS), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch, `opts.mac`, a PBMAC1 shared-secret HMAC (RFC 9481 / 9579, PBKDF2-derived), or `opts.kem`, a KEM-based MAC for a client whose key can only establish secrets (RFC 9810 §5.1.3.4): the ciphertext a peer encapsulated to its ML-KEM key is decapsulated, the key is derived under HKDF-SHA256 with a context bound to the transaction identifier of the message that carried the ciphertext, and `pki.cmp.verify` checks it from the shared secret. Protection covers the exact DER of the virtual `ProtectedPart` and is self-verified before the message is returned, and `protectionAlg` is derived rather than caller-set, so the message the parser accepts is coherent by construction. A `p10cr` request's PKCS#10 proof-of-possession is verified before the message is protected, so one whose self-signature does not verify under its subject public key is refused rather than sent. `transfer(url, message, opts)` carries a built message to a CMP endpoint over `pki.transport` (RFC 9811): one POST of the DER PKIMessage, with the response classified fail-closed — 200 only for success, a non-200 2xx or an un-followed 3xx refused, a 4xx or 5xx carrying a CMP error PKIMessage forwarded as the integrity-protected verdict — and protection surfaced rather than verified. `wellKnownUrl(base, opts)` builds the §3.4 `/.well-known/cmp` request-URIs. `verify(message, opts)` checks the protection on an incoming message, either a signature through the same certification-path engine `pki.crl.verify` and `pki.ocsp.verify` use, with the EdDSA low-order-point and algorithm-confusion gates, or a PBMAC1 MAC recomputed from `opts.sharedSecret` and the message's own PBKDF2 parameters and constant-time compared, over the exact `ProtectedPart` reconstructed from the parser's raw slices. It is fail-closed on an unprotected message, a MAC algorithm it does not compute (reported as MAC-protected under that algorithm, never as a failed signature), an omitted keyLength, or a SHA-1 PRF, and returns a `{ valid, trusted, protectionType, signer, ... }` verdict. With `opts.trustAnchors` the signer certificate is fully path-validated (RFC 5280 §6.1 plus the RFC 9483 §3.2 `keyUsage.digitalSignature` gate) at a trusted current time, or an explicit `opts.time` for historical verification and never the message's self-asserted `messageTime`, before it is reported trusted; without one the verdict is crypto-only and the signer certificate is surfaced to anchor. `session(opts)` returns a stateful enrollment session whose `enroll(request)` drives a full `ir` / `cr` / `kur` / `p10cr` transaction over the shared transport, composing `build`, `transfer`, and `verify`. Every response is protection-verified, signer-trusted, and bound to the exchange (a stable `transactionID`, a fresh-`senderNonce` and echoed-`recipNonce` chain) before its body is read, with a bounded `pollReq` / `pollRep` loop for a `waiting` status and a `certConf` / `pkiConf` (or implicit) confirmation carrying an explicit `hashAlg` for a signature algorithm that does not convey its hash. It returns a terminal `{ outcome, certificate, chain, status, trusted, confirmed, implicitConfirm, transactionID, polls, transcript }`. A certification authority can take longer to answer than a process is held open, so a `poll-timeout` carries a `resumeToken` and `resumePoll(token)` continues the same transaction in a later process: the token is plain JSON naming the transaction, the nonce the next request echoes, the polled request and the arm its grant arrives on, and the key the grant must certify. It carries no secret and grants nothing, since the protection material and the endpoint come from the session built to resume with, and the resumed poll verifies, nonce-binds, and key-binds every response. Its fields are what the resumed exchange is held to, so store it where the enrollment's own state is stored: someone who can rewrite it can widen what the resumed session accepts, as far as that session's trust anchors and the authority's protection allow and no further. The same session also drives the other two RFC 9483 operations under that shell: `revoke(request)` sends an `rr` naming a certificate as `{ certificate }` or `{ certDetails }` with an optional CRLReason `reason`, and returns `revoked` / `rejected` / `poll-timeout`; `info(request)` sends a `genm` for one of the four support messages — `{ caCerts }`, `{ rootCaCert }`, `{ certReqTemplate }`, `{ crlUpdate }` — and returns `answered` with the decoded `value` and a `present` flag, since an absent response value is how each says nothing is available. A session revokes its own certificate: the signature over the request is the proof of authorization (§4.2), so the named certificate must be `opts.cert` and a PBMAC1 session is refused. The signature flavor requires `opts.trustAnchors` to authenticate the CA; a verified rejection or error and an exhausted poll budget are terminal verdicts, while a tampered, untrusted, or desynchronized response is a typed throw. Returns DER, or a PEM `CMP` block with `opts.pem`; malformed input throws a typed `CmpError`. `openKeyPackage(container, opts)` opens a private key the CA generated centrally and delivered in the `privateKey` field of a granted `CertifiedKeyPair` (RFC 9483 §4.1.6): a CMS `SignedData` over an RFC 5958 `AsymmetricKeyPackage`, sealed in a CMS `EnvelopedData`. `opts.key` (with `opts.cert`) opens the key transport and key agreement containers a signature-protected request selects, `opts.password` the password container a MAC-protected request selects. The authority is authorized before any key material is returned: its certificate must chain to an anchor in `opts.trustAnchors` AND assert the `id-kp-cmKGA` extended key usage, since a certificate with no `extendedKeyUsage` permits every purpose and so authorizes nothing; `opts.authorizedBySharedSecret` states §4.1.6's exemption for an entity that authorizes by the secret that protected its request. Returns `{ keys, kga, trusted }`, where each key is a PKCS#8 `PrivateKeyInfo` ready for `pki.key.import`; `keys` is the whole RFC 5958 `AsymmetricKeyPackage` (`SIZE (1..MAX)`), while a session enrollment requires the sequence of one §4.1.6 profiles it to. Both CMS layers are read as a ContentInfo or as the bare structure, told apart by what the SEQUENCE opens with. `session(opts)` drives the whole exchange under `opts.acceptCentralKeyGeneration`: the request omits `certTemplate.publicKey`, carries no proof of possession, and goes out as `cmp2021`; the session opens the delivered container with the credential it enrolled under and surfaces it as `deliveredKey`, having first checked that the issued certificate certifies the delivered key. Without the option, such a request and such a grant are both refused. Parsing stays at `pki.schema.cmp.parse` — `build`, `transfer`, `wellKnownUrl`, `verify`, `openKeyPackage`, `session` |
 | `pki.crl` | CRL issuance and verification (RFC 5280 §5). `sign(spec, issuer, opts)` builds and signs a `CertificateList` from a `spec` of `thisUpdate` and `nextUpdate`, an optional `crlNumber`, a `revoked` array (each entry a `serialNumber` and `revocationDate` with an optional `reason` or `invalidityDate`), and an optional `extensions` object (authority key identifier, issuer alternative name, issuing distribution point, delta-CRL indicator, freshest CRL, authority information access, which is every extension RFC 5280 §5.2 defines) or an array of pre-encoded Extension DER, with an `issuer` of `{ cert, key }` or `{ name, publicKey, key }`. The authority key identifier is emitted on every CRL whether or not it is named, as §5.2.1 places it on every conforming issuer, from the issuer certificate's SKI or the issuer key. The signature algorithm is resolved from the issuer key, so RSA (PKCS#1 v1.5 or PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. The version is derived from the extension set (v2 when any CRL or entry extension is present, else v1), the outer `signatureAlgorithm` matches `tbsCertList.signature`, an empty revocation list omits the field rather than emitting an empty SEQUENCE, `reasonCode` is an ENUMERATED and `invalidityDate` is always GeneralizedTime, the RFC fixes per-extension criticality, and the produced signature is verified under the issuer key before return. `verify(crl, issuer)` checks a CRL signature through the one path-validation signature engine, algorithm-confusion and EdDSA low-order gates included; handed a certificate rather than a bare key it also asks what only a certificate can answer — that the certificate is the issuer the CRL names, and that its `keyUsage`, when present, asserts `cRLSign` — so a CRL minted under an end-entity certificate of the same CA does not verify as that CA's. `isRevoked(crl, serialNumber, opts)` looks a serial up, and first checks that the CRL is one a serial can be looked up in at all — it is handed a serial and nothing else, so a CRL that speaks for part of its issuer's certificates is refused rather than answered from. A delta CRL lists changes since a base, so an entry recording a release reads as a revocation when read alone; an indirect CRL carries other issuers' entries, whose serials are unrelated to yours; and any other `issuingDistributionPoint` narrows the CRL to one distribution point, one kind of certificate, or a subset of revocation reasons, none of which a serial can be matched against. A CRL speaks for a span as well as a set, so `opts.time` states the instant the question is asked at and a list that has stopped speaking for it — `nextUpdate` passed, `thisUpdate` later, or no `nextUpdate` stated at all — is refused rather than read as a clean bill of health; without `opts.time` the lookup is structural and an absent serial means only that it is not on that list. `pki.path.crlChecker` is the verb for all of them: it is handed the certificate, merges a delta with its base, performs the §6.3.3 correspondence, and decides currency against the material it fetched. Returns DER, or a PEM `X509 CRL` with `opts.pem`; malformed input throws a typed `CrlError`. Parsing stays at `pki.schema.crl.parse` — `sign`, `verify`, `isRevoked` |
 | `pki.key` | Key-material lifecycle (RFC 5958 / RFC 8018). `encrypt(privateKey, password, opts)` wraps a PKCS#8 private key (DER, PEM, or an extractable `CryptoKey`) into an `EncryptedPrivateKeyInfo` under PBES2 (PBKDF2 with AES-CBC-Pad), where `opts` selects the `cipher` (`aes-256-cbc` default, `aes-192-cbc`, `aes-128-cbc`), the `prf` (`hmacWithSHA256` default, SHA-384/512, SHA-1), the `iterations` (default 600000), and the `salt`. The plaintext is validated as PKCS#8 before encryption, a default `prf` and `keyLength` are omitted so the parameters are byte-exact with OpenSSL, and the output is re-parsed before return. `decrypt(encrypted, password, opts)` recovers the inner `PrivateKeyInfo`, re-validated through `pki.schema.pkcs8.parse`: only PBES2 / PBKDF2 / AES-CBC is accepted (PBES1, PBMAC1, and scrypt are refused), the salt and iteration count are bounded before any derivation (`opts.maxIterations` lowers the cap), and a malformed parameter set or wrong-length IV is a distinct typed error. Because a MAC-less PBES2-CBC decrypt must not become a padding oracle (RFC 8018 §8), a wrong password and a valid-pad-but-not-a-key both surface the one uniform `key/decrypt-failed`. `export(key, opts)` and `import(input, opts)` move a private key as PKCS#8 or a public key as SubjectPublicKeyInfo. The key may come from the platform's WebCrypto or from a separately installed copy of this toolkit, and is exported through whichever holds its material; a non-extractable key, or one whose implementation keeps its material out of reach, is refused with that as the reason. Encoding is delegated to WebCrypto, so RSA carries an explicit NULL, EC a named curve, and Ed25519/Ed448/X25519/X448 omit parameters, and an ambiguous RSA or EC import requires `opts.algorithm`. `generate(algorithm, opts)` produces a key pair over RSA, ECDSA/ECDH, the Edwards and Montgomery curves, and the FIPS post-quantum ML-DSA and ML-KEM; `publicFromPrivate(privateKey)` derives the public key. Returns DER or PEM, with a typed `KeyError` on failure. Parsing stays at `pki.schema.pkcs8.parse` — `encrypt`, `decrypt`, `export`, `import`, `generate`, `publicFromPrivate` |
-| `pki.pkcs12` | PKCS#12 (.p12/.pfx) issuance and reading (RFC 7292 / RFC 9579). `build(spec, opts)` assembles a store from the OpenSSL-style `{ key, cert, ca?, friendlyName?, localKeyId? }` or the full `{ safeContents: [...] }`, where each element is a plaintext or PBES2-encrypted `SafeContents` of key, shroudedKey, cert, crl, secret, or nested `safeContents` bags. Keys and certs are validated before wrapping, and `friendlyName` (BMPString) and `localKeyId` are single-value. Integrity is a classic Appendix B HMAC (the default, for maximum interoperability) or an RFC 9579 PBMAC1 (`opts.mac.algorithm`) over SHA-256/384/512, with shrouded keys and cert safes encrypted under RFC 8018 PBES2 (AES-128/192/256-CBC). Every password is encoded the PKCS#12 way — BMPString+NULL for the classic MAC, UTF-8 for the PBES2 bags and PBMAC1 — which is what OpenSSL and NSS consume, so a file it emits opens in both, cross-checked bidirectionally. The MAC covers the exact AuthenticatedSafe byte range, a DEFAULT-1 `MacData.iterations` is rejected up front, and the store is re-parsed before return. `verifyMac(pfx, password, opts)` recomputes a classic or PBMAC1 MAC over `macedBytes` and constant-time-compares it, throwing on a MAC-less or public-key-integrity store. Public-key integrity (`opts.integrity.mode: "public-key"`) wraps the AuthenticatedSafe in a CMS SignedData instead of a MAC, signed by any `pki.cms.sign` signer and carrying no MacData (§4); privacy stays independent, so `password` still PBES2-encrypts the bags. Public-key privacy wraps a SafeContents as a CMS EnvelopedData (AES-CBC, `id-envelopedData`, never GCM) encrypted to recipient public keys through the `pki.cms.encrypt` recipient model, via per-safe `recipients` or the `opts.recipientCerts` convenience, restricted to certificate recipients (RSA-OAEP, ECDH, X25519, X448, ML-KEM) since a password or KEK recipient could not be reopened by `open`. All four integrity-by-privacy combinations are permitted (§3.1). `open(pfx, password, opts)` reads a store back: it verifies the MAC first, so a wrong password is the MAC verdict rather than a decrypt error, then PBES2-decrypts every privacy safe and shrouded key bag and returns `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` — keys as re-validated PKCS#8 DER, certs, CRLs and secrets as raw DER, all with `friendlyName` and `localKeyId`, nested safes recursively. A MAC-less store is refused unless `opts.allowUnauthenticated`. A public-key-integrity store is verified through its CMS SignedData signature first (`pkcs12/signature-invalid` on failure), with the signer surfaced in `signers` but never trust-chained, which remains the caller's `pki.path.validate` step. A legacy-PBE store's Appendix C 3DES and RC2 bags are decrypted, RC2 through an in-tree RFC 2268 cipher, so an `openssl pkcs12 -legacy` or NSS store opens; the legacy RC4 schemes are refused. An `id-envelopedData` safe is decrypted with `opts.recipientKey` after the integrity gate (`pkcs12/no-recipient-key` when absent), every recipient-side fault and every post-integrity decrypt failure collapsing to the uniform `pkcs12/decrypt-failed`, and `opts.keys: 'crypto'` imports each key to a `CryptoKey`. It reads what OpenSSL and NSS produce. Returns DER or a PEM `PKCS12`, with a typed `Pkcs12Error` on failure. Parsing stays at `pki.schema.pkcs12.parse` — `build`, `verifyMac`, `open` |
+| `pki.pkcs12` | PKCS#12 (.p12/.pfx) issuance and reading (RFC 7292 / RFC 9579). `build(spec, opts)` assembles a store from the OpenSSL-style `{ key, cert, ca?, friendlyName?, localKeyId? }` or the full `{ safeContents: [...] }`, where each element is a plaintext or PBES2-encrypted `SafeContents` of key, shroudedKey, cert, crl, secret, or nested `safeContents` bags. Keys and certs are validated before wrapping, a key paired with a certificate (the `{ key, cert }` form, or bags sharing a `localKeyId`) must be the private half of that certificate's public key, and `friendlyName` (BMPString) and `localKeyId` are single-value. Integrity is a classic Appendix B HMAC (the default, for maximum interoperability) or an RFC 9579 PBMAC1 (`opts.mac.algorithm`) over SHA-256/384/512, with shrouded keys and cert safes encrypted under RFC 8018 PBES2 (AES-128/192/256-CBC). Every password is encoded the PKCS#12 way — BMPString+NULL for the classic MAC, UTF-8 for the PBES2 bags and PBMAC1 — which is what OpenSSL and NSS consume, so a file it emits opens in both, cross-checked bidirectionally. The MAC covers the exact AuthenticatedSafe byte range, a DEFAULT-1 `MacData.iterations` is rejected up front, and the store is re-parsed before return. `verifyMac(pfx, password, opts)` recomputes a classic or PBMAC1 MAC over `macedBytes` and constant-time-compares it, throwing on a MAC-less or public-key-integrity store. Public-key integrity (`opts.integrity.mode: "public-key"`) wraps the AuthenticatedSafe in a CMS SignedData instead of a MAC, signed by any `pki.cms.sign` signer and carrying no MacData (§4); privacy stays independent, so `password` still PBES2-encrypts the bags. Public-key privacy wraps a SafeContents as a CMS EnvelopedData (AES-CBC, `id-envelopedData`, never GCM) encrypted to recipient public keys through the `pki.cms.encrypt` recipient model, via per-safe `recipients` or the `opts.recipientCerts` convenience, restricted to certificate recipients (RSA-OAEP, ECDH, X25519, X448, ML-KEM) since a password or KEK recipient could not be reopened by `open`. All four integrity-by-privacy combinations are permitted (§3.1). `open(pfx, password, opts)` reads a store back: it verifies the MAC first, so a wrong password is the MAC verdict rather than a decrypt error, then PBES2-decrypts every privacy safe and shrouded key bag and returns `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` — keys as re-validated PKCS#8 DER, certs, CRLs and secrets as raw DER, all with `friendlyName` and `localKeyId`, nested safes recursively. A MAC-less store is refused unless `opts.allowUnauthenticated`. A public-key-integrity store is verified through its CMS SignedData signature first (`pkcs12/signature-invalid` on failure), with the signer surfaced in `signers` but never trust-chained, which remains the caller's `pki.path.validate` step. A legacy-PBE store's Appendix C 3DES and RC2 bags are decrypted, RC2 through an in-tree RFC 2268 cipher, so an `openssl pkcs12 -legacy` or NSS store opens; the legacy RC4 schemes are refused. An `id-envelopedData` safe is decrypted with `opts.recipientKey` after the integrity gate (`pkcs12/no-recipient-key` when absent), every recipient-side fault and every post-integrity decrypt failure collapsing to the uniform `pkcs12/decrypt-failed`, and `opts.keys: 'crypto'` imports each key to a `CryptoKey`. It reads what OpenSSL and NSS produce. Returns DER or a PEM `PKCS12`, with a typed `Pkcs12Error` on failure. Parsing stays at `pki.schema.pkcs12.parse` — `build`, `verifyMac`, `open` |
 | `pki.cms` | CMS signing, verification, encryption, and compression (RFC 5652). `sign(content, signers, opts)` produces a SignedData (§5), attached or detached, with one or many signers over RSA, RSASSA-PSS, ECDSA, EdDSA, the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814), and composite ML-DSA pairing ML-DSA with a traditional RSA, ECDSA, or EdDSA key (accepted only when both components verify, draft-ietf-lamps-cms-composite-sigs). It builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. The content may also be an async iterable of byte chunks, which signs a large detached payload without holding it in memory: the payload is hashed incrementally under every signer's digest algorithm in one pass, and `verify` accepts the same streamed form as its `content` option. A signer may also be key-only — `{ key, spki, keyIdentifier }` with no certificate — which RFC 5272 §3.2 requires when a Full PKI Request's signer is the key of a certification request that request carries: the signer identifier takes the subjectKeyIdentifier form carrying the identifier the request declares, the signature scheme resolves from the request's own public key, and no certificate is embedded. `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: with signed attributes present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), and otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate. `valid` and `trusted` are separate claims and neither implies the other: a SignedData carries its own certificates, so `valid` says the signature is sound under one of them and nothing about who signed, while `trusted` says every signer chained to a root named in `opts.trustAnchors`, validated through the same RFC 5280 path engine `pki.path.validate` uses. Without anchors there is nothing to chain to and `trusted` is `false`; anchors that cannot be read throw, rather than reading as untrusted. An unrecognized option is refused rather than ignored. `countersign(cms, signers, opts)` adds a countersignature (§11.4) — a `SignerInfo` over the countersigned SignerInfo's signature value, any signer algorithm, nestable, with the primary bytes preserved so it still verifies — attached as the id-countersignature unsigned attribute; `verify` returns each countersignature's verdict under `signers[i].countersignatures` and every unsigned attribute — including an RFC 3161 timestamp token, attachable via `sign`'s `unsignedAttributes` — under `signers[i].unsignedAttrs`, surfaced unauthenticated. `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData, with recipients auto-dispatched off the certificate key to key transport (RSAES-OAEP; v1.5 is never emitted), key agreement (ephemeral-static ECDH over P-256/384/521 with the X9.63 KDF, and X25519/X448 with HKDF), symmetric key wrap, password (PBKDF2 with RFC 3211 PWRI-KEK), or the post-quantum ML-KEM (and composite ML-KEM, draft-lamps-pq-composite-kem) KEMRecipientInfo (RFC 9629/9936), wrapping one fresh content key for every recipient. The content may also be an async iterable of byte chunks, streamed through the AES-GCM or AES-CBC content cipher so a large plaintext is encrypted without being buffered whole; the ciphertext is assembled before the definite-length encryptedContent is emitted, byte-for-byte the buffered form. `decrypt(input, keyMaterial, opts)` recovers the content through the matching arm and returns it with an `authenticated` flag; every secret-dependent failure collapses to one uniform `cms/decrypt-failed` verdict (Bleichenbacher, EFAIL, and password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. With `opts.stream: true` the recovered `content` is an async iterable of plaintext chunks instead of a single Buffer, for a payload too large to hold whole; the authenticated modes (AuthEnvelopedData, AuthenticatedData, AES-GCM) verify integrity before the iterable yields, so a forged message throws before any plaintext is exposed, while a CBC EnvelopedData or EncryptedData yields the plaintext as the cipher produces it. Every key-establishment secret the toolkit allocates is wiped once used, on the failing path as well as the succeeding one: the KEM shared secret and its derived key-encryption key, the raw ECDH / X25519 / X448 agreement secret, a password-derived key-encryption key, and the content-encryption key itself, cleared once the message is complete since all recipients share it. Caller-supplied key material is never written to (best-effort; NIST SP 800-227 §4.2, RFC 9629 §7). `authenticate(content, recipients, opts)` produces an `id-ct-authData` (§9): cleartext content plus an HMAC-SHA-256/384/512 MAC, authenticated but not encrypted, with the fresh MAC key wrapped for every recipient through the same RecipientInfo model. The MAC covers the authenticated attributes (content-type and message-digest) re-tagged to the EXPLICIT SET OF (§9.2), or the content octets directly; `decrypt` recovers the MAC key, recomputes the MAC and independently the message-digest (§9.3), and releases the content only after both pass, with every secret-dependent failure collapsing to the uniform `cms/decrypt-failed`. `compress(content, opts)` and `decompress(input, opts)` produce and consume a CompressedData (RFC 3274; ZLIB, version 0, id-alg-zlibCompress); decompress bounds the uncompressed output at 16 MiB and stops before it is materialized, so a decompression bomb fails closed as `cms/decompress-too-large`. Compression is a size transform with no integrity or confidentiality (RFC 8551 §2.4.5). `certsOnly(certs, opts?)` builds a certs-only certificate-management message (RFC 8551 §3.8): a degenerate SignedData with an empty signerInfos and no eContent that conveys certificates and CRLs without signing anything, `parseCertsOnly(input, opts?)` reads one back to its raw certificate and CRL DER (a CRL-only message is valid here, unlike the cert-required RFC 5272 form that `pki.est.parseCertsOnly` reads), and `isCertsOnly(input)` recognizes one structurally. Fail-closed with typed `cms/*` errors — `sign`, `verify`, `countersign`, `encrypt`, `authenticate`, `decrypt`, `compress`, `decompress`, `certsOnly`, `parseCertsOnly`, `isCertsOnly` |
 | `pki.smime` | S/MIME message assembly, verification, encryption, and compression over the CMS layer (RFC 8551). `sign(content, signers, opts)` wraps a MIME entity in either form: `multipart/signed`, where the content stays readable in any MUA and a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`, or `application/pkcs7-mime; smime-type=signed-data`, where the whole entity is a base64 CMS SignedData. The signed bytes are the entity's §3.1.1 canonical form with CRLF line endings, and `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies while a tampered part fails. `encrypt(content, recipients, opts)` envelopes a MIME entity as an opaque `application/pkcs7-mime` message and `decrypt(message, keyMaterial, opts)` opens one, as `smime-type=authEnveloped-data` (AES-GCM, confidentiality and integrity, the default) or `smime-type=enveloped-data` (AES-CBC, confidentiality only, so `decrypt` reports `authenticated: false`, the §3.3 no-integrity caveat). The `smime-type` is derived from the CMS body rather than the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt`, so it is algorithm-agnostic: any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA signer and any RSA-OAEP / ECDH / X25519 / X448 / AES-KW / PBKDF2 / ML-KEM recipient carries through. As with `cms.verify`, `verify` returns the per-signer verdict plus the recovered content, and `valid` and `trusted` are separate claims: `valid` says the signature is sound under a certificate the message carried, `trusted` says every signer chained to a root named in `opts.trustAnchors`. Anchoring here is validated for email at both ends of the chain — the signer certificate must carry `emailProtection` (RFC 8551 §4.4.4) and the anchor's own trust metadata must permit that purpose, since a root can be distrusted for email while remaining a good TLS root. Override either with `requiredEku` / `checkPurpose`. `compress(content, opts)` and `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (§3.6, RFC 3274), a size transform with no integrity or confidentiality (§2.4.5), bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. Header protection (RFC 9788): `sign` and `encrypt` take `opts.protectHeaders`, which inlines the caller's `opts.headers` on the Cryptographic Payload root (its Content-Type gaining `hp="clear"` when signed or `hp="cipher"` when encrypted) so the CMS signature or encryption covers them, defeating a transport that rewrites or reads Subject, From, and the rest. `verify` and `decrypt` surface the authenticated inner set as `protectedHeaders` plus `headerProtection { present, mode, fromMismatch, confidential, legacy }`, so a tampered outer header cannot alter it and `fromMismatch` flags an outer From that disagrees. Encryption applies a Header Confidentiality Policy: the default `hcp_baseline` obscures the outer Subject to `[...]` and removes Comments and Keywords, so the real values live only in the ciphertext, and `decrypt` recovers them. Every emitted header routes through a fail-closed injection guard that rejects a CR, LF, or NUL value and a non-ftext name, and a malformed or contradictory `hp` wrap fails closed as `smime/bad-header-protection` rather than silently downgrading. The CMS crypto is unchanged. Inbound legacy RFC 8551 header protection is recognized opt-in: `verify` and `decrypt` with `opts.legacyHeaderProtection` detect a legacy `message/rfc822`-wrapped payload by the RFC 9788 §4.10.1 four-condition identification and surface the inner headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }`, where `headers` is an ordered `[{ name, value }]` array retaining legally repeated fields such as `Received`. Those never appear in `protectedHeaders` and never set `present: true`. Because a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, this is an explicit heuristic (§4.10.2, "no strong end-to-end guarantees"): a caller keying trust off `present` or `protectedHeaders` is never misled, and only one that explicitly reads `headerProtection.legacy.headers` and cross-checks `legacy.fromMismatch` consumes it. It is off by default, and a nested crypto layer, an inner `hp=`, a non-`message/rfc822` payload, or a duplicate Content-Type reports `legacy: null`. Bidirectionally interoperable with `openssl smime` and `openssl cms`. `buildCertsOnly(certs, opts?)` wraps a `pki.cms.certsOnly` certificate-management message in one `application/pkcs7-mime; smime-type=certs-only; name=smime.p7c` entity, read back by OpenSSL's `pkcs7 -print_certs`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress`, `buildCertsOnly` |
 | `pki.tsp` | Time-Stamp Protocol (RFC 3161). `sign(messageImprint, tsa, opts)` produces a TimeStampToken: a CMS SignedData over `pki.cms.sign` whose content is a `TSTInfo` carrying the timestamped message imprint, the TSA policy, a serial number, and `genTime` with optional accuracy, nonce, and ordering, plus the §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). The TSA certificate is held to §2.3 before signing (one critical extendedKeyUsage naming timeStamping alone) with the codes `verify` answers, `genTime` keeps its milliseconds as the §2.4.2 fraction of a second, and an accuracy naming no field is refused. `request` and `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq); `response` and `parseResponse` handle the TimeStampResp a TSA returns, either a granted status wrapping a token or a rejection with PKIStatus and failure info, with the §2.4.2 status-to-token coupling enforced in both directions. `verify(token, data, opts)` verifies a token fail-closed: the CMS signature over the exact signed bytes, the message imprint recomputed from the data, the TSTInfo content type, the ESSCertID(V2) binding to the TSA certificate, the §2.3 critical timeStamping-only extendedKeyUsage, the request nonce when used, and, with a trust anchor supplied, full certification-path validation of the TSA certificate at the token's `genTime` — judged under the `timeStamping` purpose, so an anchor's own per-purpose trust metadata reaches the decision rather than sitting inert. It returns `{ valid, trusted, genTime, serialNumber, tstInfo, ... }`, where `trusted` is the separate claim that the authority chained to an anchor you named: without one there is nothing to chain to and it is `false`, which is the distinction a timestamp re-read years later turns on — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |

package/lib/constants.js

@@ -143,6 +143,7 @@ var LIMITS = Object.assign(Object.create(null), {
   PATH_AIA_MAX_RESPONSE_BYTES: BYTES.mib(1),
   PATH_AIA_MAX_CERTS_PER_RESPONSE: 16,
   PKCS12_MAX_ELEMENTS: 1024,
+  PKCS12_MAX_DH_PAIRS: 8,
   PKCS12_MAX_REDECODES: 64,
   PKCS12_MAX_BAG_DEPTH: 16,
   BER_MAX_STRING_NESTING: 8,

package/lib/crmf-sign.js

@@ -25,7 +25,6 @@ var _createHmac = nodeCrypto.createHmac;
 var _diffieHellman = nodeCrypto.diffieHellman;
 var _createPublicKey = nodeCrypto.createPublicKey;
 var _createPrivateKey = nodeCrypto.createPrivateKey;
-var _checkPrimeSync = nodeCrypto.checkPrimeSync;
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
@@ -445,30 +444,17 @@ function _assertAgreementExponent(parts, what) {
   }
 }
 
-/** @internal Whether a stated order and cofactor describe the p and g stated beside them. These are
- * the tests that answer that question with a comparison, a multiplication and a modulo, so their cost
- * grows gently with the modulus and every path that reads these parameters can afford them: the
- * archival arm reads a key without bounding its size, and the tests it leaves to the certifying
- * authority are the ones whose cost grows with it, a modular exponentiation and two primality proofs.
- * A cofactor states (p-1)/q, so a cofactor with no order beside it states nothing. */
+/** @internal Whether a stated order and cofactor describe the p and g stated beside them: the key
+ * module's tests, a comparison, a multiplication and a modulo, which every path that reads these
+ * parameters can afford. The archival arm reads a key without bounding its size, and the tests it
+ * leaves to the certifying authority are the ones whose cost grows with it, a modular exponentiation
+ * and two primality proofs. */
 function _assertDhParamsCoherent(p, g, q, j, what) {
-  if (p <= 2n || g <= 1n || g >= p - 1n) {
-    throw _err("crmf/bad-popo", what + " parameters are not a Diffie-Hellman group");
-  }
-  if (j !== null && (q === null || j * q !== p - 1n)) {
-    throw _err("crmf/bad-popo", what + " X9.42 cofactor does not match its own p and q");
-  }
-  if (q !== null && (q <= 1n || (p - 1n) % q !== 0n)) {
-    throw _err("crmf/bad-popo", what + " X9.42 domain parameters state a subgroup order its own p and g do not have");
-  }
+  key.assertDhDomainCoherent(p, g, q, j, CrmfError, "crmf/bad-popo", what);
 }
 
 function _assertDhGroup(p, g, y, q, j, forAgreement, what) {
-  if (p >= _DH_MAX || g >= _DH_MAX || (y !== null && y >= _DH_MAX) ||
-      (q !== null && q >= _DH_MAX) || (j !== null && j >= _DH_MAX)) {
-    throw _err("crmf/bad-popo", what + " parameters are larger than any Diffie-Hellman group this toolkit agrees over (" +
-      constants.LIMITS.DH_MAX_MODULUS_BYTES + " bytes)");
-  }
+  key.assertDhOperandsWithin([p, g, y, q, j], CrmfError, "crmf/bad-popo", what);
   _assertDhParamsCoherent(p, g, q, j, what);
   /** @internal A PrivateKeyInfo states the group without stating a public value in it, so the two
    * tests that hold a value to these parameters have nothing to run against and the rest still do.
@@ -481,12 +467,8 @@ function _assertDhGroup(p, g, y, q, j, forAgreement, what) {
    * cost seconds on a large modulus and this one costs a modular exponentiation, so a set of
    * parameters that cannot be a group is turned away at the cheaper of the two. The rest of that
    * question was already answered above, without exponentiating. */
-  if (q !== null && _modPow(g, q, p) !== 1n) {
-    throw _err("crmf/bad-popo", what + " X9.42 domain parameters state a subgroup order its own p and g do not have");
-  }
-  if (!_isPrime(p)) {
-    throw _err("crmf/bad-popo", what + " Diffie-Hellman modulus is not prime, so the group its parameters describe does not exist");
-  }
+  if (q !== null) key.assertDhGeneratorOrder(p, g, q, CrmfError, "crmf/bad-popo", what);
+  key.assertDhModulusPrime(p, CrmfError, "crmf/bad-popo", what);
   /** @internal With no stated subgroup order there is nothing to test y against, so the group itself
    * has to be one whose only small orders the range above already excluded. That is a safe prime:
    * p = 2r+1 with r prime has element orders 1, 2, r and 2r alone, and y = 1 and y = p-1 are the only
@@ -503,16 +485,12 @@ function _assertDhGroup(p, g, y, q, j, forAgreement, what) {
       throw _err("crmf/bad-popo", what + " parameters state no subgroup order and its modulus is not a safe prime, so nothing bounds the order of its public value (RFC 2875 sec. 3)");
     }
   } else {
-    if (!_isPrime(q)) {
-      throw _err("crmf/bad-popo", what + " X9.42 domain parameters state a subgroup order that is not prime, so a public value in it need not have that order");
-    }
+    key.assertDhOrderPrime(q, CrmfError, "crmf/bad-popo", what);
     order = q;
     /** @internal The public value has to lie in the subgroup the parameters name. This is what the
      * stated order says about the key, so it is checked wherever the parameters are read and not
      * only where a secret is agreed: a request carries these parameters to whoever reads it next. */
-    if (y !== null && _modPow(y, q, p) !== 1n) {
-      throw _err("crmf/bad-popo", what + " Diffie-Hellman public value is not in the subgroup its own domain parameters state, so agreeing with it would expose the private exponent of whichever side agrees");
-    }
+    if (y !== null) key.assertDhValueInSubgroup(p, q, y, CrmfError, "crmf/bad-popo", what);
   }
   /** @internal Everything above answers whether the parameters describe the key they carry, which is
    * asked of any key this reads. What follows is the strength the AGREEMENT needs, and a key being
@@ -602,50 +580,13 @@ function _spkiParts(spkiBytes) {
 }
 
 /** @internal The p, g and public value of a PKCS#3 dhKeyAgreement SubjectPublicKeyInfo, or null when
- * the key is not in that form. DHParameter is SEQUENCE { prime, base, privateValueLength OPTIONAL }
- * (PKCS#3 sec. 9), and it states no subgroup order, so the group it describes is checked without one. */
+ * the key is not in that form: the key module's reader, which is the only thing that looks at these
+ * bytes before the request travels under a MAC covering them, with this module's errors. A structure
+ * this module's own outer reader does not recognize as a key is not in that form either. */
 function _pkcs3Params(spkiBytes, what) {
   var parts = _spkiParts(spkiBytes);
   if (parts === null || parts.algOid !== O("dhKeyAgreement")) return null;
-  var node = parts.node;
-  try {
-    var prm = asn1.decode(parts.params.bytes);
-    if (!_isUniversal(prm, 16) || !prm.children || prm.children.length < 2 || prm.children.length > 3) {
-      throw _err("crmf/bad-popo", what + " PKCS#3 Diffie-Hellman parameters are not a DHParameter SEQUENCE");
-    }
-    var p = asn1.read.integer(prm.children[0]);
-    /** @internal privateValueLength is the one optional field DHParameter carries, and it is an
-     * INTEGER. A third field of any other type is not that field, and this reader is the only thing
-     * that looks at these bytes before the request travels under a MAC covering them. */
-    if (prm.children.length === 3) {
-      if (!_isUniversal(prm.children[2], 2)) {
-        throw _err("crmf/bad-popo", what + " PKCS#3 privateValueLength is not an INTEGER");
-      }
-      /** @internal Read, not counted. An INTEGER carries at least one content octet, so a field
-       * tagged as one and holding none is not a length, and this reader is the only thing that looks
-       * at these bytes before the request travels under a MAC covering them. */
-      var pvl = asn1.read.integer(prm.children[2]);
-      if (pvl <= 0n) {
-        throw _err("crmf/bad-popo", what + " PKCS#3 privateValueLength is not a positive length");
-      }
-      /** @internal The field states how many bits the private value has, and a private value is less
-       * than the modulus, so a length above the modulus's own bit count describes no value the group
-       * holds. The encoded size bounds the count before anything is shifted by it, because this
-       * reader also serves an arm that reads a key without bounding its modulus and the field itself
-       * is an INTEGER the codec admits at any width. */
-      if (pvl > intrinsic.BigInt(prm.children[0].bytes.length) * 8n || (1n << (pvl - 1n)) > p) {
-        throw _err("crmf/bad-popo", what + " PKCS#3 privateValueLength states a private value longer than its own modulus, which no value in the group is");
-      }
-    }
-    var pub = asn1.read.bitString(node.children[1]);
-    if (!guard.crypto.isOctetAligned(pub)) {
-      throw _err("crmf/bad-popo", what + " Diffie-Hellman public key BIT STRING must be octet-aligned (0 unused bits)");
-    }
-    return { p: p, g: asn1.read.integer(prm.children[1]), y: asn1.read.integer(asn1.decode(pub.bytes)) };
-  } catch (e) {
-    if (e instanceof CrmfError) throw e;
-    throw _err("crmf/bad-popo", what + " PKCS#3 Diffie-Hellman key could not be read", e);
-  }
+  return key.pkcs3Params(spkiBytes, CrmfError, "crmf/bad-popo", what);
 }
 
 /** @internal A container is read for the tag it carries and not for merely having children: a
@@ -654,61 +595,14 @@ function _pkcs3Params(spkiBytes, what) {
  * key nothing else can read. The predicate itself is the engine's. */
 var _isUniversal = schema.isUniversal;
 
-/** @internal ValidationParms is SEQUENCE { seed BIT STRING, pgenCounter INTEGER } (RFC 3279
- * sec. 2.3.3). The conversion drops it, so reading it is the only thing that answers for it: a
- * certificate whose parameters do not hold the two fields is malformed rather than merely carrying
- * something this does not need. */
-function _assertValidationParms(node, what) {
-  var kids = node.children;
-  if (!_isUniversal(node, 16) || !kids || kids.length !== 2 ||
-      !_isUniversal(kids[0], 3) || !_isUniversal(kids[1], 2)) {
-    throw _err("crmf/bad-popo", what + " X9.42 validationParms is not a seed BIT STRING with a pgenCounter INTEGER");
-  }
-  asn1.read.bitString(kids[0]);
-  asn1.read.integer(kids[1]);
-}
-
-/** @internal The p, g, q and cofactor an X9.42 DomainParameters states. DomainParameters is
- * SEQUENCE { p, g, q, j OPTIONAL, validationParms OPTIONAL } (RFC 3279 sec. 2.3.3), and the PKCS#3
- * form this runtime classifies carries none of the last three, so every field is read HERE, before
- * the parameter that states it is dropped. Both halves of a finite-field key carry this structure and
- * both take that conversion, so both read it in this one place: a field read on one side and skipped
- * on the other is a key the runtime refuses in the encoding it was handed and this rewrites into one
- * it accepts. The algorithm named dhpublicnumber, so these bytes are DomainParameters or the key is
- * malformed; there is no third reading that would let a shape this does not recognize travel on. */
+/** @internal The p, g, q and cofactor an X9.42 DomainParameters states, read by the key module,
+ * which owns the structure and the conversion that drops its last three fields; the errors are this
+ * module's. Both halves of a finite-field key carry this structure and both take that conversion,
+ * so both read it in that one place. */
 function _x942Domain(paramsNode, what) {
-  var domain = asn1.decode(paramsNode.bytes);
-  if (!_isUniversal(domain, 16) || !domain.children ||
-      domain.children.length < 3 || domain.children.length > 5) {
-    throw _err("crmf/bad-popo", what + " X9.42 domain parameters are not a DomainParameters SEQUENCE of p, g and q with at most two optional fields after them");
-  }
-  var out = {
-    p: asn1.read.integer(domain.children[0]),
-    g: asn1.read.integer(domain.children[1]),
-    q: asn1.read.integer(domain.children[2]),
-    j: null,
-  };
-  /** @internal j and validationParms are independently optional, so a fourth field is told apart by
-   * its tag rather than by its position: an INTEGER is the cofactor and a SEQUENCE is the validation
-   * parameters, which may appear with no cofactor before them. */
-  if (domain.children.length >= 4) {
-    var opt = domain.children[3];
-    if (_isUniversal(opt, 2)) {
-      out.j = asn1.read.integer(opt);
-      if (domain.children.length === 5) _assertValidationParms(domain.children[4], what);
-    } else if (_isUniversal(opt, 16)) {
-      if (domain.children.length === 5) {
-        throw _err("crmf/bad-popo", what + " X9.42 domain parameters carry a field after validationParms");
-      }
-      _assertValidationParms(opt, what);
-    } else {
-      throw _err("crmf/bad-popo", what + " X9.42 domain parameters carry a fourth field that is neither a cofactor nor validationParms");
-    }
-  }
-  return out;
+  return key.x942Domain(paramsNode, CrmfError, "crmf/bad-popo", what);
 }
 
-/** @internal One past the largest Diffie-Hellman operand this module computes with, built once. */
 /** @internal Two raised to a count of BITS, so a bound states the width it is named for: a value is
  * at least n bits wide exactly when it is not below 2^(n-1), and at most n bits wide exactly when it
  * is below 2^n. Counting in bytes and shifting by eight per byte lands a whole byte short of that. */
@@ -718,56 +612,17 @@ function _pow2(bits) {
   return v;
 }
 
-var _DH_MAX = _pow2(8 * constants.LIMITS.DH_MAX_MODULUS_BYTES);
-
 /** @internal The smallest modulus a group may be agreed in, and the smallest order a q may name. */
 var _DH_MIN_P = _pow2(8 * constants.LIMITS.DH_MIN_MODULUS_BYTES - 1);
 var _DH_MIN_Q = _pow2(8 * constants.LIMITS.DH_MIN_SUBGROUP_BYTES - 1);
 
-/** @internal Whether a value is prime, remembered across calls. Proving a 4096-bit modulus prime
- * costs seconds, and an enrollment run asks the same question of the same group every time: the
- * authority's parameters do not change between requests, and the requester's key must share them.
- * What is remembered is a fact about a number rather than anything a caller supplied, so a hit is
- * the same answer the test would give. The map is capped and cleared wholesale when it fills, which
- * bounds it without giving a caller a way to decide what stays. */
-var _PRIME_MEMO = new intrinsic.Map();
-var _PRIME_MEMO_N = 0;
-
-function _isPrime(n) {
-  var hit = intrinsic.mapGet(_PRIME_MEMO, n);
-  if (hit !== undefined) return hit;
-  var answer = _checkPrimeSync(_bigToBuf(n));
-  if (_PRIME_MEMO_N >= constants.LIMITS.DH_PRIME_MEMO_ENTRIES) {
-    _PRIME_MEMO = new intrinsic.Map();
-    _PRIME_MEMO_N = 0;
-  }
-  intrinsic.mapSet(_PRIME_MEMO, n, answer);
-  _PRIME_MEMO_N++;
-  return answer;
-}
-
-/** @internal A non-negative BigInt as the big-endian bytes the runtime's primality test reads. */
-function _bigToBuf(n) {
-  var len = 0, v = n;
-  while (v > 0n) { len++; v >>= 8n; }
-  if (len === 0) len = 1;
-  var buf = intrinsic.bufferAlloc(len);
-  v = n;
-  for (var i = len - 1; i >= 0; i--) { buf[i] = Number(v & 0xffn); v >>= 8n; }
-  return buf;
-}
+/** @internal Whether a value is prime: the key module's test, remembered there across calls, since
+ * an enrollment run asks the same question of the same group every time. */
+var _isPrime = key.isPrime;
 
-/** @internal b^e mod m by square and multiply. The exponent is a public domain parameter and the
- * base a public key, so no operand here is secret and the loop is not written to hide one. */
-function _modPow(base, exp, mod) {
-  var result = 1n, b = base % mod, e = exp;
-  while (e > 0n) {
-    if (e & 1n) result = (result * b) % mod;
-    e >>= 1n;
-    b = (b * b) % mod;
-  }
-  return result;
-}
+/** @internal b^e mod m, the key module's. The exponent is a public domain parameter and the base a
+ * public key, so no operand here is secret and the loop is not written to hide one. */
+var _modPow = key.modPow;
 
 /** @internal An X.509 Diffie-Hellman certificate names dhpublicnumber and carries X9.42
  * DomainParameters (RFC 3279 sec. 2.3.3), where this runtime classifies only the PKCS#3 DHParameter
@@ -981,7 +836,38 @@ function _buildEncryptedKeyPop(pop, outerTag, template) {
   }
 }
 
+async function _assertEnclosedKeyCorresponds(privateKeyDer, templateSpki) {
+  var pair;
+  try {
+    pair = await key.correspondsTo(privateKeyDer, templateSpki);
+  } catch (e) {
+    if (e instanceof CrmfError) throw e;
+    /** @internal A key the key module cannot read at all is bad input; one it reads and cannot
+     * exercise together with the template's key proves possession of nothing, which is the proof
+     * failing, not the input. */
+    if (e && e.isPkiError === true && e.code === "key/bad-input") {
+      throw _err("crmf/bad-input", "pop.privateKey could not be read as a private key to check against " +
+        "certTemplate.publicKey: " + (e.message || e), e);
+    }
+    throw _err("crmf/bad-popo", "the private key enclosed in the encryptedKey proof of possession could not be " +
+      "exercised with certTemplate.publicKey, so it cannot be shown to be that key's private half (RFC 4211 sec. 4.2)", e);
+  }
+  if (pair !== true) {
+    throw _err("crmf/bad-popo", "the private key enclosed in the encryptedKey proof of possession is not the " +
+      "private half of certTemplate.publicKey, so it proves possession of a key this request does not ask to " +
+      "have certified (RFC 4211 sec. 4.2)");
+  }
+}
+
 function _assertEnclosedKeyMatches(privateKeyDer, templateSpki) {
+  /** @internal Which proof the enclosed key takes depends on what its structure can carry. A
+   * finite-field PrivateKeyInfo carries the exponent alone, so the public value derived from it IS
+   * the proof, and this arm keeps that derivation at any width, with the cheap tests below. Every
+   * other family's private structure carries public components of its own (RFC 5958 sec. 2,
+   * RFC 5915, PKCS #1), which a caller could set to the template's beside private material that
+   * cannot use it, so those are proven by USING the key against the template. */
+  var enclosedAlg = key.algorithmOidAt(privateKeyDer, 1);
+  if (enclosedAlg !== null && !key.isDhOid(enclosedAlg)) return _assertEnclosedKeyCorresponds(privateKeyDer, templateSpki);
   return Promise.resolve()
     .then(function () { return key.publicFromPrivate(privateKeyDer); })
     .then(function (derivedSpki) {
@@ -1136,7 +1022,9 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  *   intended, so it takes `pop.archive: true`; `pop.privateKey` is the PKCS#8 DER, `pop.recipients` the CMS
  *   recipients to envelope it to, and `pop.identifier` (a string or GeneralName) is required, because
  *   sec. 4.2.1 makes it mandatory whenever the purpose is proving possession: without it a decrypting
- *   agent cannot tell whose key it holds. `pop.contentEncryptionAlgorithm` defaults to `aes-256-cbc`; an
+ *   agent cannot tell whose key it holds. The enclosed key is proven the private half of
+ *   `certTemplate.publicKey` with the key itself (`crmf/bad-popo` when it is not), not by the public
+ *   components its structure states. `pop.contentEncryptionAlgorithm` defaults to `aes-256-cbc`; an
  *   AEAD algorithm is refused, since it would produce an `AuthEnvelopedData` this field cannot carry.
  * - `agreeMAC`, which agrees a secret with the authority and MACs the request under a key derived from it,
  *   so nothing is signed (RFC 4211 sec. 4.3, RFC 2875 sec. 3). `pop.key` is the requester's finite-field

package/lib/est.js

@@ -1742,6 +1742,18 @@ async function _serverkeygenResult(res, opts, derived) {
     var bound = findIssuedCert(out.certificates, spki);
     if (!bound) throw E("est/key-cert-mismatch", "the cleartext server-generated private key matches no returned certificate's public key (RFC 7030 sec. 4.4.2)");
     if (findIssuedCert(out.certificates.filter(function (c) { return c !== bound; }), spki)) throw E("est/ambiguous-issued-cert", "more than one returned certificate carries the server-generated key; the issued certificate is ambiguous (RFC 7030 sec. 4.4.2)");
+    /** @internal The public half the key states selected the certificate; the pair is then proven
+     * with the PRIVATE half, since a private structure states public components of its own that a
+     * server could set to the certificate's beside private material that cannot use it. A
+     * finite-field Diffie-Hellman PrivateKeyInfo carries the exponent alone, so the value derived
+     * from it above IS the proof, at any width the runtime reads. */
+    var keyAlg = key.algorithmOidAt(out.privateKeyDer, 1);
+    if (keyAlg === null || !key.isDhOid(keyAlg)) {
+      var pair;
+      try { pair = await key.correspondsTo(out.privateKeyDer, spki); }
+      catch (e2) { throw E("est/key-cert-mismatch", "the cleartext server-generated private key could not be exercised with the returned certificate's public key, so the two cannot be shown to be a pair (RFC 7030 sec. 4.4.2)", e2); }
+      if (pair !== true) throw E("est/key-cert-mismatch", "the cleartext server-generated private key is not the private half of the returned certificate's public key (RFC 7030 sec. 4.4.2)");
+    }
     delete out.privateKeyDer;
   }
   return out;
@@ -1765,7 +1777,9 @@ async function _serverkeygenResult(res, opts, derived) {
  * the key so the issued certificate's public key is the generated one, not the throwaway CSR key. A cleartext
  * key is bound to its certificate before it resolves: the delivered private key's public half MUST match
  * exactly one returned certificate (`est/key-cert-mismatch` on none, `est/ambiguous-issued-cert` on more than
- * one), so a mis-associated key is refused, never handed back unusable.
+ * one), and the key is then proven the private half of that certificate's public key with the key itself
+ * (`est/key-cert-mismatch` when it is not; a finite-field DH key, whose structure carries the exponent alone,
+ * is proven by the value it derives), so a mis-associated or unusable key is refused, never handed back.
  * The encryption requirement + expected recipient are derived from the CSR's own DecryptKeyIdentifier /
  * AsymmetricDecryptKeyIdentifier attribute; an `opts` value that contradicts the CSR is `est/bad-input`
  * (a cleartext-key downgrade cannot slip past). The delivered key's channel is asserted confidentiality-

package/lib/key.js

@@ -21,10 +21,12 @@
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
+var constants = require("./constants");
 var oid = require("./oid");
 var pbes2 = require("./pbes2");
 var pkcs8 = require("./schema-pkcs8");
 var pkix = require("./schema-pkix");
+var schema = require("./schema-engine");
 var webcrypto = require("./webcrypto");
 var compositeKem = require("./composite-kem");
 var frameworkError = require("./framework-error");
@@ -32,6 +34,7 @@ var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
 var _assign = intrinsic.assign;
 var _create = intrinsic.create;
+var _keyEquals = intrinsic.uncurry(nodeCrypto.KeyObject.prototype.equals);
 var _isArray = intrinsic.isArray;
 var _bufferFrom = intrinsic.bufferFrom;
 var _floor = intrinsic.floor;
@@ -349,20 +352,412 @@ var _PUBLIC_FROM_PRIVATE_OPTS = _assign(_create(null), { pem: 1 });
  * from the AlgorithmIdentifier alone: a key that is not well formed enough to state one is left to the
  * decoder below, which reports it. */
 function _compositeKemOidOf(der) {
+  var algOid = _algorithmOidAt(der, 1);
+  return algOid !== null && compositeKem.isCompositeKem(algOid) ? algOid : null;
+}
+
+/** @internal The AlgorithmIdentifier OID a key structure names, read without the structure's strict
+ * rules: `at` 1 for a OneAsymmetricKey (version first), 0 for a SubjectPublicKeyInfo. A structure that
+ * cannot state one yields null and is left to the decoder that reports it. Reading loosely matters for
+ * a composite key: one that breaks a OneAsymmetricKey rule is still a composite key, and the module
+ * that owns the algorithm is the one that should say so, since the runtime decoder would report that
+ * it cannot read the key rather than that the parameters are not allowed (draft sec. 5.3). */
+function _algorithmOidAt(der, at) {
   var algOid;
   try {
-    /** @internal The AlgorithmIdentifier OID only, read without the strict OneAsymmetricKey rules. A
-     * composite key that breaks one of those rules is still a composite key, and the module that owns
-     * the algorithm is the one that should say so: parsing strictly here would send a composite key
-     * carrying parameters to the runtime decoder, which reports that it cannot read the key rather
-     * than that the parameters are not allowed (draft sec. 5.3). */
     var node = asn1.decode(der);
-    if (!node.children || node.children.length < 3) return null;
-    var alg = node.children[1];
+    if (!node.children || node.children.length <= at) return null;
+    var alg = node.children[at];
     if (!alg.children || alg.children.length < 1) return null;
     algOid = asn1.read.oid(alg.children[0]);
-  } catch (_e) { return null; }
-  return typeof algOid === "string" && compositeKem.isCompositeKem(algOid) ? algOid : null;
+  } catch (_e) { return null; } // allow:swallow-unverified a structure that states no algorithm is refused by the decoder it stands before
+  return typeof algOid === "string" ? algOid : null;
+}
+
+var _OID_DH_X942 = oid.byName("dhpublicnumber");
+var _OID_DH_PKCS3 = oid.byName("dhKeyAgreement");
+var _isUniversal = schema.isUniversal;
+
+/** @internal Whether an algorithm identifier names a finite-field Diffie-Hellman key in either of
+ * its encodings. */
+function _isDhOid(algOid) {
+  return algOid === _OID_DH_X942 || algOid === _OID_DH_PKCS3;
+}
+
+/** @internal ValidationParms is SEQUENCE { seed BIT STRING, pgenCounter INTEGER } (RFC 3279
+ * sec. 2.3.3). The conversion drops it, so reading it is the only thing that answers for it: a key
+ * whose parameters do not hold the two fields is malformed rather than merely carrying something the
+ * conversion does not need, and the counter is the count of a generation procedure, so a negative
+ * one is malformed too. */
+function _validationParms(node, ErrorClass, code, what) {
+  var kids = node.children;
+  if (!_isUniversal(node, 16) || !kids || kids.length !== 2 ||
+      !_isUniversal(kids[0], 3) || !_isUniversal(kids[1], 2)) {
+    throw new ErrorClass(code, what + " X9.42 validationParms is not a seed BIT STRING with a pgenCounter INTEGER");
+  }
+  asn1.read.bitString(kids[0]);
+  if (asn1.read.integer(kids[1]) < 0n) {
+    throw new ErrorClass(code, what + " X9.42 validationParms states a negative pgenCounter");
+  }
+}
+
+/** @internal The p, g, q and cofactor an X9.42 DomainParameters states. DomainParameters is
+ * SEQUENCE { p, g, q, j OPTIONAL, validationParms OPTIONAL } (RFC 3279 sec. 2.3.3), and the PKCS #3
+ * form the runtime classifies carries none of the last three, so every field is read HERE, before
+ * the conversion that drops it. Both halves of a finite-field key carry this structure and both take
+ * that conversion, so both read it in this one place: a field read on one side and skipped on the
+ * other is a key refused in the encoding it was handed and admitted in the one it was rewritten
+ * into. The algorithm named dhpublicnumber, so these bytes are DomainParameters or the key is
+ * malformed; there is no third reading that would let a shape this does not recognize travel on.
+ * Errors are the caller's: `new ErrorClass(code, message)`, the message led by `what`. */
+function x942Domain(paramsNode, ErrorClass, code, what) {
+  var domain = asn1.decode(paramsNode.bytes);
+  if (!_isUniversal(domain, 16) || !domain.children ||
+      domain.children.length < 3 || domain.children.length > 5) {
+    throw new ErrorClass(code, what + " X9.42 domain parameters are not a DomainParameters SEQUENCE of p, g and q with at most two optional fields after them");
+  }
+  var out = {
+    p: asn1.read.integer(domain.children[0]),
+    g: asn1.read.integer(domain.children[1]),
+    q: asn1.read.integer(domain.children[2]),
+    j: null,
+  };
+  /** @internal j and validationParms are independently optional, so a fourth field is told apart by
+   * its tag rather than by its position: an INTEGER is the cofactor and a SEQUENCE is the validation
+   * parameters, which may appear with no cofactor before them. */
+  if (domain.children.length >= 4) {
+    var opt = domain.children[3];
+    if (_isUniversal(opt, 2)) {
+      out.j = asn1.read.integer(opt);
+      if (domain.children.length === 5) _validationParms(domain.children[4], ErrorClass, code, what);
+    } else if (_isUniversal(opt, 16)) {
+      if (domain.children.length === 5) {
+        throw new ErrorClass(code, what + " X9.42 domain parameters carry a field after validationParms");
+      }
+      _validationParms(opt, ErrorClass, code, what);
+    } else {
+      throw new ErrorClass(code, what + " X9.42 domain parameters carry a fourth field that is neither a cofactor nor validationParms");
+    }
+  }
+  return out;
+}
+
+/** @internal One past the largest Diffie-Hellman operand the toolkit computes with: the largest group
+ * it agrees over. Built once, as two raised to a count of BITS, so the bound states the width it is
+ * named for. */
+var _DH_MAX = (function () {
+  var v = 1n;
+  for (var i = 0; i < 8 * constants.LIMITS.DH_MAX_MODULUS_BYTES; i++) v <<= 1n;
+  return v;
+}());
+
+/** @internal Whether every Diffie-Hellman operand in `values` (a null is an absent one) is below the
+ * largest group the toolkit agrees over. The tests whose cost grows with the operands, a modular
+ * exponentiation and a primality proof, run only after this has answered; a path that reads a key
+ * without bounding its size, such as one that archives rather than agrees, does not ask it. Errors
+ * are the caller's, as in `x942Domain`. */
+function assertDhOperandsWithin(values, ErrorClass, code, what) {
+  for (var i = 0; i < values.length; i++) {
+    if (values[i] !== null && values[i] >= _DH_MAX) {
+      throw new ErrorClass(code, what + " parameters are larger than any Diffie-Hellman group this toolkit agrees over (" +
+        constants.LIMITS.DH_MAX_MODULUS_BYTES + " bytes)");
+    }
+  }
+}
+
+/** @internal base to the power exp, modulo mod, by square-and-multiply on BigInts. */
+function modPow(base, exp, mod) {
+  var result = 1n, b = base % mod, e = exp;
+  while (e > 0n) {
+    if (e & 1n) result = (result * b) % mod;
+    e >>= 1n;
+    b = (b * b) % mod;
+  }
+  return result;
+}
+
+/** @internal Whether a stated order is one g has: g raised to q is 1 modulo p, which says the order
+ * of g divides q. This is one modular exponentiation, so it is asked only of operands already bounded
+ * by `assertDhOperandsWithin`, and after `assertDhDomainCoherent` has answered the cheaper questions.
+ * Whether q IS the order rather than a multiple of it is `assertDhOrderPrime`. Errors are the
+ * caller's. */
+function assertDhGeneratorOrder(p, g, q, ErrorClass, code, what) {
+  if (modPow(g, q, p) !== 1n) {
+    throw new ErrorClass(code, what + " X9.42 domain parameters state a subgroup order its own p and g do not have");
+  }
+}
+
+/** @internal Whether a value is prime, by the runtime's test, remembered across calls. Proving a
+ * 4096-bit modulus prime costs seconds, and the question is asked of the same group every time:
+ * a certifying authority's parameters do not change between the keys it issues, and an enrollment
+ * run asks it of the same group per request. What is remembered is a fact about a number rather
+ * than anything a caller supplied, so a hit is the same answer the test would give. The map is
+ * capped and cleared wholesale when it fills, which bounds it without giving a caller a way to
+ * decide what stays. Asked only of operands already bounded by `assertDhOperandsWithin`. */
+var _PRIME_MEMO = new intrinsic.Map();
+var _PRIME_MEMO_N = 0;
+var _checkPrimeSync = nodeCrypto.checkPrimeSync;
+
+function isPrime(n) {
+  var hit = intrinsic.mapGet(_PRIME_MEMO, n);
+  if (hit !== undefined) return hit;
+  var answer = _checkPrimeSync(_bigToBuf(n));
+  if (_PRIME_MEMO_N >= constants.LIMITS.DH_PRIME_MEMO_ENTRIES) {
+    _PRIME_MEMO = new intrinsic.Map();
+    _PRIME_MEMO_N = 0;
+  }
+  intrinsic.mapSet(_PRIME_MEMO, n, answer);
+  _PRIME_MEMO_N++;
+  return answer;
+}
+
+/** @internal A non-negative BigInt as the big-endian bytes the runtime's primality test reads. */
+function _bigToBuf(n) {
+  var len = 0, v = n;
+  while (v > 0n) { len++; v >>= 8n; }
+  if (len === 0) len = 1;
+  var buf = intrinsic.bufferAlloc(len);
+  v = n;
+  for (var i = len - 1; i >= 0; i--) { buf[i] = intrinsic.Number(v & 0xffn); v >>= 8n; }
+  return buf;
+}
+
+/** @internal Whether a Diffie-Hellman modulus is prime; a composite one describes no group. */
+function assertDhModulusPrime(p, ErrorClass, code, what) {
+  if (!isPrime(p)) {
+    throw new ErrorClass(code, what + " Diffie-Hellman modulus is not prime, so the group its parameters describe does not exist");
+  }
+}
+
+/** @internal Whether a public value lies in the subgroup its parameters state: y raised to q is 1
+ * modulo p. A value outside it agrees a secret that exposes the private exponent of whichever side
+ * agrees, modulo the small order the value does have. One modular exponentiation, asked of bounded
+ * operands after the order itself was proven. Errors are the caller's. */
+function assertDhValueInSubgroup(p, q, y, ErrorClass, code, what) {
+  if (modPow(y, q, p) !== 1n) {
+    throw new ErrorClass(code, what + " Diffie-Hellman public value is not in the subgroup its own domain parameters state, so agreeing with it would expose the private exponent of whichever side agrees");
+  }
+}
+
+/** @internal Whether a stated subgroup order is prime. `assertDhGeneratorOrder` proved the order of
+ * g divides q; only a prime q makes that order exactly q, so a q that is a multiple of the order
+ * (p-1 beside a g of order (p-1)/2 satisfies g^q = 1) names a subgroup the key need not have. */
+function assertDhOrderPrime(q, ErrorClass, code, what) {
+  if (!isPrime(q)) {
+    throw new ErrorClass(code, what + " X9.42 domain parameters state a subgroup order that is not prime, so a public value in it need not have that order");
+  }
+}
+
+/** @internal Whether a stated order and cofactor describe the p and g stated beside them. These are
+ * the tests that answer that question with a comparison, a multiplication and a modulo, so their cost
+ * grows gently with the modulus and every path that reads these parameters can afford them, bounded
+ * or not; the tests whose cost grows with the modulus, a modular exponentiation and two primality
+ * proofs, are asked separately of bounded operands. A cofactor states (p-1)/q, so a cofactor with no
+ * order beside it states nothing. Errors are the caller's, as in `x942Domain`. */
+function assertDhDomainCoherent(p, g, q, j, ErrorClass, code, what) {
+  if (p <= 2n || g <= 1n || g >= p - 1n) {
+    throw new ErrorClass(code, what + " parameters are not a Diffie-Hellman group");
+  }
+  /** @internal Each operand's sign is decided before the multiplication and the modulo that take it:
+   * a bound on these is an upper one, and a negative order or cofactor of any width would otherwise
+   * be multiplied before it is refused. */
+  if (j !== null && (q === null || j <= 0n || q <= 0n || j * q !== p - 1n)) {
+    throw new ErrorClass(code, what + " X9.42 cofactor does not match its own p and q");
+  }
+  if (q !== null && (q <= 1n || (p - 1n) % q !== 0n)) {
+    throw new ErrorClass(code, what + " X9.42 domain parameters state a subgroup order its own p and g do not have");
+  }
+}
+
+/** @internal The p and g a PKCS #3 DHParameter states, read strictly. DHParameter is SEQUENCE
+ * { prime, base, privateValueLength OPTIONAL } (PKCS #3 sec. 9); the one optional field is an
+ * INTEGER stating how many bits the private value has, so it is a positive count no longer than the
+ * modulus's own bit count, which the encoded size bounds before anything is shifted by it, since
+ * the codec admits an INTEGER at any width and a caller that archives a key does not bound its
+ * modulus. Errors are the caller's, as in `x942Domain`. */
+function _dhParameter(paramsNode, ErrorClass, code, what) {
+  var prm = asn1.decode(paramsNode.bytes);
+  if (!_isUniversal(prm, 16) || !prm.children || prm.children.length < 2 || prm.children.length > 3) {
+    throw new ErrorClass(code, what + " PKCS#3 Diffie-Hellman parameters are not a DHParameter SEQUENCE");
+  }
+  var p = asn1.read.integer(prm.children[0]);
+  if (prm.children.length === 3) {
+    if (!_isUniversal(prm.children[2], 2)) {
+      throw new ErrorClass(code, what + " PKCS#3 privateValueLength is not an INTEGER");
+    }
+    var pvl = asn1.read.integer(prm.children[2]);
+    if (pvl <= 0n) {
+      throw new ErrorClass(code, what + " PKCS#3 privateValueLength is not a positive length");
+    }
+    if (pvl > intrinsic.BigInt(prm.children[0].bytes.length) * 8n || (1n << (pvl - 1n)) > p) {
+      throw new ErrorClass(code, what + " PKCS#3 privateValueLength states a private value longer than its own modulus, which no value in the group is");
+    }
+  }
+  return { p: p, g: asn1.read.integer(prm.children[1]) };
+}
+
+/** @internal The p, g and public value of a PKCS #3 dhKeyAgreement SubjectPublicKeyInfo, or null
+ * when the key is not in that form. The parameters state no subgroup order, so the group they
+ * describe is checked without one. A structure that names the algorithm and cannot be read as the
+ * key is refused in the caller's class. */
+function pkcs3Params(spkiBytes, ErrorClass, code, what) {
+  if (_algorithmOidAt(spkiBytes, 0) !== _OID_DH_PKCS3) return null;
+  var node = asn1.decode(spkiBytes);
+  try {
+    var alg = node.children[0];
+    if (!alg.children || alg.children.length !== 2 || node.children.length !== 2) {
+      throw new ErrorClass(code, what + " PKCS#3 Diffie-Hellman key is not an AlgorithmIdentifier with parameters and a public key");
+    }
+    var dom = _dhParameter(alg.children[1], ErrorClass, code, what);
+    var pub = asn1.read.bitString(node.children[1]);
+    if (!guard.crypto.isOctetAligned(pub)) {
+      throw new ErrorClass(code, what + " Diffie-Hellman public key BIT STRING must be octet-aligned (0 unused bits)");
+    }
+    return { p: dom.p, g: dom.g, y: asn1.read.integer(asn1.decode(pub.bytes)) };
+  } catch (e) {
+    if (e instanceof ErrorClass) throw e;
+    throw new ErrorClass(code, what + " PKCS#3 Diffie-Hellman key could not be read", e);
+  }
+}
+
+/** @internal The p, g and private exponent of a PKCS #3 dhKeyAgreement PrivateKeyInfo, read to the
+ * same shape as its public half; null when the key is not in that form. */
+function _pkcs3Private(der, what) {
+  if (_algorithmOidAt(der, 1) !== _OID_DH_PKCS3) return null;
+  var node = asn1.decode(der);
+  try {
+    var alg = node.children[1];
+    if (!alg.children || alg.children.length !== 2 || !node.children[2]) {
+      throw _err("key/bad-input", what + " PKCS#3 Diffie-Hellman key is not an AlgorithmIdentifier with parameters and a private key");
+    }
+    var dom = _dhParameter(alg.children[1], KeyError, "key/bad-input", what);
+    return { p: dom.p, g: dom.g, x: asn1.read.integer(asn1.decode(asn1.read.octetString(node.children[2]))) };
+  } catch (e) {
+    if (e instanceof KeyError) throw e;
+    throw _err("key/bad-input", what + " PKCS#3 Diffie-Hellman key could not be read", e);
+  }
+}
+
+/** @internal A Diffie-Hellman structure in the PKCS #3 form (every DH key is one by the time this
+ * reads it), held to the toolkit's group bound and to being a group before the runtime imports it:
+ * the import derives or compares a public value by modular exponentiation whose cost is the width
+ * of p and of the exponent, and a delivered key states any width it likes. So p, g and the value
+ * the structure carries (the private exponent at `at` 1, the public value at `at` 0) are capped at
+ * the largest group the toolkit agrees over, the cap that every other path computing in a DH group
+ * applies; p and g are then held to describing a group and p to being prime, whichever encoding
+ * the key arrived in, so a structure the X9.42 rewrite never saw answers the same questions; and a
+ * private exponent is held inside its group: at least 1 and below p (RFC 2631 sec. 2.2 narrows it
+ * to [2, q-2], which is the agreement's test). Anything that is not a DH structure is left alone. */
+function _assertDhWithin(der, at, what) {
+  var read = at === 0 ? pkcs3Params(der, KeyError, "key/bad-input", what) : _pkcs3Private(der, what);
+  if (read === null) return;
+  var value = at === 0 ? read.y : read.x;
+  assertDhOperandsWithin([read.p, read.g, value], KeyError, "key/bad-input", what);
+  assertDhDomainCoherent(read.p, read.g, null, null, KeyError, "key/bad-input", what);
+  assertDhModulusPrime(read.p, KeyError, "key/bad-input", what);
+  if (at === 1 && (value <= 0n || value >= read.p)) {
+    throw _err("key/bad-input", what + " Diffie-Hellman private exponent is outside its own group");
+  }
+  if (at === 0 && (value <= 1n || value >= read.p - 1n)) {
+    throw _err("key/bad-input", what + " Diffie-Hellman public value is outside the group (RFC 2875 sec. 3)");
+  }
+}
+
+/** @internal One finite-field Diffie-Hellman key in the encoding the runtime classifies. A certificate
+ * names a DH key in the X9.42 form (RFC 3279 sec. 2.3.3: `dhpublicnumber` with DomainParameters
+ * { p, g, q, j, validationParms }), while a generated key is written in the PKCS #3 form
+ * (`dhKeyAgreement` with DHParameter { p, g, privateValueLength }); both carry the value itself as one
+ * INTEGER. The runtime reads the X9.42 form as a key of no type, which would call the two halves
+ * different families, so an X9.42 structure is rewritten with the PKCS #3 identifier over the same
+ * p, g and value. The order and cofactor the rewrite drops are read first and held to the p and g
+ * beside them, since the PKCS #3 form cannot carry them and nothing after this reads them: a
+ * DomainParameters that omits q or states one its own p contradicts is a malformed key, refused
+ * whatever value it carries. Anything not X9.42 is returned as given. */
+function _dhAsPkcs3(der, at, what) {
+  if (_algorithmOidAt(der, at) !== _OID_DH_X942) return der;
+  var node = asn1.decode(der);
+  var algNode = node.children[at];
+  if (!algNode.children || algNode.children.length !== 2) {
+    throw _err("key/bad-input", what + " X9.42 AlgorithmIdentifier does not carry DomainParameters");
+  }
+  /** @internal A field the codec refuses to read as the type the structure states is a malformed
+   * key, reported as one rather than as the codec's own complaint. */
+  var dom, y = null;
+  try {
+    dom = x942Domain(algNode.children[1], KeyError, "key/bad-input", what);
+    if (at === 0) {
+      var pub = asn1.read.bitString(node.children[1]);
+      if (!guard.crypto.isOctetAligned(pub)) {
+        throw _err("key/bad-input", what + " Diffie-Hellman public key BIT STRING must be octet-aligned (0 unused bits)");
+      }
+      y = asn1.read.integer(asn1.decode(pub.bytes));
+    }
+  } catch (e) {
+    if (e instanceof KeyError) throw e;
+    throw _err("key/bad-input", what + " X9.42 Diffie-Hellman key could not be read", e);
+  }
+  assertDhOperandsWithin([dom.p, dom.g, dom.q, dom.j], KeyError, "key/bad-input", what);
+  assertDhDomainCoherent(dom.p, dom.g, dom.q, dom.j, KeyError, "key/bad-input", what);
+  assertDhGeneratorOrder(dom.p, dom.g, dom.q, KeyError, "key/bad-input", what);
+  assertDhModulusPrime(dom.p, KeyError, "key/bad-input", what);
+  assertDhOrderPrime(dom.q, KeyError, "key/bad-input", what);
+  /** @internal The one field the X9.42 form states that the PKCS #3 form cannot be held to is the
+   * subgroup, so a public value is held to it here, where q is still known. */
+  if (at === 0) {
+    if (y <= 1n || y >= dom.p - 1n) {
+      throw _err("key/bad-input", what + " Diffie-Hellman public value is outside the group (RFC 2875 sec. 3)");
+    }
+    assertDhValueInSubgroup(dom.p, dom.q, y, KeyError, "key/bad-input", what);
+  }
+  var alg = b.sequence([b.oid(_OID_DH_PKCS3), b.sequence([b.integer(dom.p), b.integer(dom.g)])]);
+  var fields = [];
+  for (var i = 0; i < node.children.length; i++) guard.list.append(fields, i === at ? alg : b.raw(node.children[i].bytes));
+  return b.sequence(fields);
+}
+
+/** @internal Whether a composite ML-KEM private key and a SubjectPublicKeyInfo are one pair: a secret
+ * encapsulated to the public key decapsulates under the private key to the same value only for the
+ * pair. The toolkit's own KEM stands in for the runtime here because the runtime cannot read the
+ * algorithm; every secret the probe makes is wiped on every way out. A public key of another
+ * algorithm, composite or not, is another family and not a pair. */
+async function _compositeCorrespondsTo(privDer, spkiDer, privateOid) {
+  /** @internal The private half is read first, as on the classical route: a composite key the KEM
+   * cannot read is bad input whatever the public half names, decided before the family shortcut
+   * answers that the two are not a pair. The derivation's result is not what is compared; the
+   * read is what it answers for. */
+  try { await compositeKem.publicFromPrivate(privDer); }
+  catch (e0) {
+    if (_isKemStructureFault(e0)) throw _err("key/bad-input", "the private key could not be read", e0);
+    throw _err("key/unsupported-algorithm", "the key pair could not be exercised to decide whether its two halves correspond", e0);
+  }
+  if (_algorithmOidAt(spkiDer, 0) !== privateOid) return false;
+  var sealed = null, opened = null;
+  try {
+    /** @internal A structure the KEM cannot read is bad input, the verdict an unreadable classical
+     * key gets from the runtime import above; a decapsulation that runs and fails is the pair not
+     * deciding. The KEM tells the two apart by its own codes, and so does this. */
+    try { sealed = await compositeKem.encapsulate(spkiDer); }
+    catch (e) {
+      if (_isKemStructureFault(e)) throw _err("key/bad-input", "the public key could not be read", e);
+      throw _err("key/unsupported-algorithm", "the key pair could not be exercised to decide whether its two halves correspond", e);
+    }
+    try { opened = await compositeKem.decapsulate(privDer, sealed.ciphertext); }
+    catch (e2) {
+      if (_isKemStructureFault(e2)) throw _err("key/bad-input", "the private key could not be read", e2);
+      throw _err("key/unsupported-algorithm", "the key pair could not be exercised to decide whether its two halves correspond", e2);
+    }
+    return guard.crypto.constantTimeEqual(opened, sealed.sharedSecret);
+  } finally {
+    guard.secret.zeroizeAll([sealed && sealed.sharedSecret, opened], KeyError, "key/bad-input", "the correspondence probe secrets");
+  }
+}
+
+var _KEM_STRUCTURE_FAULTS = _assign(_create(null), { "kem/bad-key": 1, "kem/bad-input": 1, "kem/bad-algorithm": 1, "kem/bad-ciphertext": 1 });
+
+/** @internal Whether a KEM error says the key or ciphertext could not be READ, as opposed to a
+ * decapsulation that ran and failed. */
+function _isKemStructureFault(e) {
+  return !!(e && e.isPkiError === true && _KEM_STRUCTURE_FAULTS[guard.text.keyOf(e.code)] === 1);
 }
 
 async function publicFromPrivate(privateKey, opts) {
@@ -399,8 +794,10 @@ async function publicFromPrivate(privateKey, opts) {
  *
  * So the pair is proven by USING it, on whichever operation the key type can perform: a signature the
  * public half verifies, a Diffie-Hellman agreement that reaches the same secret from both sides, or a
- * key encapsulation the private half decapsulates to the same secret. Each fails for a key that merely
- * claims the public half.
+ * key encapsulation the private half decapsulates to the same secret (the toolkit's own KEM for a
+ * composite ML-KEM key the runtime cannot read). Each fails for a key that merely claims the public
+ * half. A finite-field DH key, whose private structure carries the exponent alone, is proven by the
+ * value the exponent generates, in either of its two encodings (PKCS #3 or X9.42).
  *
  * What a true answer means is exactly that: the private key WORKS with this public key, on the
  * operation its type performs. It is not a statement that every field of the private structure is
@@ -499,23 +896,60 @@ function _pssSalt(a, b) {
 
 async function correspondsTo(privateKey, spkiDer) {
   var privDer = await _toPrivateKeyDer(privateKey);
+  var spki = _bufferFrom(spkiDer);
+  var compositeOid = _compositeKemOidOf(privDer);
+  if (compositeOid !== null) return _compositeCorrespondsTo(privDer, spki, compositeOid);
+  /** @internal The private half is read FIRST, whatever the public half names: a private key that
+   * cannot be read is bad input, and a caller tells that apart from a pair that is not one. Only
+   * then is the family question asked, from the two identifiers, before the public structure is
+   * validated: a composite or a finite-field half against a half of another family is not a pair
+   * whatever it states, so the runtime is never asked to read a structure it cannot, and a DH
+   * structure's validation, which proves its modulus prime, is never run to say so. */
   var priv, pub;
-  try { priv = nodeCrypto.createPrivateKey({ key: privDer, format: "der", type: "pkcs8" }); }
-  catch (e) { throw _err("key/bad-input", "the private key could not be read", e); }
-  try { pub = nodeCrypto.createPublicKey({ key: _bufferFrom(spkiDer), format: "der", type: "spki" }); }
+  /** @internal The PKCS #3 rewrite of an X9.42 private key is this function's own copy of the
+   * exponent, wiped once the runtime holds the key. */
+  var privAsPkcs3 = _dhAsPkcs3(privDer, 1, "the private key's");
+  try {
+    _assertDhWithin(privAsPkcs3, 1, "the private key's");
+    try { priv = nodeCrypto.createPrivateKey({ key: privAsPkcs3, format: "der", type: "pkcs8" }); }
+    catch (e) { throw _err("key/bad-input", "the private key could not be read", e); }
+  } finally { if (privAsPkcs3 !== privDer) guard.secret.zeroize(privAsPkcs3, KeyError, "key/bad-input", "the rewritten private key"); }
+  var publicOid = _algorithmOidAt(spki, 0);
+  if (publicOid !== null && compositeKem.isCompositeKem(publicOid)) return false;
+  if (_isDhOid(_algorithmOidAt(privDer, 1)) !== _isDhOid(publicOid)) return false;
+  var pubAsPkcs3 = _dhAsPkcs3(spki, 0, "the public key's");
+  _assertDhWithin(pubAsPkcs3, 0, "the public key's");
+  try { pub = nodeCrypto.createPublicKey({ key: pubAsPkcs3, format: "der", type: "spki" }); }
   catch (e) { throw _err("key/bad-input", "the public key could not be read", e); }
   if (!_sameKeyFamily(priv, pub)) return false;
   var kind = guard.text.keyOf(priv.asymmetricKeyType);
+  /** @internal Every secret a probe makes, wiped once the verdict is decided, on every way out. */
+  var secrets = [];
   try {
+    /** @internal A finite-field Diffie-Hellman PrivateKeyInfo carries the exponent alone (RFC 5958 /
+     * X9.42), no public copy a caller could plant, so the public value the exponent generates is a
+     * proof of the pair on its own; there is no signature to try and no fixed group to draw an
+     * ephemeral from. */
+    if (kind === "dh") {
+      /** @internal Compared as KEYS rather than as encodings: a PKCS #3 DHParameter may carry the
+       * optional privateValueLength beside the same p and g, and two encodings of one public value
+       * are one key. The runtime's equality compares the group and the value. */
+      return _keyEquals(nodeCrypto.createPublicKey(priv), pub) === true;
+    }
     if (_PAIR_KEM[kind]) {
       var sealed = nodeCrypto.encapsulate(pub);
-      return guard.crypto.constantTimeEqual(nodeCrypto.decapsulate(priv, sealed.ciphertext), sealed.sharedKey);
+      guard.list.append(secrets, sealed.sharedKey);
+      var opened = nodeCrypto.decapsulate(priv, sealed.ciphertext);
+      guard.list.append(secrets, opened);
+      return guard.crypto.constantTimeEqual(opened, sealed.sharedKey);
     }
     if (_PAIR_AGREE[kind]) {
       var ephemeral = nodeCrypto.generateKeyPairSync(priv.asymmetricKeyType);
-      if (!guard.crypto.constantTimeEqual(
-        nodeCrypto.diffieHellman({ privateKey: priv, publicKey: ephemeral.publicKey }),
-        nodeCrypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: pub }))) return false;
+      var ours = nodeCrypto.diffieHellman({ privateKey: priv, publicKey: ephemeral.publicKey });
+      guard.list.append(secrets, ours);
+      var theirs = nodeCrypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: pub });
+      guard.list.append(secrets, theirs);
+      if (!guard.crypto.constantTimeEqual(ours, theirs)) return false;
       /** @internal The agreement proves the SCALAR, not the encoding it was handed. RFC 7748 masks the
        * top bit of an X25519 u-coordinate before the ladder, so a public value differing from the real
        * one only in a masked bit reaches the same secret from both sides. The certificate would then
@@ -541,6 +975,8 @@ async function correspondsTo(privateKey, spkiDer) {
      * not be exercised without saying that the two encodings pin conflicting parameters. */
     if (e && e.code === "key/unsupported-algorithm" && e.isPkiError === true) throw e;
     throw _err("key/unsupported-algorithm", "the key pair could not be exercised to decide whether its two halves correspond", e);
+  } finally {
+    guard.secret.zeroizeAll(secrets, KeyError, "key/bad-input", "the correspondence probe secrets");
   }
 }
 
@@ -602,4 +1038,16 @@ module.exports = {
   generate: generate,
   publicFromPrivate: publicFromPrivate,
   correspondsTo: correspondsTo,   // @internal
+  x942Domain: x942Domain,   // @internal
+  pkcs3Params: pkcs3Params,   // @internal
+  isDhOid: _isDhOid,   // @internal
+  algorithmOidAt: _algorithmOidAt,   // @internal
+  assertDhOperandsWithin: assertDhOperandsWithin,   // @internal
+  assertDhDomainCoherent: assertDhDomainCoherent,   // @internal
+  assertDhGeneratorOrder: assertDhGeneratorOrder,   // @internal
+  assertDhModulusPrime: assertDhModulusPrime,   // @internal
+  assertDhOrderPrime: assertDhOrderPrime,   // @internal
+  assertDhValueInSubgroup: assertDhValueInSubgroup,   // @internal
+  isPrime: isPrime,   // @internal
+  modPow: modPow,   // @internal
 };

package/lib/pkcs12-build.js

@@ -382,6 +382,92 @@ function _specForm(spec) {
   return { isObject: isObject, full: full, safeContents: full ? safeContents : null };
 }
 
+/** @internal The convenience form pairs one key with one certificate, and a localKeyId pairs a key
+ *  bag with a certificate bag (PKCS #9 sec. 5.5.2: "the local key id ... links a certificate to a
+ *  private key"). A pair is held to being a KEY PAIR, the key's public half being the certificate's
+ *  subjectPublicKey, since a store that links a certificate to somebody else's key is one nothing
+ *  can use and the reader trusts the link. Bags of the full form pair across every safe. */
+function _collectPairBags(bags, depth, keyBags, certBags) {
+  if (!intrinsic.isArray(bags)) return;
+  if (bags.length > C.LIMITS.PKCS12_MAX_ELEMENTS) throw _err("pkcs12/bad-input", "a SafeContents exceeds the element cap " + C.LIMITS.PKCS12_MAX_ELEMENTS);
+  bags = pkiBuild.reqDenseArray(bags, "bags", _err, "pkcs12/bad-input");
+  for (var j = 0; j < bags.length; j++) {
+    var bag = bags[j];
+    if (!bag || typeof bag !== "object") continue;
+    if (bag.type === "safeContents") {
+      if (depth + 1 <= C.LIMITS.PKCS12_MAX_BAG_DEPTH) _collectPairBags(bag.nested, depth + 1, keyBags, certBags);
+      continue;
+    }
+    if (bag.localKeyId == null || bag.localKeyId === "ski") continue;
+    if (bag.type === "key" || bag.type === "shroudedKey") guard.list.append(keyBags, bag);
+    else if (bag.type === "cert") guard.list.append(certBags, bag);
+  }
+}
+async function _assertKeyPairs(spec, form, safeContentsSpecs) {
+  var pairs = [];
+  if (!form.full) {
+    if (spec.key != null && spec.cert != null) guard.list.append(pairs, { key: spec.key, cert: spec.cert, what: "the { key, cert } pair" });
+  } else {
+    var keyBags = [], certBags = [];
+    for (var i = 0; i < safeContentsSpecs.length; i++) {
+      _collectPairBags(safeContentsSpecs[i] && safeContentsSpecs[i].bags, 0, keyBags, certBags);
+    }
+    /** @internal A localKeyId identifies ONE private key (PKCS #9 sec. 5.5.2), so the key bags are
+     *  indexed by id and each certificate bag looks its key up: the pairing costs one probe per
+     *  certificate bag, never the product of the two sets, and an id carried by two key bags links a
+     *  certificate to no one key and is refused before anything is probed. The pairs a store links
+     *  across all its safes are capped at the element cap, decided while they are collected and
+     *  before any is probed, so the work a store can ask for is bounded by one constant rather than
+     *  by the product of the safe cap and the per-safe element cap. */
+    var keyById = intrinsic.create(null);
+    for (var k = 0; k < keyBags.length; k++) {
+      var kid = intrinsic.bufToString(_bytes(keyBags[k].localKeyId, "localKeyId"), "hex");
+      if (keyById[kid] !== undefined) throw _err("pkcs12/bad-input", "localKeyId " + kid + " is carried by more than one key bag; a localKeyId names one private key (PKCS #9 sec. 5.5.2)");
+      keyById[kid] = keyBags[k];
+    }
+    for (var c = 0; c < certBags.length; c++) {
+      var cid = intrinsic.bufToString(_bytes(certBags[c].localKeyId, "localKeyId"), "hex");
+      var keyBag = keyById[cid];
+      if (keyBag === undefined) continue;
+      if (pairs.length >= C.LIMITS.PKCS12_MAX_ELEMENTS) throw _err("pkcs12/bad-input", "the store links more than " + C.LIMITS.PKCS12_MAX_ELEMENTS + " certificate bags to keys through localKeyId; the linked pairs are capped at the element cap");
+      guard.list.append(pairs, { key: keyBag.key, cert: certBags[c].cert, what: "the key and certificate bags sharing localKeyId " + cid });
+    }
+  }
+  /** @internal The correspondence is proven with the PRIVATE half (a signature, an agreement or an
+   *  encapsulation against the certificate's key), since a PKCS#8 EC or RSA key carries public
+   *  components of its own that a caller could plant beside private material they do not belong to.
+   *  The key module owns the proof for every algorithm, the composite ML-KEM route included.
+   *  Proving a finite-field Diffie-Hellman pair includes proving its group's modulus and order prime,
+   *  about a second each at the widest group the toolkit agrees over and synchronous, so the DH
+   *  pairs one store may link are budgeted, and the budget is decided from the keys' algorithms
+   *  before any pair is probed. */
+  var halves = [], dhPairs = 0;
+  for (var a = 0; a < pairs.length; a++) {
+    var keyDer = _coerceDer(pairs[a].key, "the paired key");
+    var certDer = _coerceDer(pairs[a].cert, "the paired certificate");
+    var keyAlg, certSpki;
+    try { keyAlg = pkcs8.parse(keyDer).privateKeyAlgorithm.oid; }
+    catch (e2) { throw _err("pkcs12/bad-input", pairs[a].what + ": the key is not a well-formed PKCS#8 PrivateKeyInfo", e2); }
+    try { certSpki = x509.parse(certDer).subjectPublicKeyInfo; }
+    catch (e) { throw _err("pkcs12/bad-input", pairs[a].what + ": the certificate is not a well-formed X.509 certificate", e); }
+    if (key.isDhOid(keyAlg) || key.isDhOid(certSpki.algorithm.oid)) {
+      dhPairs++;
+      if (dhPairs > C.LIMITS.PKCS12_MAX_DH_PAIRS) throw _err("pkcs12/bad-input", "the store links more than " + C.LIMITS.PKCS12_MAX_DH_PAIRS + " finite-field Diffie-Hellman pairs; proving each costs a primality proof of its group, so a store is budgeted that many");
+    }
+    guard.list.append(halves, { keyDer: keyDer, certSpki: certSpki.bytes });
+  }
+  for (var p = 0; p < pairs.length; p++) {
+    var pairKey = halves[p].keyDer;
+    var pairSpki = halves[p].certSpki;
+    var corresponds;
+    try { corresponds = await key.correspondsTo(pairKey, pairSpki); }
+    catch (e3) { throw _err("pkcs12/bad-input", pairs[p].what + ": the key could not be held to the certificate's public key", e3); }
+    if (corresponds !== true) {
+      throw _err("pkcs12/bad-input", pairs[p].what + ": the key is not the private half of the certificate's public key; a store that links a certificate to another key is refused");
+    }
+  }
+}
+
 function _normalizeSpec(spec, opts, form) {
   if (form.full) return form.safeContents;
   if (spec && (spec.key != null || spec.cert != null)) {
@@ -419,7 +505,13 @@ function _normalizeSpec(spec, opts, form) {
  * OpenSSL-style convenience form `{ key, cert, ca?, friendlyName?, localKeyId? }` (one PBES2-encrypted cert
  * safe plus one shrouded-key safe) or the full form `{ safeContents: [...] }`, where each element is a
  * plaintext or PBES2-encrypted `SafeContents` of key / shroudedKey / cert / crl / secret / nested
- * safeContents bags. Keys and certs are validated before wrapping. Password integrity (the default) MACs the
+ * safeContents bags. Keys and certs are validated before wrapping, and a key paired with a certificate
+ * (the `{ key, cert }` form, or a key bag and a certificate bag sharing a `localKeyId`, PKCS #9 sec.
+ * 5.5.2) must be the private half of that certificate's public key; a store linking a certificate to
+ * another key, or carrying one `localKeyId` on two key bags, is refused with `pkcs12/bad-input`, as is
+ * one linking more than 1024 certificate bags to keys, more than 8 finite-field Diffie-Hellman pairs,
+ * or carrying more than 1024 safes.
+ * Password integrity (the default) MACs the
  * AuthenticatedSafe with a classic Appendix B HMAC or an RFC 9579 PBMAC1. Public-key integrity
  * (`opts.integrity.mode: "public-key"`) instead wraps the AuthenticatedSafe in a CMS SignedData: a
  * signature from a keypair, no MacData (RFC 7292 sec. 4). Privacy (PBES2 bag encryption via `password`) is
@@ -476,6 +568,11 @@ async function _build(spec, opts) {
   if (pubKey && opts.mac != null && opts.mac !== false) throw _err("pkcs12/bad-integrity-mode", "public-key integrity has no MacData -- do not combine opts.mac with opts.integrity.mode 'public-key' (RFC 7292 sec. 4)");
   var safeContentsSpecs = _normalizeSpec(spec, opts, form);
   if (!Array.isArray(safeContentsSpecs) || !safeContentsSpecs.length) throw _err("pkcs12/bad-input", "the store has no safe contents");
+  /** @internal The cap the parser puts on the AuthenticatedSafe, applied before any safe is built:
+   *  a store of more safes than the parser reads back would be encrypted in full and then refused
+   *  by the re-parse. */
+  if (safeContentsSpecs.length > C.LIMITS.PKCS12_MAX_ELEMENTS) throw _err("pkcs12/bad-input", "the AuthenticatedSafe exceeds the element cap " + C.LIMITS.PKCS12_MAX_ELEMENTS + " (safeContents entries)");
+  await _assertKeyPairs(spec, form, safeContentsSpecs);
   var elements = [];
   for (var i = 0; i < safeContentsSpecs.length; i++) elements.push(await _buildAuthSafeElement(safeContentsSpecs[i], opts));
   var authSafeDer = b.sequence(elements);

package/lib/pki-build.js

@@ -1256,22 +1256,6 @@ function makeBuilder(ctx) {
     if (!ok) throw E("bad-input", "the signing key does not correspond to the public key -- the signature would not verify");
   }
 
-  function samePublicKey(spkiA, spkiB) {
-    var a = _bufferFrom(spkiA), bb = _bufferFrom(spkiB);
-    if (_bufferEquals(a, bb)) return true;
-    var ka, kb;
-    // allow:swallow-unverified an SPKI the key layer cannot import matches nothing, which is the
-    try {
-      ka = nodeCrypto.createPublicKey({ key: a, format: "der", type: "spki" });
-      kb = nodeCrypto.createPublicKey({ key: bb, format: "der", type: "spki" });
-    } catch (_e) { return false; }
-    /** @internal Two keys of different types are never the same key, and comparing them through
-     *  the runtime's equality leaves a fault queued in the crypto library that surfaces on the
-     *  next unrelated key import in the process, so the type decides that case first. */
-    if (ka.asymmetricKeyType !== kb.asymmetricKeyType) return false;
-    return _keyEquals(ka, kb) === true;
-  }
-
   return {
     E: E, code: code, KU_BIT: KU_BIT,
     encodeName: encodeName, isEmptyName: isEmptyName, encodeGeneralName: encodeGeneralName,
@@ -1319,4 +1303,22 @@ function skiValueOf(parsedCert) {
   catch (_e) { return null; }   // allow:swallow-unverified -- a malformed SKI is read as absent; a signer then derives the authorityKeyIdentifier keyIdentifier from the public key, and a verifier matches on nothing
 }
 
+/** @internal Whether two SubjectPublicKeyInfo encodings carry the same public key: byte-equal, or
+ *  equal under the runtime's key comparison once both import. */
+function samePublicKey(spkiA, spkiB) {
+  var a = _bufferFrom(spkiA), bb = _bufferFrom(spkiB);
+  if (_bufferEquals(a, bb)) return true;
+  var ka, kb;
+  // allow:swallow-unverified an SPKI the key layer cannot import matches nothing, which is the
+  try {
+    ka = nodeCrypto.createPublicKey({ key: a, format: "der", type: "spki" });
+    kb = nodeCrypto.createPublicKey({ key: bb, format: "der", type: "spki" });
+  } catch (_e) { return false; }
+  /** @internal Two keys of different types are never the same key, and comparing them through
+   *  the runtime's equality leaves a fault queued in the crypto library that surfaces on the
+   *  next unrelated key import in the process, so the type decides that case first. */
+  if (ka.asymmetricKeyType !== kb.asymmetricKeyType) return false;
+  return _keyEquals(ka, kb) === true;
+}
+
 module.exports = intrinsic.freeze({ makeBuilder: makeBuilder, reqDenseArray: reqDenseArrayImpl, KU_BIT: KU_BIT, tbsNameField: tbsNameField, tbsSerialNumber: tbsSerialNumber, randomSerial: randomSerial, skiValueOf: skiValueOf, isHttpUrl: isHttpUrl, isLdapUrl: isLdapUrl });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.7.39",
+  "version": "0.7.41",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:5b3f8b70-36de-4855-8e1e-c6d22b99d982",
+  "serialNumber": "urn:uuid:2f774cf6-ab61-4b1c-8dab-ee0085cfb2a5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-12T14:40:25.102Z",
+    "timestamp": "2026-09-12T20:24:38.981Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.7.39",
+      "bom-ref": "@blamejs/pki@0.7.41",
       "type": "application",
       "name": "pki",
-      "version": "0.7.39",
+      "version": "0.7.41",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.7.39",
+      "purl": "pkg:npm/%40blamejs/pki@0.7.41",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.7.39",
+      "ref": "@blamejs/pki@0.7.41",
       "dependsOn": []
     }
   ]