@blamejs/pki 0.5.5 → 0.5.7

package/lib/cms-verify.js

@@ -119,8 +119,7 @@ EC_CURVE[oid.byName("secp384r1")] = { curve: "P-384", coordLen: 48 };
 EC_CURVE[oid.byName("secp521r1")] = { curve: "P-521", coordLen: 66 };
 
 function _toBuf(v, what) {
-  if (Buffer.isBuffer(v)) return v;
-  if (v instanceof Uint8Array) return Buffer.from(v);
+  if (Buffer.isBuffer(v) || v instanceof Uint8Array) return guard.bytes.snapshot(v, CmsError, "cms/bad-input", what);
   throw _err("cms/bad-input", what + " must be a Buffer");
 }
 
@@ -420,7 +419,24 @@ function _computeCountersigBytes(si, csTarget) {
 // content-type / message-digest attribute disagrees.
 function _computeSignedBytes(si, content, eContentType) {
   return Promise.resolve().then(function () {
-    if (!si.signedAttrsBytes) return content;   // no signed attributes: sign over the content directly
+    if (!si.signedAttrsBytes) {
+      // No signed attributes: the signature is over the content itself (RFC 5652 sec. 5.4). That is
+      // also exactly what a stripped-attributes forgery looks like, because a CMS signature does not
+      // commit to whether attributes were present -- so a signature made over a SignedAttributes
+      // block re-presented as one made over content verifies, and with no attributes there is no
+      // message-digest or content-type attribute left to disagree. Refuse the shape: content that
+      // parses as a SignedAttributes block cannot be told apart from that forgery, and it is not
+      // the verifier's place to guess which one it is holding.
+      if (cms.looksLikeSignedAttributes(content)) {
+        return { mismatch: {
+          code: "cms/ambiguous-content",
+          message: "the content of a SignerInfo with no signed attributes is itself an encoded " +
+            "SignedAttributes block, which is indistinguishable from a signature over attributes " +
+            "re-presented as one over content (RFC 5652 sec. 5.4); sign such content WITH signed attributes",
+        } };
+      }
+      return content;
+    }
     // With signed attributes: decode them from the EXACT bytes the signature covers -- the
     // SignedAttributes SET OF, the on-wire [0] IMPLICIT tag replaced by a universal SET OF
     // (RFC 5652 sec. 5.4) -- so the content-type / message-digest checks bind the same bytes
@@ -538,7 +554,10 @@ function _surfaceUnsignedAttrs(si) {
 // Verify every countersignature attached to `si` (RFC 5652 sec. 11.4): each id-countersignature
 // value is a SignerInfo over `si`'s signature octets. Returns per-countersignature verdicts; a
 // countersignature's OWN countersignatures verify over ITS signature octets (recursive). A
-// present-but-invalid countersignature is surfaced ok:false -- never silently dropped. The recursion
+// countersignature that FAILS TO VERIFY is surfaced ok:false -- never silently dropped, and never
+// allowed to change the primary verdict. A countersignature value that is not a well-formed
+// SignerInfo does not reach here at all: the decoder validates every id-countersignature value by
+// content rather than on the attribute type, so such a message is refused whole. The recursion
 // terminates because it only walks the FINITE parsed structure: each nested countersignature value
 // is a sub-encoding of its parent, and the strict decoder already bounds total nesting by
 // C.LIMITS.DER_MAX_DEPTH at parse (CWE-834/770), so a hostile deep chain fails closed before verify.
@@ -571,7 +590,7 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
 
 /**
  * @primitive  pki.cms.verify
- * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, trusted, signers }>
+ * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, trusted, eContentType, signers }>
  * @since      0.2.14
  * @status     stable
  * @spec       RFC 5652
@@ -581,10 +600,17 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * @related    pki.schema.cms.parse, pki.path.validate
  *
  * Verify a CMS SignedData signature (RFC 5652 sec. 5). `input` is a PEM string, a DER
- * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, trusted, signers }` where each
- * `signers[i]` is `{ ok, sid, cert, trusted }` (`cert` the matched signer certificate DER) or carries
- * a `code` on a structural failure; `valid` is true when there is at least one signer and
- * every signer verified.
+ * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, trusted, eContentType, signers }`
+ * where each `signers[i]` is `{ ok, sid, cert, trusted, signedAttributesPresent }` (`cert` the
+ * matched signer certificate DER) or carries a `code` on a structural failure; `valid` is true when
+ * there is at least one signer and every signer verified.
+ *
+ * `eContentType` and `signedAttributesPresent` are there for a caller whose profile is stricter
+ * than RFC 5652's. Signing WITH attributes and signing the content directly are different claims --
+ * attributes bind a content type and a signing time alongside the digest, content-only binds
+ * nothing but the bytes -- and one message may carry a signer of each. A profile that requires
+ * attributes (RFC 8551 S/MIME does) or a particular content type can enforce it from the verdict
+ * rather than parsing the message a second time.
  *
  * `valid` and `trusted` are DIFFERENT claims and neither implies the other. A SignedData carries
  * its own certificates, so `valid` establishes that the message is internally consistent -- the
@@ -650,7 +676,14 @@ function _snapshotIfBytes(input, label) {
 // capability cannot arrive with its option silently ignored at this boundary.
 var _VERIFY_OPTS = { certs: 1, content: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1 };
 
+// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async). The checks below stay
+// synchronous -- they read a caller's mutable options and bytes, and resolving those before any turn
+// passes is what stops a value being swapped between the check and the use.
 function verify(input, opts) {
+  return guard.async.deferred(function () { return _verify(input, opts); });
+}
+
+function _verify(input, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.verify options must be an object");
   // An unrecognized option is refused, not swallowed. This is what kept the missing trust seam
@@ -663,13 +696,17 @@ function verify(input, opts) {
   // the parse surfaced -- the signed content above all -- stays a view into the
   // caller's memory across that await, and a buffer rewritten in the gap would leave
   // the result describing one message while the signature was checked over another.
-  // Only a Buffer / Uint8Array can change underneath us: a PEM string is immutable
-  // and passes through untouched, and an already-parsed object is a lifetime the
-  // caller chose. Narrow rather than blanket, so neither input form is refused here
-  // that pki.cms.parse itself accepts.
-  var parsed = (input && typeof input === "object" && !Buffer.isBuffer(input) && Array.isArray(input.signerInfos))
-    ? input
-    : cms.parse(_snapshotIfBytes(input, "pki.cms.verify"));
+  // Re-derived from the bytes the parser read, never trusted as the object it arrives as. A
+  // SignedData's meaning is a signature over a byte range, but a parsed one presents that range
+  // (`signedAttrsBytes`, or the encapsulated `eContent` when there are no signed attributes), the
+  // signature, the algorithms and the certificates as SEPARATE properties. Keep a genuine signer's
+  // signature and signed attributes and put different content beside them and every part of this
+  // check passes for a message that signer never signed -- the forgery this verb's own block claims
+  // to defend (CWE-347). A duck-type test on `signerInfos` cannot see that, because every field is
+  // individually well-formed; only re-deriving them all from one byte string can.
+  var parsed = guard.parsed.acceptDerived(input, "cms", function (bytes) {
+    return cms.parse(_snapshotIfBytes(bytes, "pki.cms.verify"));
+  }, _err, "cms/bad-input", "the SignedData");
   if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "input is not a CMS SignedData");
   var content = parsed.encapContentInfo.eContent;
   if (content == null) {
@@ -707,11 +744,25 @@ function verify(input, opts) {
       return _verifyCountersignatures(si, parsedCerts).then(function (countersignatures) {
         verdict.countersignatures = countersignatures;
         verdict.unsignedAttrs = _surfaceUnsignedAttrs(si);
+        // Whether THIS signer signed attributes or signed the content directly. The two are
+        // different claims -- attributes bind a content type and a signing time alongside the
+        // digest, and content-only binds nothing but the bytes -- and RFC 5652 lets a message carry
+        // one signer of each. A caller whose profile requires attributes (RFC 8551 S/MIME does) can
+        // only enforce it if the verdict says which they got.
+        verdict.signedAttributesPresent = !!si.signedAttrsBytes;
         return verdict;
       });
     });
   })).then(function (signers) {
-    var res = { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers };
+    // The content type travels with the verdict. An operator applying a policy of their own -- "I
+    // only accept id-data", or a profile that names its own type -- otherwise had to parse the
+    // message a second time to learn it, and a check that needs a second parse is a check most
+    // callers will not write.
+    var res = {
+      valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }),
+      eContentType: parsed.encapContentInfo.eContentType,
+      signers: signers,
+    };
     return _applyTrust(res, parsedCerts, trustCfg).then(function () { return res; });
   });
 }

package/lib/crl-sign.js

@@ -144,7 +144,7 @@ function _resolveReason(reason, isDelta) {
 // The AKI keyIdentifier from the issuer: an explicit Buffer, or true -> the issuer cert's subjectKeyIdentifier,
 // else the SHA-1 of the issuer SPKI (RFC 5280 sec. 5.2.1 key-identifier method).
 function _akiKeyId(val, ctx) {
-  if (Buffer.isBuffer(val)) return val;
+  if (Buffer.isBuffer(val)) return guard.bytes.snapshot(val, CrlError, "crl/bad-input", "the authorityKeyIdentifier keyIdentifier");
   if (val === true) {
     if (ctx.issuerCert) {
       var ski = (ctx.issuerCert.extensions || []).filter(function (e) { return e.oid === OID_SKI; })[0];
@@ -507,7 +507,13 @@ function _sign(spec, issuer, opts) {
  *   }, { cert: signerCertDer, key: signerKeyPkcs8 });
  *   pki.schema.crl.parse(der).revokedCertificates[0].serialNumberHex;   // "1234"
  */
-function sign(spec, issuer, opts) { return Promise.resolve().then(function () { return _sign(spec, issuer, opts); }); }
+function sign(spec, issuer, 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(CrlError, "crl/bad-input", [
+    [spec, "the CRL spec"], [issuer, "the issuer"], [opts, "pki.crl.sign options"],
+  ], _sign);
+}
 
 // A CRL these verbs answer from is re-derived from the bytes its parser read. Completeness -- every
 // field present with the right type -- is not enough for a verdict: the signature covers a byte
@@ -598,7 +604,7 @@ function _issuerMaySign(parsed, cert) {
  *     { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var ok = await pki.crl.verify(crlDer, { publicKey: signerSpki });   // true / false
  */
-function verify(crl, issuer) { return Promise.resolve().then(function () { return _verify(crl, issuer); }); }
+function verify(crl, issuer) { return guard.async.deferred(function () { return _verify(crl, issuer); }); }
 function _verify(crl, issuer) {
   var parsed = _coerceCrl(crl);
   var resolved = _resolveIssuer(issuer);

package/lib/crmf-sign.js

@@ -238,7 +238,11 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  *   pki.schema.crmf.parse(msg).messages[0].certReq.certTemplate.subject.dn;   // "CN=device-42"
  */
 function build(spec, key, opts) {
-  return Promise.resolve().then(function () { return _build(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(CrmfError, "crmf/bad-input", [
+    [spec, "the certificate-request-message spec"], [key, "the signing key"], [opts, "pki.crmf.build options"],
+  ], _build);
 }
 
 function _buildCertReqMsg(spec, key, opts) {

package/lib/csr-sign.js

@@ -101,7 +101,11 @@ function _challengePassword(pw) {
  *   pki.schema.csr.parse(req).subject.dn;   // "CN=req.example.com"
  */
 function sign(spec, key, opts) {
-  return Promise.resolve().then(function () { return _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);
 }
 
 function _sign(spec, key, opts) {

package/lib/est.js

@@ -826,7 +826,7 @@ var MAX_TIMEOUT = constants.TIME.seconds(600);
 // The DER of a caller-supplied CSR: a DER Buffer as-is, or a PEM "CERTIFICATE REQUEST"
 // decoded. Any other input is a config-time est/bad-input.
 function _csrDer(input) {
-  if (Buffer.isBuffer(input)) return input;
+  if (Buffer.isBuffer(input)) return guard.bytes.snapshot(input, EstError, "est/bad-input", "a CSR");
   if (typeof input === "string") return csr.pemDecode(input);
   throw E("est/bad-input", "a CSR must be a DER Buffer or a PEM CERTIFICATE REQUEST string");
 }
@@ -1428,7 +1428,7 @@ function _cmcSent(opts, der) {
 // window this exists to close, open for exactly the inputs that came in by the wider door.
 // A DataView is copied over its OWN window, not the whole backing buffer it happens to sit in.
 function _copyBytes(v) {
-  if (Buffer.isBuffer(v) || v instanceof Uint8Array) return Buffer.from(v);
+  if (Buffer.isBuffer(v) || v instanceof Uint8Array) return guard.bytes.snapshot(v, EstError, "est/bad-input", "a byte field of the request");
   if (ArrayBuffer.isView(v)) return Buffer.from(new Uint8Array(v.buffer, v.byteOffset, v.byteLength));
   if (v instanceof ArrayBuffer) return Buffer.from(new Uint8Array(v));
   return v;
@@ -1591,8 +1591,9 @@ function _shallowCopy(o) {
 function _cmcRequestDer(request) {
   // COPIED, not aliased: these bytes are parsed now (for the requested keys) and
   // transmitted later, so sharing the caller's buffer would let the two disagree.
-  if (Buffer.isBuffer(request)) return Buffer.from(request);
-  if (request instanceof Uint8Array) return Buffer.from(request);
+  if (Buffer.isBuffer(request) || request instanceof Uint8Array) {
+    return guard.bytes.snapshot(request, EstError, "est/bad-input", "the Full PKI Request");
+  }
   if (typeof request === "string") return cms.pemDecode(request);
   throw E("est/bad-input", "pki.est.fullcmc requires the Full PKI Request as DER bytes or a PEM CMS block");
 }

package/lib/guard-all.js

@@ -65,6 +65,7 @@ var header = require("./guard-header");
 var compress = require("./guard-compress");
 var secret = require("./guard-secret");
 var parsed = require("./guard-parsed");
+var async_ = require("./guard-async");
 
 module.exports = {
   bytes:  bytes,
@@ -81,4 +82,5 @@ module.exports = {
   compress: compress,
   secret: secret,
   parsed: parsed,
+  async:  async_,
 };

package/lib/guard-async.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is every verb whose
+// @signature says `-> Promise<...>`; this is how each of them refuses.
+//
+// guard-async -- a verb documented as Promise-returning refuses by REJECTING, never by throwing.
+//
+// The failure is invisible at the call site, which is what makes it worth a choke point. An operator
+// reads `-> Promise<...>` in the reference and writes the documented shape:
+//
+//     pki.acme.newOrder(opts).catch(handleIt);
+//
+// A validation that runs BEFORE the promise is created throws straight past that `.catch`, so a
+// misspelled option or a malformed input becomes an uncaught exception in code that already handles
+// errors -- and nothing in the shape of the call tells the caller which verbs do that. Eleven verbs
+// across five modules had it (pki.cms.verify / sign / countersign, pki.ocsp.sign, pki.tsp.sign and
+// six pki.acme verbs), each having grown the same way: a cheap synchronous check added at the top of
+// a function that returns a promise further down.
+//
+// What this does NOT change is WHEN the work happens. The body still runs synchronously, because
+// several of these verbs must resolve a caller's mutable options object before any turn passes --
+// reading a key, a nonce, or a request's bytes a turn later is a different value than the one that
+// was checked. Only the exit changes: a fault leaves as a rejection instead of a throw.
+//
+// @enforced-by behavioral -- the rule has no rename-proof code shape (it is the ABSENCE of a wrapper
+//   around a synchronous prefix, which no lexical pattern can see). The guard is the derived test
+//   test/layer-0-primitives/promise-contract.test.js, which reads every `-> Promise<` @signature out
+//   of lib/ and calls each verb to prove the refusal arrives as a rejection -- so a new verb is in
+//   scope the day it is documented, and no list here can go stale.
+function deferred(body) {
+  try { return Promise.resolve(body()); }
+  catch (e) { return Promise.reject(e); }
+}
+
+module.exports = { deferred: deferred };