@blamejs/pki 0.1.22 → 0.1.24

package/lib/schema-crl.js

@@ -9,7 +9,7 @@
  * @slug       crl
  *
  * @intro
- *   X.509 Certificate Revocation List handling per RFC 5280 §5. `parse` turns a
+ *   X.509 Certificate Revocation List handling per RFC 5280 sec. 5. `parse` turns a
  *   DER or PEM CRL into a structured, fully-decoded object: version, issuer
  *   distinguished name, this/next update as real `Date`s, the ordered list of
  *   revoked certificates (serial + revocation date + entry extensions), and the
@@ -19,7 +19,7 @@
  *   rules, and the raw `tbsCertList` bytes are returned for signature checking.
  *
  * @card
- *   Parse DER / PEM X.509 CRLs into structured, validated fields — revoked
+ *   Parse DER / PEM X.509 CRLs into structured, validated fields -- revoked
  *   serials with real-`Date` revocation times, named extensions, fail-closed.
  */
 
@@ -34,11 +34,13 @@ var PemError = frameworkError.PemError;
 var TAGS = asn1.TAGS;
 
 
-// CRLReason ::= ENUMERATED (RFC 5280 §5.3.1) — value 7 is unused/reserved.
-var CRL_REASONS = [0n, 1n, 2n, 3n, 4n, 5n, 6n, 8n, 9n, 10n];
+// CRLReason ::= ENUMERATED (RFC 5280 sec. 5.3.1) -- value 7 is unused/reserved.
+// The legal set lives once in pkix.CRL_REASON_NAMES (shared with the OCSP
+// RevokedInfo decoder, which surfaces the name; this decoder the numeric code).
+var CRL_REASONS = pkix.CRL_REASON_NAMES;
 
 // Extension-value decoding is keyed off the STABLE dotted OID (resolved once at
-// load from the canonical name), not the mutable display name — a caller's
+// load from the canonical name), not the mutable display name -- a caller's
 // pki.oid.register() display override must not change parse behaviour.
 var OID_CRL_NUMBER = oid.byName("cRLNumber");
 var OID_REASON_CODE = oid.byName("reasonCode");
@@ -51,16 +53,19 @@ var NS = pkix.makeNS("crl", CrlError, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
 var EXTENSIONS = pkix.extensions(NS);
-var TIME = schema.time(NS);
+// pkix.time enforces the RFC 5280 encoding cutover on decode (sec. 5.1.2.4 -
+// 5.1.2.6: thisUpdate / nextUpdate / revocationDate through 2049 must be
+// UTCTime). invalidityDate stays GeneralizedTime-only (sec. 5.3.2, decodeExt).
+var TIME = pkix.time(NS);
 
-// CRL Version ::= INTEGER { v1(0), v2(1) } — a BARE INTEGER (not [0] EXPLICIT).
+// CRL Version ::= INTEGER { v1(0), v2(1) } -- a BARE INTEGER (not [0] EXPLICIT).
 // A CRL is at most v2; reject an explicit v1 (DER forbids the default) and any
 // value >= 2. Do NOT reuse the certificate readVersion (it maps 2 -> v3).
 var CRL_VERSION = pkix.versionReader(NS, { "1": 2 });
 
 // The three cheap, high-value CRL extension values are decoded from their raw
-// extnValue octets (RFC 5280 §5.2/§5.3); GeneralNames-based extensions
-// (issuingDistributionPoint, certificateIssuer, authorityKeyIdentifier, …) stay
+// extnValue octets (RFC 5280 sec. 5.2/sec. 5.3); GeneralNames-based extensions
+// (issuingDistributionPoint, certificateIssuer, authorityKeyIdentifier, ...) stay
 // raw with their bytes reachable. A malformed decoded value fails closed.
 function decodeExt(ext) {
   var value = ext.value;
@@ -69,10 +74,10 @@ function decodeExt(ext) {
       value = asn1.read.integer(asn1.decode(ext.value));
       if (value < 0n) throw new Error("cRLNumber must be non-negative (INTEGER 0..MAX)");
     } else if (ext.oid === OID_REASON_CODE) { // reasonCode ::= ENUMERATED (CRLReason)
-      // read.enumerated asserts the ENUMERATED tag (a bare INTEGER is rejected) —
+      // read.enumerated asserts the ENUMERATED tag (a bare INTEGER is rejected) --
       // the codec owns the tag check, so this reader need not repeat it.
       var reason = asn1.read.enumerated(asn1.decode(ext.value));
-      if (CRL_REASONS.indexOf(reason) === -1) throw new Error("undefined CRLReason " + reason.toString());
+      if (!Object.prototype.hasOwnProperty.call(CRL_REASONS, reason.toString())) throw new Error("undefined CRLReason " + reason.toString());
       value = Number(reason);
     } else if (ext.oid === OID_INVALIDITY_DATE) { // invalidityDate ::= GeneralizedTime
       var n = asn1.decode(ext.value);
@@ -121,7 +126,7 @@ var REVOKED_LIST = schema.seqOf(REVOKED_ENTRY, {
 // revokedCertificates=SEQUENCE) are disambiguated by their universal tag;
 // crlExtensions is modeled as a trailing [0]..[0] so a stray non-[0] trailing
 // context tag is REJECTED (crl/bad-tbs), not silently ignored.
-// `signature` is consumed by the CERTIFICATE_LIST build (the §5.1.1.2
+// `signature` is consumed by the CERTIFICATE_LIST build (the sec. 5.1.1.2
 // outer==inner agreement check reads tbsMatch.fields.signature.node.bytes);
 // the operator reads the surfaced outer signatureAlgorithm, which that
 // check proves byte-identical.
@@ -140,7 +145,7 @@ var TBS_CERTLIST = schema.seq([
   build: function (m) {
     return {
       version: m.fields.version.present ? m.fields.version.value : 1,
-      issuer: m.fields.issuer.value.result, // Name is a seqOf → field.value is the match; .result is the {rdns, dn} build
+      issuer: m.fields.issuer.value.result, // Name is a seqOf -> field.value is the match; .result is the {rdns, dn} build
       thisUpdate: m.fields.thisUpdate.value,
       nextUpdate: m.fields.nextUpdate.present ? m.fields.nextUpdate.value : null,
       revokedCertificates: m.fields.revokedCertificates.present ? m.fields.revokedCertificates.value.result : [],
@@ -151,22 +156,22 @@ var TBS_CERTLIST = schema.seq([
 });
 
 // CertificateList ::= SEQUENCE { tbsCertList, signatureAlgorithm, signatureValue }
-// — the shared SIGNED envelope. The CRL-specific invariants (outer==inner
+// -- the shared SIGNED envelope. The CRL-specific invariants (outer==inner
 // signatureAlgorithm agreement, non-empty issuer, v2-only extensions) live in the
 // build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
 var CERTIFICATE_LIST = pkix.signedEnvelope(NS, TBS_CERTLIST, {
   code: "crl/not-a-crl", what: "CertificateList",
   build: function (e) {
     var tbs = e.tbsMatch.result;
-    // RFC 5280 §5.1.1.2 — the outer signatureAlgorithm MUST equal tbsCertList.signature.
+    // RFC 5280 sec. 5.1.1.2 -- the outer signatureAlgorithm MUST equal tbsCertList.signature.
     if (!e.outerSignatureAlgorithmBytes.equals(e.tbsMatch.fields.signature.node.bytes)) {
-      throw NS.E("crl/bad-signature-algorithm", "signatureAlgorithm must match tbsCertList.signature (RFC 5280 §5.1.1.2)");
+      throw NS.E("crl/bad-signature-algorithm", "signatureAlgorithm must match tbsCertList.signature (RFC 5280 sec. 5.1.1.2)");
     }
-    // RFC 5280 §5.1.2.3 — the issuer MUST be a non-empty distinguished name.
+    // RFC 5280 sec. 5.1.2.3 -- the issuer MUST be a non-empty distinguished name.
     if (!tbs.issuer.rdns.length) {
       throw NS.E("crl/bad-issuer", "issuer must be a non-empty distinguished name");
     }
-    // RFC 5280 §5.1.2.1 — crlExtensions / crlEntryExtensions appear only in a v2 CRL.
+    // RFC 5280 sec. 5.1.2.1 -- crlExtensions / crlEntryExtensions appear only in a v2 CRL.
     var hasExtensions = tbs.crlExtensionsPresent ||
       tbs.revokedCertificates.some(function (r) { return r.crlEntryExtensions.length > 0; });
     if (hasExtensions && tbs.version !== 2) {
@@ -202,7 +207,7 @@ var CERTIFICATE_LIST = pkix.signedEnvelope(NS, TBS_CERTLIST, {
  *
  * @example
  *   var crl = pki.schema.crl.parse(der);
- *   crl.revokedCertificates[0].serialNumberHex;  // → "0a3f…"
+ *   crl.revokedCertificates[0].serialNumberHex;  // -> "0a3f..."
  */
 var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS });
 
@@ -222,8 +227,24 @@ var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorCla
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "X509 CRL", PemError); }
 
+/**
+ * @primitive  pki.schema.crl.pemEncode
+ * @signature  pki.schema.crl.pemEncode(der, label?) -> string
+ * @since      0.1.23
+ * @status     stable
+ * @spec       RFC 7468, RFC 5280
+ * @related    pki.schema.crl.pemDecode
+ *
+ * Wrap CRL DER bytes in a PEM envelope with 64-column base64 lines (default
+ * label `X509 CRL`, the RFC 7468 sec. 6 armor `pemDecode` expects back).
+ *
+ * @example
+ *   var pem = pki.schema.crl.pemEncode(der);
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label || "X509 CRL", PemError); }
+
 // Certificate and CertificateList share the outer SEQUENCE-of-3 shape; a CRL is
-// distinguished by its tbsCertList — the first tbs element is a bare INTEGER
+// distinguished by its tbsCertList -- the first tbs element is a bare INTEGER
 // (version) or an AlgorithmIdentifier (signature) SEQUENCE, and crucially the
 // field at the certificate's Validity position is a bare Time (thisUpdate). The
 // orchestrator uses `matches` to route; a cert's tbs leads with a [0] EXPLICIT
@@ -232,7 +253,7 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "X509 CRL
 function matches(root) {
   var tbs = pkix.signedEnvelopeTbs(root);
   if (!tbs) return false;
-  // A certificate's tbs leads with [0] EXPLICIT version — a CRL never does.
+  // A certificate's tbs leads with [0] EXPLICIT version -- a CRL never does.
   if (tbs.children[0] && tbs.children[0].tagClass === "context") return false;
   // Walk to the thisUpdate / validity position: skip an optional bare INTEGER
   // version, then signature (SEQUENCE) + issuer (SEQUENCE); the next element is
@@ -247,5 +268,6 @@ function matches(root) {
 module.exports = {
   parse: parse,
   pemDecode: pemDecode,
+  pemEncode: pemEncode,
   matches: matches,
 };