@blamejs/pki 0.1.22 → 0.1.23

package/lib/schema-crmf.js

@@ -10,7 +10,7 @@
  *
  * @intro
  *   Certificate Request Message Format handling per RFC 4211. `parse` decodes a
- *   `CertReqMessages` — the request body CMP and EST enrollment carry — into an
+ *   `CertReqMessages` -- the request body CMP and EST enrollment carry -- into an
  *   array of messages, each with its `CertRequest` (certReqId, a `CertTemplate`
  *   of the requested certificate fields, and any registration controls), an
  *   optional proof-of-possession, and optional registration info.
@@ -21,7 +21,7 @@
  *   X.680 forces EXPLICIT: `issuer [3]` / `subject [5]` are `Name`, dual-accepted
  *   here (the standards-compliant EXPLICIT encoding and the dominant IMPLICIT one
  *   real tooling emits); and the `OptionalValidity` times are EXPLICIT. version,
- *   when supplied, MUST be 2 (RFC 4211 §5); certReqId is an unbounded signed
+ *   when supplied, MUST be 2 (RFC 4211 sec. 5); certReqId is an unbounded signed
  *   INTEGER (the RFC 9483 `-1` sentinel is legal). The `CertRequest` byte range
  *   the proof-of-possession signature covers, and each `poposkInput`, are surfaced
  *   RAW for a downstream verifier; registration controls / info values and the
@@ -30,7 +30,7 @@
  *
  * @card
  *   Parse DER / PEM RFC 4211 CertReqMessages into requested-certificate templates,
- *   proof-of-possession, and registration controls — dual-accepted names, raw
+ *   proof-of-possession, and registration controls -- dual-accepted names, raw
  *   verifier inputs, fail-closed.
  */
 
@@ -49,8 +49,8 @@ var NS = pkix.makeNS("crmf", CrmfError, oid);
 var TAGS = asn1.TAGS;
 
 // ---- dual-accept Name (issuer [3] / subject [5]) ---------------------
-// RFC 4211 Appendix B is IMPLICIT TAGS, but Name is a CHOICE so X.680 §31.2.7
-// forces EXPLICIT tagging — the standards-compliant wire is a context [tag]
+// RFC 4211 Appendix B is IMPLICIT TAGS, but Name is a CHOICE so X.680 sec. 31.2.7
+// forces EXPLICIT tagging -- the standards-compliant wire is a context [tag]
 // EXPLICIT wrapper around a universal RDNSequence. The dominant tooling
 // (pyasn1-modules, BouncyCastle) instead encodes IMPLICIT (the [tag] REPLACES the
 // RDNSequence 0x30, so the children ARE the RDN SETs). Both occur in real CMP /
@@ -62,7 +62,7 @@ function crmfName(tag) {
   var INAME = pkix.name(NS, { implicitTag: tag });   // IMPLICIT arm: [tag] children ARE the RDN SETs
   return schema.decode(function (n, ctx) {
     if (n.tagClass !== "context" || n.tagNumber !== tag || !n.children) {
-      throw ctx.E("crmf/bad-name", "issuer/subject [" + tag + "] must be a Name (RFC 4211 §5)");
+      throw ctx.E("crmf/bad-name", "issuer/subject [" + tag + "] must be a Name (RFC 4211 sec. 5)");
     }
     if (n.children.length === 0) return schema.walk(INAME, n, ctx).result; // IMPLICIT empty RDNSequence
     var c0 = n.children[0];
@@ -80,11 +80,11 @@ function crmfName(tag) {
   });
 }
 
-// ---- OptionalValidity (§5) -------------------------------------------
+// ---- OptionalValidity (sec. 5) -------------------------------------------
 // validity [4] IMPLICIT SEQUENCE { notBefore [0] Time OPTIONAL, notAfter [1] Time
 // OPTIONAL }. Time is a CHOICE of UTCTime / GeneralizedTime, so [0]/[1] are
 // EXPLICIT (an IMPLICIT tag would erase the UTCTime-vs-GeneralizedTime
-// discriminator). RFC 4211 §5 requires at least one of the two to be present.
+// discriminator). RFC 4211 sec. 5 requires at least one of the two to be present.
 var OPTIONAL_VALIDITY = schema.seq([
   schema.trailing([
     { tag: 0, name: "notBefore", schema: schema.time(NS), explicit: true, emptyCode: "crmf/bad-validity" },
@@ -95,14 +95,14 @@ var OPTIONAL_VALIDITY = schema.seq([
   build: function (m, ctx) {
     var f = m.fields;
     if (!f.notBefore.present && !f.notAfter.present) {
-      throw ctx.E("crmf/bad-validity", "OptionalValidity must contain notBefore or notAfter (RFC 4211 §5)");
+      throw ctx.E("crmf/bad-validity", "OptionalValidity must contain notBefore or notAfter (RFC 4211 sec. 5)");
     }
     return { notBefore: f.notBefore.present ? f.notBefore.value : null, notAfter: f.notAfter.present ? f.notAfter.value : null };
   },
 });
 
-// ---- ProofOfPossession (§4) ------------------------------------------
-// raVerified [0] NULL — the RA has already verified POP out of band.
+// ---- ProofOfPossession (sec. 4) ------------------------------------------
+// raVerified [0] NULL -- the RA has already verified POP out of band.
 var POPO_RAVERIFIED = schema.decode(function (n, ctx) {
   try { asn1.read.nullImplicit(n, 0); }
   catch (e) { throw ctx.E("crmf/bad-popo", "raVerified [0] must be an IMPLICIT NULL", e); }
@@ -110,7 +110,7 @@ var POPO_RAVERIFIED = schema.decode(function (n, ctx) {
 });
 
 // When poposkInput is present the POP signature is over the DER of the
-// POPOSigningKeyInput VALUE (RFC 4211 §4.1), which is a SEQUENCE — but on the wire
+// POPOSigningKeyInput VALUE (RFC 4211 sec. 4.1), which is a SEQUENCE -- but on the wire
 // poposkInput is an IMPLICIT [0] field, so its bytes lead with the context tag
 // (0xA0) rather than the SEQUENCE tag a verifier hashes. `asn1.sequenceTlv` recovers
 // the SEQUENCE-tagged signed region from the field's content; `signedBytes` is that
@@ -118,17 +118,31 @@ var POPO_RAVERIFIED = schema.decode(function (n, ctx) {
 // encoding its peer produced.
 
 // POPOSigningKeyInput ::= SEQUENCE { authInfo CHOICE { sender [0] GeneralName,
-// publicKeyMAC PKMACValue }, publicKey SubjectPublicKeyInfo } (§4.1). Structurally
+// publicKeyMAC PKMACValue }, publicKey SubjectPublicKeyInfo } (sec. 4.1). Structurally
 // validated (not deferred raw), so an empty or malformed poposkInput fails closed
 // rather than surfacing a signed region that was never a well-formed POP input.
-// PKMACValue ::= SEQUENCE { algId AlgorithmIdentifier, value BIT STRING }.
+// PKMACValue ::= SEQUENCE { algId AlgorithmIdentifier, value BIT STRING }. The
+// MAC value is octet-string algorithm output handed to an external verifier;
+// with no in-tree POP verify layer, octet alignment is enforced at parse.
 var PKMAC_VALUE = schema.seq([
   schema.field("algId", pkix.algorithmIdentifier(NS)),
   schema.field("value", schema.bitString()),
-], { assert: "sequence", arity: { exact: 2 }, code: "crmf/bad-popo", what: "PKMACValue" });
+], {
+  assert: "sequence", arity: { exact: 2 }, code: "crmf/bad-popo", what: "PKMACValue",
+  build: function (m, ctx) {
+    // The parsed BIT STRING structure { unusedBits, bytes } -- a structural
+    // octet-alignment check on the unused-bit COUNT, not a comparison of the
+    // MAC secret (there is no in-tree POP verify), so no timing oracle exists.
+    var macBitString = m.fields.value.value;
+    if (macBitString.unusedBits !== 0) {
+      throw ctx.E("crmf/bad-popo", "a PKMACValue MAC BIT STRING must be octet-aligned (0 unused bits)");
+    }
+    return { algId: m.fields.algId.value.result, value: { unusedBits: macBitString.unusedBits, bytes: macBitString.bytes } };
+  },
+});
 
 // authInfo CHOICE: sender [0] GeneralName is EXPLICIT (GeneralName is itself a
-// CHOICE); publicKeyMAC is a bare PKMACValue SEQUENCE — disjoint by tag class.
+// CHOICE); publicKeyMAC is a bare PKMACValue SEQUENCE -- disjoint by tag class.
 var POPOSK_AUTH_INFO = schema.choice([
   { when: { tagClass: "context", tagNumber: 0 }, schema: schema.explicit(0, pkix.generalName(NS, { code: "crmf/bad-popo" }), { code: "crmf/bad-popo" }) },
   { when: { tagClass: "universal", tagNumber: TAGS.SEQUENCE }, schema: PKMAC_VALUE },
@@ -140,11 +154,11 @@ var POPOSK_INPUT = schema.seq([
 ], { assert: "implicit", implicitTag: 0, arity: { exact: 2 }, code: "crmf/bad-popo", what: "POPOSigningKeyInput" });
 
 // POPOSigningKey ::= SEQUENCE { poposkInput [0] POPOSigningKeyInput OPTIONAL,
-// algorithmIdentifier AlgorithmIdentifier, signature BIT STRING } — IMPLICIT [1].
+// algorithmIdentifier AlgorithmIdentifier, signature BIT STRING } -- IMPLICIT [1].
 var POPO_SIGNING_KEY = schema.seq([
   schema.optional("poposkInput", schema.decode(function (n, ctx) {
     // Validate the full POPOSigningKeyInput structure fail-closed, then surface the
-    // raw [0] node plus its decoded publicKey (for the §4.1 template-match check).
+    // raw [0] node plus its decoded publicKey (for the sec. 4.1 template-match check).
     var m = schema.walk(POPOSK_INPUT, n, ctx);
     return { node: n, publicKey: m.fields.publicKey.value.result.bytes };
   }), { tag: 0 }),
@@ -152,91 +166,99 @@ var POPO_SIGNING_KEY = schema.seq([
   schema.field("signature", schema.bitString()),
 ], {
   assert: "implicit", implicitTag: 1, code: "crmf/bad-popo", what: "POPOSigningKey",
-  build: function (m) {
+  build: function (m, ctx) {
     var pin = m.fields.poposkInput;
+    var sig = m.fields.signature.value;
+    // The POP signature is octet-string algorithm output an external verifier
+    // consumes; with no in-tree POP verify layer, octet alignment is enforced
+    // at parse (RFC 4211 sec. 4.1).
+    if (sig.unusedBits !== 0) {
+      throw ctx.E("crmf/bad-popo", "a POPOSigningKey signature BIT STRING must be octet-aligned (0 unused bits)");
+    }
     return {
       type: "signature",
       poposkInput: pin.present ? { bytes: pin.node.bytes, signedBytes: asn1.sequenceTlv(pin.node), publicKey: pin.value.publicKey } : null,
       algorithmIdentifier: m.fields.algorithmIdentifier.value.result,
-      signature: { unusedBits: m.fields.signature.value.unusedBits, bytes: m.fields.signature.value.bytes },
+      signature: { unusedBits: sig.unusedBits, bytes: sig.bytes },
     };
   },
 });
 
-// keyEncipherment [2] / keyAgreement [3] POPOPrivKey (§4). POPOPrivKey is a
+// keyEncipherment [2] / keyAgreement [3] POPOPrivKey (sec. 4). POPOPrivKey is a
 // 5-arm CHOICE { thisMessage [0], subsequentMessage [1], dhMAC [2], agreeMAC [3],
-// encryptedKey [4] }, so X.680 §31.2.7 forces the outer [2]/[3] tag to be EXPLICIT
-// (a CHOICE has no single tag to replace). Validate that shell — a constructed
-// wrapper around exactly one inner context [0]..[4] alternative — before surfacing
+// encryptedKey [4] }, so X.680 sec. 31.2.7 forces the outer [2]/[3] tag to be EXPLICIT
+// (a CHOICE has no single tag to replace). Validate that shell -- a constructed
+// wrapper around exactly one inner context [0]..[4] alternative -- before surfacing
 // the arm RAW, so a primitive / empty / mis-tagged node is rejected rather than
 // reported to a verifier as a well-formed POP. The inner alternative's own value
 // (incl. the encryptedKey [4] EnvelopedData) stays deferred to the verify layer.
 // POPOPrivKey ::= CHOICE { thisMessage [0] BIT STRING (deprecated), subsequentMessage
 // [1] SubsequentMessage, dhMAC [2] BIT STRING (deprecated), agreeMAC [3] PKMACValue,
-// encryptedKey [4] EnvelopedData } (RFC 4211 §4.2). The deprecated arms are still
+// encryptedKey [4] EnvelopedData } (RFC 4211 sec. 4.2). The deprecated arms are still
 // parsed. The inner VALUE stays deferred raw (the EnvelopedData / MAC decode is a
 // verify-layer concern), but the alternative's shape is validated fail-closed.
 var POPOPRIVKEY_METHODS = { 0: "thisMessage", 1: "subsequentMessage", 2: "dhMAC", 3: "agreeMAC", 4: "encryptedKey" };
 function popoPrivKey(type) {
   return schema.decode(function (n, ctx) {
     if (!n.children || n.children.length !== 1) {
-      throw ctx.E("crmf/bad-popo", type + " [" + n.tagNumber + "] POPOPrivKey must be an EXPLICIT wrapper around one alternative (RFC 4211 §4)");
+      throw ctx.E("crmf/bad-popo", type + " [" + n.tagNumber + "] POPOPrivKey must be an EXPLICIT wrapper around one alternative (RFC 4211 sec. 4)");
     }
     var inner = n.children[0];
     if (inner.tagClass !== "context" || inner.tagNumber < 0 || inner.tagNumber > 4) {
-      throw ctx.E("crmf/bad-popo", type + " POPOPrivKey alternative must be a context [0]..[4] CHOICE element (RFC 4211 §4)");
+      throw ctx.E("crmf/bad-popo", type + " POPOPrivKey alternative must be a context [0]..[4] CHOICE element (RFC 4211 sec. 4)");
     }
-    // RFC 4211 §4.2/§4.3 — the MAC alternatives dhMAC [2] / agreeMAC [3] are the
+    // RFC 4211 sec. 4.2/sec. 4.3 -- the MAC alternatives dhMAC [2] / agreeMAC [3] are the
     // key-agreement "fourth method"; key-encipherment POP uses only the
     // thisMessage / subsequentMessage / encryptedKey methods, so a MAC arm under
     // keyEncipherment is non-conforming.
     if (type === "keyEncipherment" && (inner.tagNumber === 2 || inner.tagNumber === 3)) {
-      throw ctx.E("crmf/bad-popo", "keyEncipherment POP cannot use the MAC alternative " + POPOPRIVKEY_METHODS[inner.tagNumber] + " (RFC 4211 §4.2)");
+      throw ctx.E("crmf/bad-popo", "keyEncipherment POP cannot use the MAC alternative " + POPOPRIVKEY_METHODS[inner.tagNumber] + " (RFC 4211 sec. 4.2)");
     }
     // FORM: thisMessage [0] / subsequentMessage [1] / dhMAC [2] are primitive (BIT
     // STRING / INTEGER / BIT STRING); agreeMAC [3] PKMACValue and encryptedKey [4]
     // EnvelopedData are constructed (SEQUENCE). A wrong-form node is malformed.
     var mustBeConstructed = inner.tagNumber === 3 || inner.tagNumber === 4;
     if (mustBeConstructed !== !!inner.children) {
-      throw ctx.E("crmf/bad-popo", type + " POPOPrivKey [" + inner.tagNumber + "] has the wrong primitive/constructed form (RFC 4211 §4)");
+      throw ctx.E("crmf/bad-popo", type + " POPOPrivKey [" + inner.tagNumber + "] has the wrong primitive/constructed form (RFC 4211 sec. 4)");
     }
     // Each alternative's PAYLOAD is decoded fail-closed, not just its form:
     // thisMessage [0] / dhMAC [2] are BIT STRINGs; subsequentMessage [1] an INTEGER
     // in {0,1}; agreeMAC [3] a PKMACValue SEQUENCE; encryptedKey [4] an EnvelopedData.
     if (inner.tagNumber === 0 || inner.tagNumber === 2) {
       try { asn1.read.bitStringImplicit(inner, inner.tagNumber); }
-      catch (e) { throw ctx.E("crmf/bad-popo", POPOPRIVKEY_METHODS[inner.tagNumber] + " [" + inner.tagNumber + "] must be a BIT STRING (RFC 4211 §4.2)", e); }
+      catch (e) { throw ctx.E("crmf/bad-popo", POPOPRIVKEY_METHODS[inner.tagNumber] + " [" + inner.tagNumber + "] must be a BIT STRING (RFC 4211 sec. 4.2)", e); }
     }
     if (inner.tagNumber === 1) {
       var v;
       try { v = asn1.read.integerImplicit(inner, 1); }
       catch (e) { throw ctx.E("crmf/bad-popo", "subsequentMessage must be an INTEGER", e); }
       if (v !== 0n && v !== 1n) {
-        throw ctx.E("crmf/bad-popo", "SubsequentMessage must be encrCert(0) or challengeResp(1) (RFC 4211 §4.2)");
+        throw ctx.E("crmf/bad-popo", "SubsequentMessage must be encrCert(0) or challengeResp(1) (RFC 4211 sec. 4.2)");
       }
     }
     if (inner.tagNumber === 3) {
       try { schema.embeddedDer(PKMAC_VALUE, asn1.sequenceTlv(inner), NS, { code: "crmf/bad-popo", what: "agreeMAC [3] PKMACValue" }); }
-      catch (e) { throw ctx.E("crmf/bad-popo", "agreeMAC [3] must be a PKMACValue SEQUENCE { algId, BIT STRING } (RFC 4211 §4.2)", e); }
+      catch (e) { throw ctx.E("crmf/bad-popo", "agreeMAC [3] must be a PKMACValue SEQUENCE { algId, BIT STRING } (RFC 4211 sec. 4.2)", e); }
     }
-    // encryptedKey [4] EnvelopedData — validate the CMS structure fail-closed by
+    // encryptedKey [4] EnvelopedData -- validate the CMS structure fail-closed by
     // composing the shared EnvelopedData decoder (retag the IMPLICIT [4] to the
     // universal SEQUENCE it decodes as). The EncKeyWithID identity check lives inside
     // the ENCRYPTED content, so it stays a verify-layer concern.
     if (inner.tagNumber === 4) {
       var env;
       try { env = cms.walkEnvelopedData(asn1.decode(asn1.sequenceTlv(inner))); }
-      catch (e) { throw ctx.E("crmf/bad-popo", "encryptedKey [4] must be a well-formed EnvelopedData (RFC 4211 §4.2, RFC 5652 §6.1)", e); }
-      // RFC 4211 §4.2 — the enveloped content type MUST be id-ct-encKeyWithID (the
+      catch (e) { throw ctx.E("crmf/bad-popo", "encryptedKey [4] must be a well-formed EnvelopedData (RFC 4211 sec. 4.2, RFC 5652 sec. 6.1)", e); }
+      // RFC 4211 sec. 4.2 -- the enveloped content type MUST be id-ct-encKeyWithID (the
       // ContentType OID is in the clear even though the content itself is encrypted).
       if (env.encryptedContentInfo.contentType !== oid.byName("encKeyWithID")) {
-        throw ctx.E("crmf/bad-popo", "encryptedKey [4] EnvelopedData content type MUST be id-ct-encKeyWithID (RFC 4211 §4.2)");
+        throw ctx.E("crmf/bad-popo", "encryptedKey [4] EnvelopedData content type MUST be id-ct-encKeyWithID (RFC 4211 sec. 4.2)");
       }
-      // The encrypted key material MUST be present — CMS allows a detached
+      // The encrypted key material MUST be present -- CMS allows a detached
       // EnvelopedData (encryptedContent OPTIONAL), but a POP with no key to verify
-      // or archive is meaningless.
-      if (env.encryptedContentInfo.encryptedContent == null) {
-        throw ctx.E("crmf/bad-popo", "encryptedKey [4] EnvelopedData MUST carry the encrypted key in encryptedContent (RFC 4211 §4.2)");
+      // or archive is meaningless. A zero-length attached ciphertext is the same
+      // fault as a detached one (the rule the CMP encryptedKey arm also holds).
+      if (env.encryptedContentInfo.encryptedContent == null || env.encryptedContentInfo.encryptedContent.length === 0) {
+        throw ctx.E("crmf/bad-popo", "encryptedKey [4] EnvelopedData MUST carry a non-empty encrypted key in encryptedContent (RFC 4211 sec. 4.2)");
       }
     }
     return { type: type, method: POPOPRIVKEY_METHODS[inner.tagNumber], bytes: n.bytes };
@@ -253,7 +275,7 @@ var PROOF_OF_POSSESSION = schema.choice([
   { when: { tagClass: "context", tagNumber: 3 }, schema: popoPrivKey("keyAgreement") },
 ], { code: "crmf/bad-popo" });
 
-// ---- Controls / regInfo (§5, §6, §7) ---------------------------------
+// ---- Controls / regInfo (sec. 5, sec. 6, sec. 7) ---------------------------------
 // AttributeTypeAndValue ::= SEQUENCE { type OBJECT IDENTIFIER, value ANY DEFINED BY
 // type }. The list is decoded; each value stays RAW (the per-OID value semantics
 // are deferred). Shared shape for both controls and regInfo.
@@ -268,15 +290,15 @@ var CONTROL = schema.seq([
   },
 });
 function mapControls(m) { return m.items.map(function (it) { return it.value.result; }); }
-// Controls ::= SEQUENCE SIZE(1..MAX) OF AttributeTypeAndValue (§5).
+// Controls ::= SEQUENCE SIZE(1..MAX) OF AttributeTypeAndValue (sec. 5).
 var CONTROLS = schema.seqOf(CONTROL, { assert: "sequence", min: 1, code: "crmf/bad-controls", what: "Controls", build: mapControls });
-// regInfo ::= SEQUENCE SIZE(1..MAX) OF AttributeTypeAndValue (§7).
+// regInfo ::= SEQUENCE SIZE(1..MAX) OF AttributeTypeAndValue (sec. 7).
 var REG_INFO = schema.seqOf(CONTROL, { assert: "sequence", min: 1, code: "crmf/bad-reg-info", what: "regInfo", build: mapControls });
 
-// ---- CertTemplate (§5) — the IMPLICIT-TAGS core ----------------------
+// ---- CertTemplate (sec. 5) -- the IMPLICIT-TAGS core ----------------------
 // CertTemplate ::= SEQUENCE { version [0], serialNumber [1], signingAlg [2],
 // issuer [3] Name, validity [4] OptionalValidity, subject [5] Name, publicKey [6]
-// SubjectPublicKeyInfo, issuerUID [7], subjectUID [8], extensions [9] } — every
+// SubjectPublicKeyInfo, issuerUID [7], subjectUID [8], extensions [9] } -- every
 // field IMPLICIT and OPTIONAL, so the whole body is one ascending [0..9] trailing
 // run. issuer/subject Name and the [4] validity times are the CHOICE exceptions.
 var CERT_TEMPLATE = schema.seq([
@@ -296,15 +318,20 @@ var CERT_TEMPLATE = schema.seq([
   assert: "sequence", code: "crmf/bad-cert-template", what: "CertTemplate",
   build: function (m, ctx) {
     var f = m.fields;
-    // version MUST be 2 (v3) when supplied; SHOULD be omitted (RFC 4211 §5). This
+    // version MUST be 2 (v3) when supplied; SHOULD be omitted (RFC 4211 sec. 5). This
     // is a structural CertTemplate rule (it holds wherever the template appears);
     // the CA-assigned-field omission rule is REQUEST-context-specific and lives in
     // CERT_REQUEST.build, because the same CertTemplate structure identifies an
-    // existing certificate — serialNumber and issuer present — inside a CMP
-    // RevDetails (RFC 9810 §5.3.9). Every field is surfaced so both the request
+    // existing certificate -- serialNumber and issuer present -- inside a CMP
+    // RevDetails (RFC 9810 sec. 5.3.9). Every field is surfaced so both the request
     // omission check and the revocation consumer read them off one result.
-    if (f.version.present && f.version.value !== 2n) {
-      throw ctx.E("crmf/bad-version", "CertTemplate version MUST be 2 (v3) if supplied (RFC 4211 §5)");
+    // The ONE profile override: RFC 9810 Appendix D.6 profiles the CMP
+    // cross-certification (ccr) template as "version v1 or v3", so the caller
+    // opts in to v1 (0) via ctx.allowV1Version -- the same base-section-vs-
+    // profile-appendix override mechanism as the signingAlg relaxation below.
+    if (f.version.present && f.version.value !== 2n &&
+        !(ctx.allowV1Version && f.version.value === 0n)) {
+      throw ctx.E("crmf/bad-version", "CertTemplate version MUST be 2 (v3) if supplied (RFC 4211 sec. 5)");
     }
     return {
       version:     f.version.present ? f.version.value : null,
@@ -321,10 +348,10 @@ var CERT_TEMPLATE = schema.seq([
   },
 });
 
-// ---- CertRequest / CertReqMsg / CertReqMessages (§3, §5) --------------
+// ---- CertRequest / CertReqMsg / CertReqMessages (sec. 3, sec. 5) --------------
 // CertRequest ::= SEQUENCE { certReqId INTEGER, certTemplate CertTemplate,
 // controls Controls OPTIONAL }. certReqId is a SIGNED INTEGER with no value
-// constraint — a negative value (the RFC 9483 -1 sentinel) is legal.
+// constraint -- a negative value (the RFC 9483 -1 sentinel) is legal.
 var CERT_REQUEST = schema.seq([
   schema.field("certReqId", schema.integerLeaf()),
   schema.field("certTemplate", CERT_TEMPLATE),
@@ -333,7 +360,7 @@ var CERT_REQUEST = schema.seq([
   assert: "sequence", code: "crmf/bad-cert-request", what: "CertRequest",
   build: function (m, ctx) {
     var tpl = m.fields.certTemplate.value.result;
-    // RFC 4211 §5 — serialNumber, signingAlg, issuerUID, and subjectUID MUST be
+    // RFC 4211 sec. 5 -- serialNumber, signingAlg, issuerUID, and subjectUID MUST be
     // omitted from a REQUEST's CertTemplate: serialNumber and signingAlg are
     // assigned by the CA, and the UID pair is deprecated. A requester must not
     // dictate a CA-assigned value (a requester-chosen serialNumber is a real
@@ -350,7 +377,7 @@ var CERT_REQUEST = schema.seq([
       : ["serialNumber", "signingAlg", "issuerUID", "subjectUID"];
     for (var i = 0; i < caAssigned.length; i++) {
       if (tpl[caAssigned[i]] !== null) {
-        throw ctx.E("crmf/bad-cert-template", "CertTemplate " + caAssigned[i] + " MUST be omitted — it is CA-assigned or deprecated (RFC 4211 §5)");
+        throw ctx.E("crmf/bad-cert-template", "CertTemplate " + caAssigned[i] + " MUST be omitted -- it is CA-assigned or deprecated (RFC 4211 sec. 5)");
       }
     }
     return {
@@ -358,7 +385,7 @@ var CERT_REQUEST = schema.seq([
       certReqIdHex:  m.fields.certReqId.node.content.toString("hex"),
       certTemplate:  tpl,
       controls:      m.fields.controls.present ? m.fields.controls.value.result : null,
-      certReqBytes:  m.node.bytes,   // the exact CertRequest TLV the POP signature covers (§4.1)
+      certReqBytes:  m.node.bytes,   // the exact CertRequest TLV the POP signature covers (sec. 4.1)
     };
   },
 });
@@ -377,33 +404,33 @@ var CERT_REQ_MSG = schema.seq([
     var certReq = m.fields.certReq.value.result;
     var popo = m.fields.popo.present ? m.fields.popo.value : null;
     // A POP whose signature/MAC covers the certReq requires the CertTemplate to
-    // contain both subject and publicKey — otherwise there is no complete request
+    // contain both subject and publicKey -- otherwise there is no complete request
     // to sign / MAC over, and a verifier would be bound to the wrong identity/key.
     var complete = certReq.certTemplate.subject !== null && certReq.certTemplate.publicKey !== null;
-    // RFC 4211 §4.1 — for a signature POP, poposkInput's presence is fixed by the
+    // RFC 4211 sec. 4.1 -- for a signature POP, poposkInput's presence is fixed by the
     // CertTemplate: it MUST be omitted when the template carries BOTH subject and
     // publicKey (the signature is then over the DER of the CertRequest), and MUST be
     // present otherwise.
     if (popo && popo.type === "signature") {
       if (complete && popo.poposkInput !== null) {
-        throw ctx.E("crmf/bad-popo", "poposkInput MUST be omitted when the CertTemplate contains both subject and publicKey (RFC 4211 §4.1)");
+        throw ctx.E("crmf/bad-popo", "poposkInput MUST be omitted when the CertTemplate contains both subject and publicKey (RFC 4211 sec. 4.1)");
       }
       if (!complete && popo.poposkInput === null) {
-        throw ctx.E("crmf/bad-popo", "poposkInput MUST be present when the CertTemplate lacks subject or publicKey (RFC 4211 §4.1)");
+        throw ctx.E("crmf/bad-popo", "poposkInput MUST be present when the CertTemplate lacks subject or publicKey (RFC 4211 sec. 4.1)");
       }
-      // RFC 4211 §4.1 — the POPOSigningKeyInput publicKey MUST be exactly the template
+      // RFC 4211 sec. 4.1 -- the POPOSigningKeyInput publicKey MUST be exactly the template
       // publicKey (both surfaced as canonical SubjectPublicKeyInfo DER), so a request
       // cannot sign one key while asking for a certificate over a different key.
       if (popo.poposkInput !== null && certReq.certTemplate.publicKey !== null &&
           !popo.poposkInput.publicKey.equals(certReq.certTemplate.publicKey.bytes)) {
-        throw ctx.E("crmf/bad-popo", "POPOSigningKeyInput publicKey MUST equal the CertTemplate publicKey (RFC 4211 §4.1)");
+        throw ctx.E("crmf/bad-popo", "POPOSigningKeyInput publicKey MUST equal the CertTemplate publicKey (RFC 4211 sec. 4.1)");
       }
     }
-    // RFC 4211 §4.2/§4.3 — a MAC-based POPOPrivKey (dhMAC / agreeMAC) proves
+    // RFC 4211 sec. 4.2/sec. 4.3 -- a MAC-based POPOPrivKey (dhMAC / agreeMAC) proves
     // possession by MACing the certReq, which MUST include both subject and publicKey.
     if (popo && (popo.type === "keyEncipherment" || popo.type === "keyAgreement") &&
         (popo.method === "dhMAC" || popo.method === "agreeMAC") && !complete) {
-      throw ctx.E("crmf/bad-popo", "a MAC-based key-agreement/encipherment POP (dhMAC/agreeMAC) requires the CertTemplate to contain both subject and publicKey (RFC 4211 §4.2/§4.3)");
+      throw ctx.E("crmf/bad-popo", "a MAC-based key-agreement/encipherment POP (dhMAC/agreeMAC) requires the CertTemplate to contain both subject and publicKey (RFC 4211 sec. 4.2/sec. 4.3)");
     }
     return {
       certReq: certReq,
@@ -413,8 +440,10 @@ var CERT_REQ_MSG = schema.seq([
   },
 });
 
-// CertReqMessages ::= SEQUENCE SIZE(1..MAX) OF CertReqMsg (§3) — an empty sequence
-// is malformed.
+// CertReqMessages ::= SEQUENCE SIZE(1..MAX) OF CertReqMsg (sec. 3) -- an empty sequence
+// is malformed. The top-level reject code predates the
+// `<prefix>/not-a-<structure>` convention and stays frozen on the public
+// error-code surface.
 var CERT_REQ_MESSAGES = schema.seqOf(CERT_REQ_MSG, {
   assert: "sequence", min: 1, code: "crmf/bad-cert-req-messages", what: "CertReqMessages",
   build: function (m) { return { messages: m.items.map(function (it) { return it.value.result; }) }; },
@@ -434,17 +463,20 @@ var CERT_REQ_MESSAGES = schema.seqOf(CERT_REQ_MSG, {
  * `{ messages: [ { certReq, popo, regInfo } ] }`. Each `certReq` is
  * `{ certReqId, certReqIdHex, certTemplate, controls, certReqBytes }`, and
  * `certTemplate` carries the requestable certificate fields (`version`, `issuer`,
- * `validity`, `subject`, `publicKey`, `extensions` — each `null` when absent). The
- * CA-assigned / deprecated fields RFC 4211 §5 requires a request to omit
+ * `validity`, `subject`, `publicKey`, `extensions` -- each `null` when absent). The
+ * CA-assigned / deprecated fields RFC 4211 sec. 5 requires a request to omit
  * (`serialNumber`, `signingAlg`, `issuerUID`, `subjectUID`) are rejected, not
  * surfaced. `popo` is
  * `null`, `{ type: "raVerified" }`, `{ type: "signature", poposkInput,
  * algorithmIdentifier, signature }`, or `{ type: "keyEncipherment" |
- * "keyAgreement", method, bytes }` (where `method` is the POPOPrivKey alternative —
- * `thisMessage` / `subsequentMessage` / `dhMAC` / `agreeMAC` / `encryptedKey` — each
- * structurally validated, the `encryptedKey` EnvelopedData included). When present, `poposkInput` is `{ bytes, signedBytes }`
- * — `bytes` is the raw wire `[0]` TLV and `signedBytes` is the `POPOSigningKeyInput`
- * re-tagged to the `SEQUENCE` DER the signature actually covers (RFC 4211 §4.1).
+ * "keyAgreement", method, bytes }` (where `method` is the POPOPrivKey alternative --
+ * `thisMessage` / `subsequentMessage` / `dhMAC` / `agreeMAC` / `encryptedKey` -- each
+ * structurally validated, the `encryptedKey` EnvelopedData included). When present, `poposkInput` is
+ * `{ bytes, signedBytes, publicKey }` -- `bytes` is the raw wire `[0]` TLV,
+ * `signedBytes` is the `POPOSigningKeyInput` re-tagged to the `SEQUENCE` DER the
+ * signature actually covers, and `publicKey` is the canonical
+ * `SubjectPublicKeyInfo` DER the RFC 4211 sec. 4.1 template-match check compares
+ * against the `CertTemplate` publicKey (a POP verifier imports it directly).
  * `certReqBytes` is the exact `CertRequest` byte range a proof-of-possession
  * verifier hashes when `poposkInput` is absent.
  *
@@ -469,7 +501,7 @@ var parse = pkix.makeParser({
  * @related    pki.schema.crmf.parse
  *
  * Extract the DER bytes from a PEM block (RFC 4211 registers no RFC 7468 label, so
- * the first block is taken unless `label` is given — CRMF rides inside CMP / EST as
+ * the first block is taken unless `label` is given -- CRMF rides inside CMP / EST as
  * DER in practice). Throws `PemError` on a missing envelope or a non-base64 body.
  *
  * @example
@@ -477,6 +509,23 @@ var parse = pkix.makeParser({
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || null, PemError); }
 
+/**
+ * @primitive  pki.schema.crmf.pemEncode
+ * @signature  pki.schema.crmf.pemEncode(der, label) -> string
+ * @since      0.1.23
+ * @status     experimental
+ * @spec       RFC 7468, RFC 4211
+ * @related    pki.schema.crmf.pemDecode
+ *
+ * Wrap DER bytes in a PEM envelope. RFC 4211 registers no RFC 7468 label, so
+ * `label` is REQUIRED -- the operator names the envelope explicitly (mirroring
+ * `pemDecode`, which accepts any label). Omitting it throws `pem/bad-label`.
+ *
+ * @example
+ *   var pem = pki.schema.crmf.pemEncode(der, "CERT REQUEST MESSAGES");
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
+
 // matches(root): a CertReqMessages is a universal SEQUENCE whose first CertReqMsg
 // is a SEQUENCE whose first CertRequest is a SEQUENCE leading with a universal
 // INTEGER (certReqId) then a universal SEQUENCE (certTemplate). This 3-level probe
@@ -495,15 +544,22 @@ function matches(root) {
     schema.isUniversal(tpl, TAGS.SEQUENCE) && !!tpl.children;
 }
 
-// Validate a bare, already-decoded CertReqMessages / CertTemplate node — for a
+// Validate a bare, already-decoded CertReqMessages / CertTemplate node -- for a
 // composer that carries these structures inside its own envelope (an RFC 9810
 // CMP PKIBody's ir/cr/kur/krr/ccr arms; a RevDetails.certDetails). NS-bound to
 // crmf so an interior failure throws CrmfError with a crmf/* code, never the
 // composer's class wearing a foreign code. Same contract as the CMS walkers.
-// opts.allowSigningAlg relaxes the request-template signingAlg-omission rule for
-// the CMP cross-certification (ccr) arm only (RFC 9810 Appendix D.6).
+// The opts carry the RFC 9810 Appendix D.6 ccr-profile overrides of RFC 4211 sec. 5,
+// applied by the CMP composer to the cross-certification arm only:
+// opts.allowSigningAlg relaxes the request-template signingAlg-omission rule and
+// opts.allowV1Version accepts a CertTemplate version of v1 ("version v1 or v3").
 function walkCertReqMessages(node, opts) {
-  var ctx = (opts && opts.allowSigningAlg) ? Object.assign({}, NS, { allowSigningAlg: true }) : NS;
+  var ctx = NS;
+  if (opts && (opts.allowSigningAlg || opts.allowV1Version)) {
+    ctx = Object.assign({}, NS);
+    if (opts.allowSigningAlg) ctx.allowSigningAlg = true;
+    if (opts.allowV1Version) ctx.allowV1Version = true;
+  }
   return schema.walk(CERT_REQ_MESSAGES, node, ctx).result;
 }
 function walkCertTemplate(node) { return schema.walk(CERT_TEMPLATE, node, NS).result; }
@@ -511,11 +567,12 @@ function walkCertTemplate(node) { return schema.walk(CERT_TEMPLATE, node, NS).re
 module.exports = {
   parse: parse,
   pemDecode: pemDecode,
+  pemEncode: pemEncode,
   matches: matches,
   walkCertReqMessages: walkCertReqMessages,
   walkCertTemplate: walkCertTemplate,
   // The top schema, exposed (not on the curated pki.schema.crmf surface) so a
   // round-trip test can prove schema.encode(schema, v) -> decode -> parse recovers
-  // v — the invariant that structurally validates the IMPLICIT/EXPLICIT tag handling.
+  // v -- the invariant that structurally validates the IMPLICIT/EXPLICIT tag handling.
   certReqMessagesSchema: CERT_REQ_MESSAGES,
 };