@blamejs/pki 0.6.14 → 0.6.16

package/lib/csr-sign.js

@@ -16,11 +16,6 @@
  * @spec RFC 2986
  * @card Build and sign a PKCS#10 certification request (proof of possession by the subject key).
  */
-//
-// The signature algorithm resolves from the SUBJECT public key through the shared sign-scheme registry
-// (RSA / ECDSA / EdDSA / ML-DSA / SLH-DSA / composite), so there is no per-algorithm branch here. The
-// distinguished-name / extension / SPKI encoders + the post-sign self-check are the shared lib/pki-build
-// primitives (the same ones pki.x509.sign composes), bound to the csr namespace.
 
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
@@ -30,7 +25,7 @@ var pkix = require("./schema-pkix");
 var pkiBuild = require("./pki-build");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
-require("./path-validate");   // side-effect: path-validate injects its signature engine into csr-verify at load
+require("./path-validate");
 var csrVerify = require("./csr-verify");
 
 var CsrError = frameworkError.CsrError;
@@ -47,18 +42,12 @@ var _b = pkiBuild.makeBuilder({
   NAME_SCHEMA: pkix.name(NS), SPKI_SCHEMA: pkix.spki(NS), EXT_DECODERS: EXT_DECODERS,
 });
 
-// attributes ::= [0] IMPLICIT SET OF Attribute (RFC 2986). The IMPLICIT tag replaces the universal SET,
-// so it is a context-constructed [0] whose DER-sorted members ARE the SET-OF; empty -> A0 00.
 function _implicitSetOf0(members) {
   return b.contextConstructed(0, Buffer.concat(members.slice().sort(Buffer.compare)));
 }
 
-// The requested v3 Extensions (a bare SEQUENCE OF Extension, RFC 2985 sec. 5.4.2) -- the shared builder
-// primitive (a CSR REQUESTS extensions; no CA gates), object form or a pre-encoded Extension DER array.
 function _buildRequestedExtensions(extSpec, subjectSpki) { return _b.requestedExtensions(extSpec, subjectSpki); }
 
-// challengePassword ::= DirectoryString bounded 1..255 (RFC 2985 sec. 5.4.1). PrintableString when the
-// value is in that charset, else UTF8String; never a Teletex/BMP/Universal string for a new value.
 function _challengePassword(pw) {
   if (typeof pw !== "string" || pw.length < 1 || pw.length > 255) throw _err("csr/bad-input", "challengePassword must be a 1..255 character string (RFC 2985 sec. 5.4.1)");
   return asn1.isPrintableString(pw) ? b.printable(pw) : b.utf8(pw);
@@ -101,8 +90,6 @@ function _challengePassword(pw) {
  *   pki.schema.csr.parse(req).subject.dn;   // "CN=req.example.com"
  */
 function sign(spec, key, opts) {
-  // Every caller-owned argument copied at entry and released when the call settles -- see the note
-  // on the same call in x509-sign.
   return guard.bytes.fixedCall(CsrError, "csr/bad-input", [
     [spec, "the certification-request spec"], [key, "the signing key"], [opts, "pki.csr.sign options"],
   ], _sign);
@@ -111,10 +98,7 @@ function sign(spec, key, opts) {
 function _sign(spec, key, opts) {
   opts = opts || {};
   if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("csr/bad-input", "the certification-request spec must be an object");
-  // Reject a typo'd spec field at config-time rather than silently dropping it (a misspelled `subjcet`
-  // would otherwise yield an empty-subject request).
   guard.identifier.assertKnownKeys(spec, KNOWN_SPEC_KEYS, _err, "csr/bad-input", "unknown spec field ");
-  // The signing key is the second argument (a PKCS#8 key / CryptoKey / composite key pair), or { key }.
   var signingKey = (key && typeof key === "object" && !Buffer.isBuffer(key) && !(key instanceof Uint8Array) && key.type == null && "key" in key) ? key.key : key;
   if (signingKey == null) throw _err("csr/bad-input", "a signing key (the subject's private key) is required");
 
@@ -122,13 +106,11 @@ function _sign(spec, key, opts) {
   _b.assertValidSpki(subjectSpki, "spec.subjectPublicKey");
   var subjectDer = _b.encodeName(spec.subject == null ? [] : spec.subject);
 
-  // attributes: extensionRequest + challengePassword + pre-encoded opaque Attribute DER (the escape
-  // hatch). A recognized attribute may appear at most once (RFC 2985 SINGLE VALUE + producer hygiene).
   var attrs = [], seenAttr = {};
   function addAttr(attrType, valueTlv) {
     if (seenAttr[attrType]) throw _err("csr/bad-input", "duplicate " + (oid.name(attrType) || attrType) + " attribute");
     seenAttr[attrType] = true;
-    attrs.push(b.sequence([b.oid(attrType), b.set([valueTlv])]));   // Attribute ::= SEQUENCE { type, SET OF value }
+    attrs.push(b.sequence([b.oid(attrType), b.set([valueTlv])]));
   }
   if (spec.extensionRequest != null) addAttr(O("extensionRequest"), _buildRequestedExtensions(spec.extensionRequest, subjectSpki));
   if (spec.challengePassword != null) addAttr(O("challengePassword"), _challengePassword(spec.challengePassword));
@@ -143,13 +125,8 @@ function _sign(spec, key, opts) {
       var at;
       try { at = asn1.read.oid(n.children[0]); }
       catch (e) { throw _err("csr/bad-input", "pre-encoded attribute [" + i + "] type is not an OBJECT IDENTIFIER", e); }
-      // A type with a dedicated typed spec field must go through that field so its value syntax is always
-      // enforced (RFC 2985 sec. 5.4): the opaque escape hatch is for UNRECOGNIZED attribute types only and
-      // must never carry a recognized type with an unvalidated value the strict parser would then reject.
       if (at === O("extensionRequest")) throw _err("csr/bad-input", "pass requested extensions via spec.extensionRequest, not a pre-encoded extensionRequest attribute");
       if (at === O("challengePassword")) throw _err("csr/bad-input", "pass the challenge password via spec.challengePassword, not a pre-encoded challengePassword attribute");
-      // Attribute ::= SEQUENCE { type, values SET SIZE(1..MAX) }: an empty value SET is malformed and the
-      // strict parser rejects it, so reject at build time -- a signed request must always round-trip.
       if (!n.children[1].children || n.children[1].children.length === 0) throw _err("csr/bad-input", "pre-encoded attribute [" + i + "] value SET must contain at least one value (RFC 2986 SET SIZE(1..MAX))");
       if (seenAttr[at]) throw _err("csr/bad-input", "duplicate " + (oid.name(at) || at) + " attribute");
       seenAttr[at] = true;
@@ -157,14 +134,11 @@ function _sign(spec, key, opts) {
     });
   }
 
-  // Resolve the signature scheme from the SUBJECT public key (the request proves possession of its private half).
   var scheme = signScheme.resolveSignScheme(_b.certLikeFromSpki(subjectSpki), { combinedRsaSig: true, pss: opts.pss, digestAlgorithm: opts.digestAlgorithm }, true, _signE);
 
-  // CertificationRequestInfo ::= SEQUENCE { version INTEGER(0), subject, subjectPKInfo, attributes [0] }.
   var criDer = b.sequence([b.integer(0n), subjectDer, b.raw(subjectSpki), _implicitSetOf0(attrs)]);
 
   return signScheme.signOverTbs(scheme, signingKey, criDer, _signE).then(function (sig) {
-    // Proof of possession: the signature MUST verify under the subject public key (what openssl req -verify checks).
     return Promise.resolve(_b.assertSignatureVerifies(criDer, sig, subjectSpki, scheme)).then(function () {
       var der = b.sequence([criDer, scheme.sigAlgId, b.bitString(sig, 0)]);
       return opts.pem ? csr.pemEncode(der, "CERTIFICATE REQUEST") : der;
@@ -229,15 +203,10 @@ function _coerceCsr(request) {
  */
 function verify(request) { return guard.async.deferred(function () { return _verify(request); }); }
 function _verify(request) {
-  // The fields come off the structure the door re-derived from the recorded bytes, never off the
-  // argument. A caller who normalizes a parse result in place -- rewriting subject or attributes
-  // before verifying -- still holds their edited object afterwards, and a bare boolean would let
-  // them issue from it while the verdict was about something else. Handing back the verified
-  // structure means the fields a CA acts on are the fields the signature covers.
   var parsed = _coerceCsr(request);
   return Promise.resolve(csrVerify.verifyCsrSignature(parsed)).then(function (ok) {
     return {
-      valid: ok === true,   // canonical toolkit-wide verdict alias, beside the verb's own `verified`
+      valid: ok === true,
       verified: ok === true,
       subject: parsed.subject,
       subjectPublicKeyInfo: parsed.subjectPublicKeyInfo,

package/lib/csr-verify.js

@@ -1,24 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- the single PKCS#10 proof-of-possession signature seam for an INBOUND request, shared
-// by pki.csr.verify and by every enrollment path that accepts one, so all of them route through one
-// signature engine and no second, weaker verifier of untrusted requests can drift. The producing
-// side runs its own check over what it just signed (pki-build's assertSignatureVerifies, called
-// from csr-sign), which is a different question about a key the caller already controls. The slot,
-// the wiring assertion and the octet-alignment refusal are the shared seam (lib/verify-seam.js). It
-// is not wired into index.js and is reached only by require.
+// @internal
 
 var frameworkError = require("./framework-error");
 var seam = require("./verify-seam");
 
 var _seam = seam.makeSeam("csr-verify", frameworkError.CsrError, "csr/bad-input");
 
-// Verify a parsed certification request's signature over its exact certificationRequestInfo bytes
-// under the subjectPKInfo the request carries. A CSR has no issuer: the verifying key is the one
-// inside the signed preimage, which is what makes the signature a proof of possession and nothing
-// more.
 function verifyCsrSignature(parsed) {
   return _seam.verify(parsed.signatureAlgorithm, parsed.signatureValue,
     parsed.subjectPublicKeyInfo.bytes, parsed.certificationRequestInfoBytes);