@blamejs/pki 0.3.11 → 0.3.13

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.13 — 2026-07-24
+
+CMS gains countersignatures and unsigned attributes (RFC 5652 sec. 11.4).
+
+### Added
+
+- pki.cms.countersign(cms, signers, opts) adds RFC 5652 section 11.4 countersignatures to a CMS SignedData. Each countersigner is the same { cert, key, digestAlgorithm?, pss? } descriptor pki.cms.sign takes (RSA, RSASSA-PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or composite ML-DSA), and its signature covers the countersigned SignerInfo's signature octets under the section 11.4 preimage -- message-digest bound to those octets, content-type omitted. opts.signerIndex selects which primary signer(s) to countersign (an index, an array, or 'all'), opts.countersignatureOf countersigns an existing countersignature (a nested countersignature), opts.signedAttributes false signs the target signature directly, and the countersigner certificate is embedded by default. The countersigned SignedData's original bytes are preserved so the primary signature verifies unchanged, and multiple countersignatures on one signer land as multiple values of the one id-countersignature attribute. Returns a DER Buffer or, with opts.pem, a PEM string. RFC 5652 sec. 11.4.
+- pki.cms.verify surfaces countersignatures and unsigned attributes per signer. Each res.signers[i] carries countersignatures -- an array of per-countersignature verdicts { ok, sid, cert, digestAlgorithm, ... }, each verified over the exact RFC 5652 section 11.4 preimage, nested for a countersignature of a countersignature -- and unsignedAttrs, the decoded unsigned attributes with their type names. Both are unauthenticated by definition (an unsigned attribute is outside the signature) and never change signers[i].ok or res.valid; a present-but-invalid countersignature is surfaced ok:false, never silently dropped.
+- pki.cms.sign gains an unsignedAttributes option: an array of { type, values } unsigned attributes placed in each SignerInfo, outside the signature. It is the vehicle for attaching an RFC 3161 timestamp token (id-aa-timeStampToken) or another unsigned attribute at signing time. content-type, message-digest, and signing-time are rejected as unsigned attributes (RFC 5652 sec. 11), as is a duplicate attribute type.
+
+## v0.3.12 — 2026-07-23
+
+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).

package/README.md

@@ -229,8 +229,8 @@ 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 bag decryption are not yet built. Returns DER or a PEM `PKCS12`; fail-closed with typed `Pkcs12Error`. Parsing stays at `pki.schema.pkcs12.parse` — `build` / `verifyMac` |
-| `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.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`. **Countersignatures** (RFC 5652 §11.4): `countersign(cms, signers, opts)` adds a countersignature — a `SignerInfo` over the countersigned SignerInfo's signature value, any signer algorithm, nestable, the primary bytes preserved so it still verifies — attached as the id-countersignature unsigned attribute; `verify` returns each countersignature's verdict under `signers[i].countersignatures` and every unsigned attribute (an RFC 3161 timestamp token attachable via `sign`'s `unsignedAttributes`) under `signers[i].unsignedAttrs`, surfaced unauthenticated. **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`, `countersign`, `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` |
 | `pki.ocsp` | RFC 6960 Online Certificate Status Protocol — the responder and relying-party surface. `buildRequest(query, opts)` builds an OCSPRequest for one or more `{ cert, issuer }` pairs (CertID hashed under SHA-1 by default per the RFC 5019 lightweight profile, or SHA-2; optional RFC 9654 nonce, optional requestor signature). `sign(responseData, responder, opts)` produces a signed BasicOCSPResponse over the exact `ResponseData` DER — the issuing CA directly or a delegated responder, any `pki.cms.sign` key including the post-quantum ML-DSA / SLH-DSA sets, with `good` / `revoked` (reason + time) / `unknown` per-certificate status, and `buildErrorResponse(status)` the unsigned §2.3 error (`tryLater` / `unauthorized` / …). `verify(response, opts)` verifies a response fail-closed against the same hardened gates `pki.path.ocspChecker` runs: the CertID binding, responder authorization (the issuing CA or a CA-issued delegate bearing id-kp-OCSPSigning **and** id-pkix-ocsp-nocheck, passing the full out-of-path certificate gates), the signature over `tbsResponseDataBytes`, currency (`thisUpdate`/`nextUpdate`), and the request-nonce echo — returning `{ status: "good" / "revoked" / "unknown", … }`, never a silent accept. Transport-free — `buildRequest`, `sign`, `buildErrorResponse`, `verify` |
@@ -271,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/lib/cms-sign.js

@@ -23,6 +23,7 @@ var frameworkError = require("./framework-error");
 var signScheme = require("./sign-scheme");
 var guard = require("./guard-all");
 var pkiBuild = require("./pki-build");
+var cms = require("./schema-cms");
 var CmsError = frameworkError.CmsError;
 var b = asn1.build;
 function _err(code, message, cause) { return new CmsError(code, message, cause); }
@@ -57,6 +58,73 @@ function _skiValue(cert) {
 }
 
 
+// The SignerInfo SignerIdentifier + its coupled CMSVersion (RFC 5652 sec. 5.3): a [0] IMPLICIT
+// subjectKeyIdentifier => version 3, else an IssuerAndSerialNumber => version 1. Shared by the
+// top-level signer and the sec. 11.4 countersignature (a countersignature IS a SignerInfo).
+function _buildSid(cert, useSki) {
+  var sid = useSki
+    ? b.contextPrimitive(0, _skiValue(cert))                                       // [0] IMPLICIT SubjectKeyIdentifier
+    : b.sequence([b.raw(pkiBuild.tbsNameField(cert, "issuer")), b.integer(cert.serialNumber)]);   // IssuerAndSerialNumber
+  return { sid: sid, version: useSki ? 3 : 1 };
+}
+
+// Assemble a SignedAttributes SET from resolved attribute pairs (each { type: <dotted OID>, values:
+// [<build node or DER Buffer>] }), returning { setOf, wire }: `setOf` is the canonical DER SET OF
+// (tag 0x31, build.set SET-OF-sorts) the signature covers (RFC 5652 sec. 5.4); `wire` is the same
+// bytes with the on-wire [0] IMPLICIT tag (0xA0). Each attribute type appears AT MOST ONCE (sec.
+// 5.3) -- a duplicate throws. Shared by the top-level signer (content-type + message-digest +
+// signing-time + caller attrs) and the countersignature builder (message-digest over the target
+// signature octets + signing-time, content-type OMITTED per sec. 11.4).
+function _buildSignedAttrs(pairs) {
+  var seenTypes = {};
+  var attrs = pairs.map(function (p) {
+    if (seenTypes[p.type]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    seenTypes[p.type] = 1;
+    return b.sequence([b.oid(p.type), b.set(p.values)]);
+  });
+  var setOf = b.set(attrs);   // SET OF (tag 0x31) -- the exact bytes the signature covers (sec. 5.4)
+  var wire = Buffer.from(setOf); wire[0] = 0xA0;   // the on-wire [0] IMPLICIT tag
+  return { setOf: setOf, wire: wire };
+}
+
+// Resolve caller-supplied additional signed attributes ({ type: OID name or dotted, values: [DER] })
+// into the pair shape _buildSignedAttrs consumes; each MUST carry >= 1 value (Attribute values is
+// SET SIZE (1..MAX)).
+function _resolveAttrPairs(list, what) {
+  return (list || []).map(function (a) {
+    var vals = (a.values || []).map(function (v) { return _toBuf(v, what); });
+    if (!vals.length) throw _err("cms/bad-input", "a signed attribute must carry at least one value (RFC 5652 -- Attribute values is SET SIZE (1..MAX))");
+    return { type: /^\d+(\.\d+)+$/.test(a.type) ? a.type : O(a.type), values: vals };
+  });
+}
+
+// content-type / message-digest / signing-time are content-binding SIGNED attributes and MUST NOT
+// appear as unsigned attributes (RFC 5652 sec. 11.1/11.2/11.3 -- the parser's ATTR_FORBIDDEN_IN).
+var UNSIGNED_FORBIDDEN = {};
+UNSIGNED_FORBIDDEN[O("contentType")] = "content-type";
+UNSIGNED_FORBIDDEN[O("messageDigest")] = "message-digest";
+UNSIGNED_FORBIDDEN[O("signingTime")] = "signing-time";
+
+// Build the [1] IMPLICIT unsignedAttrs SET OF (on-wire tag 0xA1) from opts.unsignedAttributes
+// (each { type, values: [DER] } -- a countersignature, an RFC 3161 timestamp token), or null when
+// absent/empty. Unsigned attributes are OUTSIDE the signature; a placement-forbidden type or a
+// duplicate type (RFC 5652 sec. 11 / sec. 5.3) is a config-time cms/bad-input.
+function _buildUnsignedAttrs(list) {
+  if (list == null) return null;
+  if (!Array.isArray(list)) throw _err("cms/bad-input", "opts.unsignedAttributes must be an array of { type, values }");
+  if (!list.length) return null;
+  var pairs = _resolveAttrPairs(list, "an unsigned attribute value");
+  var seen = {};
+  pairs.forEach(function (p) {
+    if (UNSIGNED_FORBIDDEN[p.type]) throw _err("cms/bad-input", "the " + UNSIGNED_FORBIDDEN[p.type] + " attribute must not appear as an unsigned attribute (RFC 5652 sec. 11)");
+    if (seen[p.type]) throw _err("cms/bad-input", "unsignedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    seen[p.type] = 1;
+  });
+  var setOf = b.set(pairs.map(function (p) { return b.sequence([b.oid(p.type), b.set(p.values)]); }));
+  var wire = Buffer.from(setOf); wire[0] = 0xA1;   // SET OF -> [1] IMPLICIT UnsignedAttributes
+  return wire;
+}
+
 // Build one SignerInfo (RFC 5652 sec. 5.3) and sign it. Resolves the SignerInfo (as a build
 // node) plus its digestAlgorithm AlgorithmIdentifier and the signer certificate DER (for the
 // SignedData digestAlgorithms + certificates sets).
@@ -65,44 +133,28 @@ function _buildSignerInfo(signer, content, eContentType, opts) {
   var certDer = _normCertDer(so.cert);
   var cert = x509.parse(certDer);
   var scheme = signScheme.resolveSignScheme(cert, so, opts.signedAttributes === false, _signE);
-  var useSki = opts.sid === "ski";
-  var sid = useSki
-    ? b.contextPrimitive(0, _skiValue(cert))                                       // [0] IMPLICIT SubjectKeyIdentifier
-    : b.sequence([b.raw(pkiBuild.tbsNameField(cert, "issuer")), b.integer(cert.serialNumber)]);   // IssuerAndSerialNumber
-  var version = useSki ? 3 : 1;
+  var sidv = _buildSid(cert, opts.sid === "ski");
+  var sid = sidv.sid, version = sidv.version;
 
   return Promise.resolve().then(function () {
     if (opts.signedAttributes === false) return content;   // sign the content directly (no signed attributes)
     // Signed attributes (RFC 5652 sec. 5.3): content-type == eContentType, message-digest ==
-    // digest(content), and (by default) signing-time. build.set canonical-DER SET-OF-sorts them.
-    // Each attribute type appears AT MOST ONCE across the whole set (RFC 5652 sec. 5.3);
-    // `seenTypes` catches a caller-supplied attribute that duplicates a built-in or another.
-    var seenTypes = {};
-    function _pushAttr(typeOid, values) {
-      if (seenTypes[typeOid]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + typeOid);
-      seenTypes[typeOid] = 1;
-      attrs.push(b.sequence([b.oid(typeOid), b.set(values)]));
-    }
-    var attrs = [];
-    _pushAttr(O("contentType"), [b.oid(eContentType)]);
-    _pushAttr(O("messageDigest"), [b.octetString(_digest(scheme.digest, content))]);
-    if (opts.signingTime !== false) _pushAttr(O("signingTime"), [_timeValue(opts.signingTime)]);
-    // Caller-supplied signed attributes (e.g. an RFC 3161 signing-certificate attribute): each
-    // { type: <OID name or dotted string>, values: [<DER value Buffer>] }. build.set sorts them in.
-    (opts.additionalSignedAttributes || []).forEach(function (a) {
-      var vals = (a.values || []).map(function (v) { return _toBuf(v, "a signed attribute value"); });
-      if (!vals.length) throw _err("cms/bad-input", "a signed attribute must carry at least one value (RFC 5652 -- Attribute values is SET SIZE (1..MAX))");
-      _pushAttr(/^\d+(\.\d+)+$/.test(a.type) ? a.type : O(a.type), vals);
-    });
-    var setOf = b.set(attrs);   // SET OF (tag 0x31) -- the exact bytes the signature covers (sec. 5.4)
-    var wire = Buffer.from(setOf); wire[0] = 0xA0;   // the on-wire [0] IMPLICIT tag
-    return { setOf: setOf, wire: wire };
+    // digest(content), and (by default) signing-time, plus any caller-supplied attribute.
+    var pairs = [
+      { type: O("contentType"), values: [b.oid(eContentType)] },
+      { type: O("messageDigest"), values: [b.octetString(_digest(scheme.digest, content))] },
+    ];
+    if (opts.signingTime !== false) pairs.push({ type: O("signingTime"), values: [_timeValue(opts.signingTime)] });
+    pairs = pairs.concat(_resolveAttrPairs(opts.additionalSignedAttributes, "a signed attribute value"));
+    return _buildSignedAttrs(pairs);
   }).then(function (toSign) {
     var signedBytes = toSign.setOf ? toSign.setOf : toSign;   // SET-OF form for signing (sec. 5.4)
     return signScheme.signOverTbs(scheme, so.key, signedBytes, _signE).then(function (sig) {
       var fields = [b.integer(BigInt(version)), sid, scheme.digestAlgId];
       if (toSign.wire) fields.push(toSign.wire);              // [0] IMPLICIT signedAttrs
       fields.push(scheme.sigAlgId, b.octetString(sig));
+      var ua = _buildUnsignedAttrs(opts.unsignedAttributes);
+      if (ua) fields.push(ua);                                 // [1] IMPLICIT unsignedAttrs
       return { si: b.sequence(fields), digestAlgId: scheme.digestAlgId, version: version, certDer: certDer };
     });
   });
@@ -191,6 +243,179 @@ function _toBuf(v, what) {
   throw _err("cms/bad-input", what + " must be a Buffer");
 }
 
+// ---- pki.cms.countersign (RFC 5652 sec. 11.4) ------------------------------
+// A countersignature is a SignerInfo (Countersignature ::= SignerInfo) over the CONTENTS of the
+// countersigned SignerInfo's signature OCTET STRING -- NOT the eContent -- attached as the
+// id-countersignature unsigned attribute. It reuses the whole build+sign flow (resolveSignScheme /
+// _buildSid / _buildSignedAttrs / signOverTbs); only the preimage (the target signature octets) and
+// the content-type OMISSION are the deltas, and the orchestrator splices the [1] unsignedAttrs into
+// an existing SignedData while preserving the targeted SignerInfo's signed bytes BYTE-FOR-BYTE.
+
+// Resolve opts.signerIndex (a number, an array of numbers, or "all"; default 0) to primary indices.
+function _resolveSignerIndices(spec, n) {
+  if (spec == null) { if (n < 1) throw _err("cms/bad-input", "the SignedData carries no SignerInfo to countersign"); return [0]; }
+  if (spec === "all") { var all = []; for (var i = 0; i < n; i++) all.push(i); return all; }
+  var arr = Array.isArray(spec) ? spec : [spec];
+  if (!arr.length) throw _err("cms/bad-input", "signerIndex must select at least one signer");
+  arr.forEach(function (i) { if (typeof i !== "number" || !Number.isInteger(i) || i < 0 || i >= n) throw _err("cms/bad-input", "signerIndex out of range: " + i); });
+  return arr;
+}
+
+// Build one countersignature value (RFC 5652 sec. 11.4) over `targetSigOctets`: message-digest bound
+// to digest(targetSigOctets) under the countersignature's own digestAlgorithm, content-type OMITTED,
+// signed through the SAME per-algorithm scheme machinery as a top-level signer.
+function _buildCountersignature(targetSigOctets, countersigner, opts) {
+  var so = countersigner || {};
+  var certDer = _normCertDer(so.cert);
+  var cert = x509.parse(certDer);
+  var scheme = signScheme.resolveSignScheme(cert, so, opts.signedAttributes === false, _signE);
+  var sidv = _buildSid(cert, opts.sid === "ski");
+  return Promise.resolve().then(function () {
+    if (opts.signedAttributes === false) return null;   // sign the target signature octets directly
+    var pairs = [{ type: O("messageDigest"), values: [b.octetString(_digest(scheme.digest, targetSigOctets))] }];
+    if (opts.signingTime !== false) pairs.push({ type: O("signingTime"), values: [_timeValue(opts.signingTime)] });
+    var extra = _resolveAttrPairs(opts.additionalSignedAttributes, "a countersignature signed attribute value");
+    extra.forEach(function (p) { if (p.type === O("contentType")) throw _err("cms/bad-input", "a countersignature must not carry a content-type attribute (RFC 5652 sec. 11.4)"); });
+    return _buildSignedAttrs(pairs.concat(extra));
+  }).then(function (attrs) {
+    return signScheme.signOverTbs(scheme, so.key, attrs ? attrs.setOf : targetSigOctets, _signE).then(function (sig) {
+      var fields = [b.integer(BigInt(sidv.version)), sidv.sid, scheme.digestAlgId];
+      if (attrs) fields.push(attrs.wire);          // [0] IMPLICIT signedAttrs
+      fields.push(scheme.sigAlgId, b.octetString(sig));
+      return { value: b.sequence(fields), certDer: certDer };
+    });
+  });
+}
+
+// Build the [1] IMPLICIT unsignedAttrs bytes for a SignerInfo, merging `newCsValues` into the ONE
+// id-countersignature attribute (RFC 5652 sec. 11: single instance per type, MULTIPLE values), and
+// keeping every OTHER unsigned attribute and every EXISTING countersignature value verbatim.
+function _mergeCountersig(uaNode, newCsValues) {
+  var CS = O("countersignature");
+  var others = [], csValues = [];
+  if (uaNode) uaNode.children.forEach(function (attr) {
+    if (asn1.read.oid(attr.children[0]) === CS) attr.children[1].children.forEach(function (v) { csValues.push(v.bytes); });
+    else others.push(attr.bytes);
+  });
+  newCsValues.forEach(function (v) { csValues.push(v); });
+  var csAttr = b.sequence([b.oid(CS), b.set(csValues)]);
+  var setOf = b.set(others.concat([csAttr]));
+  var wire = Buffer.from(setOf); wire[0] = 0xA1;   // SET OF -> [1] IMPLICIT UnsignedAttributes
+  return wire;
+}
+
+// Append countersignature values to a SignerInfo node, preserving version / sid / digestAlgorithm /
+// signedAttrs / signatureAlgorithm / signature BYTE-FOR-BYTE (the signed preimage), only adding the
+// [1] unsignedAttrs. Returns the new SignerInfo bytes.
+function _appendCountersigs(siNode, newCsValues) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var hasUa = last.tagClass === "context" && last.tagNumber === 1;
+  var base = (hasUa ? kids.slice(0, kids.length - 1) : kids).map(function (k) { return k.bytes; });
+  base.push(_mergeCountersig(hasUa ? last : null, newCsValues));
+  return b.sequence(base);
+}
+
+// Splice countersignature values into the j-th countersignature VALUE of a SignerInfo node (nested
+// countersignature, RFC 5652 sec. 11.4). Returns the new SignerInfo bytes.
+function _spliceNested(siNode, j, newCsValues) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var CS = O("countersignature");
+  if (!last || last.tagClass !== "context" || last.tagNumber !== 1) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var found = false;
+  var attrs = last.children.map(function (attr) {
+    if (asn1.read.oid(attr.children[0]) !== CS) return attr.bytes;
+    var values = attr.children[1].children;
+    if (j < 0 || j >= values.length) throw _err("cms/bad-input", "countersignatureOf out of range: " + j);
+    found = true;
+    return b.sequence([b.oid(CS), b.set(values.map(function (v, vi) { return vi === j ? _appendCountersigs(v, newCsValues) : v.bytes; }))]);
+  });
+  if (!found) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var setOf = b.set(attrs); var wire = Buffer.from(setOf); wire[0] = 0xA1;
+  var base = kids.slice(0, kids.length - 1).map(function (k) { return k.bytes; });
+  base.push(wire);
+  return b.sequence(base);
+}
+
+// The signature-value octets of a SignerInfo node: the last universal OCTET STRING, i.e. the last
+// child unless a [1] IMPLICIT unsignedAttrs (a prior countersignature) follows it.
+function _signatureOctets(siNode) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var sigNode = (last.tagClass === "context" && last.tagNumber === 1) ? kids[kids.length - 2] : last;
+  return asn1.read.octetString(sigNode);
+}
+
+// The sec. 11.4 preimage for a target: the primary SignerInfo's signature octets, or (nested) the
+// j-th countersignature value's signature octets.
+function _targetPreimage(siNode, opts) {
+  if (opts.countersignatureOf == null) return _signatureOctets(siNode);
+  var last = siNode.children[siNode.children.length - 1];
+  var CS = O("countersignature");
+  if (!last || last.tagClass !== "context" || last.tagNumber !== 1) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var attr = last.children.filter(function (a) { return asn1.read.oid(a.children[0]) === CS; })[0];
+  if (!attr) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var values = attr.children[1].children;
+  var j = opts.countersignatureOf;
+  if (typeof j !== "number" || !Number.isInteger(j) || j < 0 || j >= values.length) throw _err("cms/bad-input", "countersignatureOf out of range: " + j);
+  return _signatureOctets(values[j]);
+}
+
+// pki.cms.countersign -- documented by the @primitive block in cms-verify.js (the @module pki.cms home).
+function countersign(cmsInput, signers, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.countersign options must be an object");
+  var list = Array.isArray(signers) ? signers : [signers];
+  if (!list.length) throw _err("cms/bad-input", "pki.cms.countersign requires at least one countersigner");
+  if (opts.signingTime != null && opts.signingTime !== false) guard.time.assertValid(opts.signingTime, _err, "cms/bad-input", "signingTime");
+  var der = pkix.coerceToDer(cmsInput, { pemLabel: null, PemError: frameworkError.PemError, ErrorClass: CmsError, prefix: "cms" });
+  // cms.parse throws a typed cms/* error on a malformed input (mirroring verify's own parse call); a
+  // structurally-valid but non-SignedData CMS (an EnvelopedData) parses without a signerInfos array.
+  var parsed = cms.parse(der);
+  if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "pki.cms.countersign input is not a CMS SignedData");
+  var targets = _resolveSignerIndices(opts.signerIndex, parsed.signerInfos.length);
+  var root = asn1.decode(der);
+  var sd = root.children[1].children[0];
+  var sdKids = sd.children;
+  var siSet = sdKids[sdKids.length - 1];
+
+  // Build every countersignature value (target x countersigner), then splice into the node tree.
+  var jobs = [];
+  targets.forEach(function (t) {
+    var preimage = _targetPreimage(siSet.children[t], opts);
+    list.forEach(function (cs) { jobs.push({ t: t, p: _buildCountersignature(preimage, cs, opts) }); });
+  });
+  return Promise.all(jobs.map(function (j) { return j.p; })).then(function (built) {
+    var byTarget = {}, certDers = [];
+    built.forEach(function (res, i) { (byTarget[jobs[i].t] = byTarget[jobs[i].t] || []).push(res.value); certDers.push(res.certDer); });
+
+    var newSiSet = b.set(siSet.children.map(function (siNode, idx) {
+      if (!byTarget[idx]) return siNode.bytes;
+      return opts.countersignatureOf == null ? _appendCountersigs(siNode, byTarget[idx]) : _spliceNested(siNode, opts.countersignatureOf, byTarget[idx]);
+    }));
+
+    // Rebuild SignedData: version, digestAlgorithms (UNCHANGED -- a countersignature digest is not a
+    // SignedData digestAlgorithm), encapContentInfo, certificates [0]?, crls [1]?, the new signerInfos.
+    var certsNode = null, crlsNode = null;
+    for (var i = 3; i < sdKids.length - 1; i++) {
+      if (sdKids[i].tagClass === "context" && sdKids[i].tagNumber === 0) certsNode = sdKids[i];
+      else if (sdKids[i].tagClass === "context" && sdKids[i].tagNumber === 1) crlsNode = sdKids[i];
+    }
+    var existing = [];
+    if (certsNode) certsNode.children.forEach(function (c) { existing.push(c.bytes); });
+    if (opts.certificates !== false) certDers.forEach(function (d) { existing.push(d); });
+    var allCerts = _dedupe(existing).sort(Buffer.compare);   // X.690 sec. 11.6
+
+    var newSdFields = [sdKids[0].bytes, sdKids[1].bytes, sdKids[2].bytes];   // version, digestAlgs, encap (raw)
+    if (allCerts.length) newSdFields.push(b.contextConstructed(0, Buffer.concat(allCerts)));
+    if (crlsNode) newSdFields.push(crlsNode.bytes);
+    newSdFields.push(newSiSet);
+    var newCi = b.sequence([root.children[0].bytes, b.explicit(0, b.sequence(newSdFields))]);
+    return opts.pem ? pkix.pemEncode(newCi, "CMS", frameworkError.PemError) : newCi;
+  });
+}
+
 // Coverage residual -- three defensive branches are unreachable through the shipped path:
 //   * `_skiValue`'s `cert.extensions || []` fallback -- x509.parse always surfaces `extensions`
 //     as an array (empty when absent), so the `|| []` never fires.
@@ -199,4 +424,13 @@ function _toBuf(v, what) {
 //   * `_assertKeyMatchesScheme`'s `!ka.hash` guard -- an `imp.hash` is set only for an RSA
 //     scheme, which requires `ka.name` to already equal the RSA name (else the earlier name
 //     check throws); an RSA CryptoKey always carries a `hash`, so `!ka.hash` never fires.
-module.exports = { sign: sign };
+// Countersign-side residuals also unreachable through the shipped path:
+//   * `_resolveSignerIndices`'s `n < 1` throw -- a parsed SignedData always carries at least one
+//     SignerInfo, so the default index [0] is always in range.
+//   * `_spliceNested`'s no-countersignature / index-out-of-range / not-found throws -- the same node
+//     is validated by `_targetPreimage` FIRST (it computes the nested preimage before the build), so
+//     by the time `_spliceNested` re-walks it those conditions cannot hold; the checks are
+//     belt-and-suspenders against a future caller reordering the two.
+//   * the `crls [1]` preservation branches in `countersign` -- pki.cms.sign never emits a crls field,
+//     so a store this producer countersigns never carries one to preserve.
+module.exports = { sign: sign, countersign: countersign };

package/lib/cms-verify.js

@@ -51,6 +51,7 @@ function _err(code, message, cause) { return new CmsError(code, message, cause);
 
 var OID_MESSAGE_DIGEST = oid.byName("messageDigest");
 var OID_CONTENT_TYPE = oid.byName("contentType");
+var OID_COUNTERSIGNATURE = oid.byName("countersignature");
 
 // A digest-algorithm name -> the WebCrypto hash.
 var DIGEST_HASH = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
@@ -309,12 +310,16 @@ function _decodeSignedAttrs(setOfBytes) {
 
 // Verify one SignerInfo. Returns { ok, sid, cert, ... } -- a resolved false is a verdict; a
 // structural failure carries a code.
-function _verifyOne(si, content, eContentType, parsedCerts) {
+// `csTarget`, when set (a Buffer), makes this a COUNTERSIGNATURE verify (RFC 5652 sec. 11.4): the
+// preimage is the countersigned signature octets, not the sec. 5.4 content preimage, and no
+// content-type attribute is required or checked (_computeCountersigBytes). content/eContentType are
+// unused in that mode.
+function _verifyOne(si, content, eContentType, parsedCerts, csTarget) {
   // A composite ML-DSA SignerInfo (draft-ietf-lamps-cms-composite-sigs) is keyed by its composite
   // OID, not a SIG_SCHEME name; intercept it before the classical dispatch (its verify has no
   // single external signature hash, so it never routes through the SIG_SCHEME/sigHash gate below).
   var composite = compositeSig.COMPOSITE_ALGS[si.signatureAlgorithm.oid];
-  if (composite) return _verifyComposite(si, composite, content, eContentType, parsedCerts);
+  if (composite) return _verifyComposite(si, composite, content, eContentType, parsedCerts, csTarget);
   var scheme = SIG_SCHEME[si.signatureAlgorithm.name];
   if (!scheme) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported signature algorithm " + JSON.stringify(si.signatureAlgorithm.name) });
   var digestHash = DIGEST_HASH[si.digestAlgorithm.name];
@@ -362,12 +367,43 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
   if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
 
-  return _computeSignedBytes(si, content, eContentType).then(function (signedBytes) {
+  return (csTarget != null ? _computeCountersigBytes(si, csTarget) : _computeSignedBytes(si, content, eContentType)).then(function (signedBytes) {
     if (signedBytes && signedBytes.mismatch) return { ok: false, code: signedBytes.mismatch.code, sid: si.sid, cert: signers[0].der, message: signedBytes.mismatch.message };
     return _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, si.sid, signers, pss ? pss.saltLength : 0, scheme.sameKeyOid ? oid.byName(si.signatureAlgorithm.name) : null);
   });
 }
 
+// The exact bytes a countersignature covers (RFC 5652 sec. 11.4): the countersigned SignerInfo's
+// signature value octets (`csTarget`). With signed attributes present, the message-digest attribute
+// MUST equal digest(csTarget) under the countersignature's own digestAlgorithm and the signature
+// covers the re-tagged SignedAttributes ([0] -> universal SET OF) -- the identical transform the
+// top-level signer uses, minus the content-type attribute (which sec. 11.4 FORBIDS). Resolves the
+// signed bytes, or { mismatch } when the message-digest disagrees.
+function _computeCountersigBytes(si, csTarget) {
+  return Promise.resolve().then(function () {
+    if (!si.signedAttrsBytes) return csTarget;   // no signed attributes: sign over the target signature octets directly
+    var reTagged = Buffer.from(si.signedAttrsBytes);
+    reTagged[0] = 0x31;   // [0] IMPLICIT -> universal SET OF
+    var attrs;
+    try {
+      attrs = _decodeSignedAttrs(reTagged);
+    } catch (e) { if (e instanceof CmsError) throw e; throw _err("cms/bad-signed-attrs", "the countersignature signedAttrs is not a valid SET OF Attribute", e); }
+    // sec. 11.4: a content-type attribute MUST NOT appear (the parser already rejects it at parse, but
+    // verify never relies on the parse alone -- a parsed-object input could carry one).
+    if (attrs.filter(function (a) { return a.type === OID_CONTENT_TYPE; }).length) throw _err("cms/misplaced-attr", "a countersignature must not carry a content-type attribute (RFC 5652 sec. 11.4)");
+    var mdAttr = attrs.filter(function (a) { return a.type === OID_MESSAGE_DIGEST; })[0];
+    if (!mdAttr || mdAttr.values.length !== 1) throw _err("cms/bad-signed-attrs", "a countersignature's signedAttrs must carry exactly one message-digest attribute (RFC 5652 sec. 11.4)");
+    var declared;
+    try {
+      declared = asn1.read.octetString(mdAttr.values[0]);
+    } catch (e) { throw _err("cms/bad-signed-attrs", "the message-digest attribute value is not an OCTET STRING", e); }
+    return _computeDigest(si.digestAlgorithm.name, csTarget).then(function (d) {
+      if (!d.equals(declared)) return { mismatch: { code: "cms/message-digest-mismatch", message: "the countersignature message-digest does not match the countersigned signature" } };
+      return reTagged;
+    });
+  });
+}
+
 // The exact bytes the signature covers (RFC 5652 sec. 5.4), shared by the classical and composite
 // verify paths so both bind the message-digest / content-type checks to the VERIFIED preimage (not
 // the caller-mutable parsed si.signedAttrs). Resolves the signed bytes, or { mismatch } when a
@@ -418,7 +454,7 @@ function _computeSignedBytes(si, content, eContentType) {
 // pre-hash. It reuses the sec. 5.4 preimage + message-digest binding UNCHANGED, then dispatches
 // compositeVerify per candidate certificate (BOTH components must verify -- never an AND->OR
 // downgrade).
-function _verifyComposite(si, comp, content, eContentType, parsedCerts) {
+function _verifyComposite(si, comp, content, eContentType, parsedCerts, csTarget) {
   if (si.signatureAlgorithm.parameters !== null && si.signatureAlgorithm.parameters !== undefined) {
     return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the composite signatureAlgorithm parameters must be absent (draft-ietf-lamps-cms-composite-sigs sec. 3.4)" });
   }
@@ -447,7 +483,7 @@ function _verifyComposite(si, comp, content, eContentType, parsedCerts) {
   var signers = _findSignerCerts(si.sid, parsedCerts);
   if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
-  return _computeSignedBytes(si, content, eContentType).then(function (signedBytes) {
+  return (csTarget != null ? _computeCountersigBytes(si, csTarget) : _computeSignedBytes(si, content, eContentType)).then(function (signedBytes) {
     if (signedBytes && signedBytes.mismatch) return { ok: false, code: signedBytes.mismatch.code, sid: si.sid, cert: signers[0].der, message: signedBytes.mismatch.message };
     return _verifyCompositeAgainstCandidates(comp, sigBytes, signedBytes, si.sid, signers, si.signatureAlgorithm.oid);
   });
@@ -480,6 +516,49 @@ function _verifyCompositeAgainstCandidates(comp, sigBytes, signedBytes, sid, can
   return attempt(0);
 }
 
+// The decoded unsigned attributes of a SignerInfo, surfaced UNAUTHENTICATED (they are outside the
+// signature) with each OID resolved to a name -- so a caller can read an attached RFC 3161 timestamp
+// token or inspect a countersignature attribute. NEVER counted toward a signer's ok / res.valid.
+function _surfaceUnsignedAttrs(si) {
+  return (si.unsignedAttrs || []).map(function (a) {
+    return { type: a.type, typeName: oid.name(a.type) || null, values: a.values };
+  });
+}
+
+// Verify every countersignature attached to `si` (RFC 5652 sec. 11.4): each id-countersignature
+// value is a SignerInfo over `si`'s signature octets. Returns per-countersignature verdicts; a
+// countersignature's OWN countersignatures verify over ITS signature octets (recursive). A
+// present-but-invalid countersignature is surfaced ok:false -- never silently dropped. The recursion
+// terminates because it only walks the FINITE parsed structure: each nested countersignature value
+// is a sub-encoding of its parent, and the strict decoder already bounds total nesting by
+// C.LIMITS.DER_MAX_DEPTH at parse (CWE-834/770), so a hostile deep chain fails closed before verify.
+function _verifyCountersignatures(si, parsedCerts) {
+  // si.signature is always a Buffer from the strict parser (and from walkCountersignature on the
+  // recursive path), so _toBuf is a pass-through here -- the SignerInfo is already well-formed.
+  var targetSig = _toBuf(si.signature, "the countersigned signature");
+  var values = [];
+  (si.unsignedAttrs || []).forEach(function (a) {
+    if (a.type !== OID_COUNTERSIGNATURE) return;
+    a.values.forEach(function (v) { values.push(v && v.bytes ? v.bytes : v); });
+  });
+  return Promise.all(values.map(function (vDer) { return _verifyOneCountersig(vDer, targetSig, parsedCerts); }));
+}
+
+function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
+  var csSi;
+  try { csSi = cms.walkCountersignature(asn1.decode(Buffer.isBuffer(vDer) ? vDer : Buffer.from(vDer))); }
+  catch (e) { return Promise.resolve({ ok: false, code: (e instanceof CmsError ? e.code : "cms/bad-countersignature"), message: e && e.message }); }
+  return _verifyOne(csSi, targetSig, null, parsedCerts, targetSig).then(function (verdict) {
+    return _verifyCountersignatures(csSi, parsedCerts).then(function (nested) {
+      var node = { ok: verdict.ok, sid: verdict.sid, cert: verdict.cert, digestAlgorithm: csSi.digestAlgorithm.name };
+      if (verdict.code) node.code = verdict.code;
+      node.unsignedAttrs = _surfaceUnsignedAttrs(csSi);
+      node.countersignatures = nested;
+      return node;
+    });
+  });
+}
+
 /**
  * @primitive  pki.cms.verify
  * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, signers }>
@@ -533,8 +612,17 @@ function verify(input, opts) {
   (parsed.certificates || []).forEach(function (c) { _addCert(parsedCerts, c && c.bytes ? c.bytes : c); });
   (opts.certs || []).forEach(function (c) { _addCert(parsedCerts, c); });
   var eContentType = parsed.encapContentInfo.eContentType;
-  return Promise.all(parsed.signerInfos.map(function (si) { return _verifyOne(si, content, eContentType, parsedCerts); }))
-    .then(function (signers) { return { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers }; });
+  return Promise.all(parsed.signerInfos.map(function (si) {
+    // res.valid reflects only the PRIMARY signerInfos; a countersignature / unsigned attribute is
+    // outside the signature and NEVER flips the top-level verdict. Both are surfaced per signer.
+    return _verifyOne(si, content, eContentType, parsedCerts).then(function (verdict) {
+      return _verifyCountersignatures(si, parsedCerts).then(function (countersignatures) {
+        verdict.countersignatures = countersignatures;
+        verdict.unsignedAttrs = _surfaceUnsignedAttrs(si);
+        return verdict;
+      });
+    });
+  })).then(function (signers) { return { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers }; });
 }
 // Parse a candidate cert DER and index its SKI; a cert that will not parse is skipped (it
 // simply cannot be a signer match, and a malformed embedded cert must not fail the verify).
@@ -595,12 +683,61 @@ function _addCert(out, der) {
  * @opts  sid               `"issuerAndSerial"` (default) or `"ski"` (subjectKeyIdentifier).
  * @opts  certificates      Embed the signer certificates in the output. Default true.
  * @opts  pem               Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
+ * @opts  unsignedAttributes  Unsigned attributes for every SignerInfo, each `{ type, values }`
+ *                          (`type` an OID name or dotted string, `values` an array of DER value
+ *                          `Buffer`s). Placed in the SignerInfo `[1]` unsignedAttrs -- OUTSIDE the
+ *                          signature, so they carry no cryptographic assurance and a verifier never
+ *                          reports them authenticated. The vehicle for an RFC 3161 timestamp token
+ *                          (`timeStampToken`); content-type / message-digest / signing-time are
+ *                          rejected here (RFC 5652 sec. 11). Use `pki.cms.countersign` for a
+ *                          countersignature specifically.
  * @example
  *   var p7 = await pki.cms.sign(Buffer.from("hello"), { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var res = await pki.cms.verify(p7);   // res.valid === true
  */
 var sign = cmsSign.sign;
 
+/**
+ * @primitive  pki.cms.countersign
+ * @signature  pki.cms.countersign(cms, signers, opts?) -> Promise<Buffer|string>
+ * @since      0.3.13
+ * @status     experimental
+ * @spec       RFC 5652
+ * @related    pki.cms.sign, pki.cms.verify, pki.schema.cms.parse
+ *
+ * Add one or more countersignatures to an existing CMS SignedData (RFC 5652 sec. 11.4). A
+ * countersignature is itself a `SignerInfo` whose signature covers the CONTENTS of the countersigned
+ * SignerInfo's signature value (NOT the content), attached as the `id-countersignature` unsigned
+ * attribute -- the construction Authenticode timestamps and signature-attestation workflows rest on.
+ * `cms` is the SignedData (a DER `Buffer` or a PEM `CMS` string -- the wire bytes are preserved, so
+ * the countersigned primary still verifies byte-for-byte). Each `signers[i]` is the same descriptor
+ * `pki.cms.sign` takes -- `{ cert, key, digestAlgorithm?, pss? }`, any RSA / RSASSA-PSS / ECDSA /
+ * EdDSA / ML-DSA / SLH-DSA / composite key -- and countersigns over the target signature octets;
+ * `pki.cms.verify` returns each countersignature verdict under `signers[i].countersignatures`. A
+ * countersignature never carries a content-type attribute (sec. 11.4); multiple countersignatures on
+ * one signer are multiple values of the one id-countersignature attribute.
+ *
+ * @opts  signerIndex           Which primary SignerInfo(s) to countersign: an index (default 0), an
+ *                              array of indices, or `"all"`.
+ * @opts  countersignatureOf    Countersign the Nth existing countersignature of the target signer
+ *                              instead of the primary signature (a nested countersignature).
+ * @opts  signedAttributes      Include signed attributes (message-digest + signing-time; NEVER a
+ *                              content-type). Default true; false signs the target signature octets
+ *                              directly.
+ * @opts  signingTime           A `Date` for the countersignature's signing-time, or false to omit it.
+ * @opts  additionalSignedAttributes  Extra signed attributes on the countersignature (a content-type
+ *                              is rejected, RFC 5652 sec. 11.4).
+ * @opts  sid                   `"issuerAndSerial"` (default) or `"ski"`.
+ * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default true.
+ * @opts  pem                   Return a PEM string instead of a DER Buffer.
+ * @example
+ *   var p7 = await pki.cms.sign(Buffer.from("hi"), { cert: signerCertDer, key: signerKeyPkcs8 });
+ *   var cs = await pki.cms.countersign(p7, { cert: signerCertDer, key: signerKeyPkcs8 });
+ *   var res = await pki.cms.verify(cs);
+ *   res.signers[0].countersignatures[0].ok;   // true
+ */
+var countersign = cmsSign.countersign;
+
 /**
  * @primitive pki.cms.encrypt
  * @signature pki.cms.encrypt(content, recipients, opts?) -> Promise<Buffer | string>
@@ -708,4 +845,4 @@ var compress = cmsCompress.compress;
  */
 var decompress = cmsCompress.decompress;
 
-module.exports = { verify: verify, sign: sign, encrypt: encrypt, decrypt: decrypt, compress: compress, decompress: decompress };
+module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, decrypt: decrypt, compress: compress, decompress: decompress };

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

@@ -145,6 +145,38 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   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()]); }
@@ -179,6 +211,6 @@ module.exports = {
   prfNodeByName: prfNodeByName, prfNodeByOid: prfNodeByOid,
   pbkdf2ParamsSeq: pbkdf2ParamsSeq, pbes2AlgId: pbes2AlgId, parsePbkdf2Params: parsePbkdf2Params,
   requireChildren: requireChildren, seqChildren: seqChildren,
-  cbcEncrypt: cbcEncrypt, cbcDecrypt: cbcDecrypt, pbes2Encrypt: pbes2Encrypt, 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

@@ -32,6 +32,7 @@ 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");
@@ -428,7 +429,123 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
   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-cms.js

@@ -1204,6 +1204,12 @@ function walkEnvelopedData(node) { return schema.walk(ENVELOPED_DATA, node, NS).
 // walkEnvelopedData: the node is the bare structure, typed cms/* on rejection.
 function walkSignedData(node) { return schema.walk(SIGNED_DATA, node, NS).result; }
 function walkEncryptedData(node) { return schema.walk(ENCRYPTED_DATA, node, NS).result; }
+// Validate + surface one countersignature value (RFC 5652 sec. 11.4, Countersignature ::=
+// SignerInfo) into the same parsed shape parse() gives a top-level SignerInfo -- so pki.cms.verify
+// can verify a countersignature through the ONE SignerInfo definition (its sec. 11.4 rules
+// enforced: message-digest present, content-type FORBIDDEN via mode "countersig"). The node is the
+// bare id-countersignature value; a malformed / content-type-carrying value throws a typed cms/*.
+function walkCountersignature(node) { return schema.walk(COUNTERSIGNATURE_SIGNER_INFO, node, NS).result; }
 
 // assertAttachedCiphertext(eci, E, code, label): reject an EnvelopedData /
 // EncryptedData encryptedContentInfo whose encryptedContent (the payload itself)
@@ -1227,6 +1233,7 @@ module.exports = {
   walkEnvelopedData: walkEnvelopedData,
   walkSignedData: walkSignedData,
   walkEncryptedData: walkEncryptedData,
+  walkCountersignature: walkCountersignature,
   assertAttachedCiphertext: assertAttachedCiphertext,
   // The structure's own algorithm tables, exported (like the walk* helpers) as the single source
   // of truth the crypto layer (cms-encrypt / cms-decrypt) shares -- so the wrap<->KEK-length, the

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.11",
+  "version": "0.3.13",
   "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:253a6908-56c1-4a56-bdf4-33cb2035a161",
+  "serialNumber": "urn:uuid:ddc37e54-2fea-49ec-a673-31366e0c6424",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-23T22:26:59.213Z",
+    "timestamp": "2026-07-24T03:47:36.459Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.11",
+      "bom-ref": "@blamejs/pki@0.3.13",
       "type": "application",
       "name": "pki",
-      "version": "0.3.11",
+      "version": "0.3.13",
       "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.11",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.11",
+      "ref": "@blamejs/pki@0.3.13",
       "dependsOn": []
     }
   ]