@blamejs/pki 0.1.21 → 0.1.23

package/lib/schema-tsp.js

@@ -10,7 +10,7 @@
  *
  * @intro
  *   RFC 3161 Time-Stamp Protocol handling. A `TimeStampResp` is what a client
- *   receives from a TSA — a `PKIStatusInfo` plus, on success, a `TimeStampToken`;
+ *   receives from a TSA -- a `PKIStatusInfo` plus, on success, a `TimeStampToken`;
  *   `parse` decodes it and enforces the status-to-token coupling (a granted
  *   response carries a token, a rejection does not). A `TimeStampToken` is itself a
  *   CMS SignedData whose encapsulated content is a `TSTInfo`, so `parseToken`
@@ -21,13 +21,14 @@
  *   The parser surfaces everything a verifier needs and interprets nothing it
  *   cannot: `messageImprint.hashAlgorithm` and the raw `hashedMessage`, the
  *   `genTime` (with sub-second precision), the `serialNumber` and `nonce` (lossless,
- *   as BigInt + hex), and the `policy`. The imprint-to-request and nonce-to-request
- *   round-trips, the ESS signing-certificate binding, the timestamping EKU, and the
- *   signature are verification-layer concerns above parse altitude. DER-only,
- *   fail-closed.
+ *   as BigInt + hex), and the `policy`. The PRESENCE of the ESS
+ *   SigningCertificate(V2) attribute is asserted at parse (a structural token
+ *   property); the imprint-to-request and nonce-to-request round-trips, the ESS
+ *   hash-vs-certificate binding, the timestamping EKU, and the signature are
+ *   verification-layer concerns above parse altitude. DER-only, fail-closed.
  *
  * @card
- *   Parse DER / PEM RFC 3161 timestamp responses and tokens — per-response status,
+ *   Parse DER / PEM RFC 3161 timestamp responses and tokens -- per-response status,
  *   the TSTInfo payload (imprint, genTime, serial, nonce, accuracy), raw verifier
  *   inputs, single-signer token composition over CMS, fail-closed.
  */
@@ -47,16 +48,22 @@ var NS = pkix.makeNS("tsp", TspError, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var EXTENSION = pkix.extension(NS);
 
-// TSTInfo.version is INTEGER { v1(1) } — the only legal value is 1.
+// TSTInfo.version is INTEGER { v1(1) } -- the only legal value is 1.
 var VERSION = pkix.versionReader(NS, { "1": 1 });
 
 // id-ct-TSTInfo is the eContentType that identifies a timestamp token (RFC 3161
-// §2.4.2); resolved from the registry, never a dotted literal.
+// sec. 2.4.2); resolved from the registry, never a dotted literal.
 var OID_TST_INFO = oid.byName("tSTInfo");
 
+// The ESS certificate-identifier attributes: RFC 3161 sec. 2.4.2 requires the TSA
+// certificate identifier as a SigningCertificate signed attribute; RFC 5816
+// additionally permits SigningCertificateV2.
+var OID_SIGNING_CERT = oid.byName("signingCertificate");
+var OID_SIGNING_CERT_V2 = oid.byName("signingCertificateV2");
+
 var TAGS = asn1.TAGS;
 
-// PKIFailureInfo ::= BIT STRING NamedBitList (RFC 3161 §2.4.2). bit 0 is the MSB of
+// PKIFailureInfo ::= BIT STRING NamedBitList (RFC 3161 sec. 2.4.2). bit 0 is the MSB of
 // the first content octet; a set bit outside the named set is surfaced by index.
 var FAILURE_BITS = {
   0: "badAlg", 2: "badRequest", 5: "badDataFormat", 14: "timeNotAvailable",
@@ -65,33 +72,23 @@ var FAILURE_BITS = {
 
 // ---- shared leaves ---------------------------------------------------
 
-// GeneralizedTime-only leaf. RFC 3161 §2.4.2 requires genTime to be GeneralizedTime,
+// GeneralizedTime-only leaf. RFC 3161 sec. 2.4.2 requires genTime to be GeneralizedTime,
 // never UTCTime; assert the tag before the (fractional-capable) codec read.
-var GEN_TIME = schema.decode(function (n, ctx) {
-  if (n.tagClass !== "universal" || n.tagNumber !== TAGS.GENERALIZED_TIME) {
-    throw ctx.E("tsp/bad-gentime", "genTime must be a GeneralizedTime (RFC 3161 §2.4.2)");
-  }
-  // RFC 3161 genTime may carry sub-second precision (X.690 §11.7 fractional profile).
-  return asn1.read.time(n, { allowFractional: true });
-});
+// RFC 3161 genTime may carry sub-second precision (X.690 sec. 11.7 fractional profile).
+var GEN_TIME = pkix.generalizedTime(NS, { code: "tsp/bad-gentime", message: "genTime must be a GeneralizedTime (RFC 3161 sec. 2.4.2)", allowFractional: true });
 
-// tsa [0] EXPLICIT GeneralName (RFC 3161 §2.4.2) — validated + surfaced raw via the
-// shared pkix.generalName primitive (RFC 5280 §4.2.1.6), which checks the chosen
+// tsa [0] EXPLICIT GeneralName (RFC 3161 sec. 2.4.2) -- validated + surfaced raw via the
+// shared pkix.generalName primitive (RFC 5280 sec. 4.2.1.6), which checks the chosen
 // alternative's form and content so a malformed GeneralName fails closed.
 var GENERAL_NAME_RAW = pkix.generalName(NS, { code: "tsp/bad-tsa" });
 
-// A PKIFreeText element MUST be a UTF8String (RFC 3161 §2.4.2).
-var UTF8_TEXT = schema.decode(function (n, ctx) {
-  if (n.tagClass !== "universal" || n.tagNumber !== TAGS.UTF8_STRING) {
-    throw ctx.E("tsp/bad-status-info", "PKIFreeText elements must be UTF8String");
-  }
-  return asn1.read.string(n);
-});
+// A PKIFreeText element MUST be a UTF8String (RFC 3161 sec. 2.4.2).
+var UTF8_TEXT = pkix.utf8Text(NS, { code: "tsp/bad-status-info", message: "PKIFreeText elements must be UTF8String" });
 
 // ---- MessageImprint --------------------------------------------------
 
 // MessageImprint ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, hashedMessage
-// OCTET STRING } (RFC 3161 §2.4.1). hashedMessage is a digest — surfaced RAW.
+// OCTET STRING } (RFC 3161 sec. 2.4.1). hashedMessage is a digest -- surfaced RAW.
 var MESSAGE_IMPRINT = schema.seq([
   schema.field("hashAlgorithm", ALGORITHM_IDENTIFIER),
   schema.field("hashedMessage", schema.octetString()),
@@ -106,7 +103,7 @@ var MESSAGE_IMPRINT = schema.seq([
 
 // Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] IMPLICIT INTEGER
 // (1..999) OPTIONAL, micros [1] IMPLICIT INTEGER (1..999) OPTIONAL } (RFC 3161
-// §2.4.2). Every sub-field is optional; a missing one defaults to 0.
+// sec. 2.4.2). Every sub-field is optional; a missing one defaults to 0.
 var ACCURACY = schema.seq([
   schema.optional("seconds", schema.integerLeaf(), { whenUniversal: [TAGS.INTEGER] }),
   schema.trailing([
@@ -119,13 +116,19 @@ var ACCURACY = schema.seq([
     function sub(f) {
       if (!f.present) return 0;
       var v = f.value;
-      // millis / micros are constrained to 1..999 (RFC 3161 §2.4.2); 0 is also
+      // millis / micros are constrained to 1..999 (RFC 3161 sec. 2.4.2); 0 is also
       // excluded (and non-canonical for a positive count).
       if (v < 1n || v > 999n) throw NS.E("tsp/bad-accuracy", "Accuracy millis/micros must be in 1..999");
       return Number(v);
     }
+    // Accuracy is the +/- deviation added to and subtracted from genTime (RFC
+    // 3161 sec. 2.4.2), so a negative seconds inverts the time window a verifier
+    // computes -- the same semantically-impossible class as a 0 millis/micros.
+    if (m.fields.seconds.present && m.fields.seconds.value < 0n) {
+      throw NS.E("tsp/bad-accuracy", "Accuracy seconds must not be negative (RFC 3161 sec. 2.4.2)");
+    }
     return {
-      // seconds is an unbounded INTEGER — keep it lossless as a BigInt (millis /
+      // seconds is an unbounded INTEGER -- keep it lossless as a BigInt (millis /
       // micros are constrained to 1..999, so Number is exact for those).
       seconds: m.fields.seconds.present ? m.fields.seconds.value : 0n,
       millis: sub(m.fields.millis),
@@ -139,7 +142,7 @@ var ACCURACY = schema.seq([
 // TSTInfo ::= SEQUENCE { version, policy, messageImprint, serialNumber, genTime,
 // accuracy OPTIONAL, ordering DEFAULT FALSE, nonce OPTIONAL, tsa [0] EXPLICIT
 // GeneralName OPTIONAL, extensions [1] IMPLICIT Extensions OPTIONAL } (RFC 3161
-// §2.4.2). The five mandatory fields come first; the optionals are consumed by tag.
+// sec. 2.4.2). The five mandatory fields come first; the optionals are consumed by tag.
 var TST_INFO = schema.seq([
   schema.field("version", VERSION),
   schema.field("policy", schema.oidLeaf()),
@@ -156,9 +159,9 @@ var TST_INFO = schema.seq([
 ], {
   assert: "sequence", code: "tsp/bad-tst-info", what: "TSTInfo",
   build: function (m, ctx) {
-    // ordering BOOLEAN DEFAULT FALSE — an explicit FALSE must be omitted (DER).
+    // ordering BOOLEAN DEFAULT FALSE -- an explicit FALSE must be omitted (DER).
     if (m.fields.ordering.present && m.fields.ordering.value === false) {
-      throw NS.E("tsp/bad-ordering", "ordering is BOOLEAN DEFAULT FALSE — an explicit FALSE must be omitted");
+      throw NS.E("tsp/bad-ordering", "ordering is BOOLEAN DEFAULT FALSE -- an explicit FALSE must be omitted");
     }
     var policy = m.fields.policy.value;
     var tsa = m.fields.tsa;
@@ -187,7 +190,7 @@ var TST_INFO = schema.seq([
 // ---- PKIStatusInfo / TimeStampResp -----------------------------------
 
 // PKIStatusInfo ::= SEQUENCE { status PKIStatus (INTEGER), statusString PKIFreeText
-// OPTIONAL, failInfo PKIFailureInfo OPTIONAL } (RFC 3161 §2.4.2, from RFC 4210).
+// OPTIONAL, failInfo PKIFailureInfo OPTIONAL } (RFC 3161 sec. 2.4.2, from RFC 4210).
 var PKI_STATUS_INFO = schema.seq([
   schema.field("status", schema.integerLeaf()),
   schema.optional("statusString", schema.seqOf(UTF8_TEXT, { assert: "sequence", min: 1, code: "tsp/bad-status-info", what: "statusString" }), { whenUniversal: [TAGS.SEQUENCE] }),
@@ -197,7 +200,7 @@ var PKI_STATUS_INFO = schema.seq([
   build: function (m) {
     var status = m.fields.status.value;
     // PKIStatus ::= INTEGER { granted(0) .. revocationNotification(5) }.
-    if (status < 0n || status > 5n) throw NS.E("tsp/bad-status", "PKIStatus " + status + " is outside 0..5 (RFC 3161 §2.4.2)");
+    if (status < 0n || status > 5n) throw NS.E("tsp/bad-status", "PKIStatus " + status + " is outside 0..5 (RFC 3161 sec. 2.4.2)");
     var failInfo = null;
     if (m.fields.failInfo.present) {
       var bs = m.fields.failInfo.value;
@@ -212,7 +215,7 @@ var PKI_STATUS_INFO = schema.seq([
   },
 });
 
-// X.690 §11.2.2 — a BIT STRING typed with a NamedBitList (PKIFailureInfo) MUST have
+// X.690 sec. 11.2.2 -- a BIT STRING typed with a NamedBitList (PKIFailureInfo) MUST have
 // all trailing 0 bits removed under DER: no trailing all-zero content octet, and the
 // declared unusedBits must sit exactly below the lowest set bit of the last octet (so
 // the encoding is minimal). The empty value encodes as 0 content octets, 0 unusedBits.
@@ -221,15 +224,15 @@ function _assertMinimalNamedBits(unusedBits, bytes) {
 }
 
 // Decode the set NamedBitList bits to their RFC 3161 names (bit 0 = MSB of byte 0).
-// A set bit outside the defined set is an unsupported PKIFailureInfo value — a client
-// MUST error on a failInfo it does not understand (RFC 3161 §2.4.2), so reject it
+// A set bit outside the defined set is an unsupported PKIFailureInfo value -- a client
+// MUST error on a failInfo it does not understand (RFC 3161 sec. 2.4.2), so reject it
 // rather than surfacing an opaque "bitN".
 function _namedBits(bytes) {
   var out = [];
   for (var i = 0; i < bytes.length * 8; i++) {
     if ((bytes[i >> 3] >> (7 - (i & 7))) & 1) {
       var nm = FAILURE_BITS[i];
-      if (!nm) throw NS.E("tsp/bad-failinfo", "unsupported PKIFailureInfo bit " + i + " (RFC 3161 §2.4.2)");
+      if (!nm) throw NS.E("tsp/bad-failinfo", "unsupported PKIFailureInfo bit " + i + " (RFC 3161 sec. 2.4.2)");
       out.push(nm);
     }
   }
@@ -237,8 +240,10 @@ function _namedBits(bytes) {
 }
 
 // TimeStampResp ::= SEQUENCE { status PKIStatusInfo, timeStampToken TimeStampToken
-// OPTIONAL } (RFC 3161 §2.4.2). There is NO version field. The token is a CMS
+// OPTIONAL } (RFC 3161 sec. 2.4.2). There is NO version field. The token is a CMS
 // ContentInfo, decoded via cms.parse; the status-to-token coupling is load-bearing.
+// The top-level reject code predates the `<prefix>/not-a-<structure>` convention
+// and stays frozen on the public error-code surface.
 var TIME_STAMP_RESP = schema.seq([
   schema.field("status", PKI_STATUS_INFO),
   schema.optional("timeStampToken", schema.any(), { whenUniversal: [TAGS.SEQUENCE] }),
@@ -247,15 +252,15 @@ var TIME_STAMP_RESP = schema.seq([
   build: function (m) {
     var status = m.fields.status.value.result;
     var present = m.fields.timeStampToken.present;
-    // RFC 3161 §2.4.2 — granted / grantedWithMods carry a token; any other status
+    // RFC 3161 sec. 2.4.2 -- granted / grantedWithMods carry a token; any other status
     // (rejection / waiting / revocation*) MUST NOT.
     var granted = status.status === 0 || status.status === 1;
-    if (granted && !present) throw NS.E("tsp/missing-token", "a granted TimeStampResp must carry a timeStampToken (RFC 3161 §2.4.2)");
-    if (!granted && present) throw NS.E("tsp/unexpected-token", "a non-granted TimeStampResp must not carry a timeStampToken (RFC 3161 §2.4.2)");
+    if (granted && !present) throw NS.E("tsp/missing-token", "a granted TimeStampResp must carry a timeStampToken (RFC 3161 sec. 2.4.2)");
+    if (!granted && present) throw NS.E("tsp/unexpected-token", "a non-granted TimeStampResp must not carry a timeStampToken (RFC 3161 sec. 2.4.2)");
     // failInfo is the reason a request was rejected, so it is present ONLY when the
-    // status is rejection(2) — not on granted(0/1) nor on waiting / revocation* (3/4/5).
-    if (status.status !== 2 && status.failInfo) throw NS.E("tsp/unexpected-failinfo", "failInfo is present only when the status is rejection(2) (RFC 3161 §2.4.2)");
-    // A granted response's timeStampToken MUST be a well-formed TimeStampToken —
+    // status is rejection(2) -- not on granted(0/1) nor on waiting / revocation* (3/4/5).
+    if (status.status !== 2 && status.failInfo) throw NS.E("tsp/unexpected-failinfo", "failInfo is present only when the status is rejection(2) (RFC 3161 sec. 2.4.2)");
+    // A granted response's timeStampToken MUST be a well-formed TimeStampToken --
     // decode it (composing the CMS parser) rather than surfacing arbitrary SEQUENCE
     // bytes as a token; a malformed token fails the response parse.
     return {
@@ -275,8 +280,8 @@ var TIME_STAMP_RESP = schema.seq([
  * @spec       RFC 3161
  * @related    pki.schema.tsp.parseToken, pki.schema.tsp.parse
  *
- * Parse a bare `TSTInfo` payload (a DER `Buffer`) — the structure a timestamp token
- * encapsulates — into `{ version, policy, messageImprint, serialNumber, genTime,
+ * Parse a bare `TSTInfo` payload (a DER `Buffer`) -- the structure a timestamp token
+ * encapsulates -- into `{ version, policy, messageImprint, serialNumber, genTime,
  * accuracy, ordering, nonce, tsa, extensions }`. `messageImprint.hashedMessage` is
  * the raw digest; `serialNumber` / `nonce` are lossless (BigInt + hex); `genTime` is
  * a `Date` with sub-second precision. A malformed structure throws a typed
@@ -299,7 +304,7 @@ var parseTstInfo = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorCl
  *
  * Parse a DER `Buffer` or a PEM string into a `TimeStampResp`: `{ status,
  * statusString, failInfo, timeStampToken }`. The status-to-token coupling is
- * enforced — a granted response (status 0/1) carries `timeStampToken` (surfaced raw
+ * enforced -- a granted response (status 0/1) carries `timeStampToken` (surfaced raw
  * for `parseToken`), any other status does not. `failInfo` decodes the
  * `PKIFailureInfo` named bits. A malformed structure throws a typed `TspError`.
  *
@@ -318,13 +323,17 @@ var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: Ts
  * @spec       RFC 3161, RFC 5652
  * @related    pki.schema.tsp.parse, pki.schema.cms.parse
  *
- * Parse a `TimeStampToken` (a DER `Buffer` or PEM) — a CMS SignedData whose
+ * Parse a `TimeStampToken` (a DER `Buffer` or PEM) -- a CMS SignedData whose
  * encapsulated content is a `TSTInfo`. Composes `pki.schema.cms.parse`, asserts the
  * `id-ct-TSTInfo` content type (`tsp/wrong-econtent-type`), that the content is
- * attached (`tsp/detached-token`), and the single-signer rule (`tsp/multi-signer`,
- * RFC 3161 §2.4.2), then decodes the inner `TSTInfo`. Returns `{ tstInfo, eContent,
- * signerInfo, certificates }` — the decoded payload, the raw eContent bytes a verifier
- * hashes for the CMS message-digest, and the CMS signer material.
+ * attached (`tsp/detached-token`), the single-signer rule (`tsp/multi-signer`,
+ * RFC 3161 sec. 2.4.2), and that the signerInfo carries a SigningCertificate or
+ * SigningCertificateV2 signed attribute (`tsp/missing-signing-certificate`,
+ * RFC 3161 sec. 2.4.2 / RFC 5816 -- the hash-vs-certificate binding stays a
+ * verification-layer concern), then decodes the inner `TSTInfo`. Returns
+ * `{ tstInfo, eContent, signerInfo, certificates }` -- the decoded payload, the raw
+ * eContent bytes a verifier hashes for the CMS message-digest, and the CMS signer
+ * material.
  *
  * @example
  *   var token = pki.schema.tsp.parseToken(tokenDer);
@@ -333,10 +342,10 @@ var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: Ts
  */
 function parseToken(input) {
   // De-armor with TSP's label-agnostic PEM rules first (RFC 3161 has no standard
-  // label), THEN hand DER to the CMS parser — otherwise cms.parse would reject any
+  // label), THEN hand DER to the CMS parser -- otherwise cms.parse would reject any
   // PEM block not labeled "CMS" before the TSP checks run.
   var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: TspError, prefix: "tsp" });
-  // Wrap the CMS decode so tsp.parse / parseToken keep their typed-TspError contract —
+  // Wrap the CMS decode so tsp.parse / parseToken keep their typed-TspError contract --
   // a malformed token surfaces tsp/bad-token, not a bare cms/* error.
   var signed;
   try { signed = cms.parse(der); }
@@ -344,13 +353,35 @@ function parseToken(input) {
     if (e instanceof TspError) throw e;
     throw new TspError("tsp/bad-token", "the timeStampToken did not decode as a CMS SignedData: " + ((e && e.message) || String(e)), e);
   }
+  // cms.parse decodes every CMS content type; a TimeStampToken MUST be a
+  // SignedData (RFC 3161 sec. 2.4.2). Gate on the dispatched content type before
+  // any SignedData-only field access -- an AuthenticatedData / EnvelopedData
+  // whose eContentType happens to be id-ct-TSTInfo would otherwise reach a raw
+  // TypeError on the absent signerInfos.
+  if (signed.contentTypeName !== "signedData") {
+    throw new TspError("tsp/not-signed-data", "a TimeStampToken must be a CMS SignedData, got " + (signed.contentTypeName || signed.contentType));
+  }
   var encap = signed.encapContentInfo;
   if (encap.eContentType !== OID_TST_INFO) {
     throw new TspError("tsp/wrong-econtent-type", "a TimeStampToken must encapsulate id-ct-TSTInfo, got " + encap.eContentType);
   }
-  if (encap.eContent === null) throw new TspError("tsp/detached-token", "a TimeStampToken must carry attached eContent (RFC 3161 §2.4.2)");
+  if (encap.eContent === null) throw new TspError("tsp/detached-token", "a TimeStampToken must carry attached eContent (RFC 3161 sec. 2.4.2)");
   if (signed.signerInfos.length !== 1) {
-    throw new TspError("tsp/multi-signer", "a TimeStampToken must contain exactly one (TSA) signerInfo (RFC 3161 §2.4.2)");
+    throw new TspError("tsp/multi-signer", "a TimeStampToken must contain exactly one (TSA) signerInfo (RFC 3161 sec. 2.4.2)");
+  }
+  // RFC 3161 sec. 2.4.2 / RFC 5816 -- the TSA certificate identifier MUST be present
+  // as a SigningCertificate (or SigningCertificateV2) signed attribute. Presence
+  // is a structural token property, same altitude as the single-signer rule; the
+  // hash-vs-certificate BINDING stays a verification-layer concern. signedAttrs
+  // is non-null here: the CMS parse already required it for a non-id-data
+  // eContentType (RFC 5652 sec. 5.3), and the eContentType is id-ct-TSTInfo.
+  var signedAttrs = signed.signerInfos[0].signedAttrs || [];
+  var hasSigningCert = false;
+  for (var a = 0; a < signedAttrs.length; a++) {
+    if (signedAttrs[a].type === OID_SIGNING_CERT || signedAttrs[a].type === OID_SIGNING_CERT_V2) { hasSigningCert = true; break; }
+  }
+  if (!hasSigningCert) {
+    throw new TspError("tsp/missing-signing-certificate", "a TimeStampToken signerInfo must carry a SigningCertificate or SigningCertificateV2 signed attribute (RFC 3161 sec. 2.4.2, RFC 5816)");
   }
   var tstInfo;
   try { tstInfo = schema.embeddedDer(TST_INFO, encap.eContent, NS, { code: "tsp/bad-der", what: "the encapsulated TSTInfo" }); }
@@ -359,7 +390,7 @@ function parseToken(input) {
     throw new TspError("tsp/bad-der", "the encapsulated TSTInfo did not decode: " + ((e && e.message) || String(e)), e);
   }
   // Surface the RAW eContent (the exact DER a verifier hashes for the CMS
-  // message-digest signed attribute) alongside the decoded TSTInfo — a re-serialized
+  // message-digest signed attribute) alongside the decoded TSTInfo -- a re-serialized
   // tstInfo may not byte-match, so the raw bytes are the verification feed.
   return { tstInfo: tstInfo.result, eContent: encap.eContent, signerInfo: signed.signerInfos[0], certificates: signed.certificates };
 }
@@ -381,6 +412,23 @@ function parseToken(input) {
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || null, PemError); }
 
+/**
+ * @primitive  pki.schema.tsp.pemEncode
+ * @signature  pki.schema.tsp.pemEncode(der, label) -> string
+ * @since      0.1.23
+ * @status     stable
+ * @spec       RFC 7468, RFC 3161
+ * @related    pki.schema.tsp.pemDecode
+ *
+ * Wrap DER bytes in a PEM envelope. RFC 3161 defines no standard PEM 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.tsp.pemEncode(der, "TSP RESPONSE");
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
+
 // A TimeStampResp root is a SEQUENCE of 1-2 whose first child is a PKIStatusInfo (a
 // SEQUENCE whose own first child is an INTEGER status). Disjoint from the OID-first
 // CMS ContentInfo, the INTEGER-first PKCS#8 key, and the exactly-3 signed-envelope
@@ -400,5 +448,6 @@ module.exports = {
   parseTstInfo: parseTstInfo,
   parseToken: parseToken,
   pemDecode: pemDecode,
+  pemEncode: pemEncode,
   matches: matches,
 };

package/lib/schema-x509.js

@@ -11,7 +11,7 @@
  *
  * @intro
  *   X.509 certificate handling per RFC 5280. The seed surface is
- *   `parse` — turn a DER or PEM certificate into a structured,
+ *   `parse` -- turn a DER or PEM certificate into a structured,
  *   fully-decoded object: version, serial, signature algorithm, issuer
  *   and subject distinguished names, validity window (as real `Date`s),
  *   subject public-key info, and the extension list. The parser composes
@@ -48,15 +48,16 @@ var PemError = frameworkError.PemError;
  * @spec       RFC 7468, RFC 5280
  * @related    pki.schema.x509.pemEncode
  *
- * Extract the DER bytes from a PEM block. With `label` given (e.g.
- * `"CERTIFICATE"`) the block type must match; without it, the first block
- * is taken. Throws `PemError` on a missing / mismatched envelope or a
- * non-base64 body.
+ * Extract the DER bytes from a PEM block (default label `CERTIFICATE`, the
+ * RFC 7468 sec. 5 armor -- the canonical-label default every sibling format
+ * applies). Pass a `label` to enforce a different block type, or an explicit
+ * `null` to take the first block of any type. Throws `PemError` on a
+ * missing / mismatched envelope or a non-base64 body.
  *
  * @example
- *   var der = pki.schema.x509.pemDecode(pemText, "CERTIFICATE");
+ *   var der = pki.schema.x509.pemDecode(pemText);
  */
-function pemDecode(text, label) { return pkix.pemDecode(text, label, PemError); }
+function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? null : (label || "CERTIFICATE"), PemError); }
 
 /**
  * @primitive  pki.schema.x509.pemEncode
@@ -85,17 +86,19 @@ var NS = pkix.makeNS("x509", CertificateError, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
 
-// Validity ::= SEQUENCE { notBefore Time, notAfter Time }. The historical guard
-// checked only children.length===2 (not the SEQUENCE tag) -> assert "constructed".
+// Validity ::= SEQUENCE { notBefore Time, notAfter Time } -- the outer tag is
+// asserted (a SET-tagged body is a different ASN.1 type, not a Validity).
+// pkix.time enforces the RFC 5280 sec. 4.1.2.5 encoding cutover on decode: a
+// validity date through 2049 must be UTCTime, GeneralizedTime is 2050 onward.
 var VALIDITY = schema.seq([
-  schema.field("notBefore", schema.time(NS)),
-  schema.field("notAfter", schema.time(NS)),
+  schema.field("notBefore", pkix.time(NS)),
+  schema.field("notAfter", pkix.time(NS)),
 ], {
-  assert: "constructed", arity: { exact: 2 }, code: "x509/bad-validity", what: "Validity",
+  assert: "sequence", arity: { exact: 2 }, code: "x509/bad-validity", what: "Validity",
   build: function (m) { return { notBefore: m.fields.notBefore.value, notAfter: m.fields.notAfter.value }; },
 });
 
-// SubjectPublicKeyInfo — the shared pkix.spki factory under the x509 NS.
+// SubjectPublicKeyInfo -- the shared pkix.spki factory under the x509 NS.
 var SPKI = pkix.spki(NS);
 
 var EXTENSIONS = pkix.extensions(NS);
@@ -103,7 +106,7 @@ var EXTENSIONS = pkix.extensions(NS);
 // Version ::= INTEGER { v1(0), v2(1), v3(2) }, [0] EXPLICIT DEFAULT v1. Read as a
 // BigInt so an out-of-range value can't coerce to a float; reject an explicitly-
 // encoded v1 (DER forbids encoding the DEFAULT).
-// version ::= INTEGER { v1(0), v2(1), v3(2) } inside a [0] EXPLICIT DEFAULT v1 —
+// version ::= INTEGER { v1(0), v2(1), v3(2) } inside a [0] EXPLICIT DEFAULT v1 --
 // DER forbids encoding the default, so 0 is rejected; 1->v2, 2->v3.
 var CERTIFICATE_VERSION = pkix.versionReader(NS, { "1": 2, "2": 3 });
 
@@ -122,19 +125,21 @@ var CERTIFICATE_TBS = schema.seq([
   schema.field("subject", NAME),
   schema.field("subjectPublicKeyInfo", SPKI),
   schema.trailing([
-    { tag: 1, name: "issuerUniqueID", schema: schema.any() },
-    { tag: 2, name: "subjectUniqueID", schema: schema.any() },
+    // RFC 5280 sec. 4.1.2.8 -- the unique identifiers are [n] IMPLICIT BIT
+    // STRING (context PRIMITIVE, unusedBits validated), never an EXPLICIT wrap.
+    { tag: 1, name: "issuerUniqueID", schema: schema.implicitBitString(1) },
+    { tag: 2, name: "subjectUniqueID", schema: schema.implicitBitString(2) },
     { tag: 3, name: "extensions", schema: EXTENSIONS, explicit: true, emptyCode: "x509/bad-extensions" },
   ], { minTag: 1, maxTag: 3, unexpectedCode: "x509/bad-tbs", orderCode: "x509/bad-tbs" }),
-], { assert: "constructed", code: "x509/bad-tbs", what: "tbsCertificate" });
+], { assert: "sequence", code: "x509/bad-tbs", what: "tbsCertificate" });
 
 // Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue
-// BIT STRING }. The build runs the RFC 5280 cross-field checks (§4.1.1.2 sig-alg
-// agreement, §4.1.2.4 non-empty issuer, §4.1.2.9 extensions-only-in-v3) after the
+// BIT STRING }. The build runs the RFC 5280 cross-field checks (sec. 4.1.1.2 sig-alg
+// agreement, sec. 4.1.2.4 non-empty issuer, sec. 4.1.2.9 extensions-only-in-v3) after the
 // structural walk, then assembles the public parse result. Raw-byte accessors
 // (serialNumberHex, tbsBytes, sig-alg agreement) read off the match-tree nodes.
 // Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue }
-// — the shared SIGNED envelope. The certificate-specific invariants (outer==inner
+// -- the shared SIGNED envelope. The certificate-specific invariants (outer==inner
 // signatureAlgorithm agreement, non-empty issuer, v3-only extensions) live in the
 // build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
 var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
@@ -142,25 +147,31 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
   build: function (e, ctx) {
     var tbs = e.tbsMatch; // CERTIFICATE_TBS seq-match (no build)
 
-    // RFC 5280 §4.1.1.2 — outer signatureAlgorithm MUST equal tbsCertificate.signature.
+    // RFC 5280 sec. 4.1.1.2 -- outer signatureAlgorithm MUST equal tbsCertificate.signature.
     if (!e.outerSignatureAlgorithmBytes.equals(tbs.fields.signature.node.bytes)) {
-      throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
+      throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 sec. 4.1.1.2)");
     }
 
     var version = tbs.fields.version.value; // 1 (default) | 2 | 3
     var issuer = tbs.fields.issuer.value.result;
-    // RFC 5280 §4.1.2.4 — issuer MUST be non-empty (an empty subject is permitted, §4.1.2.6).
+    // RFC 5280 sec. 4.1.2.4 -- issuer MUST be non-empty (an empty subject is permitted, sec. 4.1.2.6).
     if (!issuer.rdns.length) {
       throw ctx.E("x509/bad-issuer", "issuer must be a non-empty distinguished name");
     }
 
     var extField = tbs.fields.extensions;
     var hasExtensions = !!(extField && extField.present);
-    // RFC 5280 §4.1.2.9 — extensions appear only in a v3 certificate.
+    // RFC 5280 sec. 4.1.2.9 -- extensions appear only in a v3 certificate.
     if (hasExtensions && version !== 3) {
       throw ctx.E("x509/bad-version", "extensions are only permitted in a v3 certificate");
     }
 
+    // RFC 5280 sec. 4.1.2.8 -- issuerUniqueID / subjectUniqueID MUST NOT
+    // appear when the version is 1; they require a v2 or v3 certificate.
+    if ((tbs.fields.issuerUniqueID.present || tbs.fields.subjectUniqueID.present) && version < 2) {
+      throw ctx.E("x509/bad-version", "issuerUniqueID/subjectUniqueID require a v2 or v3 certificate (RFC 5280 sec. 4.1.2.8)");
+    }
+
     var serialNode = tbs.fields.serialNumber.node;
     return {
       version:               version,
@@ -211,7 +222,7 @@ var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, Error
 
 // matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
 // share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the
-// tbs: a certificate has a Validity — a SEQUENCE of exactly two Time values — at
+// tbs: a certificate has a Validity -- a SEQUENCE of exactly two Time values -- at
 // position [serial, signature, issuer, VALIDITY] after the optional [0] version.
 // A CSR's certificationRequestInfo has subjectPublicKeyInfo there (no Validity),
 // and a CRL leads with a bare Time; neither matches. Used by the orchestrator.