@blamejs/pki 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.3.10 — 2026-07-23
+
+pki.key exports, imports, and PBES2-encrypts private keys (RFC 5958, RFC 8018) over every WebCrypto algorithm.
+
+### Added
+
+- pki.key.encrypt(privateKey, password, opts) encrypts a PKCS#8 private key (DER, PEM, or an extractable CryptoKey) into an RFC 5958 EncryptedPrivateKeyInfo under RFC 8018 PBES2. opts selects the cipher (aes-256-cbc default, aes-192-cbc, aes-128-cbc), the pseudorandom function (hmacWithSHA256 default, SHA-384, SHA-512, SHA-1), the iteration count (default 600000, bounded by the decryptor's cap), and the salt (16 random octets by default); opts.pem returns an ENCRYPTED PRIVATE KEY string. The plaintext is validated as a well-formed PKCS#8 structure before encryption and the output is re-parsed before return. A default pseudorandom function is omitted and keyLength is omitted, so the parameters are byte-exact with OpenSSL. RFC 5958 sec. 3, RFC 8018.
+- pki.key.decrypt(encrypted, password, opts) decrypts an RFC 5958 EncryptedPrivateKeyInfo (DER or ENCRYPTED PRIVATE KEY PEM), returning the inner PrivateKeyInfo re-validated through pki.schema.pkcs8.parse. Only PBES2 with a PBKDF2 key-derivation function and an AES-CBC scheme is accepted -- PBES1, PBMAC1, scrypt, and any other algorithm are refused. The salt and iteration count are bounded before any key derivation (opts.maxIterations lowers the cap for this call, never raises it), a malformed parameter set or wrong-length IV is a distinct typed error, and -- because a MAC-less PBES2-CBC decrypt must not be a padding oracle (RFC 8018 sec. 8) -- a wrong password and a valid pad that is not a private key both surface the single uniform decrypt-failed. RFC 5958 sec. 3, RFC 8018.
+- pki.key.export(key, opts) exports an extractable CryptoKey to DER or PEM: a private key as PKCS#8, a public key as SubjectPublicKeyInfo. The encoding is delegated to WebCrypto, so the algorithm-specific parameters are correct -- RSA an explicit NULL, EC a named curve, Ed25519/Ed448/X25519/X448 parameters absent (RFC 8410 sec. 3). RFC 5958, RFC 5280 sec. 4.1.2.7.
+- pki.key.import(input, opts) imports a DER or PEM PKCS#8 private key, SPKI public key, or (with opts.password) an ENCRYPTED PRIVATE KEY into a CryptoKey, auto-detecting the structure. The WebCrypto algorithm is inferred for the algorithms that name exactly one (Ed25519, Ed448, X25519, X448, ML-DSA, ML-KEM, SLH-DSA); RSA and EC are ambiguous between signing and key agreement, so opts.algorithm is required for them -- import fails closed rather than guess a use.
+- pki.key.generate(algorithm, opts) generates a key pair over the WebCrypto engine -- RSA, ECDSA/ECDH, Ed25519/Ed448, X25519/X448, and the FIPS post-quantum ML-DSA and ML-KEM -- with usages defaulting to the algorithm's natural set. pki.key.publicFromPrivate(privateKey) derives the SubjectPublicKeyInfo public key from a private key.
+- pki.errors.KeyError is the typed error for the pki.key domain (key/bad-input, key/unsupported-algorithm, key/bad-algorithm-parameters, key/iteration-limit, key/bad-version, key/decrypt-failed).
+
 ## v0.3.9 — 2026-07-23
 
 pki.crl builds, signs, and verifies X.509 certificate revocation lists (RFC 5280 sec. 5) over any registry algorithm.

package/README.md

@@ -228,6 +228,7 @@ is callable today; nothing below is a stub.
 | `pki.crmf` | RFC 4211 certificate-request-message issuance — `build(spec, key, opts)` assembles a `CertReqMessages`: a `spec` of `certReqId` (default 0; the RFC 9483 `-1` sentinel allowed), a `certTemplate` of the requested certificate fields (`subject`, `publicKey` — the SPKI DER of the key being certified — `validity`, requested `extensions`, an optional `version` 2), optional `controls` and `regInfo` (regToken / authenticator / utf8Pairs / oldCertID / protocolEncrKey, or pre-encoded `AttributeTypeAndValue` DER), and an optional `pop` selector. `key` (or `{ key }`) is the requester's private key — the message carries a `POPOSigningKey` proof of possession signed with the private half of `certTemplate.publicKey` (verified before the message is returned), exactly as a PKCS#10 CSR proves possession; a complete template signs the `CertRequest`, an incomplete one signs a `POPOSigningKeyInput`. The signature algorithm is resolved from the requested public key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. `key` is optional for a `raVerified` proof. Pass an array of specs for a batch; the CA-assigned template fields are never emitted. Returns DER, or a PEM block with `opts.pem`; malformed input throws a typed `CrmfError`. Parsing stays at `pki.schema.crmf.parse` — `build` |
 | `pki.cmp` | RFC 9810 Certificate Management Protocol message building — `build(message, opts)` assembles a protected `PKIMessage`. `message.header` carries the `sender` / `recipient` GeneralNames (including the anonymous NULL-DN) plus optional transaction metadata (`transactionID`, `senderNonce` / `recipNonce`, `messageTime` as a GeneralizedTime, `senderKID` / `recipKID`, `freeText`, `generalInfo`); `message.body` is a single-key object naming the arm. Request-side: `ir` / `cr` / `kur` (a `CertReqMessages` spec delegated to `pki.crmf.build`), `p10cr` (a PKCS#10 `CertificationRequest`), `certConf`, `pollReq`, `genm`, `rr`. CA/responder-side: `ip` / `cp` / `kup` / `ccp` (a `CertRepMessage` — `caPubs` and `response` entries carrying a `PKIStatusInfo` and, under a granting status, a `certifiedKeyPair`), `rp` (revocation response), `genp`, `error`, `pollRep`, `krp` (key-recovery response), `pkiconf`. Protection is exactly one of `opts.{ key, cert }` — a signature over the message under the sender key, 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 — or `opts.mac` — a PBMAC1 shared-secret HMAC (RFC 9481 / 9579, PBKDF2-derived). The protection covers the exact DER of the virtual `ProtectedPart` (the header and body) and is self-verified before the message is returned; the `protectionAlg` is derived, never caller-set, so the message the parser accepts is coherent by construction. Returns DER, or a PEM `CMP` block with `opts.pem`; malformed input throws a typed `CmpError`. Parsing stays at `pki.schema.cmp.parse` — `build` |
 | `pki.crl` | RFC 5280 §5 certificate revocation list issuance — `sign(spec, issuer, opts)` builds and signs a `CertificateList`: a `spec` of `thisUpdate` / `nextUpdate`, an optional `crlNumber`, a `revoked` array (each entry a `serialNumber` + `revocationDate` with an optional `reason` or `invalidityDate`), and an optional `extensions` object (authority key identifier, issuing distribution point, delta-CRL indicator, freshest CRL, authority information access) or an array of pre-encoded Extension DER; an `issuer` of `{ cert, key }` or `{ name, publicKey, key }`. The signature algorithm is resolved from the issuer key, so RSA (PKCS#1 v1.5 / 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, per-extension criticality is fixed by the RFC, 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), and `isRevoked(crl, serialNumber)` looks a serial up in the revocation list. 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` | RFC 5958 / RFC 8018 key-material lifecycle — `encrypt(privateKey, password, opts)` wraps a PKCS#8 private key (DER, PEM, or an extractable `CryptoKey`) into an `EncryptedPrivateKeyInfo` under PBES2 (PBKDF2 + AES-CBC-Pad): `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, scrypt refused), the salt and iteration count are bounded before any derivation (`opts.maxIterations` lowers the cap), a malformed parameter set or wrong-length IV is a distinct typed error, and — because a MAC-less PBES2-CBC decrypt must not be 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)` / `import(input, opts)` move a private key as PKCS#8 or a public key as SubjectPublicKeyInfo, delegating the encoding to WebCrypto so RSA carries an explicit NULL, EC a named curve, and Ed25519/Ed448/X25519/X448 omit parameters (an ambiguous RSA/EC import requires `opts.algorithm`). `generate(algorithm, opts)` produces a key pair over RSA, ECDSA/ECDH, the Edwards/Montgomery curves, and the FIPS post-quantum ML-DSA / ML-KEM, and `publicFromPrivate(privateKey)` derives the public key. Returns DER or PEM; fail-closed with typed `KeyError`. Parsing stays at `pki.schema.pkcs8.parse` — `encrypt` / `decrypt` / `export` / `import` / `generate` / `publicFromPrivate` |
 | `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, 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 / EdDSA — 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. `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: when signed attributes are 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), otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. **Content encryption** (RFC 5652/5083/5084/9629): `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData — recipients auto-dispatch off the certificate key to key-transport (RSAES-OAEP; v1.5 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 + RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936) — one fresh content key wrapped for every recipient. `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 / password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. **Compression** (RFC 3274): `compress(content, opts)` / `decompress(input, opts)` produce and consume a CompressedData (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` — a size transform with no integrity/confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.smime` | RFC 8551 S/MIME message assembly, verification, encryption, and compression over the CMS layer — `sign(content, signers, opts)` wraps a MIME entity as a signed S/MIME message in either form: `multipart/signed` (clear-signed — the content stays readable in any MUA, a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`) or `application/pkcs7-mime; smime-type=signed-data` (opaque — the whole entity is a base64 CMS SignedData). The signed bytes are the entity's RFC 8551 §3.1.1 canonical form (CRLF line endings); `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies and 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 — `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, not the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt` — 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 (algorithm-agnostic). Like `cms.verify`, `verify` returns the per-signer cryptographic verdict plus the recovered content; chaining a signer to a trust anchor is the caller's `pki.path.validate` step. `compress(content, opts)` / `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (RFC 8551 §3.6, RFC 3274) — a size transform with no integrity/confidentiality (§2.4.5), decompress bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. Bidirectionally interoperable with `openssl smime` / `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.tsp` | RFC 3161 Time-Stamp Protocol — `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 / ordering), plus the RFC 3161 §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). `request` / `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq), `response` / `parseResponse` the TimeStampResp a TSA returns — a granted status wrapping a token, or a rejection with PKIStatus and failure info, the §2.4.2 status↔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`, returning `{ valid, genTime, serialNumber, tstInfo, … }` — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |

package/index.js

@@ -46,6 +46,7 @@ var attrcert  = require("./lib/attrcert-sign");
 var crmf      = require("./lib/crmf-sign");
 var cmp       = require("./lib/cmp-build");
 var crl       = require("./lib/crl-sign");
+var key       = require("./lib/key");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
@@ -113,6 +114,10 @@ module.exports = {
   // over any registry algorithm, pki.crl.verify checks a CRL signature through the one path-validation
   // signature engine, and pki.crl.isRevoked looks a serial up. Parsing lives at pki.schema.crl.parse.
   crl:       crl,
+  // `key` is the key-material lifecycle domain -- pki.key.encrypt / decrypt a private key under RFC 8018
+  // PBES2 (EncryptedPrivateKeyInfo), pki.key.export / import a PKCS#8 private or SPKI public key, and
+  // pki.key.generate / publicFromPrivate over every WebCrypto algorithm. Parsing lives at pki.schema.pkcs8.
+  key:       key,
   // `merkle` is the RFC 6962 / RFC 9162 Merkle-tree proof-verification core --
   // pki.merkle.leafHash / nodeHash / emptyRootHash build the domain-separated
   // (0x00 leaf / 0x01 node) SHA-256 tree hashes; pki.merkle.verifyInclusion and

package/lib/cms-decrypt.js

@@ -23,7 +23,7 @@ var schemaCms = require("./schema-cms");
 var webcrypto = require("./webcrypto");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
-var C = require("./constants");
+var pbes2 = require("./pbes2");
 var b = asn1.build;
 var subtle = webcrypto.webcrypto.subtle;
 var CmsError = frameworkError.CmsError;
@@ -35,8 +35,7 @@ function _err(code, message, cause) { return new CmsError(code, message, cause);
 // The ONE uniform secret-dependent-failure verdict. No cause chaining that distinguishes the site.
 function _fail() { return new CmsError("cms/decrypt-failed", "the CMS content could not be decrypted (uniform by design -- padding / integrity / key-unwrap failures are indistinguishable to defeat oracles)"); }
 
-var CONTENT_KEYBITS = {}; // content-encryption OID -> key bits
-[["aes128-CBC", 128], ["aes192-CBC", 192], ["aes256-CBC", 256], ["aes128-GCM", 128], ["aes192-GCM", 192], ["aes256-GCM", 256]].forEach(function (r) { CONTENT_KEYBITS[O(r[0])] = r[1]; });
+var CONTENT_KEYBITS = pbes2.CONTENT_KEYBITS; // content-encryption OID -> key bits (the shared PBES2 table)
 
 // ---- entry -----------------------------------------------------------------
 async function decrypt(input, keyMaterial, opts) {
@@ -255,7 +254,7 @@ async function _pwriCek(ri, km, opts) {
   var kdf = ri.keyDerivationAlgorithm;
   if (!kdf) throw _err("cms/missing-key-derivation", "the pwri recipient has no keyDerivationAlgorithm (externally-supplied KEK is not supported)");
   if (kdf.oid !== O("pbkdf2")) throw _err("cms/unsupported-algorithm", "unsupported pwri key-derivation " + kdf.oid);
-  var pb = _pbkdf2Params(kdf.parameters, opts);
+  var pb = pbes2.parsePbkdf2Params(kdf.parameters, opts, _err, "cms");
   var kea = ri.keyEncryptionAlgorithm;
   if (kea.oid !== O("id-alg-PWRI-KEK")) throw _err("cms/unsupported-algorithm", "unsupported pwri key-encryption " + kea.oid);
   var inner = asn1.decode(kea.parameters);                 // inner AES-CBC AlgorithmIdentifier
@@ -263,7 +262,7 @@ async function _pwriCek(ri, km, opts) {
   var innerBits = CONTENT_KEYBITS[innerOid];
   if (!innerBits || !/CBC/.test(oid.name(innerOid) || "")) throw _err("cms/unsupported-algorithm", "unsupported pwri inner cipher");
   var iv = asn1.read.octetString(inner.children[1]);
-  var kek = nodeCrypto.pbkdf2Sync(_passwordBytes(km.password), pb.salt, pb.iterations, innerBits / 8, pb.prfNode);
+  var kek = nodeCrypto.pbkdf2Sync(pbes2.passwordBytes(km.password, _err, "cms"), pb.salt, pb.iterations, innerBits / 8, pb.prfNode);
   return _pwriUnwrap(kek, ri.encryptedKey, iv, innerBits);
 }
 
@@ -307,7 +306,7 @@ async function _openContent(parsed, eci, cek, ct) {
     }
     var iv = asn1.read.octetString(asn1.decode(alg.parameters));
     if (iv.length !== 16) throw _fail();
-    return _cbcOpen(cek, iv, eci.encryptedContent, keyBits);
+    return pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits);
   } catch (e) {
     if (e instanceof CmsError && e.code !== "cms/decrypt-failed") throw e;
     throw _fail();
@@ -322,10 +321,6 @@ function _gcmOpen(cek, nonce, ct, tag, aad, keyBits, icvLen) {
   if (aad && aad.length) d.setAAD(aad);
   return Buffer.concat([d.update(ct), d.final()]); // final() throws on tag mismatch -> uniform
 }
-function _cbcOpen(cek, iv, ct, keyBits) {
-  var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-cbc", cek, iv);
-  return Buffer.concat([d.update(ct), d.final()]); // final() throws on bad pad -> uniform
-}
 
 // ---- EncryptedData (sec. 8) ------------------------------------------------
 async function _decryptEncryptedData(parsed, km, opts) {
@@ -339,7 +334,7 @@ async function _decryptEncryptedData(parsed, km, opts) {
   var cek = guard.bytes.view(km.cek, CmsError, "cms/bad-input", "cek");
   if (cek.length !== keyBits / 8) throw _err("cms/bad-input", "the supplied cek length does not match the content algorithm");
   var iv = asn1.read.octetString(asn1.decode(alg.parameters));
-  try { return { content: _cbcOpen(cek, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "cek", recipientIndex: -1, contentEncryptionAlgorithm: alg.name || alg.oid, authenticated: false }; }
+  try { return { content: pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "cek", recipientIndex: -1, contentEncryptionAlgorithm: alg.name || alg.oid, authenticated: false }; }
   catch (_e) { throw _fail(); }
 }
 async function _decryptPbes2(parsed, eci, km, opts) {
@@ -349,11 +344,11 @@ async function _decryptPbes2(parsed, eci, km, opts) {
   // cms/bad-input, never a raw dereference fault (the PBES2 structure is public -- not a decrypt oracle).
   var kdf, encOid, iv, pb;
   try {
-    var params = _seqChildren(eci.contentEncryptionAlgorithm.parameters, 2, "PBES2 parameters");
-    kdf = _requireChildren(params[0], 2, "PBES2 keyDerivationFunc");
-    var encScheme = _requireChildren(params[1], 2, "PBES2 encryptionScheme");
+    var params = pbes2.seqChildren(eci.contentEncryptionAlgorithm.parameters, 2, "PBES2 parameters", _err, "cms");
+    kdf = pbes2.requireChildren(params[0], 2, "PBES2 keyDerivationFunc", _err, "cms");
+    var encScheme = pbes2.requireChildren(params[1], 2, "PBES2 encryptionScheme", _err, "cms");
     if (asn1.read.oid(kdf[0]) !== O("pbkdf2")) throw _err("cms/unsupported-algorithm", "PBES2 keyDerivationFunc must be PBKDF2");
-    pb = _pbkdf2Params(kdf[1].bytes, opts);
+    pb = pbes2.parsePbkdf2Params(kdf[1].bytes, opts, _err, "cms");
     encOid = asn1.read.oid(encScheme[0]);
     iv = asn1.read.octetString(encScheme[1]);
   } catch (e) {
@@ -362,8 +357,8 @@ async function _decryptPbes2(parsed, eci, km, opts) {
   }
   var keyBits = CONTENT_KEYBITS[encOid];
   if (!keyBits) throw _err("cms/unsupported-algorithm", "unsupported PBES2 content cipher " + encOid);
-  var key = nodeCrypto.pbkdf2Sync(_passwordBytes(km.password), pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
-  try { return { content: _cbcOpen(key, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "password", recipientIndex: -1, contentEncryptionAlgorithm: oid.name(encOid) || encOid, authenticated: false }; }
+  var key = nodeCrypto.pbkdf2Sync(pbes2.passwordBytes(km.password, _err, "cms"), pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
+  try { return { content: pbes2.cbcDecrypt(key, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "password", recipientIndex: -1, contentEncryptionAlgorithm: oid.name(encOid) || encOid, authenticated: false }; }
   catch (_e) { throw _fail(); }
 }
 
@@ -410,44 +405,11 @@ function _pwriUnwrap(kek, wrapped, iv, keyBits) {
   if (bad !== 0) throw _fail();
   return Buffer.from(cek);
 }
-// SEQUENCE structural guards -- a malformed (primitive / too-short) attacker-controlled parameter
-// SEQUENCE is a typed cms/bad-input, never a raw `.children` dereference fault.
-function _requireChildren(node, minLen, what) {
-  if (!node || !node.children || node.children.length < minLen) throw _err("cms/bad-input", "malformed " + what);
-  return node.children;
-}
-function _seqChildren(paramsDer, minLen, what) {
-  if (paramsDer == null) throw _err("cms/bad-input", "missing " + what);
-  return _requireChildren(asn1.decode(paramsDer), minLen, what);
-}
-function _pbkdf2Params(paramsDer, opts) {
-  var node = Buffer.isBuffer(paramsDer) ? asn1.decode(paramsDer) : paramsDer;
-  var kids = _requireChildren(node, 2, "PBKDF2 parameters");
-  var salt = asn1.read.octetString(kids[0]);
-  if (salt.length > C.LIMITS.PBKDF2_MAX_SALT) throw _err("cms/bad-input", "PBKDF2 salt exceeds the " + C.LIMITS.PBKDF2_MAX_SALT + "-octet cap");
-  var iterations = guard.range.positiveInt31(asn1.read.integer(kids[1]), _err, "cms/bad-input", "PBKDF2 iterationCount");
-  // A caller-supplied maxIterations must be a positive integer -- a NaN / non-number would make
-  // Math.min return NaN and silently disable the DoS cap (iterations > NaN is always false).
-  var cap = C.LIMITS.PBKDF2_MAX_ITERATIONS;
-  if (opts.maxIterations != null) {
-    if (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations) throw _err("cms/bad-input", "maxIterations must be a positive integer");
-    cap = Math.min(opts.maxIterations, cap);
-  }
-  if (iterations > cap) throw _err("cms/iteration-limit", "PBKDF2 iterationCount " + iterations + " exceeds the cap " + cap);
-  var prfNode = "sha1";
-  for (var i = 2; i < node.children.length; i++) {
-    var ch = node.children[i];
-    if (ch.tagClass === "universal" && ch.tagNumber === asn1.TAGS.SEQUENCE) prfNode = _prfNode(asn1.read.oid(ch.children[0]));
-  }
-  return { salt: salt, iterations: iterations, prfNode: prfNode };
-}
-// Coverage residual (the unsupported-algorithm throw arm of each lookup below -- _prfNode, _hashW3c,
+// Coverage residual (the unsupported-algorithm throw arm of each lookup below -- _hashW3c,
 // _x963Hash, and _originatorSpki that follow): reachable only from a fully well-formed recipient that
-// names an inner algorithm we do not implement (a non-registry prf / OAEP hash / kari scheme /
-// originator form). The producer never emits one; the fuzz harness (fuzz/cms-decrypt.fuzz.js) drives
-// these arms behaviorally under the PkiError-only contract.
-var PRF_NODE = {}; PRF_NODE[O("hmacWithSHA1")] = "sha1"; PRF_NODE[O("hmacWithSHA256")] = "sha256"; PRF_NODE[O("hmacWithSHA384")] = "sha384"; PRF_NODE[O("hmacWithSHA512")] = "sha512";
-function _prfNode(oidStr) { if (!PRF_NODE[oidStr]) throw _err("cms/unsupported-algorithm", "unsupported PBKDF2 prf " + oidStr); return PRF_NODE[oidStr]; }
+// names an inner algorithm we do not implement (a non-registry OAEP hash / kari scheme / originator
+// form). The producer never emits one; the fuzz harness (fuzz/cms-decrypt.fuzz.js) drives these arms
+// behaviorally under the PkiError-only contract.
 
 function _oaepHashFromParams(paramsBytes) {
   if (paramsBytes == null) return "SHA-1"; // absent = the RFC 4055 defaults (accept floor)
@@ -529,11 +491,5 @@ function _normCertDer(cert) {
   if (typeof cert === "string") { try { return x509.pemDecode(cert); } catch (e) { throw _err("cms/bad-input", "the recipient certificate PEM could not be decoded", e); } }
   throw _err("cms/bad-input", "the recipient certificate must be a DER Buffer or PEM string");
 }
-function _passwordBytes(p) {
-  if (Buffer.isBuffer(p)) return p;
-  if (p instanceof Uint8Array) return Buffer.from(p);
-  if (typeof p === "string") return Buffer.from(p, "utf8");
-  throw _err("cms/bad-input", "a password must be a string, Buffer, or Uint8Array");
-}
 
 module.exports = { decrypt: decrypt };

package/lib/cms-encrypt.js

@@ -23,7 +23,7 @@ var schemaCms = require("./schema-cms");
 var webcrypto = require("./webcrypto");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
-var C = require("./constants");
+var pbes2 = require("./pbes2");
 var b = asn1.build;
 var subtle = webcrypto.webcrypto.subtle;
 var CmsError = frameworkError.CmsError;
@@ -230,25 +230,11 @@ async function _buildKekri(cek, desc) {
 }
 
 // A PBKDF2 iterationCount MUST be a positive integer within the same cap the decryptor enforces -- a
-// fractional / non-finite / <1 value would reach node's pbkdf2 (or BigInt() on encode) as a native
-// RangeError, and an over-cap value would produce a message our own decrypt refuses (cms/iteration-limit).
-function _assertIterations(n) {
-  if (typeof n !== "number" || !isFinite(n) || n < 1 || Math.floor(n) !== n) throw _err("cms/bad-input", "iterations must be a positive integer");
-  if (n > C.LIMITS.PBKDF2_MAX_ITERATIONS) throw _err("cms/bad-input", "iterations exceeds the " + C.LIMITS.PBKDF2_MAX_ITERATIONS + " cap");
-  return n;
-}
-// Bound the PBKDF2 salt to the same cap the decryptor enforces, so a message we emit is always one we
-// can read back.
-function _assertSalt(salt) {
-  guard.limits.byteCap(salt, C.LIMITS.PBKDF2_MAX_SALT, _err, "cms/bad-input", "salt");
-  return salt;
-}
-
 // ---- pwri (password) : PBKDF2 + RFC 3211 double-CBC PWRI-KEK ---------------
 async function _buildPwri(cek, desc) {
-  var password = _passwordBytes(desc.password);
-  var iterations = _assertIterations(desc.iterations == null ? 600000 : desc.iterations);
-  var salt = desc.salt ? _assertSalt(guard.bytes.view(desc.salt, CmsError, "cms/bad-input", "salt")) : nodeCrypto.randomBytes(16);
+  var password = pbes2.passwordBytes(desc.password, _err, "cms");
+  var iterations = pbes2.assertIterations(desc.iterations == null ? 600000 : desc.iterations, _err, "cms");
+  var salt = desc.salt ? pbes2.assertSalt(guard.bytes.view(desc.salt, CmsError, "cms/bad-input", "salt"), _err, "cms") : nodeCrypto.randomBytes(16);
   var prf = desc.prf || "hmacWithSHA256";
   var innerKeyBytes = 32; // AES-256-CBC inner
   var kekKey = await subtle.importKey("raw", password, { name: "PBKDF2" }, false, ["deriveBits"]);
@@ -258,7 +244,7 @@ async function _buildPwri(cek, desc) {
   var iv = nodeCrypto.randomBytes(16);
   var encryptedKey = _pwriWrapIv(kek, cek, iv);
   // PBKDF2-params as keyDerivationAlgorithm [0] IMPLICIT.
-  var kdfParams = _pbkdf2ParamsSeq(salt, iterations, prf);
+  var kdfParams = pbes2.pbkdf2ParamsSeq(salt, iterations, prf);
   var kdfAlg = b.contextConstructed(0, Buffer.concat([b.oid(O("pbkdf2")), kdfParams]));
   var keyEncAlg = b.sequence([b.oid(O("id-alg-PWRI-KEK")), b.sequence([b.oid(O("aes256-CBC")), b.octetString(iv)])]);
   return { tag: 3, node: b.sequence([b.integer(0n), kdfAlg, keyEncAlg, b.octetString(encryptedKey)]) };
@@ -330,12 +316,6 @@ function _pwriWrapIv(kek, cek, iv) {
   return Buffer.concat([c2.update(pass1), c2.final()]);
 }
 
-function _passwordBytes(p) {
-  if (Buffer.isBuffer(p)) return p;
-  if (p instanceof Uint8Array) return Buffer.from(p);
-  if (typeof p === "string") return Buffer.from(p, "utf8");
-  throw _err("cms/bad-input", "a password must be a string, Buffer, or Uint8Array");
-}
 var PRF_HASH = { hmacWithSHA1: "SHA-1", hmacWithSHA256: "SHA-256", hmacWithSHA384: "SHA-384", hmacWithSHA512: "SHA-512" };
 function _prfHash(prf) { if (!PRF_HASH[prf]) throw _err("cms/bad-input", "unsupported pwri prf " + JSON.stringify(prf)); return PRF_HASH[prf]; }
 
@@ -401,7 +381,7 @@ function _emit(inner, ctName, opts) {
 
 function _envelopedData(contentBytes, cek, ca, contentType, riNodes, recips) {
   var iv = nodeCrypto.randomBytes(16);
-  var enc = _cbcEncrypt(cek, iv, contentBytes, ca.keyBits);
+  var enc = pbes2.cbcEncrypt(cek, iv, contentBytes, ca.keyBits);
   var eci = b.sequence([b.oid(O(contentType)), b.sequence([b.oid(O(ca.oid)), b.octetString(iv)]), b.contextPrimitive(0, enc)]);
   return b.sequence([b.integer(BigInt(_envelopedVersion(recips, false))), b.setOf(riNodes), eci]);
 }
@@ -444,43 +424,26 @@ function _encryptedData(contentBytes, desc, ca, contentType, opts, cek) {
   } else {
     throw _err("cms/bad-input", "EncryptedData needs a single { cek } or { password } descriptor");
   }
-  var enc = _cbcEncrypt(encKey, iv, contentBytes, ca.keyBits);
+  var enc = pbes2.cbcEncrypt(encKey, iv, contentBytes, ca.keyBits);
   var eci = b.sequence([b.oid(O(contentType)), contentAlgNode, b.contextPrimitive(0, enc)]);
   var inner = b.sequence([b.integer(0n), eci]);
   return _emit(inner, "encryptedData", opts);
 }
 
 function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
-  var password = _passwordBytes(desc.password);
-  var iterations = _assertIterations(desc.iterations == null ? 600000 : desc.iterations);
-  var salt = desc.salt ? _assertSalt(guard.bytes.view(desc.salt, CmsError, "cms/bad-input", "salt")) : nodeCrypto.randomBytes(16);
+  var password = pbes2.passwordBytes(desc.password, _err, "cms");
+  var iterations = pbes2.assertIterations(desc.iterations == null ? 600000 : desc.iterations, _err, "cms");
+  var salt = desc.salt ? pbes2.assertSalt(guard.bytes.view(desc.salt, CmsError, "cms/bad-input", "salt"), _err, "cms") : nodeCrypto.randomBytes(16);
   var prf = desc.prf || "hmacWithSHA256";
-  var key = nodeCrypto.pbkdf2Sync(password, salt, iterations, ca.keyBits / 8, _prfNode(prf));
-  var enc = _cbcEncrypt(key, iv, contentBytes, ca.keyBits);
-  var pbkdf2Params = _pbkdf2ParamsSeq(salt, iterations, prf);
-  var kdf = b.sequence([b.oid(O("pbkdf2")), pbkdf2Params]);
-  var encScheme = b.sequence([b.oid(O(ca.oid)), b.octetString(iv)]);
-  var pbes2Params = b.sequence([kdf, encScheme]);
-  var contentAlg = b.sequence([b.oid(O("pbes2")), pbes2Params]);
+  var key = nodeCrypto.pbkdf2Sync(password, salt, iterations, ca.keyBits / 8, pbes2.prfNodeByName(prf, _err, "cms"));
+  var enc = pbes2.cbcEncrypt(key, iv, contentBytes, ca.keyBits);
+  var contentAlg = pbes2.pbes2AlgId(salt, iterations, prf, ca.oid, iv);
   var eci = b.sequence([b.oid(O(contentType)), contentAlg, b.contextPrimitive(0, enc)]);
   var inner = b.sequence([b.integer(0n), eci]);
   return _emit(inner, "encryptedData", { pem: opts && opts.pem != null ? opts.pem : desc.pem });
 }
-var PRF_NODE = { hmacWithSHA1: "sha1", hmacWithSHA256: "sha256", hmacWithSHA384: "sha384", hmacWithSHA512: "sha512" };
-function _prfNode(prf) { if (!PRF_NODE[prf]) throw _err("cms/bad-input", "unsupported prf " + JSON.stringify(prf)); return PRF_NODE[prf]; }
-// PBKDF2-params { salt OCTET STRING, iterationCount, prf DEFAULT hmacWithSHA1 } -- one builder for
-// pwri + PBES2. prf equal to the DEFAULT (hmacWithSHA1) MUST be omitted (X.690 / RFC 8018 App. A.2).
-function _pbkdf2ParamsSeq(salt, iterations, prf) {
-  var kids = [b.octetString(salt), b.integer(BigInt(iterations))];
-  if (prf !== "hmacWithSHA1") kids.push(_algId(prf, "null"));
-  return b.sequence(kids);
-}
 
 // ---- content-encryption primitives ----------------------------------------
-function _cbcEncrypt(key, iv, plaintext, keyBits) {
-  var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
-  return Buffer.concat([c.update(plaintext), c.final()]);
-}
 function _gcmEncrypt(key, nonce, plaintext, aad, keyBits, tagLen) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-gcm", key, nonce, { authTagLength: tagLen });
   if (aad && aad.length) c.setAAD(aad);

package/lib/framework-error.js

@@ -318,6 +318,15 @@ var WebauthnError = defineClass("WebauthnError", { withCause: true });
 // on malformed input -- a linter surveys a corpus that includes malformed members,
 // so hostile bytes surface a `fatal` finding (lint/unparseable) and return a report.
 var LintError = defineClass("LintError", { withCause: true });
+// KeyError -- the pki.key key-material lifecycle domain: a bad export/import
+// input (not a CryptoKey / DER / PEM), an unsupported key or PBES2 algorithm, a
+// malformed EncryptedPrivateKeyInfo / PBES2 parameter set, an attacker-controlled
+// PBKDF2 salt or iteration count over its cap, a version<=>publicKey mismatch on a
+// produced OneAsymmetricKey, or a failed PBES2 decryption. A MAC-less PBES2-CBC
+// decrypt collapses every post-derivation failure (wrong password, valid pad but
+// not a PrivateKeyInfo) into ONE uniform key/decrypt-failed so it is not a padding
+// oracle; the structural pre-derivation faults stay distinct and typed.
+var KeyError = defineClass("KeyError", { withCause: true });
 
 module.exports = {
   PkiError:         PkiError,
@@ -355,4 +364,5 @@ module.exports = {
   JoseError:        JoseError,
   AcmeError:        AcmeError,
   TrustError:       TrustError,
+  KeyError:         KeyError,
 };

package/lib/key.js

@@ -0,0 +1,420 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.key
+ * @nav        Signing
+ * @title      Keys
+ * @intro The key-material lifecycle: export / import a private key as PKCS#8 (`OneAsymmetricKey`,
+ *   RFC 5958) or a public key as SPKI (RFC 5280 sec. 4.1.2.7), encrypt / decrypt a private key under
+ *   RFC 8018 PBES2 (`EncryptedPrivateKeyInfo`, PBKDF2 + AES-CBC-Pad), and `generate` /
+ *   `publicFromPrivate` over every algorithm the WebCrypto engine drives -- RSA, EC, Ed25519/Ed448,
+ *   X25519/X448, and the FIPS post-quantum ML-DSA / ML-KEM. Unencrypted export / import DELEGATES to the
+ *   WebCrypto `exportKey` / `importKey` PKCS#8 / SPKI encoders (which already emit each algorithm's
+ *   `AlgorithmIdentifier.parameters` correctly -- RSA NULL, EC namedCurve, Ed/X ABSENT), so the wrapper
+ *   never re-encodes an AlgorithmIdentifier. PBES2 encrypt / decrypt composes the one shared `lib/pbes2.js`
+ *   home (the same PBKDF2 + AES-CBC primitives `pki.cms` uses). Parsing lives at `pki.schema.pkcs8.parse`.
+ * @spec RFC 5958, RFC 8018, RFC 5280
+ * @card Export / import PKCS#8 and SPKI keys and encrypt a private key under RFC 8018 PBES2.
+ */
+//
+// PBES2 is composed from lib/pbes2.js (the ONE PBKDF2 + AES-CBC home shared with pki.cms), bound to the key
+// namespace through the `_err` error FACTORY + the "key" domain prefix so every reject keeps a key/* code.
+// A MAC-less PBES2-CBC decrypt is not a padding oracle (RFC 8018 sec. 8): every post-derivation failure --
+// a bad PKCS#7 pad OR a valid pad that does not re-parse as a PrivateKeyInfo -- collapses into ONE uniform
+// key/decrypt-failed; the structural pre-derivation faults (a non-PBKDF2 KDF, a non-AES-CBC scheme, an
+// over-cap salt / iteration count, a wrong-length IV, a malformed parameter SEQUENCE) stay distinct and are
+// thrown BEFORE any key derivation, so they leak nothing password-dependent. Unencrypted export / import
+// and publicFromPrivate DELEGATE to the WebCrypto / node key engines rather than re-serialize an
+// AlgorithmIdentifier -- a re-encode is exactly where a params-absent-vs-NULL divergence sneaks back in.
+
+var nodeCrypto = require("crypto");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var pbes2 = require("./pbes2");
+var pkcs8 = require("./schema-pkcs8");
+var pkix = require("./schema-pkix");
+var webcrypto = require("./webcrypto");
+var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
+
+var b = asn1.build;
+var subtle = webcrypto.webcrypto.subtle;
+var CryptoKey = webcrypto.CryptoKey;
+var KeyError = frameworkError.KeyError;
+var PemError = frameworkError.PemError;
+function O(n) { return oid.byName(n); }
+// The guard / pbes2 error convention: a (code, msg, cause) FACTORY, never the KeyError class -- pbes2 and
+// the guards invoke it as E(code, msg) with no `new` (a class there crashes on the error path).
+function _err(code, msg, cause) { return new KeyError(code, msg, cause); }
+
+// The operator-facing node cipher name <-> the AES-CBC registry name the PBES2 home speaks.
+var CIPHER_NAME = { "aes-128-cbc": "aes128-CBC", "aes-192-cbc": "aes192-CBC", "aes-256-cbc": "aes256-CBC" };
+
+// import inference: the algorithm OIDs that name exactly ONE WebCrypto algorithm and need no parameters --
+// the Edwards/Montgomery curves and the FIPS post-quantum ML-DSA, ML-KEM, and SLH-DSA (all signing-only or
+// agreement-only, so unambiguous). RSA (sign vs OAEP) and EC (ECDSA vs ECDH) are deliberately ABSENT -- they
+// are ambiguous, so import fails closed and asks for opts.algorithm rather than guess a plausible use.
+var INFER_ALG = {};
+["Ed25519", "Ed448", "X25519", "X448"].forEach(function (n) { INFER_ALG[O(n)] = { name: n }; });
+[["id-ml-dsa-44", "ML-DSA-44"], ["id-ml-dsa-65", "ML-DSA-65"], ["id-ml-dsa-87", "ML-DSA-87"],
+ ["id-ml-kem-512", "ML-KEM-512"], ["id-ml-kem-768", "ML-KEM-768"], ["id-ml-kem-1024", "ML-KEM-1024"]
+].forEach(function (r) { INFER_ALG[O(r[0])] = { name: r[1] }; });
+// SLH-DSA (FIPS 205) -- all twelve parameter sets; the WebCrypto name is the OID name minus "id-", uppercased.
+["sha2-128s", "sha2-128f", "sha2-192s", "sha2-192f", "sha2-256s", "sha2-256f",
+ "shake-128s", "shake-128f", "shake-192s", "shake-192f", "shake-256s", "shake-256f"
+].forEach(function (s) { INFER_ALG[O("id-slh-dsa-" + s)] = { name: ("SLH-DSA-" + s).toUpperCase() }; });
+
+function _isCryptoKey(x) { return x instanceof CryptoKey; }
+function _algName(a) { return typeof a === "string" ? a : (a && a.name); }
+
+// A private-key input (CryptoKey | DER Buffer | 'PRIVATE KEY' PEM) -> the raw PKCS#8 PrivateKeyInfo DER.
+async function _toPrivateKeyDer(input) {
+  if (_isCryptoKey(input)) {
+    if (input.type !== "private") throw _err("key/bad-input", "a private CryptoKey is required (got a " + input.type + " key)");
+    return Buffer.from(await subtle.exportKey("pkcs8", input));
+  }
+  return pkix.coerceToDer(input, { pemLabel: "PRIVATE KEY", PemError: PemError, ErrorClass: KeyError, prefix: "key" });
+}
+
+/**
+ * @primitive pki.key.encrypt
+ * @signature pki.key.encrypt(privateKey, password, opts?) -> Promise<Buffer|string>
+ * @since 0.3.10
+ * @status experimental
+ * @spec RFC 5958 sec. 3, RFC 8018
+ * @related pki.key.decrypt, pki.schema.pkcs8.parseEncrypted, pki.cms.encrypt
+ *
+ * Encrypt a PKCS#8 private key into an RFC 5958 `EncryptedPrivateKeyInfo` under RFC 8018 PBES2 (PBKDF2 +
+ * AES-CBC-Pad). `privateKey` is a DER `Buffer`, a `PRIVATE KEY` PEM string, or an extractable private
+ * `CryptoKey`; `password` is a string (UTF-8-encoded, byte-identical to OpenSSL), `Buffer`, or `Uint8Array`.
+ * The plaintext is the DER `PrivateKeyInfo`, validated as a well-formed PKCS#8 structure before encryption
+ * (never encrypt opaque bytes), and the produced `EncryptedPrivateKeyInfo` is re-parsed before return.
+ *
+ * The PBKDF2 `prf` equal to the default (`hmacWithSHA1`) is omitted from the parameters (X.690 sec. 11.5),
+ * `keyLength` is omitted (the AES cipher OID fixes the key size), and the salt / iteration count are bounded
+ * -- so the output is byte-exact with OpenSSL's `pkcs8 -topk8 -v2`. A bad input throws a typed `KeyError`.
+ *
+ * @opts
+ *   - `cipher` (string) -- `aes-256-cbc` (default), `aes-192-cbc`, or `aes-128-cbc`.
+ *   - `prf` (string) -- `hmacWithSHA256` (default), `hmacWithSHA384`, `hmacWithSHA512`, or `hmacWithSHA1`.
+ *   - `iterations` (number) -- PBKDF2 iteration count, default 600000 (bounded by the decryptor's cap).
+ *   - `salt` (Buffer) -- an explicit PBKDF2 salt (default 16 random octets).
+ *   - `pem` (boolean) -- return an `ENCRYPTED PRIVATE KEY` PEM string instead of DER.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.key.export(pair.privateKey);
+ *   var enc = await pki.key.encrypt(der, "s3cr3t", { pem: true });
+ *   var back = await pki.key.decrypt(enc, "s3cr3t");
+ */
+async function encrypt(privateKey, password, opts) {
+  opts = opts || {};
+  var der = await _toPrivateKeyDer(privateKey);
+  // RFC 5958 sec. 3: the plaintext is the DER PrivateKeyInfo -- validate it IS one (the strict parser
+  // rejects BER / non-canonical / trailing bytes) before encrypting, so we never wrap opaque input.
+  try { pkcs8.parse(der); } catch (e) { throw _err("key/bad-input", "the private key is not a well-formed PKCS#8 PrivateKeyInfo", e); }
+  var cipherName = CIPHER_NAME[opts.cipher || "aes-256-cbc"];
+  if (!cipherName) throw _err("key/bad-input", "unsupported cipher " + JSON.stringify(opts.cipher) + " (aes-128-cbc / aes-192-cbc / aes-256-cbc)");
+  var keyBits = pbes2.CONTENT_KEYBITS[O(cipherName)];
+  var prf = opts.prf || "hmacWithSHA256";
+  var prfNode = pbes2.prfNodeByName(prf, _err, "key");
+  var iterations = pbes2.assertIterations(opts.iterations == null ? 600000 : opts.iterations, _err, "key");
+  var salt = opts.salt != null ? pbes2.assertSalt(guard.bytes.view(opts.salt, KeyError, "key/bad-input", "salt"), _err, "key") : nodeCrypto.randomBytes(16);
+  var iv = nodeCrypto.randomBytes(16);
+  var dk = nodeCrypto.pbkdf2Sync(pbes2.passwordBytes(password, _err, "key"), salt, iterations, keyBits / 8, prfNode);
+  var ciphertext = pbes2.cbcEncrypt(dk, iv, der, keyBits);
+  var epki = b.sequence([pbes2.pbes2AlgId(salt, iterations, prf, cipherName, iv), b.octetString(ciphertext)]);
+  pkcs8.parseEncrypted(epki);   // self-check: the produced EncryptedPrivateKeyInfo re-parses
+  return opts.pem ? pkcs8.pemEncode(epki, "ENCRYPTED PRIVATE KEY") : epki;
+}
+
+/**
+ * @primitive pki.key.decrypt
+ * @signature pki.key.decrypt(encrypted, password, opts?) -> Promise<Buffer|string>
+ * @since 0.3.10
+ * @status experimental
+ * @spec RFC 5958 sec. 3, RFC 8018 sec. 6.2, RFC 8018 sec. 8
+ * @defends pbes2-padding-oracle (CWE-208), pbkdf2-work-dos (CWE-400)
+ * @related pki.key.encrypt, pki.schema.pkcs8.parse
+ *
+ * Decrypt an RFC 5958 `EncryptedPrivateKeyInfo` (DER `Buffer` or `ENCRYPTED PRIVATE KEY` PEM) under RFC 8018
+ * PBES2, returning the inner `PrivateKeyInfo` (re-validated via `pki.schema.pkcs8.parse`). Only PBES2 with a
+ * PBKDF2 key-derivation function and an AES-CBC encryption scheme is accepted; PBES1, PBMAC1, scrypt, and any
+ * other `encryptionAlgorithm` fail closed with `key/unsupported-algorithm`.
+ *
+ * The salt and iteration count are attacker-controlled work: both caps are enforced BEFORE any derivation
+ * (`opts.maxIterations` may lower the cap, never raise it), and a wrong-length IV or malformed parameter set
+ * is a typed `key/bad-algorithm-parameters`. A MAC-less PBES2-CBC decrypt is not a padding oracle -- a wrong
+ * password and a valid-pad-but-not-a-PrivateKeyInfo both surface the single uniform `key/decrypt-failed`.
+ *
+ * @opts
+ *   - `maxIterations` (number) -- lower the PBKDF2 iteration cap for this decrypt (downward-only).
+ *   - `pem` (boolean) -- return a `PRIVATE KEY` PEM string instead of DER.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var enc = await pki.key.encrypt(await pki.key.export(pair.privateKey), "s3cr3t", { pem: true });
+ *   var der = await pki.key.decrypt(enc, "s3cr3t");
+ */
+async function decrypt(encrypted, password, opts) {
+  opts = opts || {};
+  // opts.maxIterations is a CALLER authoring bound (a downward-only cap): validate it config-time so an
+  // invalid value is a key/bad-input, never a NaN that silently disables the DoS cap and never mis-coded as
+  // a fault in the attacker-controlled input parameters.
+  if (opts.maxIterations != null && (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations)) {
+    throw _err("key/bad-input", "maxIterations must be a positive integer");
+  }
+  var input = pkix.coerceToDer(encrypted, { pemLabel: "ENCRYPTED PRIVATE KEY", PemError: PemError, ErrorClass: KeyError, prefix: "key" });
+  var epki;
+  try { epki = pkcs8.parseEncrypted(input); }
+  catch (e) { throw _err("key/bad-input", "the input is not a well-formed EncryptedPrivateKeyInfo", e); }
+  var encAlg = epki.encryptionAlgorithm;
+  if (encAlg.oid !== O("pbes2")) throw _err("key/unsupported-algorithm", "unsupported key encryption algorithm " + (encAlg.name || encAlg.oid) + " (only RFC 8018 PBES2 is supported)");
+  var plaintext = _decryptPbes2(encAlg, epki.encryptedData, password, opts);
+  return opts.pem ? pkcs8.pemEncode(plaintext, "PRIVATE KEY") : plaintext;
+}
+
+function _decryptPbes2(encAlg, ciphertext, password, opts) {
+  var pb, keyBits, iv;
+  // Structural parse (typed, pre-derivation). These faults are not password-dependent, so a distinct code
+  // per fault leaks no oracle; a raw asn1 fault is normalized to key/bad-algorithm-parameters.
+  try {
+    var params = pbes2.seqChildren(encAlg.parameters, 2, "PBES2 parameters", _err, "key");
+    var kdf = pbes2.requireChildren(params[0], 2, "PBES2 keyDerivationFunc", _err, "key");
+    var encScheme = pbes2.requireChildren(params[1], 2, "PBES2 encryptionScheme", _err, "key");
+    if (asn1.read.oid(kdf[0]) !== O("pbkdf2")) throw _err("key/unsupported-algorithm", "the PBES2 keyDerivationFunc must be PBKDF2 (RFC 8018 sec. 6.2)");
+    pb = pbes2.parsePbkdf2Params(kdf[1].bytes, opts, _err, "key", true);   // strictPrf: reject a non-canonical explicit default prf
+    var encOid = asn1.read.oid(encScheme[0]);
+    keyBits = pbes2.CONTENT_KEYBITS[encOid];
+    if (!keyBits || !/CBC/.test(oid.name(encOid) || "")) throw _err("key/unsupported-algorithm", "unsupported PBES2 encryptionScheme " + (oid.name(encOid) || encOid) + " (AES-CBC only)");
+    iv = asn1.read.octetString(encScheme[1]);
+    if (iv.length !== 16) throw _err("key/bad-algorithm-parameters", "the AES-CBC IV must be 16 octets");
+  } catch (e) {
+    // The shared PBES2 home rejects a malformed / truncated / over-cap parameter with the generic
+    // key/bad-input; in the PBES2 parameter-structure context that IS a bad-algorithm-parameters. The
+    // semantic verdicts it raises (unsupported-algorithm, iteration-limit) keep their precise codes.
+    if (e instanceof KeyError) {
+      if (e.code === "key/bad-input") throw _err("key/bad-algorithm-parameters", e.message, e.cause);
+      throw e;
+    }
+    throw _err("key/bad-algorithm-parameters", "malformed PBES2 parameters", e);
+  }
+  var dk = nodeCrypto.pbkdf2Sync(pbes2.passwordBytes(password, _err, "key"), pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
+  // Post-derivation failures collapse to ONE uniform verdict (RFC 8018 sec. 8): a bad PKCS#7 pad and a
+  // valid pad whose plaintext is not a PrivateKeyInfo are indistinguishable -- the re-parse is the integrity
+  // check for MAC-less PBES2-CBC, and it MUST run (never skipped).
+  var plaintext;
+  try { plaintext = pbes2.cbcDecrypt(dk, iv, ciphertext, keyBits); }
+  catch (_e) { throw _err("key/decrypt-failed", "decryption failed"); }
+  try { pkcs8.parse(plaintext); }
+  catch (_e) { throw _err("key/decrypt-failed", "decryption failed"); }
+  return plaintext;
+}
+
+/**
+ * @primitive pki.key.export
+ * @signature pki.key.export(key, opts?) -> Promise<Buffer|string>
+ * @since 0.3.10
+ * @status experimental
+ * @spec RFC 5958, RFC 5280 sec. 4.1.2.7, RFC 8410 sec. 3
+ * @related pki.key.import, pki.key.publicFromPrivate, pki.schema.pkcs8.parse
+ *
+ * Export an extractable `CryptoKey` to DER (or PEM): a private key as PKCS#8 `OneAsymmetricKey`, a public
+ * key as SubjectPublicKeyInfo. The encoding is delegated to the WebCrypto `exportKey` PKCS#8 / SPKI encoder,
+ * so the algorithm-specific `AlgorithmIdentifier.parameters` are byte-correct -- RSA carries an explicit
+ * NULL, EC a namedCurve OID, and Ed25519 / Ed448 / X25519 / X448 omit parameters (RFC 8410 sec. 3); the
+ * wrapper never re-encodes the AlgorithmIdentifier.
+ *
+ * @opts
+ *   - `format` (string) -- `der` (default) or `pem`.
+ *   - `label` (string) -- the PEM label (defaults `PRIVATE KEY` / `PUBLIC KEY` by key type).
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var spkiPem = await pki.key.export(pair.publicKey, { format: "pem" });
+ */
+async function export_(key, opts) {
+  opts = opts || {};
+  if (!_isCryptoKey(key)) throw _err("key/bad-input", "export expects a WebCrypto CryptoKey");
+  var format, defaultLabel;
+  if (key.type === "private") { format = "pkcs8"; defaultLabel = "PRIVATE KEY"; }
+  else if (key.type === "public") { format = "spki"; defaultLabel = "PUBLIC KEY"; }
+  else throw _err("key/bad-input", "export supports asymmetric (private / public) CryptoKeys only");
+  var der = Buffer.from(await subtle.exportKey(format, key));
+  var fmt = opts.format || "der";
+  if (fmt === "der") return der;
+  if (fmt === "pem") return pkix.pemEncode(der, opts.label || defaultLabel, PemError);
+  throw _err("key/bad-input", "unsupported format " + JSON.stringify(opts.format) + " (der / pem)");
+}
+
+/**
+ * @primitive pki.key.import
+ * @signature pki.key.import(input, opts?) -> Promise<CryptoKey>
+ * @since 0.3.10
+ * @status experimental
+ * @spec RFC 5958, RFC 5280 sec. 4.1.2.7, RFC 8018
+ * @related pki.key.export, pki.key.decrypt
+ *
+ * Import a DER / PEM PKCS#8 private key, SPKI public key, or (with `opts.password`) an `ENCRYPTED PRIVATE
+ * KEY` -- auto-detecting the structure -- into a `CryptoKey`. The WebCrypto algorithm is inferred from the
+ * key's OID for the algorithms that name exactly one (Ed25519 / Ed448 / X25519 / X448 / ML-DSA / ML-KEM /
+ * SLH-DSA); RSA and EC are ambiguous between signing and key agreement, so `opts.algorithm` must be supplied
+ * for them (import fails closed rather than guess a use). Default key usages follow the algorithm and key type.
+ *
+ * @opts
+ *   - `algorithm` (string | object) -- the WebCrypto algorithm (required for RSA / EC; overrides inference).
+ *   - `usages` (string[]) -- key usages (default derived from the algorithm and public/private type).
+ *   - `extractable` (boolean) -- default false.
+ *   - `password` (string | Buffer) -- decrypt an `ENCRYPTED PRIVATE KEY` first.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var spki = await pki.key.export(pair.publicKey);
+ *   var pub = await pki.key.import(spki);                       // Ed25519 -- algorithm inferred
+ */
+async function import_(input, opts) {
+  opts = opts || {};
+  var detected = _detectKeyInput(input);
+  if (detected.format === "encrypted") {
+    if (opts.password == null) throw _err("key/bad-input", "an ENCRYPTED PRIVATE KEY requires opts.password to import");
+    detected = { format: "pkcs8", der: await decrypt(detected.der, opts.password) };
+  }
+  var algorithm = opts.algorithm != null ? opts.algorithm : _inferAlgorithm(detected);
+  var isPublic = detected.format === "spki";
+  var usages = opts.usages || _importUsages(_algName(algorithm), isPublic);
+  var extractable = opts.extractable != null ? opts.extractable : false;
+  try {
+    return await subtle.importKey(detected.format, detected.der, algorithm, extractable, usages);
+  } catch (e) {
+    if (e && e.isPkiError) throw e;
+    throw _err("key/bad-input", "importKey failed", e);
+  }
+}
+
+/**
+ * @primitive pki.key.generate
+ * @signature pki.key.generate(algorithm, opts?) -> Promise<{ privateKey, publicKey }>
+ * @since 0.3.10
+ * @status experimental
+ * @spec W3C WebCrypto, FIPS 203, FIPS 204
+ * @related pki.key.export, pki.key.publicFromPrivate
+ *
+ * Generate an asymmetric key pair over the WebCrypto engine: RSA, ECDSA / ECDH, Ed25519 / Ed448, X25519 /
+ * X448, and the FIPS post-quantum ML-DSA / ML-KEM. `algorithm` is a WebCrypto algorithm string or object;
+ * usages default to the algorithm's natural set (sign/verify, deriveBits/deriveKey, or encapsulate/
+ * decapsulate) and keys are extractable by default. Returns the `{ privateKey, publicKey }` `CryptoKey` pair.
+ *
+ * @opts
+ *   - `extractable` (boolean) -- default true.
+ *   - `usages` (string[]) -- override the default key usages.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pkcs8 = await pki.key.export(pair.privateKey);
+ */
+async function generate(algorithm, opts) {
+  opts = opts || {};
+  var extractable = opts.extractable != null ? opts.extractable : true;
+  var usages = opts.usages || _generateUsages(_algName(algorithm));
+  var pair;
+  try { pair = await subtle.generateKey(algorithm, extractable, usages); }
+  catch (e) { if (e && e.isPkiError) throw e; throw _err("key/bad-input", "generateKey failed", e); }
+  if (!pair || !pair.privateKey || !pair.publicKey) throw _err("key/bad-input", "the algorithm does not generate an asymmetric key pair");
+  return { privateKey: pair.privateKey, publicKey: pair.publicKey };
+}
+
+/**
+ * @primitive pki.key.publicFromPrivate
+ * @signature pki.key.publicFromPrivate(privateKey, opts?) -> Promise<Buffer|string>
+ * @since 0.3.10
+ * @status experimental
+ * @spec RFC 5280 sec. 4.1.2.7, RFC 8410 sec. 3
+ * @related pki.key.export, pki.key.import
+ *
+ * Derive the SubjectPublicKeyInfo (SPKI) public key from a PKCS#8 private key (DER `Buffer`, `PRIVATE KEY`
+ * PEM, or extractable private `CryptoKey`). The derivation is delegated to the node key engine, which infers
+ * the algorithm from the key structure, so no `AlgorithmIdentifier` is re-encoded -- Ed25519 stays
+ * parameters-absent, RSA keeps its NULL, EC keeps its namedCurve.
+ *
+ * @opts
+ *   - `pem` (boolean) -- return a `PUBLIC KEY` PEM string instead of DER.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var spki = await pki.key.publicFromPrivate(await pki.key.export(pair.privateKey));
+ */
+async function publicFromPrivate(privateKey, opts) {
+  opts = opts || {};
+  var der = await _toPrivateKeyDer(privateKey);
+  var spki;
+  try {
+    var priv = nodeCrypto.createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+    spki = nodeCrypto.createPublicKey(priv).export({ format: "der", type: "spki" });
+  } catch (e) { throw _err("key/bad-input", "could not derive the public key from the private key", e); }
+  return opts.pem ? pkix.pemEncode(spki, "PUBLIC KEY", PemError) : spki;
+}
+
+// ---- import helpers --------------------------------------------------------
+
+// Auto-detect a key input by structure (works for a raw DER Buffer or a label-agnostic PEM): a PrivateKeyInfo
+// leads with an INTEGER version; an SPKI is SEQ{ algId, BIT STRING }; an EncryptedPrivateKeyInfo is
+// SEQ{ algId, OCTET STRING }. Returns { format, der }.
+function _detectKeyInput(input) {
+  var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: KeyError, prefix: "key" });
+  var root;
+  try { root = asn1.decode(der); } catch (e) { throw _err("key/bad-input", "the input is not DER or a PEM key", e); }
+  var kids = root.children || [];
+  if (kids.length >= 1 && kids[0].tagClass === "universal" && kids[0].tagNumber === asn1.TAGS.INTEGER) return { format: "pkcs8", der: der };
+  if (kids.length === 2 && kids[1].tagClass === "universal" && kids[1].tagNumber === asn1.TAGS.BIT_STRING) return { format: "spki", der: der };
+  if (kids.length === 2 && kids[1].tagClass === "universal" && kids[1].tagNumber === asn1.TAGS.OCTET_STRING) return { format: "encrypted", der: der };
+  throw _err("key/bad-input", "the input is not a recognized PKCS#8, SPKI, or EncryptedPrivateKeyInfo");
+}
+
+// The AlgorithmIdentifier OID from a detected key: privateKeyAlgorithm (PKCS#8) or algorithm (SPKI).
+function _readAlgOid(detected) {
+  try {
+    if (detected.format === "pkcs8") return pkcs8.parse(detected.der).privateKeyAlgorithm.oid;
+    // SPKI: SEQUENCE { algorithm AlgorithmIdentifier SEQUENCE { OID, ... }, subjectPublicKey BIT STRING }.
+    // Validate the algorithm SEQUENCE shape before dereferencing its OID -- a malformed SPKI must be a typed
+    // reject, never a raw children[] fault.
+    var alg = asn1.decode(detected.der).children[0];
+    if (!alg || alg.tagClass !== "universal" || alg.tagNumber !== asn1.TAGS.SEQUENCE || !alg.children || !alg.children.length) {
+      throw _err("key/bad-input", "malformed SubjectPublicKeyInfo algorithm identifier");
+    }
+    return asn1.read.oid(alg.children[0]);
+  } catch (e) {
+    if (e instanceof KeyError) throw e;
+    throw _err("key/bad-input", "the key algorithm could not be read for inference", e);
+  }
+}
+
+function _inferAlgorithm(detected) {
+  var algOid = _readAlgOid(detected);
+  var a = INFER_ALG[algOid];
+  if (a) return a;
+  throw _err("key/unsupported-algorithm", "cannot infer the WebCrypto algorithm for " + (oid.name(algOid) || algOid) +
+    " (RSA and EC are ambiguous between signing and key agreement -- pass opts.algorithm)");
+}
+
+// Default key usages by algorithm CLASS. The name is normalized to upper case first: WebCrypto matches
+// algorithm names case-insensitively, so a caller passing { name: "x25519" } / "ml-kem-768" must land on the
+// same usage class as the canonical spelling rather than fall through to the signing default.
+function _importUsages(name, isPublic) {
+  var n = String(name == null ? "" : name).toUpperCase();
+  if (n === "X25519" || n === "X448" || n === "ECDH") return isPublic ? [] : ["deriveBits", "deriveKey"];
+  if (/^ML-KEM/.test(n)) return isPublic ? ["encapsulateBits"] : ["decapsulateBits"];
+  if (n === "RSA-OAEP") return isPublic ? ["encrypt"] : ["decrypt"];
+  return isPublic ? ["verify"] : ["sign"];   // signing default (Ed / ECDSA / RSA-* sign / ML-DSA / SLH-DSA)
+}
+
+function _generateUsages(name) {
+  var n = String(name == null ? "" : name).toUpperCase();
+  if (n === "X25519" || n === "X448" || n === "ECDH") return ["deriveBits", "deriveKey"];
+  if (/^ML-KEM/.test(n)) return ["encapsulateBits", "decapsulateBits"];
+  if (n === "RSA-OAEP") return ["encrypt", "decrypt"];
+  return ["sign", "verify"];
+}
+
+module.exports = {
+  encrypt: encrypt,
+  decrypt: decrypt,
+  export: export_,
+  import: import_,
+  generate: generate,
+  publicFromPrivate: publicFromPrivate,
+};

package/lib/pbes2.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- the RFC 8018 PBES2 / PBKDF2 primitives, the ONE home shared by pki.cms EncryptedData / PWRI
+// password encryption and pki.key EncryptedPrivateKeyInfo (RFC 5958). Error-factory-parameterized like the
+// guard family: every reject goes through the CALLER's `E(code, msg, cause)` full-code factory plus a domain
+// `prefix`, so pki.cms keeps cms/* codes and pki.key keeps key/* codes off ONE implementation. Extracted
+// behavior-preservingly from cms-encrypt.js + cms-decrypt.js -- the shipped CMS PBES2 tests are the guard.
+// A shape here that CANNOT route through a guard stays with its caller; the reusable PBES2 shape lives here
+// so a fourth copy (the drift a reviewer flags) cannot re-accrete.
+
+var nodeCrypto = require("crypto");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var guard = require("./guard-all");
+var C = require("./constants");
+
+var b = asn1.build;
+function O(n) { return oid.byName(n); }
+
+// PBKDF2 prf tables: the OID name -> node digest (encrypt names the prf) and the OID -> node digest (decrypt
+// reads the OID). One source, both directions.
+var PRF_NODE_BY_NAME = { hmacWithSHA1: "sha1", hmacWithSHA256: "sha256", hmacWithSHA384: "sha384", hmacWithSHA512: "sha512" };
+var PRF_NODE_BY_OID = {}; Object.keys(PRF_NODE_BY_NAME).forEach(function (n) { PRF_NODE_BY_OID[O(n)] = PRF_NODE_BY_NAME[n]; });
+
+// content-encryption OID -> AES key bits (CBC + GCM). The PBES2 encryptionScheme + CMS content cipher table.
+var CONTENT_KEYBITS = {};
+[["aes128-CBC", 128], ["aes192-CBC", 192], ["aes256-CBC", 256], ["aes128-GCM", 128], ["aes192-GCM", 192], ["aes256-GCM", 256]].forEach(function (r) { CONTENT_KEYBITS[O(r[0])] = r[1]; });
+
+// A password is an octet string (RFC 8018 sec. 2): a string is UTF-8-encoded deterministically (correct for
+// non-ASCII, and byte-identical to OpenSSL), a Buffer/Uint8Array used verbatim.
+function passwordBytes(p, E, prefix) {
+  if (Buffer.isBuffer(p)) return p;
+  if (p instanceof Uint8Array) return Buffer.from(p);
+  if (typeof p === "string") return Buffer.from(p, "utf8");
+  throw E(prefix + "/bad-input", "a password must be a string, Buffer, or Uint8Array");
+}
+
+// iterationCount for a PRODUCED PBES2/PWRI structure: a positive integer at or below the cap the decryptor
+// enforces, so a structure we emit is always one we can read back (config-time throw on a bad value).
+function assertIterations(n, E, prefix) {
+  if (typeof n !== "number" || !isFinite(n) || n < 1 || Math.floor(n) !== n) throw E(prefix + "/bad-input", "iterations must be a positive integer");
+  if (n > C.LIMITS.PBKDF2_MAX_ITERATIONS) throw E(prefix + "/bad-input", "iterations exceeds the " + C.LIMITS.PBKDF2_MAX_ITERATIONS + " cap");
+  return n;
+}
+
+// Bound a PRODUCED salt to the same cap the decryptor enforces.
+function assertSalt(salt, E, prefix) {
+  guard.limits.byteCap(salt, C.LIMITS.PBKDF2_MAX_SALT, E, prefix + "/bad-input", "salt");
+  return salt;
+}
+
+function prfNodeByName(prf, E, prefix) { if (!PRF_NODE_BY_NAME[prf]) throw E(prefix + "/bad-input", "unsupported prf " + JSON.stringify(prf)); return PRF_NODE_BY_NAME[prf]; }
+function prfNodeByOid(oidStr, E, prefix) { if (!PRF_NODE_BY_OID[oidStr]) throw E(prefix + "/unsupported-algorithm", "unsupported PBKDF2 prf " + oidStr); return PRF_NODE_BY_OID[oidStr]; }
+
+// PBKDF2-params { salt OCTET STRING, iterationCount INTEGER, prf DEFAULT hmacWithSHA1 }. prf equal to the
+// DEFAULT (hmacWithSHA1) MUST be omitted on encode (X.690 sec. 11.5 / RFC 8018 App. A.2); every other prf is
+// an hmacWithSHA_n AlgorithmIdentifier carrying NULL parameters.
+function pbkdf2ParamsSeq(salt, iterations, prf) {
+  var kids = [b.octetString(salt), b.integer(BigInt(iterations))];
+  if (prf !== "hmacWithSHA1") kids.push(b.sequence([b.oid(O(prf)), b.nullValue()]));
+  return b.sequence(kids);
+}
+
+// The PBES2 AlgorithmIdentifier: SEQUENCE { id-PBES2, SEQUENCE { keyDerivationFunc PBKDF2, encryptionScheme } }.
+// The ONE home for the CMS EncryptedData contentEncryptionAlgorithm AND the RFC 5958 EncryptedPrivateKeyInfo
+// encryptionAlgorithm -- both wrap the same PBES2 structure around a PBKDF2 KDF plus an AES-CBC scheme whose
+// IV rides in the encryptionScheme parameter. `cipherName` is a registry NAME (an AES-CBC OID name).
+function pbes2AlgId(salt, iterations, prf, cipherName, iv) {
+  var kdf = b.sequence([b.oid(O("pbkdf2")), pbkdf2ParamsSeq(salt, iterations, prf)]);
+  var encScheme = b.sequence([b.oid(O(cipherName)), b.octetString(iv)]);
+  return b.sequence([b.oid(O("pbes2")), b.sequence([kdf, encScheme])]);
+}
+
+// SEQUENCE structural guards -- a malformed (primitive / too-short) attacker-controlled parameter SEQUENCE is
+// a typed E(prefix + "/bad-input"), never a raw `.children` dereference fault (a PBES2 structure is public,
+// not a decrypt oracle).
+function requireChildren(node, minLen, what, E, prefix) {
+  if (!node || !node.children || node.children.length < minLen) throw E(prefix + "/bad-input", "malformed " + what);
+  return node.children;
+}
+function seqChildren(paramsDer, minLen, what, E, prefix) {
+  if (paramsDer == null) throw E(prefix + "/bad-input", "missing " + what);
+  return requireChildren(asn1.decode(paramsDer), minLen, what, E, prefix);
+}
+
+// Strict PBKDF2-params decode: salt (capped BEFORE derivation), iterationCount (positiveInt31 + cap, downward-
+// overridable via a validated-positive-int opts.maxIterations so Math.min(NaN, cap) cannot silently disable
+// the DoS cap), prf. Returns { salt, iterations, prfNode }.
+function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
+  var node = Buffer.isBuffer(paramsDer) ? asn1.decode(paramsDer) : paramsDer;
+  var kids = requireChildren(node, 2, "PBKDF2 parameters", E, prefix);
+  var salt = asn1.read.octetString(kids[0]);
+  if (salt.length > C.LIMITS.PBKDF2_MAX_SALT) throw E(prefix + "/bad-input", "PBKDF2 salt exceeds the " + C.LIMITS.PBKDF2_MAX_SALT + "-octet cap");
+  var iterations = guard.range.positiveInt31(asn1.read.integer(kids[1]), E, prefix + "/bad-input", "PBKDF2 iterationCount");
+  var cap = C.LIMITS.PBKDF2_MAX_ITERATIONS;
+  if (opts && opts.maxIterations != null) {
+    if (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations) throw E(prefix + "/bad-input", "maxIterations must be a positive integer");
+    cap = Math.min(opts.maxIterations, cap);
+  }
+  if (iterations > cap) throw E(prefix + "/iteration-limit", "PBKDF2 iterationCount " + iterations + " exceeds the cap " + cap);
+  var prfNode = "sha1";
+  for (var i = 2; i < node.children.length; i++) {
+    var ch = node.children[i];
+    if (ch.tagClass === "universal" && ch.tagNumber === asn1.TAGS.SEQUENCE) {
+      var prfOid = asn1.read.oid(ch.children[0]);
+      // X.690 sec. 11.5 / RFC 8018 App. A.2: a prf equal to the DEFAULT (hmacWithSHA1 with NULL parameters)
+      // MUST be omitted -- an explicit encoding of it is non-canonical. A strictPrf caller rejects it.
+      if (strictPrf && prfOid === O("hmacWithSHA1") && ch.children.length > 1 && ch.children[1].tagClass === "universal" && ch.children[1].tagNumber === asn1.TAGS.NULL) {
+        throw E(prefix + "/bad-input", "a PBKDF2 prf equal to the default hmacWithSHA1 must be omitted (X.690 sec. 11.5)");
+      }
+      prfNode = prfNodeByOid(prfOid, E, prefix);
+    }
+  }
+  return { salt: salt, iterations: iterations, prfNode: prfNode };
+}
+
+// AES-CBC content encryption / decryption (PKCS#7 pad). decrypt's final() throws on bad pad -- the caller
+// collapses that into its uniform decrypt-failed verdict.
+function cbcEncrypt(key, iv, plaintext, keyBits) {
+  var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
+  return Buffer.concat([c.update(plaintext), c.final()]);
+}
+function cbcDecrypt(key, iv, ct, keyBits) {
+  var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-cbc", key, iv);
+  return Buffer.concat([d.update(ct), d.final()]);
+}
+
+module.exports = {
+  passwordBytes: passwordBytes, assertIterations: assertIterations, assertSalt: assertSalt,
+  prfNodeByName: prfNodeByName, prfNodeByOid: prfNodeByOid,
+  pbkdf2ParamsSeq: pbkdf2ParamsSeq, pbes2AlgId: pbes2AlgId, parsePbkdf2Params: parsePbkdf2Params,
+  requireChildren: requireChildren, seqChildren: seqChildren,
+  cbcEncrypt: cbcEncrypt, cbcDecrypt: cbcDecrypt, CONTENT_KEYBITS: CONTENT_KEYBITS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "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:c2eb240a-1337-4a5a-862e-43dad1701426",
+  "serialNumber": "urn:uuid:0bc607cc-142c-4a49-a525-90a6f0216e38",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-23T16:52:13.594Z",
+    "timestamp": "2026-07-23T18:57:16.468Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.9",
+      "bom-ref": "@blamejs/pki@0.3.10",
       "type": "application",
       "name": "pki",
-      "version": "0.3.9",
+      "version": "0.3.10",
       "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.3.9",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.10",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.9",
+      "ref": "@blamejs/pki@0.3.10",
       "dependsOn": []
     }
   ]