@blamejs/pki 0.3.10 → 0.3.12

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.3.12 — 2026-07-24
+
+pki.pkcs12.open reads and decrypts a password-integrity PKCS#12 store (RFC 7292, RFC 9579).
+
+### Added
+
+- pki.pkcs12.open(pfx, password, opts) reads a password-integrity PKCS#12 store. It verifies the classic Appendix B HMAC or RFC 9579 PBMAC1 MAC before decrypting (RFC 7292 sec. 5.1), then PBES2-decrypts every privacy safe and pkcs8ShroudedKeyBag, returning { integrityMode, macVerified, keys, certs, crls, secrets } -- private keys as re-validated PKCS#8 DER, certificates/CRLs/secrets as raw DER, all carrying friendlyName and localKeyId, and nested safeContents recursively. A wrong password fails at the MAC gate (pkcs12/mac-mismatch); a MAC-less store is refused (pkcs12/no-integrity) unless opts.allowUnauthenticated is set; a public-key-integrity store and a legacy (non-PBES2) bag are refused; a post-MAC decrypt failure is the uniform pkcs12/decrypt-failed. opts.maxIterations lowers the KDF/MAC iteration cap for the call, and opts.keys 'crypto' imports each private key to a WebCrypto CryptoKey (opts.importAlgorithm for the ambiguous RSA/EC arms). pfx accepts a DER Buffer, PEM string, or a pki.schema.pkcs12.parse result. RFC 7292 sec. 5.1, RFC 9579, RFC 8018.
+
+## v0.3.11 — 2026-07-23
+
+pki.pkcs12 builds and MAC-verifies password-integrity PKCS#12 (.p12/.pfx) stores (RFC 7292, RFC 9579).
+
+### Added
+
+- pki.pkcs12.build(spec, opts) builds a password-integrity PKCS#12 store. spec is { key, cert, ca?, friendlyName?, localKeyId? } (one PBES2-encrypted cert safe plus one shrouded-key safe) or { 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. opts.mac selects a classic Appendix B HMAC (default) or an RFC 9579 PBMAC1 over SHA-256/384/512, or false for a MAC-less store; opts.password is the shared privacy + integrity password; opts.pem returns a PEM PKCS12 string. Shrouded keys and cert safes are encrypted under RFC 8018 PBES2 (AES-128/192/256-CBC). Passwords are BMPString+NULL encoded for the classic MAC and UTF-8 for the PBES2 bags and PBMAC1, so the output opens in OpenSSL and NSS; the MAC covers the exact AuthenticatedSafe byte range, a DEFAULT-1 MacData iterations and a <=160-bit PBMAC1 digest are rejected, and the store is re-parsed before return. RFC 7292, RFC 9579, RFC 8018.
+- pki.pkcs12.verifyMac(pfx, password, opts) verifies a password-integrity store's MAC. pfx is a pki.schema.pkcs12.parse result, a DER Buffer, or a PEM string; the password is BMPString+NULL (classic) or UTF-8 (PBMAC1) encoded, the MAC is recomputed over the store's exact AuthenticatedSafe byte range with the store's own MAC parameters, and constant-time-compared to the stored value. Returns true / false for the password match; throws Pkcs12Error on a MAC-less or public-key-integrity store, or an unsupported MAC algorithm. RFC 7292 sec. 5.1, RFC 9579.
+- pki.asn1.build.bmpString(str) encodes a JS string as a universal BMPString (UTF-16BE) TLV, rejecting an unpaired surrogate code point.
+
 ## v0.3.10 — 2026-07-23
 
 pki.key exports, imports, and PBES2-encrypts private keys (RFC 5958, RFC 8018) over every WebCrypto algorithm.

package/README.md

@@ -229,6 +229,7 @@ is callable today; nothing below is a stub.
 | `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.pkcs12` | RFC 7292 / RFC 9579 PKCS#12 (.p12/.pfx) issuance — `build(spec, opts)` assembles a password-integrity store. `spec` is 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 / nested `safeContents` bags. Keys and certs are validated before wrapping; `friendlyName` (BMPString) and `localKeyId` attributes are single-value. The store is protected by a classic Appendix B HMAC (default, max interop) or an RFC 9579 PBMAC1 (`opts.mac.algorithm`), over SHA-256/384/512, with the 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 (what OpenSSL and NSS consume) — so a file it emits opens in OpenSSL and NSS, cross-checked bidirectionally. The MAC is computed over 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 store's classic or PBMAC1 MAC over `macedBytes` and constant-time-compares it, throwing on a MAC-less or public-key-integrity store. Public-key integrity and legacy-PBE (PKCS#12 Appendix C) bag decryption are not yet built. Returns DER or a PEM `PKCS12`; fail-closed with typed `Pkcs12Error`. `open(pfx, password, opts)` reads a store back: it verifies the MAC **first** (a wrong password is the MAC verdict, not a decrypt error), then PBES2-decrypts every privacy safe and shrouded key bag and returns `{ integrityMode, macVerified, keys, certs, crls, secrets }` — keys as re-validated PKCS#8 DER, certs/CRLs/secrets as raw DER, all with `friendlyName`/`localKeyId`, nested safes recursively. A MAC-less store is refused unless `opts.allowUnauthenticated`, a public-key-integrity or legacy-PBE store is refused, a post-MAC decrypt failure is the uniform `pkcs12/decrypt-failed`, and `opts.keys: 'crypto'` imports each key to a `CryptoKey`; it reads what OpenSSL and NSS produce. Parsing stays at `pki.schema.pkcs12.parse` — `build` / `verifyMac` / `open` |
 | `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` |
@@ -270,11 +271,10 @@ certificate and writes a DER (or `--pem`) SignedData to `--out` or stdout.
 
 ### What's coming
 
-Certificate build/sign/verify, CMS AuthenticatedData /
-AuthEnvelopedData, PKCS#8 decryption (PBES2) / SPKI, PKCS#12 MAC verification
-and bag decryption, and the post-quantum certificate and CMS surface (ML-DSA /
-ML-KEM / SLH-DSA and hybrid composites) are on the roadmap and ride this same
-core. See
+Thin enrollment-protocol HTTP clients (ACME, EST, CMP transport over
+`node:https`), PKCS#12 public-key integrity and legacy-PBE (Appendix C) bag
+decryption, and CMS countersignatures / unsigned attributes are on the roadmap
+and ride this same core. See
 [ROADMAP.md](ROADMAP.md) for the full plan and current status of each area, and
 [CHANGELOG.md](CHANGELOG.md) for what has landed.
 

package/index.js

@@ -47,6 +47,7 @@ var crmf      = require("./lib/crmf-sign");
 var cmp       = require("./lib/cmp-build");
 var crl       = require("./lib/crl-sign");
 var key       = require("./lib/key");
+var pkcs12    = require("./lib/pkcs12-build");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
@@ -118,6 +119,11 @@ module.exports = {
   // 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,
+  // `pkcs12` is the RFC 7292 / RFC 9579 PKCS#12 (.p12/.pfx) producing side -- pki.pkcs12.build assembles a
+  // password-integrity store (key/cert/crl/secret bags in an AuthenticatedSafe, shrouded keys + cert safes
+  // under PBES2, a classic HMAC or PBMAC1 MAC), and pki.pkcs12.verifyMac checks a store's MAC. Parsing lives
+  // at pki.schema.pkcs12.parse.
+  pkcs12:    pkcs12,
   // `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/asn1-der.js

@@ -971,6 +971,20 @@ var build = {
     if (!PRINTABLE_RE.test(s)) throw new Asn1Error("asn1/bad-printable-string", "value has characters outside the PrintableString set");
     return _universal(TAGS.PRINTABLE_STRING, false, Buffer.from(s, "latin1"));
   },
+  bmpString: function (s) {
+    // BMPString (UCS-2, X.680) encodes each character as a 2-byte big-endian BMP scalar value -- the exact
+    // inverse of _decodeUtf16be. A surrogate code unit (U+D800..U+DFFF), whether lone or half of a >U+FFFF
+    // pair, cannot be a BMPString character, so it is rejected rather than silently emitted.
+    s = String(s);
+    var out = Buffer.alloc(s.length * 2);
+    for (var i = 0; i < s.length; i++) {
+      var u = s.charCodeAt(i);
+      if (u >= 0xD800 && u <= 0xDFFF) throw new Asn1Error("asn1/bad-bmp-string", "BMPString cannot encode a surrogate code point (non-BMP characters are unsupported)");
+      out[i * 2] = (u >> 8) & 0xFF;
+      out[i * 2 + 1] = u & 0xFF;
+    }
+    return _universal(TAGS.BMP_STRING, false, out);
+  },
   utcTime:  function (date) { return _universal(TAGS.UTC_TIME, false, Buffer.from(_utcTimeString(date), "latin1")); },
   generalizedTime: function (date) { return _universal(TAGS.GENERALIZED_TIME, false, Buffer.from(_generalizedTimeString(date), "latin1")); },
   sequence: function (children) { return _universal(TAGS.SEQUENCE, true, Buffer.concat(_asBufferArray(children, "build.sequence"))); },

package/lib/cmp-build.js

@@ -38,6 +38,7 @@ var signScheme = require("./sign-scheme");
 var pkix = require("./schema-pkix");
 var pkiBuild = require("./pki-build");
 var webcrypto = require("./webcrypto");
+var pbes2 = require("./pbes2");
 var constants = require("./constants");
 var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
@@ -148,9 +149,6 @@ function _encodeGeneralInfo(itavs, code, what) {
 
 // An AlgorithmIdentifier { algorithm OID, parameters ANY OPTIONAL } for a bare/absent-params digest.
 function _algIdNoParams(name) { return b.sequence([b.oid(O(name))]); }
-// An HMAC AlgorithmIdentifier carries NULL parameters (RFC 8018 App. B.1.1 / RFC 4231), unlike a bare SHA-2
-// digest algId (ABSENT parameters, RFC 5754 sec. 2). Used for the PBMAC1 prf + messageAuthScheme.
-function _hmacAlgId(name) { return b.sequence([b.oid(O(name)), b.nullValue()]); }
 
 // PKIHeader ::= SEQUENCE { pvno INTEGER, sender GeneralName, recipient GeneralName, EXPLICIT [0..8] }.
 // protectionAlgDer is the DERIVED AlgorithmIdentifier ([1]), present iff the message is protected. Returns
@@ -473,17 +471,6 @@ function _encodeBody(bodySpec, key, opts) {
 
 // ---- protection ----
 
-// PBMAC1 protectionAlg: id-PBMAC1 with PBMAC1-params { keyDerivationFunc PBKDF2{salt,iter,keyLength,prf},
-// messageAuthScheme HMAC } -- the byte-exact inverse of schema-pkcs12.js PBMAC1_PARAMS / PBKDF2_PARAMS.
-function _encodePbmac1AlgId(pd) {
-  var pbkdf2Params = [b.octetString(pd.salt), b.integer(BigInt(pd.iterationCount)), b.integer(BigInt(pd.keyLength))];
-  // prf: omit iff the DEFAULT algid-hmacWithSHA1; else the prf AlgorithmIdentifier with ABSENT params.
-  // nosemgrep: pki-non-constant-time-secret-compare -- prfName is a PRF algorithm name, not a secret
-  if (pd.prfName !== "hmacWithSHA1") pbkdf2Params.push(_hmacAlgId(pd.prfName));
-  var pbkdf2AlgId = b.sequence([b.oid(O("pbkdf2")), b.sequence(pbkdf2Params)]);
-  var pbmac1Params = b.sequence([pbkdf2AlgId, _hmacAlgId(pd.macName)]);
-  return b.sequence([b.oid(O("pbmac1")), pbmac1Params]);
-}
 
 // Resolve the protection selector to { protectionAlgDer, computeBits(protectedPartDer)->Promise<Buffer> },
 // senderSpki, senderScheme } BEFORE the header is built (protectionAlg is opts-derived, not header-derived).
@@ -538,28 +525,16 @@ function _resolveProtection(opts) {
   var macDesc = { salt: salt, iterationCount: iterationCount, keyLength: keyLength, prfName: PBMAC1_PRF[prf], macName: PBMAC1_MAC_OID[prf] };
 
   return {
-    protectionAlgDer: _encodePbmac1AlgId(macDesc),
+    protectionAlgDer: pbes2.pbmac1AlgId(macDesc),
     certDer: null,
     computeBits: function (protectedPartDer) {
-      return _pbmac1(secretBuf, salt, iterationCount, keyLength, prf, protectedPartDer).then(function (mac) {
+      return pbes2.pbmac1(secretBuf, salt, iterationCount, keyLength, prf, prf, protectedPartDer).then(function (mac) {
         return b.bitString(mac, 0);
       });
     },
   };
 }
 
-// PBKDF2-derive an HMAC key from the shared secret, then HMAC the ProtectedPart (both via the engine).
-function _pbmac1(secretBuf, salt, iterationCount, keyLength, prf, message) {
-  var subtle = webcrypto.webcrypto.subtle;
-  return subtle.importKey("raw", secretBuf, { name: "PBKDF2" }, false, ["deriveBits"]).then(function (baseKey) {
-    return subtle.deriveBits({ name: "PBKDF2", salt: salt, iterations: iterationCount, hash: prf }, baseKey, keyLength * 8);
-  }).then(function (bits) {
-    return subtle.importKey("raw", Buffer.from(bits), { name: "HMAC", hash: prf }, false, ["sign"]).then(function (hmacKey) {
-      return subtle.sign({ name: "HMAC" }, hmacKey, message);
-    });
-  }).then(function (sig) { return Buffer.from(sig); });
-}
-
 // ---- orchestrator ----
 
 function build(message, opts) {

package/lib/key.js

@@ -174,37 +174,10 @@ async function decrypt(encrypted, password, opts) {
 }
 
 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"); }
+  // The shared PBES2 decrypt home (strict params + the uniform decrypt-failed on a wrong key / bad pad). The
+  // plaintext re-parse below is the MAC-less PBES2-CBC integrity check (RFC 8018 sec. 8): a bad pad and a
+  // valid pad whose plaintext is not a PrivateKeyInfo are indistinguishable, and it MUST run (never skipped).
+  var plaintext = pbes2.pbes2Decrypt(pbes2.passwordBytes(password, _err, "key"), encAlg.parameters, ciphertext, opts, _err, "key");
   try { pkcs8.parse(plaintext); }
   catch (_e) { throw _err("key/decrypt-failed", "decryption failed"); }
   return plaintext;

package/lib/pbes2.js

@@ -13,6 +13,7 @@
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
+var webcrypto = require("./webcrypto");
 var guard = require("./guard-all");
 var C = require("./constants");
 
@@ -127,10 +128,89 @@ function cbcDecrypt(key, iv, ct, keyBits) {
   return Buffer.concat([d.update(ct), d.final()]);
 }
 
+// Higher-level PBES2 AES-CBC encrypt: derive an AES key from PRE-FORMATTED password bytes (the caller owns
+// the encoding -- CMS UTF-8 vs PKCS#12 App. B.1) and encrypt the plaintext, returning the PBES2
+// AlgorithmIdentifier + ciphertext. `cipherName` is an AES-CBC registry name (aes128/192/256-CBC).
+function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
+  opts = opts || {};
+  var cipherName = opts.cipher || "aes256-CBC";
+  var keyBits = CONTENT_KEYBITS[O(cipherName)];
+  if (!keyBits || !/CBC/.test(cipherName)) throw E(prefix + "/bad-input", "unsupported PBES2 cipher " + cipherName + " (AES-CBC only)");
+  var prf = opts.prf || "hmacWithSHA256";
+  var prfNode = prfNodeByName(prf, E, prefix);
+  var iterations = assertIterations(opts.iterations == null ? 2048 : opts.iterations, E, prefix);
+  var salt = opts.salt != null ? assertSalt(opts.salt, E, prefix) : nodeCrypto.randomBytes(16);
+  var iv = opts.iv != null ? opts.iv : nodeCrypto.randomBytes(16);
+  var key = nodeCrypto.pbkdf2Sync(pwBytes, salt, iterations, keyBits / 8, prfNode);
+  return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits) };
+}
+
+// PBES2 AES-CBC DECRYPT: parse the PBES2 params (PBKDF2 kdf + AES-CBC scheme), derive the key from
+// PRE-FORMATTED password bytes (the caller owns UTF-8 vs BMPString), and AES-CBC-decrypt. Structural faults
+// (a non-PBKDF2 KDF, a non-AES-CBC scheme, an over-cap salt/iteration, a wrong-length IV, a malformed param
+// SEQUENCE) are typed pre-derivation and password-independent, so they leak no oracle; the generic
+// <prefix>/bad-input a param guard raises is normalized to the structural <prefix>/bad-algorithm-parameters.
+// A wrong key / bad PKCS#7 pad collapses to the UNIFORM <prefix>/decrypt-failed (RFC 8018 sec. 8). The
+// plaintext integrity re-check (re-parse as a PrivateKeyInfo / SafeContents) is the CALLER's step.
+function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix) {
+  var keyBits, iv, pb;
+  try {
+    var p = seqChildren(params, 2, "PBES2 parameters", E, prefix);
+    var kdf = requireChildren(p[0], 2, "PBES2 keyDerivationFunc", E, prefix);
+    var encScheme = requireChildren(p[1], 2, "PBES2 encryptionScheme", E, prefix);
+    if (asn1.read.oid(kdf[0]) !== O("pbkdf2")) throw E(prefix + "/unsupported-algorithm", "the PBES2 keyDerivationFunc must be PBKDF2 (RFC 8018 sec. 6.2)");
+    pb = parsePbkdf2Params(kdf[1].bytes, opts, E, prefix, true);   // strictPrf: reject a non-canonical explicit default prf
+    var encOid = asn1.read.oid(encScheme[0]);
+    keyBits = CONTENT_KEYBITS[encOid];
+    if (!keyBits || !/CBC/.test(oid.name(encOid) || "")) throw E(prefix + "/unsupported-algorithm", "unsupported PBES2 encryptionScheme " + (oid.name(encOid) || encOid) + " (AES-CBC only)");
+    iv = asn1.read.octetString(encScheme[1]);
+    if (iv.length !== 16) throw E(prefix + "/bad-algorithm-parameters", "the AES-CBC IV must be 16 octets");
+  } catch (e) {
+    if (e && e.isPkiError && typeof e.code === "string" && e.code.indexOf(prefix + "/") === 0) {
+      if (e.code === prefix + "/bad-input") throw E(prefix + "/bad-algorithm-parameters", e.message, e.cause);
+      throw e;
+    }
+    throw E(prefix + "/bad-algorithm-parameters", "malformed PBES2 parameters", e);
+  }
+  var dk = nodeCrypto.pbkdf2Sync(pwBytes, pb.salt, pb.iterations, keyBits / 8, pb.prfNode);
+  try { return cbcDecrypt(dk, iv, ciphertext, keyBits); }
+  catch (_e) { throw E(prefix + "/decrypt-failed", "decryption failed"); }
+}
+
+// ---- PBMAC1 (RFC 9579 / RFC 8018 App. A.5) : PBKDF2 -> HMAC over a message --
+// An hmacWithSHA_n AlgorithmIdentifier carries NULL parameters (RFC 8018 B.1.1).
+function _hmacAlgId(name) { return b.sequence([b.oid(O(name)), b.nullValue()]); }
+
+// The id-PBMAC1 AlgorithmIdentifier: id-PBMAC1 + PBMAC1-params { keyDerivationFunc PBKDF2, messageAuthScheme
+// HMAC } -- the byte-exact inverse of schema-pkcs12 / schema-cmp's PBMAC1_PARAMS. `desc` = { salt,
+// iterationCount, keyLength, prfName, macName }. The prf is omitted iff it equals the default hmacWithSHA1.
+function pbmac1AlgId(desc) {
+  var pbkdf2Params = [b.octetString(desc.salt), b.integer(BigInt(desc.iterationCount)), b.integer(BigInt(desc.keyLength))];
+  if (desc.prfName !== "hmacWithSHA1") pbkdf2Params.push(_hmacAlgId(desc.prfName));
+  var pbkdf2AlgId = b.sequence([b.oid(O("pbkdf2")), b.sequence(pbkdf2Params)]);
+  return b.sequence([b.oid(O("pbmac1")), b.sequence([pbkdf2AlgId, _hmacAlgId(desc.macName)])]);
+}
+
+// Compute PBMAC1 = HMAC_macHash(PBKDF2(pwBytes, salt, iter, keyLength, prfHash), message). The PBKDF2 prf
+// and the HMAC messageAuthScheme are INDEPENDENT (RFC 9579 sec. 4 / RFC 8018 App. A.5) -- e.g. a SHA-512 PRF
+// with a SHA-256 HMAC -- so both are passed explicitly. `prfHash` / `macHash` are WebCrypto hash names
+// ("SHA-256"); pwBytes is pre-formatted (the caller owns the encoding).
+function pbmac1(pwBytes, salt, iterationCount, keyLength, prfHash, macHash, message) {
+  var subtle = webcrypto.webcrypto.subtle;
+  return subtle.importKey("raw", pwBytes, { name: "PBKDF2" }, false, ["deriveBits"]).then(function (baseKey) {
+    return subtle.deriveBits({ name: "PBKDF2", salt: salt, iterations: iterationCount, hash: prfHash }, baseKey, keyLength * 8);
+  }).then(function (bits) {
+    return subtle.importKey("raw", Buffer.from(bits), { name: "HMAC", hash: macHash }, false, ["sign"]).then(function (hmacKey) {
+      return subtle.sign({ name: "HMAC" }, hmacKey, message);
+    });
+  }).then(function (sig) { return Buffer.from(sig); });
+}
+
 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,
+  cbcEncrypt: cbcEncrypt, cbcDecrypt: cbcDecrypt, pbes2Encrypt: pbes2Encrypt, pbes2Decrypt: pbes2Decrypt, CONTENT_KEYBITS: CONTENT_KEYBITS,
+  pbmac1AlgId: pbmac1AlgId, pbmac1: pbmac1,
 };

package/lib/pkcs12-build.js

@@ -0,0 +1,551 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.pkcs12
+ * @nav        Signing
+ * @title      PKCS#12
+ * @intro The PKCS#12 (.p12 / .pfx) producing side (RFC 7292, RFC 9579). `pki.pkcs12.build` assembles a
+ *   password-integrity PFX -- key, certificate, CRL, and secret bags (shrouded keys and cert safes encrypted
+ *   under RFC 8018 PBES2) wrapped in an AuthenticatedSafe, protected by either a classic Appendix B HMAC or
+ *   an RFC 9579 PBMAC1 (PBKDF2 + HMAC) MAC, over AES-128/192/256-CBC and SHA-256/384/512. Every password is
+ *   encoded the PKCS#12 way (BMPString + NULL, Appendix B.1), so a file it emits opens in OpenSSL and NSS.
+ *   `pki.pkcs12.verifyMac` recomputes a store's MAC over the exact AuthenticatedSafe byte range and
+ *   constant-time-compares it. Parsing lives at `pki.schema.pkcs12.parse`.
+ * @spec RFC 7292, RFC 9579, RFC 8018
+ * @card Build a password-integrity PKCS#12 store (RFC 7292 / RFC 9579) and verify its MAC.
+ */
+//
+// The PBES2 bag encryption and the PBMAC1 MAC compose the shared lib/pbes2.js home (the same PBKDF2 + AES-CBC
+// + HMAC primitives pki.cms and pki.key use), fed PKCS#12 App. B.1-formatted password bytes -- NOT the CMS
+// UTF-8 encoding, the single most common PKCS#12 interop failure. The classic Appendix B.2 KDF (ID=3, the MAC
+// integrity purpose) is bespoke PKCS#12 crypto with no in-tree equivalent, built here as one primitive and
+// cross-checked against OpenSSL. The MAC is computed over the CONTENT octets of the id-data authSafe OCTET
+// STRING (excluding its TLV header) -- exactly the parser's `macedBytes`, the canonical off-by-the-header
+// trap designed out. Public-key integrity (an id-signedData authSafe) and bag/store DECRYPTION are deferred:
+// build produces password-integrity stores, and a `pki.pkcs12.open` reader is the re-open condition.
+
+var nodeCrypto = require("crypto");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var pbes2 = require("./pbes2");
+var pkcs8 = require("./schema-pkcs8");
+var x509 = require("./schema-x509");
+var schemaCrl = require("./schema-crl");
+var key = require("./key");
+var schemaPkcs12 = require("./schema-pkcs12");
+var pkix = require("./schema-pkix");
+var guard = require("./guard-all");
+var frameworkError = require("./framework-error");
+var C = require("./constants");
+
+var b = asn1.build;
+var Pkcs12Error = frameworkError.Pkcs12Error;
+var PemError = frameworkError.PemError;
+function O(n) { return oid.byName(n); }
+function _err(code, msg, cause) { return new Pkcs12Error(code, msg, cause); }
+
+// PKCS#12 integrity/privacy defaults (named, not call-site literals -- rule 12).
+var DEFAULT_MAC_ITER = 2048;
+var DEFAULT_PBMAC1_ITER = 2048;
+var MAC_SALT_BYTES = 8;
+var MAX_PBMAC1_KEYLEN = 1024;   // an HMAC key beyond a hash block is pointless -- bound the derived length
+// The classic Appendix B KDF is a SYNCHRONOUS JS hash loop (unlike native/async PBKDF2), so its iteration
+// count is capped far lower than the PBKDF2 limit -- a store just under the PBKDF2 cap would block the event
+// loop for seconds. 1e6 is ~500x the OpenSSL default (2048) yet bounds the loop to a fraction of a second.
+var CLASSIC_MAC_MAX_ITERATIONS = 1000000;
+
+// The classic App. B.2 KDF (u = hash output bytes, v = compression block bytes) per RFC 7292 App. B.2.
+var P12_KDF_UV = {
+  sha1: { u: 20, v: 64 }, sha224: { u: 28, v: 64 }, sha256: { u: 32, v: 64 },
+  sha384: { u: 48, v: 128 }, sha512: { u: 64, v: 128 },
+};
+// PBMAC1 hash -> { prf AlgorithmIdentifier name, WebCrypto hash, HMAC key length }. RFC 9579 sec. 5/7 forbids
+// a <= 160-bit digest, so SHA-1 is absent.
+var PBMAC1_PRF = {
+  sha256: { prfName: "hmacWithSHA256", wc: "SHA-256", keyLen: 32 },
+  sha384: { prfName: "hmacWithSHA384", wc: "SHA-384", keyLen: 48 },
+  sha512: { prfName: "hmacWithSHA512", wc: "SHA-512", keyLen: 64 },
+};
+// PBMAC1 prf AlgorithmIdentifier name -> WebCrypto hash (verify direction).
+var PRF_WC = { hmacWithSHA1: "SHA-1", hmacWithSHA256: "SHA-256", hmacWithSHA384: "SHA-384", hmacWithSHA512: "SHA-512" };
+// operator cipher name -> 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" };
+// classic-MAC hash node name -> the registered digest OID name (identical spelling here).
+var DIGEST_NAME = { sha1: "sha1", sha256: "sha256", sha384: "sha384", sha512: "sha512" };
+
+// ---- password + KDF primitives ---------------------------------------------
+
+// RFC 7292 App. B.1: a PKCS#12 password is the BMPString (UTF-16BE) encoding of the string plus a trailing
+// 2-byte NULL terminator. "Beavis" -> 14 bytes. A non-BMP scalar (surrogate) is rejected. A Buffer/Uint8Array
+// is taken verbatim as already-formatted bytes (an escape hatch for a caller that pre-encodes).
+function _p12Password(pw) {
+  if (pw == null) pw = "";
+  if (Buffer.isBuffer(pw)) return pw;
+  if (pw instanceof Uint8Array) return Buffer.from(pw);
+  if (typeof pw !== "string") throw _err("pkcs12/bad-input", "a password must be a string, Buffer, or Uint8Array");
+  var out = Buffer.alloc(pw.length * 2 + 2);   // + the 2-byte NULL terminator
+  for (var i = 0; i < pw.length; i++) {
+    var u = pw.charCodeAt(i);
+    if (u >= 0xD800 && u <= 0xDFFF) throw _err("pkcs12/bad-input", "the password contains a non-BMP character (a surrogate code point cannot be BMPString-encoded)");
+    out[i * 2] = (u >> 8) & 0xFF;
+    out[i * 2 + 1] = u & 0xFF;
+  }
+  return out;   // the final two bytes are already 0x00 0x00
+}
+
+// The password bytes for the RFC 8018 PBES2 bag ciphers and the RFC 9579 PBMAC1 MAC. Although RFC 9579 sec. 6
+// specifies the BMPString encoding here too, OpenSSL and NSS -- and thus the interoperable ecosystem -- feed
+// PBKDF2 the raw UTF-8 password for these modern schemes (confirmed byte-for-byte against `openssl pkcs12`),
+// reserving the BMPString+NULL form for the bespoke Appendix B KDF only. A file we emit must open in OpenSSL,
+// so the modern schemes use UTF-8 here; only the classic Appendix B MAC uses `_p12Password`.
+function _pbePassword(pw) {
+  if (pw == null) pw = "";
+  if (Buffer.isBuffer(pw)) return pw;
+  if (pw instanceof Uint8Array) return Buffer.from(pw);
+  if (typeof pw !== "string") throw _err("pkcs12/bad-input", "a password must be a string, Buffer, or Uint8Array");
+  return Buffer.from(pw, "utf8");
+}
+
+// Concatenate copies of `src` to the smallest positive multiple of `blockSize` (>= src length), truncating
+// the final copy. An empty source yields an empty buffer (RFC 7292 App. B.2 steps 2/3).
+function _blockFill(src, blockSize) {
+  if (src.length === 0) return Buffer.alloc(0);
+  var total = blockSize * Math.ceil(src.length / blockSize);
+  var out = Buffer.alloc(total);
+  for (var i = 0; i < total; i++) out[i] = src[i % src.length];
+  return out;
+}
+
+// RFC 7292 Appendix B.2 KDF: derive `nBytes` of key material for purpose `id` (3 = MAC integrity) from the
+// App. B.1 password bytes + salt over `iterations` rounds of `hashName`. NOT PBKDF2. The only consumer is the
+// classic MAC, which always requests exactly the hash output length u, so the App. B.2 block count
+// c = ceil(nBytes/u) is 1 -- one diversified, salted, iterated hash (D || S || P, hashed r times). The
+// multi-block feedback (the c > 1 case, App. B.2 step 6C) has no consumer here; a future >u-byte derivation
+// (e.g. a classic-PBE bag path) reintroduces it with its own known-answer test rather than shipping it
+// untested. `nBytes` over u is rejected. The single-block path is proven bidirectionally against OpenSSL.
+function _p12Kdf(hashName, id, pwBytes, salt, iterations, nBytes) {
+  var uv = P12_KDF_UV[hashName];
+  if (nBytes > uv.u) throw _err("pkcs12/unsupported-algorithm", "the App. B.2 KDF here derives at most the hash output length");
+  var v = uv.v;
+  var A = Buffer.concat([Buffer.alloc(v, id), _blockFill(salt, v), _blockFill(pwBytes, v)]);   // D || S || P
+  for (var r = 0; r < iterations; r++) A = nodeCrypto.createHash(hashName).update(A).digest();   // H^r(D||I)
+  return A.subarray(0, nBytes);
+}
+
+// ---- input coercion --------------------------------------------------------
+
+function _coerceDer(input, what) {
+  return pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: Pkcs12Error, prefix: "pkcs12" });
+}
+function _bytes(input, label) {
+  return guard.bytes.view(input, Pkcs12Error, "pkcs12/bad-input", label);
+}
+function _assertMacIter(n, cap) {
+  if (typeof n !== "number" || !isFinite(n) || n < 1 || Math.floor(n) !== n) throw _err("pkcs12/bad-input", "MAC iterations must be a positive integer");
+  if (n === 1) throw _err("pkcs12/bad-input", "MAC iterations must be greater than 1 (a DEFAULT-1 MacData iterations cannot be DER-encoded, X.690 sec. 11.5)");
+  if (n > cap) throw _err("pkcs12/bad-input", "MAC iterations exceeds the cap " + cap);
+  return n;
+}
+
+// ---- bag builders ----------------------------------------------------------
+
+// PKCS12Attribute SET OF: friendlyName (a single BMPString) + localKeyId (a single OCTET STRING). Each
+// attribute's attrValues is a single-value SET OF (RFC 2985 SINGLE VALUE).
+function _bagAttributes(bag) {
+  var attrs = [];
+  if (bag.friendlyName != null) attrs.push(b.sequence([b.oid(O("friendlyName")), b.set([b.bmpString(String(bag.friendlyName))])]));
+  if (bag.localKeyId != null) {
+    if (bag.localKeyId === "ski") throw _err("pkcs12/bad-input", "localKeyId 'ski' auto-derivation is not yet supported -- supply an explicit Buffer");
+    attrs.push(b.sequence([b.oid(O("localKeyId")), b.set([b.octetString(_bytes(bag.localKeyId, "localKeyId"))])]));
+  }
+  return attrs.length ? b.set(attrs) : null;
+}
+
+// A secretBag secretTypeId is a caller-chosen content type: a registered OID name, or an arbitrary
+// dotted-decimal OID string preserved verbatim (a name -> its OID; an already-dotted OID passes through).
+function _secretTypeOid(id) {
+  try { return b.oid(O(id) || id); }   // O() (oid.byName) throws OidError on a non-string -- keep it inside the domain wrap
+  catch (e) { throw _err("pkcs12/bad-input", "secretTypeId must be a registered name or a dotted-decimal OID string", e); }
+}
+
+// A SafeBag ::= SEQUENCE { bagId, bagValue [0] EXPLICIT DEFINED BY bagId, bagAttributes SET OF OPTIONAL }.
+function _safeBag(bagName, bagValueDer, bag) {
+  var children = [b.oid(O(bagName)), b.explicit(0, bagValueDer)];
+  var attrs = _bagAttributes(bag);
+  if (attrs) children.push(attrs);
+  return b.sequence(children);
+}
+
+function _buildBag(bag, opts, depth) {
+  if (!bag || typeof bag !== "object") throw _err("pkcs12/bad-input", "each bag must be an object with a type");
+  switch (bag.type) {
+    case "key": {
+      var keyDer = _coerceDer(bag.key, "keyBag key");
+      try { pkcs8.parse(keyDer); } catch (e) { throw _err("pkcs12/bad-input", "keyBag key is not a well-formed PKCS#8 PrivateKeyInfo", e); }
+      return _safeBag("keyBag", keyDer, bag);
+    }
+    case "shroudedKey": {
+      var kDer = _coerceDer(bag.key, "shroudedKey key");
+      try { pkcs8.parse(kDer); } catch (e2) { throw _err("pkcs12/bad-input", "shroudedKey key is not a well-formed PKCS#8 PrivateKeyInfo", e2); }
+      var enc = bag.encrypt || {};
+      var pw = _pbePassword(enc.password != null ? enc.password : opts.password);
+      var r = pbes2.pbes2Encrypt(pw, kDer, _pbeOpts(enc), _err, "pkcs12");
+      return _safeBag("pkcs8ShroudedKeyBag", b.sequence([r.algId, b.octetString(r.ct)]), bag);   // EncryptedPrivateKeyInfo
+    }
+    case "cert": {
+      var certDer = _coerceDer(bag.cert, "certBag cert");
+      try { x509.parse(certDer); } catch (e3) { throw _err("pkcs12/bad-input", "certBag cert is not a well-formed X.509 certificate", e3); }
+      return _safeBag("certBag", b.sequence([b.oid(O("x509Certificate")), b.explicit(0, b.octetString(certDer))]), bag);
+    }
+    case "crl": {
+      var crlDer = _coerceDer(bag.crl, "crlBag crl");
+      try { schemaCrl.parse(crlDer); } catch (e4) { throw _err("pkcs12/bad-input", "crlBag crl is not a well-formed X.509 CRL", e4); }
+      return _safeBag("crlBag", b.sequence([b.oid(O("x509CRL")), b.explicit(0, b.octetString(crlDer))]), bag);
+    }
+    case "secret": {
+      if (bag.secretTypeId == null) throw _err("pkcs12/bad-input", "a secret bag needs a secretTypeId");
+      var secretValueDer = _reqDer(bag.secretValue, "secretValue");
+      return _safeBag("secretBag", b.sequence([_secretTypeOid(bag.secretTypeId), b.explicit(0, secretValueDer)]), bag);
+    }
+    case "safeContents": {
+      if (depth + 1 > C.LIMITS.PKCS12_MAX_BAG_DEPTH) throw _err("pkcs12/bad-input", "safeContents bag nesting exceeds the depth cap " + C.LIMITS.PKCS12_MAX_BAG_DEPTH);
+      return _safeBag("safeContentsBag", _buildSafeContents(bag.nested || [], opts, depth + 1), bag);
+    }
+    default:
+      throw _err("pkcs12/bad-input", "unknown bag type " + JSON.stringify(bag.type) + " (key / shroudedKey / cert / crl / secret / safeContents)");
+  }
+}
+
+// A pre-encoded DER value (one well-formed TLV, no trailing bytes) supplied verbatim (secretValue).
+function _reqDer(input, label) {
+  if (input == null) throw _err("pkcs12/bad-input", label + " is required");
+  var der = _bytes(input, label);
+  var node;
+  try { node = asn1.decode(der); } catch (e) { throw _err("pkcs12/bad-input", label + " must be one well-formed DER value", e); }
+  if (node.bytes.length !== der.length) throw _err("pkcs12/bad-input", label + " must be exactly one DER value with no trailing bytes");
+  return der;
+}
+
+function _pbeOpts(enc) {
+  var cipher = CIPHER_NAME[enc.cipher || "aes-256-cbc"];
+  if (!cipher) throw _err("pkcs12/bad-input", "unsupported PBES2 cipher " + JSON.stringify(enc.cipher) + " (aes-128-cbc / aes-192-cbc / aes-256-cbc)");
+  return {
+    cipher: cipher,
+    salt: enc.salt != null ? _bytes(enc.salt, "encrypt salt") : undefined,
+    iterations: enc.iterations,
+    prf: enc.prf,
+  };
+}
+
+// SafeContents ::= SEQUENCE OF SafeBag (ordered, NOT a SET OF).
+function _buildSafeContents(bags, opts, depth) {
+  if (!Array.isArray(bags)) throw _err("pkcs12/bad-input", "bags must be an array");
+  if (bags.length > C.LIMITS.PKCS12_MAX_ELEMENTS) throw _err("pkcs12/bad-input", "a SafeContents exceeds the element cap " + C.LIMITS.PKCS12_MAX_ELEMENTS);
+  return b.sequence(bags.map(function (bag) { return _buildBag(bag, opts, depth); }));
+}
+
+// One AuthenticatedSafe element: a plaintext id-data ContentInfo, or an id-encryptedData ContentInfo whose
+// EncryptedData is the PBES2 encryption of the SafeContents (RFC 7292 sec. 5.1 step 2A/2B).
+function _buildAuthSafeElement(sc, opts) {
+  if (!sc || typeof sc !== "object") throw _err("pkcs12/bad-input", "each safeContents entry must be an object");
+  var safeContentsDer = _buildSafeContents(sc.bags || [], opts, 0);
+  if (!sc.encrypt) {
+    return b.sequence([b.oid(O("data")), b.explicit(0, b.octetString(safeContentsDer))]);
+  }
+  var pw = _pbePassword(sc.encrypt.password != null ? sc.encrypt.password : opts.password);
+  var r = pbes2.pbes2Encrypt(pw, safeContentsDer, _pbeOpts(sc.encrypt), _err, "pkcs12");
+  var eci = b.sequence([b.oid(O("data")), r.algId, b.contextPrimitive(0, r.ct)]);   // EncryptedContentInfo, [0] IMPLICIT ct
+  var encData = b.sequence([b.integer(0n), eci]);                                    // EncryptedData { version 0, eci }
+  return b.sequence([b.oid(O("encryptedData")), b.explicit(0, encData)]);
+}
+
+// ---- MacData ---------------------------------------------------------------
+
+// MacData over the AuthenticatedSafe DER (= the parser's macedBytes). Classic App. B HMAC (default, max
+// interop) or RFC 9579 PBMAC1. Returns the MacData DER.
+async function _buildMacData(macOpts, sharedPassword, authSafeDer) {
+  var password = macOpts.password != null ? macOpts.password : sharedPassword;
+  var algorithm = macOpts.algorithm || "hmac";
+  var hash = macOpts.hash || "sha256";
+  var salt = macOpts.salt != null ? _bytes(macOpts.salt, "mac salt") : nodeCrypto.randomBytes(MAC_SALT_BYTES);
+  if (salt.length === 0) throw _err("pkcs12/bad-input", "the MAC salt must be non-empty (RFC 9579 sec. 4c)");
+  if (salt.length > C.LIMITS.PBKDF2_MAX_SALT) throw _err("pkcs12/bad-input", "the MAC salt exceeds the " + C.LIMITS.PBKDF2_MAX_SALT + "-octet cap");
+
+  if (algorithm === "hmac") {
+    var node = DIGEST_NAME[hash];
+    if (!node || !P12_KDF_UV[node]) throw _err("pkcs12/unsupported-algorithm", "unsupported classic MAC hash " + JSON.stringify(hash) + " (sha1 / sha256 / sha384 / sha512)");
+    var iter = _assertMacIter(macOpts.iterations == null ? DEFAULT_MAC_ITER : macOpts.iterations, CLASSIC_MAC_MAX_ITERATIONS);
+    var macKey = _p12Kdf(node, 3, _p12Password(password), salt, iter, P12_KDF_UV[node].u);   // classic KDF -> BMPString
+    var digest = nodeCrypto.createHmac(node, macKey).update(authSafeDer).digest();
+    var digestInfo = b.sequence([b.sequence([b.oid(O(node)), b.nullValue()]), b.octetString(digest)]);
+    return b.sequence([digestInfo, b.octetString(salt), b.integer(BigInt(iter))]);
+  }
+  if (algorithm === "pbmac1") {
+    var prf = PBMAC1_PRF[hash];
+    if (!prf) throw _err("pkcs12/unsupported-algorithm", "PBMAC1 requires a SHA-256/384/512 digest (RFC 9579 sec. 5/7 forbids a <= 160-bit digest, e.g. SHA-1)");
+    var iter2 = _assertMacIter(macOpts.iterations == null ? DEFAULT_PBMAC1_ITER : macOpts.iterations, C.LIMITS.PBKDF2_MAX_ITERATIONS);
+    var keyLen = macOpts.keyLength != null ? macOpts.keyLength : prf.keyLen;
+    if (typeof keyLen !== "number" || !Number.isInteger(keyLen) || keyLen < 20 || keyLen > MAX_PBMAC1_KEYLEN) throw _err("pkcs12/bad-input", "PBMAC1 keyLength must be an integer in [20, " + MAX_PBMAC1_KEYLEN + "] (RFC 9579 sec. 9)");
+    var mac = await pbes2.pbmac1(_pbePassword(password), salt, iter2, keyLen, prf.wc, prf.wc, authSafeDer);   // PBKDF2 -> UTF-8; prf == messageAuthScheme on build
+    var desc = { salt: salt, iterationCount: iter2, keyLength: keyLen, prfName: prf.prfName, macName: prf.prfName };
+    var digestInfo2 = b.sequence([pbes2.pbmac1AlgId(desc), b.octetString(mac)]);
+    // MacData.macSalt + iterations are ignored on a PBMAC1 verify but MUST be present + non-1 (RFC 9579 4c/4d).
+    return b.sequence([digestInfo2, b.octetString(salt), b.integer(BigInt(iter2))]);
+  }
+  throw _err("pkcs12/bad-input", "opts.mac.algorithm must be 'hmac' or 'pbmac1', got " + JSON.stringify(algorithm));
+}
+
+// ---- spec normalization ----------------------------------------------------
+
+// Accept the OpenSSL-style convenience form ({ key, cert, ca, friendlyName, localKeyId }) or the full
+// inverse-of-parse form ({ safeContents: SafeContentsSpec[] }). The convenience form -> one privacy safe of
+// PBES2 cert bags + one shrouded-key safe.
+function _normalizeSpec(spec, opts) {
+  if (spec && Array.isArray(spec.safeContents)) return spec.safeContents;
+  if (spec && (spec.key != null || spec.cert != null)) {
+    var certBags = [];
+    if (spec.cert != null) certBags.push({ type: "cert", cert: spec.cert, friendlyName: spec.friendlyName, localKeyId: spec.localKeyId });
+    if (spec.ca != null && !Array.isArray(spec.ca)) throw _err("pkcs12/bad-input", "spec.ca must be an array of certificates");
+    (spec.ca || []).forEach(function (ca) { certBags.push({ type: "cert", cert: ca }); });
+    var sc = [];
+    if (certBags.length) sc.push({ encrypt: { password: opts.password }, bags: certBags });
+    if (spec.key != null) sc.push({ bags: [{ type: "shroudedKey", key: spec.key, encrypt: { password: opts.password }, friendlyName: spec.friendlyName, localKeyId: spec.localKeyId }] });
+    return sc;
+  }
+  throw _err("pkcs12/bad-input", "spec must be { safeContents: [...] } or { key, cert, ca? }");
+}
+
+// ---- public API ------------------------------------------------------------
+
+/**
+ * @primitive pki.pkcs12.build
+ * @signature pki.pkcs12.build(spec, opts?) -> Promise<Buffer|string>
+ * @since 0.3.11
+ * @status experimental
+ * @spec RFC 7292, RFC 9579, RFC 8018
+ * @related pki.schema.pkcs12.parse, pki.pkcs12.verifyMac
+ *
+ * Build a password-integrity PKCS#12 (.p12 / .pfx) store. `spec` is either the 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; every password is BMPString+NULL encoded (RFC 7292 App. B.1). The store is
+ * MACed with a classic Appendix B HMAC (default) or an RFC 9579 PBMAC1, and re-parsed before return.
+ *
+ * @opts
+ *   - `password` -- the shared privacy + integrity password (string / Buffer / Uint8Array).
+ *   - `mac` -- `false` for a MAC-less store, or `{ algorithm: 'hmac'(default)|'pbmac1', hash: 'sha256'(default)|'sha1'|'sha384'|'sha512', salt?, iterations?, keyLength? }`.
+ *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
+ * @example
+ *   var p12 = await pki.pkcs12.build({ safeContents: [{ bags: [
+ *     { type: 'cert', cert: signerCertDer },
+ *     { type: 'shroudedKey', key: signerKeyPkcs8, encrypt: { password: 'changeit' } } ] }] },
+ *     { password: 'changeit', mac: { algorithm: 'hmac', hash: 'sha256' } });
+ */
+async function build(spec, opts) {
+  opts = opts || {};
+  if (opts.integrity && opts.integrity.mode === "public-key") {
+    throw _err("pkcs12/unsupported-algorithm", "public-key integrity (an id-signedData authSafe) is not yet supported -- use password integrity");
+  }
+  var safeContentsSpecs = _normalizeSpec(spec, opts);
+  if (!Array.isArray(safeContentsSpecs) || !safeContentsSpecs.length) throw _err("pkcs12/bad-input", "the store has no safe contents");
+  var elements = [];
+  for (var i = 0; i < safeContentsSpecs.length; i++) elements.push(_buildAuthSafeElement(safeContentsSpecs[i], opts));
+  var authSafeDer = b.sequence(elements);   // AuthenticatedSafe ::= SEQUENCE OF ContentInfo
+
+  var pfxChildren = [b.integer(3n), b.sequence([b.oid(O("data")), b.explicit(0, b.octetString(authSafeDer))])];
+  if (opts.mac != null && opts.mac !== false && typeof opts.mac !== "object") throw _err("pkcs12/bad-input", "opts.mac must be false or a { algorithm, hash, salt, iterations, keyLength } object");
+  if (opts.mac !== false) pfxChildren.push(await _buildMacData(opts.mac || {}, opts.password, authSafeDer));
+  var pfx = b.sequence(pfxChildren);
+
+  // Self-check: the emitted store round-trips through the strict parser (structure + MAC coherence).
+  try { schemaPkcs12.parse(pfx); } catch (e) { throw _err("pkcs12/bad-input", "the produced PKCS#12 store did not re-parse (build bug)", e); }
+  return opts.pem ? schemaPkcs12.pemEncode(pfx, "PKCS12") : pfx;
+}
+
+/**
+ * @primitive pki.pkcs12.verifyMac
+ * @signature pki.pkcs12.verifyMac(pfx, password, opts?) -> Promise<boolean>
+ * @since 0.3.11
+ * @status experimental
+ * @spec RFC 7292 sec. 5.1, RFC 9579
+ * @defends pkcs12-mac-forgery (CWE-347)
+ * @related pki.pkcs12.build, pki.schema.pkcs12.parse
+ *
+ * Verify a password-integrity PKCS#12 store's MAC. `pfx` is a `pki.schema.pkcs12.parse` result, a DER
+ * `Buffer`, or a PEM string. The password is BMPString+NULL encoded (RFC 7292 App. B.1), the MAC is
+ * recomputed over the store's exact AuthenticatedSafe byte range (`macedBytes`) using the store's own MAC
+ * parameters -- the classic Appendix B (ID=3) HMAC or the RFC 9579 PBMAC1 -- and constant-time-compared to
+ * the stored MAC value. Returns `true` / `false` for the password match; throws `Pkcs12Error` on a MAC-less
+ * or public-key-integrity store, or an unsupported MAC algorithm (never a falsy verdict standing in for an error).
+ *
+ * @example
+ *   var p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
+ *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
+ */
+async function verifyMac(pfx, password, opts) {
+  opts = opts || {};
+  var m = (pfx && pfx.integrityMode !== undefined && pfx.mac !== undefined) ? pfx : schemaPkcs12.parse(_coerceDer(pfx, "pfx"));
+  if (m.integrityMode !== "password" || !m.mac) throw _err("pkcs12/bad-input", "the store carries no password MAC (integrityMode " + m.integrityMode + ")");
+  var expected = m.mac.macValue;
+  var computed;
+  if (m.mac.kind === "hmac") {
+    var node = (m.mac.hashName || "").toLowerCase();
+    if (!P12_KDF_UV[node]) throw _err("pkcs12/unsupported-algorithm", "unsupported classic MAC hash " + m.mac.hashName);
+    // The iteration count and salt are attacker-controlled work factors: bound them BEFORE the KDF runs.
+    _capWork(m.mac.iterations, m.mac.macSalt, opts, undefined, CLASSIC_MAC_MAX_ITERATIONS);
+    var macKey = _p12Kdf(node, 3, _p12Password(password), m.mac.macSalt, m.mac.iterations, P12_KDF_UV[node].u);   // classic KDF -> BMPString
+    computed = nodeCrypto.createHmac(node, macKey).update(m.macedBytes).digest();
+  } else {
+    var kdf = m.mac.pbmac1.kdf;
+    var prfWc = PRF_WC[kdf.prfName];
+    // RFC 9579: HMAC under the messageAuthScheme, keyed by PBKDF2 under the (independent) prf.
+    var macWc = PRF_WC[m.mac.pbmac1.schemeName];
+    if (!prfWc) throw _err("pkcs12/unsupported-algorithm", "unsupported PBMAC1 prf " + kdf.prfName);
+    if (!macWc) throw _err("pkcs12/unsupported-algorithm", "unsupported PBMAC1 messageAuthScheme " + m.mac.pbmac1.schemeName);
+    // RFC 9579 sec. 5/7: a <= 160-bit digest (SHA-1) MUST NOT be used for PBMAC1 -- refuse it on verify, so a
+    // downgraded store cannot pass under a weak MAC even though the algorithm identifiers parse.
+    if (prfWc === "SHA-1" || macWc === "SHA-1") throw _err("pkcs12/unsupported-algorithm", "PBMAC1 with a <= 160-bit digest (SHA-1) is refused (RFC 9579 sec. 5/7)");
+    _capWork(kdf.iterationCount, kdf.salt, opts, kdf.keyLength, C.LIMITS.PBKDF2_MAX_ITERATIONS);
+    computed = await pbes2.pbmac1(_pbePassword(password), kdf.salt, kdf.iterationCount, kdf.keyLength, prfWc, macWc, m.macedBytes);   // PBKDF2 -> UTF-8
+  }
+  return computed.length === expected.length && guard.crypto.constantTimeEqual(computed, expected);
+}
+
+// Bound the attacker-controlled MAC work factors before a hostile store can force an expensive derivation:
+// the iteration count (<= PBKDF2_MAX_ITERATIONS, downward-overridable via opts.maxIterations), the salt, and
+// the PBMAC1 keyLength. A store that exceeds any cap is a typed reject, never a multi-second CPU burn.
+function _capWork(iterations, salt, opts, keyLength, hardCap) {
+  var cap = hardCap;
+  if (opts.maxIterations != null) {
+    if (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations) throw _err("pkcs12/bad-input", "maxIterations must be a positive integer");
+    cap = Math.min(opts.maxIterations, cap);
+  }
+  if (iterations > cap) throw _err("pkcs12/iteration-limit", "the MAC iteration count " + iterations + " exceeds the cap " + cap);
+  if (salt && salt.length > C.LIMITS.PBKDF2_MAX_SALT) throw _err("pkcs12/bad-input", "the MAC salt exceeds the " + C.LIMITS.PBKDF2_MAX_SALT + "-octet cap");
+  // RFC 9579 sec. 9: the PBMAC1 keyLength floor (>= 20) is enforced on verify too, so a downgraded store with
+  // a short derived key is refused rather than accepted under a weak MAC.
+  if (keyLength != null && (keyLength < 20 || keyLength > MAX_PBMAC1_KEYLEN)) throw _err("pkcs12/bad-input", "the PBMAC1 keyLength must be in [20, " + MAX_PBMAC1_KEYLEN + "] (RFC 9579 sec. 9)");
+}
+
+/**
+ * @primitive pki.pkcs12.open
+ * @signature pki.pkcs12.open(pfx, password, opts?) -> Promise<OpenResult>
+ * @since 0.3.12
+ * @status experimental
+ * @spec RFC 7292 sec. 5.1, RFC 9579, RFC 8018
+ * @defends pkcs12-unauthenticated-decrypt (CWE-347), pbes2-padding-oracle (CWE-208)
+ * @related pki.pkcs12.build, pki.pkcs12.verifyMac, pki.schema.pkcs12.parse
+ *
+ * Read a password-integrity PKCS#12 store: verify its MAC FIRST (RFC 7292 sec. 5.1 -- never trust a bag from a
+ * store whose password MAC fails), then decrypt every PBES2 privacy safe and pkcs8ShroudedKeyBag with the same
+ * password, returning a structured bundle `{ integrityMode, macVerified, keys, certs, crls, secrets }` -- each
+ * private key as PKCS#8 `PrivateKeyInfo` DER (re-validated), each certificate / CRL / secret as raw DER, all
+ * carrying their `friendlyName` / `localKeyId` for pairing. `pfx` is a DER `Buffer`, PEM string, or a
+ * `pki.schema.pkcs12.parse` result.
+ *
+ * A MAC-less store is refused (`pkcs12/no-integrity`) unless `opts.allowUnauthenticated` is set; a public-key
+ * integrity store is refused. Only PBES2 (AES-CBC) bags are decrypted -- a legacy PBE scheme is named and
+ * refused. The password is BMPString+NULL for the MAC and UTF-8 for the PBES2 bags; a wrong password fails at
+ * the MAC gate (`pkcs12/mac-mismatch`), and a post-MAC decrypt failure is the uniform `pkcs12/decrypt-failed`.
+ *
+ * @opts
+ *   - `allowUnauthenticated` (boolean) -- open a MAC-less store anyway (result carries `macVerified: false`).
+ *   - `maxIterations` (number) -- lower the PBKDF2 / MAC iteration cap for this call (downward-only).
+ *   - `keys` (string) -- `der` (default) or `crypto` (also `pki.key.import` each private key to a CryptoKey).
+ *   - `importAlgorithm` -- forwarded to `pki.key.import` for the ambiguous RSA / EC arms when `keys: crypto`.
+ * @example
+ *   var p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
+ *   var store = await pki.pkcs12.open(p12, 'changeit');
+ *   var keyDer = store.keys[0].pkcs8, certDer = store.certs[0].cert;
+ */
+async function open(pfx, password, opts) {
+  opts = opts || {};
+  if (opts.maxIterations != null && (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations)) {
+    throw _err("pkcs12/bad-input", "maxIterations must be a positive integer");
+  }
+  var m = (pfx && pfx.integrityMode !== undefined && pfx.mac !== undefined) ? pfx : schemaPkcs12.parse(_coerceDer(pfx, "pfx"));
+  if (m.integrityMode === "public-key") throw _err("pkcs12/bad-integrity-mode", "public-key-integrity (id-signedData) stores are not supported by open");
+  var macVerified = false;
+  if (m.integrityMode === "password") {
+    macVerified = await verifyMac(m, password, opts);
+    if (!macVerified) throw _err("pkcs12/mac-mismatch", "the PKCS#12 MAC did not verify (wrong password or a tampered store)");
+  } else if (!opts.allowUnauthenticated) {
+    throw _err("pkcs12/no-integrity", "the store carries no integrity MAC (integrityMode " + m.integrityMode + "); set opts.allowUnauthenticated to open it anyway");
+  }
+  // The PBES2 bag/safe password is UTF-8 (the pinned interop convention), distinct from the classic MAC BMPString.
+  var pwBytes = _pbePassword(password);
+  var out = { integrityMode: m.integrityMode, macVerified: macVerified, keys: [], certs: [], crls: [], secrets: [] };
+  var i;
+  for (i = 0; i < m.safeBags.length; i++) _openBag(m.safeBags[i], pwBytes, opts, out, 0);
+  for (i = 0; i < m.encryptedSafes.length; i++) _openEncryptedSafe(m.encryptedSafes[i], pwBytes, opts, out, 0);
+  if (opts.keys === "crypto") {
+    for (i = 0; i < out.keys.length; i++) out.keys[i].key = await key.import(out.keys[i].pkcs8, { algorithm: opts.importAlgorithm });
+  }
+  return out;
+}
+
+function _openBag(bag, pwBytes, opts, out, depth) {
+  switch (bag.type) {
+    case "keyBag":
+      // The open contract surfaces keys[].pkcs8 as canonical PrivateKeyInfo DER (key.import re-decodes strict
+      // DER). The parser accepts a BER keyBag value, so re-parse it strictly here -- guaranteeing DER exactly as
+      // the shrouded path does via _decryptShroudedKey's pkcs8.parse. A non-DER (BER) plaintext key is refused.
+      try { pkcs8.parse(bag.keyDer); }
+      catch (e) { throw _err("pkcs12/bad-der", "a plaintext keyBag PrivateKeyInfo is not canonical DER", e); }
+      out.keys.push({ pkcs8: bag.keyDer, encrypted: false, friendlyName: bag.friendlyName, localKeyId: bag.localKeyId });
+      break;
+    case "pkcs8ShroudedKeyBag":
+      out.keys.push({ pkcs8: _decryptShroudedKey(bag.encrypted, pwBytes, opts), encrypted: true, friendlyName: bag.friendlyName, localKeyId: bag.localKeyId });
+      break;
+    case "certBag":
+      out.certs.push({ cert: bag.certValue, certType: bag.certType, friendlyName: bag.friendlyName, localKeyId: bag.localKeyId });
+      break;
+    case "crlBag":
+      out.crls.push({ crl: bag.crlValue, crlType: bag.crlType, friendlyName: bag.friendlyName, localKeyId: bag.localKeyId });
+      break;
+    case "secretBag":
+      out.secrets.push({ secretTypeId: bag.secretTypeId, secretTypeName: bag.secretTypeName, secretValue: bag.secretValue, friendlyName: bag.friendlyName, localKeyId: bag.localKeyId });
+      break;
+    case "safeContentsBag":
+      if (depth + 1 > C.LIMITS.PKCS12_MAX_BAG_DEPTH) throw _err("pkcs12/too-deep", "safeContentsBag nesting exceeds the depth cap " + C.LIMITS.PKCS12_MAX_BAG_DEPTH);
+      for (var n = 0; n < (bag.nested || []).length; n++) _openBag(bag.nested[n], pwBytes, opts, out, depth + 1);
+      break;
+    default:
+      throw _err("pkcs12/bad-input", "unexpected bag type " + bag.type);
+  }
+}
+
+// A pkcs8ShroudedKeyBag is a bare EncryptedPrivateKeyInfo (RFC 5958 sec. 3): PBES2-decrypt to a PrivateKeyInfo,
+// re-validated (the re-parse is the MAC-less integrity check for the bag ciphertext).
+function _decryptShroudedKey(encrypted, pwBytes, opts) {
+  if (encrypted.encryptionAlgorithm.oid !== O("pbes2")) throw _err("pkcs12/unsupported-algorithm", "the shrouded key uses " + (encrypted.encryptionAlgorithm.name || encrypted.encryptionAlgorithm.oid) + " (only RFC 8018 PBES2 is decrypted; re-export with -keypbe AES-256-CBC)");
+  var der = pbes2.pbes2Decrypt(pwBytes, encrypted.encryptionAlgorithm.parameters, encrypted.encryptedData, opts, _err, "pkcs12");
+  try { pkcs8.parse(der); } catch (_e) { throw _err("pkcs12/decrypt-failed", "decryption failed"); }
+  return der;
+}
+
+// An id-encryptedData privacy safe: PBES2-decrypt the SafeContents, then re-walk it through the strict parser
+// (same PKCS12_MAX_* caps) and open each recovered bag.
+function _openEncryptedSafe(encSafe, pwBytes, opts, out, depth) {
+  if (encSafe.type !== "encryptedData") throw _err("pkcs12/unsupported-algorithm", "an " + encSafe.type + " privacy safe is not supported (only id-encryptedData under PBES2)");
+  var eci = encSafe.content.encryptedContentInfo;
+  if (eci.contentEncryptionAlgorithm.oid !== O("pbes2")) throw _err("pkcs12/unsupported-algorithm", "the privacy safe uses " + (eci.contentEncryptionAlgorithm.name || eci.contentEncryptionAlgorithm.oid) + " (only RFC 8018 PBES2 is decrypted; re-export with -certpbe AES-256-CBC)");
+  if (eci.encryptedContent == null) throw _err("pkcs12/bad-input", "the encrypted privacy safe has no content");
+  var safeContentsDer = pbes2.pbes2Decrypt(pwBytes, eci.contentEncryptionAlgorithm.parameters, eci.encryptedContent, opts, _err, "pkcs12");
+  // The bag/safe password MAY differ from the (already-verified) MAC password, so a decrypt under the MAC
+  // password can succeed with a valid pad yet yield bytes that are not a SafeContents. Collapse THAT re-parse
+  // failure into the same uniform pkcs12/decrypt-failed as a bad pad -- a distinguishable structural code here
+  // would be a padding oracle (RFC 8018 sec. 8). The strict walk's caps still fire (bounding the work).
+  var bags;
+  try { bags = schemaPkcs12.walkSafeContents(safeContentsDer); }
+  catch (_e) { throw _err("pkcs12/decrypt-failed", "decryption failed"); }
+  for (var i = 0; i < bags.length; i++) _openBag(bags[i], pwBytes, opts, out, depth);
+}
+
+module.exports = {
+  build: build,
+  verifyMac: verifyMac,
+  open: open,
+};

package/lib/schema-pkcs12.js

@@ -437,6 +437,19 @@ function _walkAuthenticatedSafe(bytes, state, ctx) {
 // carries plaintext SafeContents (re-decoded here); the two privacy modes are
 // full CMS structures validated by the CMS module on the already-decoded node
 // -- ciphertext stays opaque inside the CMS surface.
+// @internal -- re-parse a DECRYPTED privacy-safe's plaintext (a SafeContents ::= SEQUENCE OF SafeBag) through
+// the SAME strict SAFE_CONTENTS walk + bag dispatch the plaintext path uses, so a decrypted blob shares every
+// PKCS12_MAX_* cap and produces the identical bag records. Consumed by pki.pkcs12.open for an encrypted safe.
+function walkSafeContents(der) {
+  // PKCS#12 content regions are normatively BER (RFC 7292 sec. 4.1) -- a decrypted SafeContents may use an
+  // indefinite-length SEQUENCE, exactly as the plaintext-safe path (_dispatchSafes) decodes it with ber:true.
+  var walked = schema.walk(SAFE_CONTENTS, asn1.decode(der, { ber: true }), NS);
+  var state = { budget: { remaining: C.LIMITS.PKCS12_MAX_REDECODES }, bagDepth: 0 };
+  var bags = [];
+  for (var i = 0; i < walked.items.length; i++) bags.push(_buildBag(walked.items[i].value.result, state, NS));
+  return bags;
+}
+
 function _dispatchSafes(asMatch, state, ctx) {
   var safeBags = [];
   var encryptedSafes = [];
@@ -476,6 +489,7 @@ function _buildBag(rec, state, ctx) {
   if (rec.bagId === OID_KEY_BAG) {
     bag.type = "keyBag";
     bag.key = pkcs8.walkPrivateKeyInfo(rec.valueNode);
+    bag.keyDer = rec.valueNode.bytes;   // the raw PrivateKeyInfo DER (pki.pkcs12.open surfaces it verbatim)
     return bag;
   }
   if (rec.bagId === OID_SHROUDED_KEY_BAG) {
@@ -621,4 +635,5 @@ module.exports = {
   pemDecode: pemDecode,
   pemEncode: pemEncode,
   matches: matches,
+  walkSafeContents: walkSafeContents,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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:0bc607cc-142c-4a49-a525-90a6f0216e38",
+  "serialNumber": "urn:uuid:a2281c9c-5058-4827-83e2-53a8a4561863",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-23T18:57:16.468Z",
+    "timestamp": "2026-07-24T02:15:58.035Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.10",
+      "bom-ref": "@blamejs/pki@0.3.12",
       "type": "application",
       "name": "pki",
-      "version": "0.3.10",
+      "version": "0.3.12",
       "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.10",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.10",
+      "ref": "@blamejs/pki@0.3.12",
       "dependsOn": []
     }
   ]