@blamejs/pki 0.1.22 → 0.1.23

package/lib/schema-pkcs12.js

@@ -10,8 +10,8 @@
  *
  * @intro
  *   PKCS#12 (PFX) key-and-certificate store handling per RFC 7292. `parse`
- *   decodes a `.p12` / `.pfx` container — the personal-information-exchange
- *   format OpenSSL, Windows CAPI, macOS Keychain, and NSS emit — into its
+ *   decodes a `.p12` / `.pfx` container -- the personal-information-exchange
+ *   format OpenSSL, Windows CAPI, macOS Keychain, and NSS emit -- into its
  *   bags: private keys (delegated to the PKCS#8 parser), shrouded keys
  *   (algorithm surfaced, ciphertext kept opaque), certificates, CRLs,
  *   secrets, and nested safe contents, each with its `friendlyName` /
@@ -26,14 +26,14 @@
  *   (`macedBytes`), public-key mode the SignedData with its signers, and a
  *   MAC-less store surfaces `integrityMode: "none"` for the caller's policy
  *   to judge. RFC 7292
- *   §4.1 encodes content in BER, so parsing this one format accepts exactly
- *   two BER shapes — indefinite lengths and constructed OCTET STRINGs —
+ *   sec. 4.1 encodes content in BER, so parsing this one format accepts exactly
+ *   two BER shapes -- indefinite lengths and constructed OCTET STRINGs --
  *   anywhere in the store; every other strictness verdict, and every other
  *   format, stays strict DER, fail-closed.
  *
  * @card
  *   Parse DER / BER / PEM RFC 7292 PKCS#12 (PFX) stores into key / cert /
- *   CRL / secret bags with their attributes — keys via the PKCS#8 parser,
+ *   CRL / secret bags with their attributes -- keys via the PKCS#8 parser,
  *   encrypted safes via CMS, MAC inputs surfaced raw for external
  *   verification, fail-closed.
  */
@@ -52,26 +52,30 @@ var PemError = frameworkError.PemError;
 var NS = pkix.makeNS("pkcs12", Pkcs12Error, oid);
 var TAGS = asn1.TAGS;
 
-// Content types (RFC 5652 §4 / RFC 7292 §4.1).
+// Content types (RFC 5652 sec. 4 / RFC 7292 sec. 4.1).
 var OID_DATA = oid.byName("data");
 var OID_SIGNED_DATA = oid.byName("signedData");
 var OID_ENVELOPED_DATA = oid.byName("envelopedData");
 var OID_ENCRYPTED_DATA = oid.byName("encryptedData");
-// Bag types (RFC 7292 §4.2).
+// Bag types (RFC 7292 sec. 4.2).
 var OID_KEY_BAG = oid.byName("keyBag");
 var OID_SHROUDED_KEY_BAG = oid.byName("pkcs8ShroudedKeyBag");
 var OID_CERT_BAG = oid.byName("certBag");
 var OID_CRL_BAG = oid.byName("crlBag");
 var OID_SECRET_BAG = oid.byName("secretBag");
 var OID_SAFE_CONTENTS_BAG = oid.byName("safeContentsBag");
-// CertBag / CRLBag discriminators (§4.2.3-§4.2.4).
+// CertBag / CRLBag discriminators (sec. 4.2.3-sec. 4.2.4).
 var OID_X509_CERTIFICATE = oid.byName("x509Certificate");
 var OID_SDSI_CERTIFICATE = oid.byName("sdsiCertificate");
 var OID_X509_CRL = oid.byName("x509CRL");
-// Bag attributes (§4.2) + the RFC 9579 MacData arm.
+// Bag attributes (sec. 4.2) + the RFC 9579 MacData arm.
 var OID_FRIENDLY_NAME = oid.byName("friendlyName");
 var OID_LOCAL_KEY_ID = oid.byName("localKeyId");
 var OID_PBMAC1 = oid.byName("pbmac1");
+// The PBKDF2-params prf DEFAULT is algid-hmacWithSHA1 -- hmacWithSHA1 with NULL
+// parameters (RFC 8018 sec. 5.2) -- needed for the encoded-DEFAULT rejection below.
+var OID_HMAC_SHA1 = oid.byName("hmacWithSHA1");
+var DER_NULL = asn1.build.nullValue();
 
 // DigestInfo ::= SEQUENCE { digestAlgorithm AlgorithmIdentifier, digest OCTET STRING }.
 var DIGEST_INFO = schema.seq([
@@ -84,9 +88,9 @@ var DIGEST_INFO = schema.seq([
   },
 });
 
-// PBKDF2-params (RFC 8018 §5.2), constrained to the RFC 9579 PBMAC1 profile:
+// PBKDF2-params (RFC 8018 sec. 5.2), constrained to the RFC 9579 PBMAC1 profile:
 // the salt MUST use the specified (OCTET STRING) choice and keyLength MUST be
-// present (§4.b / §5 — a MacData consumer cannot infer the MAC key size).
+// present (sec. 4.b / sec. 5 -- a MacData consumer cannot infer the MAC key size).
 var PBKDF2_PARAMS = schema.seq([
   schema.field("salt", schema.octetString()),
   schema.field("iterationCount", schema.integerLeaf()),
@@ -96,9 +100,9 @@ var PBKDF2_PARAMS = schema.seq([
   assert: "sequence", code: "pkcs12/bad-mac-data", what: "PBKDF2-params",
   build: function (m, ctx) {
     if (!m.fields.keyLength.present) {
-      throw ctx.E("pkcs12/bad-mac-data", "PBMAC1 PBKDF2-params must carry keyLength (RFC 9579 §5)");
+      throw ctx.E("pkcs12/bad-mac-data", "PBMAC1 PBKDF2-params must carry keyLength (RFC 9579 sec. 5)");
     }
-    // Both counters surface as exact JS numbers — a value past the bound
+    // Both counters surface as exact JS numbers -- a value past the bound
     // would round silently on conversion and hand a verifier wrong inputs.
     var iterations = m.fields.iterationCount.value;
     if (iterations < 1n || iterations > 2147483647n) {
@@ -109,18 +113,27 @@ var PBKDF2_PARAMS = schema.seq([
       throw ctx.E("pkcs12/bad-mac-data", "PBKDF2 keyLength must be a positive integer within the key-length range");
     }
     var prf = m.fields.prf.present ? m.fields.prf.value.result : null;
+    // X.690 sec. 11.5 -- a DEFAULT-valued component must be omitted from a DER
+    // encoding, and the prf DEFAULT is algid-hmacWithSHA1: hmacWithSHA1 with
+    // NULL parameters (RFC 8018 sec. 5.2). An explicit prf byte-equal to that
+    // default is non-canonical and rejects -- the structured-value analogue of
+    // the MacData iterations rule below. hmacWithSHA1 with ABSENT parameters
+    // is a different value from the NULL-parameters default and decodes.
+    if (prf && prf.oid === OID_HMAC_SHA1 && prf.parameters !== null && prf.parameters.equals(DER_NULL)) {
+      throw ctx.E("pkcs12/bad-mac-data", "a PBKDF2 prf equal to its DEFAULT algid-hmacWithSHA1 must be omitted (X.690 sec. 11.5, RFC 8018 sec. 5.2)");
+    }
     return {
       salt: m.fields.salt.value,
       iterationCount: Number(iterations),
       keyLength: Number(keyLength),
-      prfOid: prf ? prf.oid : oid.byName("hmacWithSHA1"),
+      prfOid: prf ? prf.oid : OID_HMAC_SHA1,
       prfName: prf ? prf.name : "hmacWithSHA1",
     };
   },
 });
 
 // PBMAC1-params ::= SEQUENCE { keyDerivationFunc AlgorithmIdentifier{PBKDF2},
-// messageAuthScheme AlgorithmIdentifier } (RFC 8018 §A.5 / RFC 9579 §4).
+// messageAuthScheme AlgorithmIdentifier } (RFC 8018 sec. A.5 / RFC 9579 sec. 4).
 var PBMAC1_PARAMS = schema.seq([
   schema.field("keyDerivationFunc", schema.seq([
     schema.field("algorithm", schema.oidLeaf()),
@@ -132,7 +145,7 @@ var PBMAC1_PARAMS = schema.seq([
   build: function (m, ctx) {
     var kdf = m.fields.keyDerivationFunc.value;
     if (kdf.fields.algorithm.value !== oid.byName("pbkdf2")) {
-      throw ctx.E("pkcs12/bad-mac-data", "PBMAC1 keyDerivationFunc must be PBKDF2 (RFC 9579 §4)");
+      throw ctx.E("pkcs12/bad-mac-data", "PBMAC1 keyDerivationFunc must be PBKDF2 (RFC 9579 sec. 4)");
     }
     var scheme = m.fields.messageAuthScheme.value.result;
     return {
@@ -152,23 +165,23 @@ var MAC_DATA = schema.seq([
 ], {
   assert: "sequence", code: "pkcs12/bad-mac-data", what: "MacData",
   build: function (m, ctx) {
-    // X.690 §11.5 — a DEFAULT-valued component must be omitted from a DER
+    // X.690 sec. 11.5 -- a DEFAULT-valued component must be omitted from a DER
     // encoding, so an explicitly-encoded iterations = 1 is non-canonical.
     var it = m.fields.iterations;
     var iterations = 1;
     if (it.present) {
       var v = it.value;
-      if (v === 1n) throw ctx.E("pkcs12/bad-mac-iterations", "iterations equal to its DEFAULT 1 must be omitted (X.690 §11.5)");
+      if (v === 1n) throw ctx.E("pkcs12/bad-mac-iterations", "iterations equal to its DEFAULT 1 must be omitted (X.690 sec. 11.5)");
       if (v < 1n || v > 2147483647n) throw ctx.E("pkcs12/bad-mac-iterations", "iterations must be a positive integer within the iteration-count range");
       iterations = Number(v);
     }
     var di = m.fields.mac.value.result;
     var pbmac1 = null;
     if (di.digestAlgorithm.oid === OID_PBMAC1) {
-      // RFC 9579 §4 — the PBMAC1 algorithm identifier MUST carry PBMAC1-params
+      // RFC 9579 sec. 4 -- the PBMAC1 algorithm identifier MUST carry PBMAC1-params
       // (the KDF and MAC scheme a verifier needs live there, not in MacData).
       if (di.digestAlgorithm.parameters === null) {
-        throw ctx.E("pkcs12/bad-mac-data", "a PBMAC1 MacData must carry PBMAC1-params (RFC 9579 §4)");
+        throw ctx.E("pkcs12/bad-mac-data", "a PBMAC1 MacData must carry PBMAC1-params (RFC 9579 sec. 4)");
       }
       pbmac1 = schema.embeddedDer(PBMAC1_PARAMS, di.digestAlgorithm.parameters, ctx,
         { code: "pkcs12/bad-mac-data", what: "PBMAC1-params", ber: true }).result;
@@ -186,7 +199,7 @@ var MAC_DATA = schema.seq([
   },
 });
 
-// CertBag ::= SEQUENCE { certId OID, certValue [0] EXPLICIT ANY } (§4.2.3):
+// CertBag ::= SEQUENCE { certId OID, certValue [0] EXPLICIT ANY } (sec. 4.2.3):
 // x509Certificate wraps the DER certificate in an OCTET STRING; sdsiCertificate
 // is an IA5String. Both arms of the closed set are accepted; the value is
 // surfaced raw (byte-exact), never re-encoded or recursively parsed.
@@ -203,15 +216,15 @@ var CERT_BAG = schema.seq([
     }
     if (certId === OID_SDSI_CERTIFICATE) {
       if (!(node.tagClass === "universal" && node.tagNumber === TAGS.IA5_STRING && node.content)) {
-        throw ctx.E("pkcs12/bad-bag-value", "an sdsiCertificate certValue must be an IA5String (RFC 7292 §4.2.3)");
+        throw ctx.E("pkcs12/bad-bag-value", "an sdsiCertificate certValue must be an IA5String (RFC 7292 sec. 4.2.3)");
       }
       return { certType: "sdsiCertificate", certId: certId, certValue: node.content };
     }
-    throw ctx.E("pkcs12/bad-cert-type", (ctx.oid.name(certId) || certId) + " is not a recognized CertBag certId (RFC 7292 §4.2.3)");
+    throw ctx.E("pkcs12/bad-cert-type", (ctx.oid.name(certId) || certId) + " is not a recognized CertBag certId (RFC 7292 sec. 4.2.3)");
   },
 });
 
-// CRLBag ::= SEQUENCE { crlId OID, crlValue [0] EXPLICIT ANY } (§4.2.4).
+// CRLBag ::= SEQUENCE { crlId OID, crlValue [0] EXPLICIT ANY } (sec. 4.2.4).
 var CRL_BAG = schema.seq([
   schema.field("crlId", schema.oidLeaf()),
   schema.field("crlValue", schema.explicit(0, schema.any(), { code: "pkcs12/bad-bag-value", what: "crlValue" })),
@@ -220,15 +233,15 @@ var CRL_BAG = schema.seq([
   build: function (m, ctx) {
     var crlId = m.fields.crlId.value;
     if (crlId !== OID_X509_CRL) {
-      throw ctx.E("pkcs12/bad-crl-type", (ctx.oid.name(crlId) || crlId) + " is not a recognized CRLBag crlId (RFC 7292 §4.2.4)");
+      throw ctx.E("pkcs12/bad-crl-type", (ctx.oid.name(crlId) || crlId) + " is not a recognized CRLBag crlId (RFC 7292 sec. 4.2.4)");
     }
     return { crlType: "x509CRL", crlId: crlId, crlValue: _octetContent(m.fields.crlValue.value, ctx, "an x509CRL crlValue") };
   },
 });
 
 // SecretBag ::= SEQUENCE { secretTypeId OID, secretValue [0] EXPLICIT ANY }
-// (§4.2.5). SecretTypes is an open set, so the type is surfaced by OID with
-// the value raw — an unrecognized secret is representable, not a fault.
+// (sec. 4.2.5). SecretTypes is an open set, so the type is surfaced by OID with
+// the value raw -- an unrecognized secret is representable, not a fault.
 var SECRET_BAG = schema.seq([
   schema.field("secretTypeId", schema.oidLeaf()),
   schema.field("secretValue", schema.explicit(0, schema.any(), { code: "pkcs12/bad-bag-value", what: "secretValue" })),
@@ -241,7 +254,7 @@ var SECRET_BAG = schema.seq([
 });
 
 // SafeBag ::= SEQUENCE { bagId OID, bagValue [0] EXPLICIT ANY DEFINED BY bagId,
-//                        bagAttributes SET OF PKCS12Attribute OPTIONAL } (§4.2).
+//                        bagAttributes SET OF PKCS12Attribute OPTIONAL } (sec. 4.2).
 // The build surfaces the structural record (bagId + the inner value node +
 // decoded attributes); the bagId dispatch happens in _buildBag, where the
 // per-parse recursion state lives.
@@ -289,14 +302,14 @@ var SAFE_BAG = schema.seq([
   },
 });
 
-// SafeContents ::= SEQUENCE OF SafeBag (§4.2). Strictly a SEQUENCE — a SET OF
+// SafeContents ::= SEQUENCE OF SafeBag (sec. 4.2). Strictly a SEQUENCE -- a SET OF
 // here is a known producer divergence and rejects.
 var SAFE_CONTENTS = schema.seqOf(SAFE_BAG, {
   code: "pkcs12/bad-safe-contents", what: "SafeContents",
   max: C.LIMITS.PKCS12_MAX_ELEMENTS, maxCode: "pkcs12/too-many-elements",
 });
 
-// AuthenticatedSafe ::= SEQUENCE OF ContentInfo (§4.1) — each element parsed
+// AuthenticatedSafe ::= SEQUENCE OF ContentInfo (sec. 4.1) -- each element parsed
 // structurally here and dispatched by contentType in _dispatchSafes.
 var AS_ELEMENT = schema.seq([
   schema.field("contentType", schema.oidLeaf()),
@@ -312,7 +325,7 @@ var AUTHENTICATED_SAFE = schema.seqOf(AS_ELEMENT, {
   max: C.LIMITS.PKCS12_MAX_ELEMENTS, maxCode: "pkcs12/too-many-elements",
 });
 
-// The authSafe ContentInfo (§4): contentType is data (password integrity) or
+// The authSafe ContentInfo (sec. 4): contentType is data (password integrity) or
 // signedData (public-key integrity) and nothing else.
 var AUTH_SAFE = schema.seq([
   schema.field("contentType", schema.oidLeaf()),
@@ -325,7 +338,7 @@ var AUTH_SAFE = schema.seq([
 });
 
 // PFX ::= SEQUENCE { version INTEGER {v3(3)}, authSafe ContentInfo,
-//                    macData MacData OPTIONAL } (§4).
+//                    macData MacData OPTIONAL } (sec. 4).
 var PFX = schema.seq([
   schema.field("version", pkix.versionReader(NS, { "3": 3 })),
   schema.field("authSafe", AUTH_SAFE),
@@ -342,14 +355,14 @@ var PFX = schema.seq([
     var state = { budget: { remaining: C.LIMITS.PKCS12_MAX_REDECODES }, bagDepth: 0 };
 
     if (authSafe.contentType === OID_DATA) {
-      // §5.1 step 5B — the MAC covers the value octets of the id-data OCTET
+      // sec. 5.1 step 5B -- the MAC covers the value octets of the id-data OCTET
       // STRING (the AuthenticatedSafe encoding), excluding the TLV header.
       // MacData itself is OPTIONAL in the PFX syntax: a store without it
       // (OpenSSL `pkcs12 -export -nomac`) carries no integrity protection at
-      // all, which is a policy concern for the caller — surfaced as
+      // all, which is a policy concern for the caller -- surfaced as
       // integrityMode "none", never rejected by a parser that surfaces
       // integrity inputs rather than verifying them.
-      var macedBytes = _octetContent(authSafe.innerNode, ctx, "an id-data authSafe content");
+      var macedBytes = _octetContent(authSafe.innerNode, ctx, "an id-data authSafe content", "pkcs12/bad-authsafe");
       var dispatched = _dispatchSafes(_walkAuthenticatedSafe(macedBytes, state, ctx), state, ctx);
       return {
         version: version, integrityMode: macPresent ? "password" : "none", mac: mac, macedBytes: macedBytes,
@@ -357,19 +370,19 @@ var PFX = schema.seq([
       };
     }
     if (authSafe.contentType === OID_SIGNED_DATA) {
-      // §4 integrity coherence: public-key integrity has no MacData.
-      if (macPresent) throw ctx.E("pkcs12/bad-integrity-mode", "an id-signedData authSafe (public-key integrity) must omit macData (RFC 7292 §4)");
+      // sec. 4 integrity coherence: public-key integrity has no MacData.
+      if (macPresent) throw ctx.E("pkcs12/bad-integrity-mode", "an id-signedData authSafe (public-key integrity) must omit macData (RFC 7292 sec. 4)");
       var signed = cms.walkSignedData(authSafe.innerNode);
       if (signed.encapContentInfo.eContentType !== OID_DATA) {
-        throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must encapsulate id-data carrying the AuthenticatedSafe (RFC 7292 §4.1)");
+        throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must encapsulate id-data carrying the AuthenticatedSafe (RFC 7292 sec. 4.1)");
       }
       if (signed.encapContentInfo.eContent === null) {
-        throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must carry attached eContent (RFC 7292 §4.1)");
+        throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must carry attached eContent (RFC 7292 sec. 4.1)");
       }
-      // A signer-less SignedData carries no integrity at all — the one thing
+      // A signer-less SignedData carries no integrity at all -- the one thing
       // public-key-integrity mode exists to provide.
       if (signed.signerInfos.length < 1) {
-        throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must carry at least one SignerInfo (RFC 7292 §4)");
+        throw ctx.E("pkcs12/bad-authsafe", "a public-key-integrity authSafe must carry at least one SignerInfo (RFC 7292 sec. 4)");
       }
       var dispatchedSigned = _dispatchSafes(_walkAuthenticatedSafe(signed.encapContentInfo.eContent, state, ctx), state, ctx);
       return {
@@ -377,7 +390,7 @@ var PFX = schema.seq([
         authSafeSigned: signed, safeBags: dispatchedSigned.safeBags, encryptedSafes: dispatchedSigned.encryptedSafes,
       };
     }
-    throw ctx.E("pkcs12/bad-authsafe-type", "authSafe contentType must be id-data or id-signedData (RFC 7292 §4), got " +
+    throw ctx.E("pkcs12/bad-authsafe-type", "authSafe contentType must be id-data or id-signedData (RFC 7292 sec. 4), got " +
       (ctx.oid.name(authSafe.contentType) || authSafe.contentType));
   },
 });
@@ -391,19 +404,19 @@ function _octetContent(node, ctx, what, code) {
   return node.content;
 }
 
-// RFC 7292 §4.1 — a privacy-mode safe wraps a SafeContents, so the encrypted
+// RFC 7292 sec. 4.1 -- a privacy-mode safe wraps a SafeContents, so the encrypted
 // content's declared type must be id-data whichever CMS privacy structure
 // carries it, and the ciphertext must be attached: CMS permits a detached
-// EncryptedContentInfo, but here the ciphertext IS the safe's contents — a
+// EncryptedContentInfo, but here the ciphertext IS the safe's contents -- a
 // safe without it holds nothing a passphrase could ever recover.
 function _privacySafe(content, ctx) {
   if (content.encryptedContentInfo.contentType !== OID_DATA) {
     throw ctx.E("pkcs12/bad-safe-contentinfo-type",
-      "an encrypted safe must declare id-data (SafeContents) as its encrypted content type (RFC 7292 §4.1)");
+      "an encrypted safe must declare id-data (SafeContents) as its encrypted content type (RFC 7292 sec. 4.1)");
   }
-  if (content.encryptedContentInfo.encryptedContent === null) {
+  if (content.encryptedContentInfo.encryptedContent === null || content.encryptedContentInfo.encryptedContent.length === 0) {
     throw ctx.E("pkcs12/bad-safe-contentinfo",
-      "an encrypted safe must carry attached ciphertext — its encryptedContent is the SafeContents (RFC 7292 §4.1)");
+      "an encrypted safe must carry non-empty attached ciphertext -- its encryptedContent is the SafeContents (RFC 7292 sec. 4.1)");
   }
   return content;
 }
@@ -413,7 +426,7 @@ function _privacySafe(content, ctx) {
 function _bmpValue(bytes, ctx) {
   var node = asn1.decode(bytes, { ber: true });
   if (!(node.tagClass === "universal" && node.tagNumber === TAGS.BMP_STRING)) {
-    throw ctx.E("pkcs12/bad-friendly-name", "a friendlyName value must be a BMPString (RFC 7292 §4.2)");
+    throw ctx.E("pkcs12/bad-friendly-name", "a friendlyName value must be a BMPString (RFC 7292 sec. 4.2)");
   }
   return asn1.read.string(node);
 }
@@ -426,17 +439,17 @@ function _walkAuthenticatedSafe(bytes, state, ctx) {
   });
 }
 
-// Dispatch each AuthenticatedSafe element by contentType (§4.1): id-data
+// Dispatch each AuthenticatedSafe element by contentType (sec. 4.1): id-data
 // 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.
+// -- ciphertext stays opaque inside the CMS surface.
 function _dispatchSafes(asMatch, state, ctx) {
   var safeBags = [];
   var encryptedSafes = [];
   for (var i = 0; i < asMatch.items.length; i++) {
     var el = asMatch.items[i].value.result;
     if (el.contentType === OID_DATA) {
-      var contents = schema.embeddedDer(SAFE_CONTENTS, _octetContent(el.innerNode, ctx, "an id-data safe content"), ctx, {
+      var contents = schema.embeddedDer(SAFE_CONTENTS, _octetContent(el.innerNode, ctx, "an id-data safe content", "pkcs12/bad-safe-contentinfo"), ctx, {
         code: "pkcs12/bad-der", what: "a SafeContents", ber: true,
         budget: state.budget, budgetCode: "pkcs12/too-deep",
       });
@@ -448,14 +461,14 @@ function _dispatchSafes(asMatch, state, ctx) {
     } else if (el.contentType === OID_ENVELOPED_DATA) {
       encryptedSafes.push({ type: "envelopedData", content: _privacySafe(cms.walkEnvelopedData(el.innerNode), ctx) });
     } else {
-      throw ctx.E("pkcs12/bad-safe-contentinfo-type", "an AuthenticatedSafe element must be id-data, id-encryptedData, or id-envelopedData (RFC 7292 §4.1), got " +
+      throw ctx.E("pkcs12/bad-safe-contentinfo-type", "an AuthenticatedSafe element must be id-data, id-encryptedData, or id-envelopedData (RFC 7292 sec. 4.1), got " +
         (ctx.oid.name(el.contentType) || el.contentType));
     }
   }
   return { safeBags: safeBags, encryptedSafes: encryptedSafes };
 }
 
-// bagId dispatch (§4.2, Appendix D). The bag-type set is closed: an
+// bagId dispatch (sec. 4.2, Appendix D). The bag-type set is closed: an
 // unrecognized bagId rejects. Key material delegates to the exported PKCS#8
 // parsers; cert / CRL / secret values are surfaced raw.
 function _buildBag(rec, state, ctx) {
@@ -463,7 +476,7 @@ function _buildBag(rec, state, ctx) {
     type: null, bagId: rec.bagId,
     friendlyName: rec.friendlyName, localKeyId: rec.localKeyId, attributes: rec.attributes,
   };
-  // Key bags are walked from the DECODED node — their wire bytes may carry
+  // Key bags are walked from the DECODED node -- their wire bytes may carry
   // BER shapes the strict pkcs8 parse entry refuses, and the node already
   // exists (no re-decode).
   if (rec.bagId === OID_KEY_BAG) {
@@ -495,7 +508,7 @@ function _buildBag(rec, state, ctx) {
     return bag;
   }
   if (rec.bagId === OID_SAFE_CONTENTS_BAG) {
-    // §4.2.6 recursion — bounded independently of the codec depth cap so a
+    // sec. 4.2.6 recursion -- bounded independently of the codec depth cap so a
     // chain across re-decode boundaries cannot restart it.
     if (state.bagDepth + 1 > C.LIMITS.PKCS12_MAX_BAG_DEPTH) {
       throw ctx.E("pkcs12/too-deep", "safeContentsBag nesting exceeds the depth cap " + C.LIMITS.PKCS12_MAX_BAG_DEPTH);
@@ -509,7 +522,7 @@ function _buildBag(rec, state, ctx) {
     }
     return bag;
   }
-  throw ctx.E("pkcs12/bad-bag-type", (ctx.oid.name(rec.bagId) || rec.bagId) + " is not a recognized SafeBag bagId (RFC 7292 §4.2)");
+  throw ctx.E("pkcs12/bad-bag-type", (ctx.oid.name(rec.bagId) || rec.bagId) + " is not a recognized SafeBag bagId (RFC 7292 sec. 4.2)");
 }
 
 /**
@@ -524,29 +537,32 @@ function _buildBag(rec, state, ctx) {
  * Parse a DER / BER `Buffer` or a PEM string into a structured PFX:
  * `{ version, integrityMode, mac, macedBytes, authSafeSigned, safeBags,
  * encryptedSafes }`. `integrityMode` is `"password"` (id-data authSafe with
- * MacData — `mac` carries `{ kind, hashOid, hashName, hashParameters,
+ * MacData -- `mac` carries `{ kind, hashOid, hashName, hashParameters,
  * pbmac1, macValue, macSalt, iterations }`, where `kind` distinguishes the
  * RFC 9579 PBMAC1 arm; for PBMAC1 the required parameters are validated and
  * decoded onto `pbmac1` (`{ kdf: { salt, iterationCount, keyLength, prfOid,
  * prfName }, schemeOid, schemeName }`) with `hashParameters` keeping the raw
  * bytes, and `macedBytes` is the exact byte range the HMAC covers),
- * `"none"` (id-data authSafe without MacData — the shape
+ * `"none"` (id-data authSafe without MacData -- the shape
  * `openssl pkcs12 -export -nomac` emits; `mac` is `null` and the store
  * carries no integrity protection, a policy decision left to the caller),
- * or `"public-key"` (id-signedData authSafe — the CMS SignedData surfaced
+ * or `"public-key"` (id-signedData authSafe -- the CMS SignedData surfaced
  * on `authSafeSigned`, signature not verified here). Each of `safeBags` is
  * `{ type, bagId, friendlyName, localKeyId, attributes }` plus its arm:
  * a `keyBag` carries `key` (the PKCS#8 parse), a `pkcs8ShroudedKeyBag`
  * carries `encrypted` (algorithm surfaced, ciphertext opaque), `certBag` /
  * `crlBag` / `secretBag` carry their values raw and byte-exact, and a
  * `safeContentsBag` carries `nested` bags. Encrypted / enveloped safes are
- * surfaced structurally on `encryptedSafes` via the CMS module — recipient
+ * surfaced structurally on `encryptedSafes` via the CMS module -- recipient
  * infos and algorithms decoded, ciphertext never parsed. MAC verification
  * and bag decryption are passphrase operations for an external layer; the
  * inputs are surfaced exactly.
  *
  * Throws `Pkcs12Error` when the bytes are not a well-formed PFX, and
- * `Asn1Error` when the underlying encoding is malformed.
+ * `Asn1Error` when the underlying encoding is malformed. Faults inside a
+ * delegated CMS structure (a signedData authSafe, an encrypted / enveloped
+ * safe) surface as `CmsError` (`cms/*`) and inside a key bag as `Pkcs8Error`
+ * (`pkcs8/*`) -- all `PkiError` subclasses.
  *
  * @example
  *   var store = pki.schema.pkcs12.parse(der);
@@ -566,7 +582,7 @@ var parse = pkix.makeParser({
  * @related    pki.schema.pkcs12.parse
  *
  * Extract the DER bytes from a PEM block (default label `PKCS12`). A
- * `.p12` / `.pfx` file is almost always binary — the PEM path is a
+ * `.p12` / `.pfx` file is almost always binary -- the PEM path is a
  * convenience for stores that transit text channels.
  *
  * @example
@@ -590,8 +606,8 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "PKCS12",
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "PKCS12", PemError); }
 
 // A PFX root leads with a universal INTEGER (version), colliding with the
-// PKCS#8 detector on the first child — so the discriminators are children[1]
-// (a ContentInfo: SEQUENCE of exactly 2, OID first, [0] constructed second —
+// PKCS#8 detector on the first child -- so the discriminators are children[1]
+// (a ContentInfo: SEQUENCE of exactly 2, OID first, [0] constructed second --
 // a shape a PrivateKeyInfo's AlgorithmIdentifier never presents) and
 // children[2] (a SEQUENCE MacData or absent, never PKCS#8's OCTET STRING).
 function matches(root) {

package/lib/schema-pkcs8.js

@@ -9,25 +9,25 @@
  * @slug       pkcs8
  *
  * @intro
- *   PKCS#8 private-key handling per RFC 5208 §5 (PrivateKeyInfo) and RFC 5958 §2
+ *   PKCS#8 private-key handling per RFC 5208 sec. 5 (PrivateKeyInfo) and RFC 5958 sec. 2
  *   (OneAsymmetricKey). `parse` turns a DER or PEM (`PRIVATE KEY`) key into a
  *   structured object: version, the private-key algorithm identifier, the raw
- *   private-key bytes, the optional attributes, and — for a v2 OneAsymmetricKey —
+ *   private-key bytes, the optional attributes, and -- for a v2 OneAsymmetricKey --
  *   the optional public key. It composes the same schema engine and shared PKIX
  *   sub-schemas (AlgorithmIdentifier, Attribute) the other parsers use.
  *
  *   A PKCS#8 key is a container, not a signed structure: it has no signature, no
  *   distinguished name, and no to-be-signed region. The private-key OCTET STRING
- *   content is kept raw — the algorithm-specific inner key (an RSAPrivateKey, an
+ *   content is kept raw -- the algorithm-specific inner key (an RSAPrivateKey, an
  *   ECPrivateKey, a CurvePrivateKey) is decoded by the caller using the surfaced
  *   algorithm OID, so an unknown or future key type never fails the parse. An
- *   `ENCRYPTED PRIVATE KEY` (EncryptedPrivateKeyInfo, RFC 5958 §3) is recognized
+ *   `ENCRYPTED PRIVATE KEY` (EncryptedPrivateKeyInfo, RFC 5958 sec. 3) is recognized
  *   and surfaced with its encryption algorithm and raw ciphertext; decrypting it
  *   needs a passphrase and is out of scope for structural parsing.
  *
  * @card
  *   Parse DER / PEM PKCS#8 private keys (RFC 5208 / 5958) into structured,
- *   validated fields — algorithm, raw key bytes, attributes, optional public key,
+ *   validated fields -- algorithm, raw key bytes, attributes, optional public key,
  *   fail-closed. Encrypted keys are recognized, not decrypted.
  */
 
@@ -46,7 +46,7 @@ var NS = pkix.makeNS("pkcs8", Pkcs8Error, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var ATTRIBUTE = pkix.attribute(NS);
 
-// version ::= INTEGER { v1(0), v2(1) } — 0 and 1 are both LEGAL (the divergence
+// version ::= INTEGER { v1(0), v2(1) } -- 0 and 1 are both LEGAL (the divergence
 // from every other reader; cert/CRL reject 0, CSR accepts only 0). Surface as the
 // RFC's vN number.
 var PKCS8_VERSION = pkix.versionReader(NS, { "0": 1, "1": 2 });
@@ -69,7 +69,7 @@ var PRIVATE_KEY_INFO = schema.seq([
   build: function (m) {
     var version = m.fields.version.value;              // 1 (v1) | 2 (v2)
     var hasPublicKey = m.fields.publicKey.present;
-    // RFC 5958 §2 — publicKey present <=> version is v2. Enforce both directions.
+    // RFC 5958 sec. 2 -- publicKey present <=> version is v2. Enforce both directions.
     if (hasPublicKey && version !== 2) throw NS.E("pkcs8/bad-version", "a [1] publicKey is permitted only in a v2 OneAsymmetricKey");
     if (!hasPublicKey && version === 2) throw NS.E("pkcs8/bad-version", "a v2 OneAsymmetricKey must carry a [1] publicKey");
     return {
@@ -83,7 +83,7 @@ var PRIVATE_KEY_INFO = schema.seq([
 });
 
 // EncryptedPrivateKeyInfo ::= SEQUENCE { encryptionAlgorithm AlgorithmIdentifier,
-//   encryptedData OCTET STRING } (RFC 5958 §3). Recognized and surfaced; the raw
+//   encryptedData OCTET STRING } (RFC 5958 sec. 3). Recognized and surfaced; the raw
 // ciphertext is kept for a later decryption layer (PBES2/PBKDF2 + a passphrase).
 var ENCRYPTED_PRIVATE_KEY_INFO = schema.seq([
   schema.field("encryptionAlgorithm", ALGORITHM_IDENTIFIER),
@@ -172,7 +172,7 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "PRIVATE
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "PRIVATE KEY", PemError); }
 
 // A PKCS#8 PrivateKeyInfo root is a SEQUENCE whose first child is a universal
-// INTEGER (version) and third child a universal OCTET STRING (privateKey) — a
+// INTEGER (version) and third child a universal OCTET STRING (privateKey) -- a
 // shape the signed-envelope trio (whose children[0] is a SEQUENCE and children[2]
 // a BIT STRING) can never present, so the detectors are mutually exclusive
 // regardless of registry order. Trailing context fields are [0]/[1] in ascending
@@ -193,16 +193,16 @@ function matches(root) {
 }
 
 // NOTE: there is intentionally no `matchesEncrypted` detector. An
-// EncryptedPrivateKeyInfo is a SEQUENCE { SEQUENCE, OCTET STRING } — a shape it
+// EncryptedPrivateKeyInfo is a SEQUENCE { SEQUENCE, OCTET STRING } -- a shape it
 // shares with a PKCS#1 DigestInfo and other AlgorithmIdentifier-plus-octets
-// structures — so it cannot be classified from structure alone. The orchestrator
+// structures -- so it cannot be classified from structure alone. The orchestrator
 // does not auto-route it; an operator who knows a key is encrypted (e.g. from an
 // 'ENCRYPTED PRIVATE KEY' PEM label) calls parseEncrypted directly. A structural
 // auto-route can return once a validated encryption-algorithm discriminator (the
 // PBES layer) exists.
 
 // Validate a bare, already-decoded PrivateKeyInfo / EncryptedPrivateKeyInfo
-// node — for a composer that holds a decoded node and must not re-parse its
+// node -- for a composer that holds a decoded node and must not re-parse its
 // bytes (an RFC 7292 PFX key bag, whose wire encoding may be BER that the
 // strict `parse` entry would refuse). Same contract as the CMS walkers: the
 // node is the bare structure, typed pkcs8/* on rejection.