@blamejs/pki 0.8.30 → 0.8.48

package/examples/issue-a-certificate.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * Issue a certificate from your own CA, then validate the path.
+ *
+ *   node examples/issue-a-certificate.js
+ *
+ * Generates a CA key and a self-signed CA certificate, generates a leaf key, issues a leaf
+ * certificate from the CA, and validates leaf-against-CA through RFC 5280 path validation.
+ * Nothing is written to disk and no network is used.
+ */
+
+var pki = require("@blamejs/pki");
+
+// A subject is a distinguished name, and `pki.x509.parseDn(s).bytes` is how a DN string becomes one
+// the builders take. Handing them the string directly is not an error and not the same thing: a bare
+// string is read as a COMMON NAME, so "CN=Example CA, O=Example" would certify one commonName whose
+// value is that whole text.
+function dn(s) { return pki.x509.parseDn(s).bytes; }
+
+async function main() {
+  // A CA key and the self-signed certificate that names it. basicConstraints cA marks it as a CA
+  // and keyCertSign is what lets it sign other certificates; a CA missing either is refused as an
+  // issuer during path validation.
+  var caKeys = await pki.key.generate("ML-DSA-65");
+  var caSpki = await pki.key.export(caKeys.publicKey);
+  var caKey = await pki.key.export(caKeys.privateKey);
+  var now = new Date();
+  var caDer = await pki.x509.sign({
+    subject: dn("CN=Example CA, O=Example"),
+    subjectPublicKey: caSpki,
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(3650)),
+    extensions: {
+      basicConstraints: { cA: true },
+      keyUsage: ["keyCertSign", "cRLSign"],
+      subjectKeyIdentifier: true,
+    },
+  }, { key: caKey });
+  console.log("ca subject:   " + pki.schema.x509.parse(caDer).subject.dn);
+
+  // The leaf. Its key is its own; the CA only signs over its public half.
+  var leafKeys = await pki.key.generate("ML-DSA-65");
+  var leafDer = await pki.x509.sign({
+    subject: dn("CN=host.example"),
+    subjectPublicKey: await pki.key.export(leafKeys.publicKey),
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(90)),
+    extensions: {
+      subjectAltName: ["host.example", "www.host.example"],
+      keyUsage: ["digitalSignature"],
+      extendedKeyUsage: ["serverAuth"],
+    },
+  }, { key: caKey, cert: caDer });
+  var leaf = pki.schema.x509.parse(leafDer);
+  console.log("leaf subject: " + leaf.subject.dn);
+  console.log("leaf issuer:  " + leaf.issuer.dn);
+  console.log("leaf serial:  " + leaf.serialNumberHex.length / 2 + " bytes of entropy");
+
+  // Path validation is the verb that decides whether the leaf is trusted, and it is separate from
+  // having issued it: the anchor is supplied as a name and a key, never as bytes to be trusted.
+  var ca = pki.schema.x509.parse(caDer);
+  var result = await pki.path.validate([leafDer], {
+    time: now,
+    trustAnchors: {
+      name: ca.subject,
+      publicKey: ca.subjectPublicKeyInfo.bytes,
+      algorithm: ca.subjectPublicKeyInfo.algorithm.oid,
+    },
+  });
+  console.log("path valid:   " + result.valid);
+
+  // The same validation one day after the leaf expires. A certificate outside its validity window
+  // is not trusted, which is the check an expiry outage is.
+  var expired = await pki.path.validate([leafDer], {
+    time: new Date(now.getTime() + pki.C.TIME.days(91)),
+    trustAnchors: {
+      name: ca.subject,
+      publicKey: ca.subjectPublicKeyInfo.bytes,
+      algorithm: ca.subjectPublicKeyInfo.algorithm.oid,
+    },
+  });
+  console.log("after expiry: " + expired.valid);
+}
+
+main().then(null, function (e) {
+  console.error(e && (e.code ? e.code + ": " + e.message : e.message));
+  process.exitCode = 1;
+});

package/examples/post-quantum.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * Post-quantum signatures and key establishment, through the same verbs as everything else.
+ *
+ *   node examples/post-quantum.js
+ *
+ * ML-DSA (FIPS 204) and SLH-DSA (FIPS 205) sign certificates here the way ECDSA and Ed25519 do:
+ * an algorithm is a registry entry, so nothing about issuing, verifying or validating a path
+ * changes with the suite. ML-KEM (FIPS 203) does key establishment. No network.
+ */
+
+var pki = require("@blamejs/pki");
+
+async function certificateFor(alg) {
+  var keys = await pki.key.generate(alg);
+  var now = new Date();
+  var der = await pki.x509.sign({
+    subject: pki.x509.parseDn("CN=" + alg.toLowerCase() + ".example").bytes,
+    subjectPublicKey: await pki.key.export(keys.publicKey),
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(365)),
+    extensions: { keyUsage: ["digitalSignature"] },
+  }, { key: await pki.key.export(keys.privateKey) });
+  return { der: der, cert: pki.schema.x509.parse(der) };
+}
+
+async function main() {
+  // The same call shape across three signature families. The name the certificate carries comes
+  // from the OID registry, so a reader sees the algorithm rather than a dotted string.
+  for (var alg of ["ML-DSA-65", "SLH-DSA-SHA2-128s", "Ed25519"]) {
+    var made = await certificateFor(alg);
+    console.log(alg.padEnd(18) + " certificate " + String(made.der.length).padStart(6) +
+      " bytes, signed with " + made.cert.signatureAlgorithm.name);
+  }
+
+  // A post-quantum certificate validates through the same path validator, with no suite-specific
+  // argument: the anchor names its own key algorithm and the verifier resolves the rest.
+  var ca = await certificateFor("ML-DSA-65");
+  var result = await pki.path.validate([ca.der], {
+    time: new Date(),
+    trustAnchors: {
+      name: ca.cert.subject,
+      publicKey: ca.cert.subjectPublicKeyInfo.bytes,
+      algorithm: ca.cert.subjectPublicKeyInfo.algorithm.oid,
+    },
+  });
+  console.log("path validates with a post-quantum anchor: " + result.valid);
+
+  // ML-KEM is key establishment rather than signing: the sender encapsulates to the recipient's
+  // public key and both sides end up with the same secret, which neither transmitted. This is the
+  // pair the CMS KEMRecipientInfo arm rides on.
+  var kemAlg = { name: "ML-KEM-768" };
+  var kem = await pki.key.generate("ML-KEM-768");
+  var sent = await pki.webcrypto.subtle.encapsulateBits(kemAlg, kem.publicKey);
+  var received = await pki.webcrypto.subtle.decapsulateBits(kemAlg, kem.privateKey, sent.ciphertext);
+  var agreed = Buffer.compare(Buffer.from(sent.sharedKey), Buffer.from(received)) === 0;
+  console.log("ml-kem-768 ciphertext " + sent.ciphertext.byteLength + " bytes, shared secret " +
+    sent.sharedKey.byteLength + " bytes, both sides agree: " + agreed);
+}
+
+main().then(null, function (e) {
+  console.error(e && (e.code ? e.code + ": " + e.message : e.message));
+  process.exitCode = 1;
+});

package/examples/read-a-certificate.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * Read a certificate: parse it, render it, lint it, dump its bytes.
+ *
+ *   node examples/read-a-certificate.js
+ *
+ * The four ways this toolkit reads one certificate, from the structured fields a program uses to
+ * the byte offsets a debugger needs. No network, nothing written to disk.
+ */
+
+var pki = require("@blamejs/pki");
+
+async function main() {
+  // A certificate to read. Any DER or PEM certificate works here; this one is generated so the
+  // example needs no fixture.
+  var keys = await pki.key.generate("Ed25519");
+  var now = new Date();
+  var der = await pki.x509.sign({
+    subject: pki.x509.parseDn("CN=host.example, O=Example").bytes,
+    subjectPublicKey: await pki.key.export(keys.publicKey),
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(90)),
+    extensions: { subjectAltName: ["host.example"], keyUsage: ["digitalSignature"] },
+  }, { key: await pki.key.export(keys.privateKey) });
+
+  // 1. parse -- the structured fields, validated. This is what a program reads.
+  var cert = pki.schema.x509.parse(der);
+  console.log("subject:      " + cert.subject.dn);
+  console.log("algorithm:    " + cert.signatureAlgorithm.name);
+  console.log("extensions:   " + cert.extensions.map(function (e) { return e.name || e.oid; }).join(", "));
+
+  // 2. inspect -- the report a person reads, the pure-JS equivalent of `openssl x509 -text`.
+  //    pki.inspect.any detects the format, so the same call reads a CRL or a CMS message.
+  var report = pki.inspect.any(der);
+  console.log("report lines: " + report.split("\n").length);
+
+  // 3. lint -- graded conformance findings. The data path never throws: malformed bytes become a
+  //    fatal finding rather than an exception, so a survey over a corpus cannot be stopped by one
+  //    bad file. `worst` is the highest severity present, and "pass" means nothing was found.
+  var lint = pki.lint.certificate(der);
+  console.log("lint worst:   " + (lint.worst || "pass"));
+  console.log("lint findings: " + lint.findings.length);
+
+  // 4. asn1 -- the structural dump, in the shape `openssl asn1parse` prints. This one renders every
+  //    value in the file, so it is the verb to reach for on a file that is wrong rather than one
+  //    holding a key.
+  var dump = pki.inspect.asn1(der);
+  console.log("first node:   " + dump.split("\n")[1].trim());
+}
+
+main().then(null, function (e) {
+  console.error(e && (e.code ? e.code + ": " + e.message : e.message));
+  process.exitCode = 1;
+});

package/examples/revoke-and-check.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * Revoke a certificate and see a path stop trusting it (CRL, RFC 5280 section 5).
+ *
+ *   node examples/revoke-and-check.js
+ *
+ * Issues a leaf, validates it, publishes a CRL that revokes it, and validates again with that
+ * CRL supplied. The second answer is the one revocation exists to produce. No network.
+ */
+
+var pki = require("@blamejs/pki");
+
+function dn(s) { return pki.x509.parseDn(s).bytes; }
+
+async function main() {
+  var now = new Date();
+  var caKeys = await pki.key.generate("Ed25519");
+  var caKey = await pki.key.export(caKeys.privateKey);
+  var caDer = await pki.x509.sign({
+    subject: dn("CN=Revocation CA"),
+    subjectPublicKey: await pki.key.export(caKeys.publicKey),
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(3650)),
+    extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"], subjectKeyIdentifier: true },
+  }, { key: caKey });
+  var ca = pki.schema.x509.parse(caDer);
+
+  var leafKeys = await pki.key.generate("Ed25519");
+  var leafDer = await pki.x509.sign({
+    subject: dn("CN=doomed.example"),
+    subjectPublicKey: await pki.key.export(leafKeys.publicKey),
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(90)),
+    extensions: { keyUsage: ["digitalSignature"] },
+  }, { key: caKey, cert: caDer });
+  var leaf = pki.schema.x509.parse(leafDer);
+  console.log("leaf serial:  " + leaf.serialNumberHex.slice(0, 16) + "...");
+
+  var anchor = {
+    name: ca.subject,
+    publicKey: ca.subjectPublicKeyInfo.bytes,
+    algorithm: ca.subjectPublicKeyInfo.algorithm.oid,
+  };
+  var before = await pki.path.validate([leafDer], { time: now, trustAnchors: anchor });
+  console.log("before crl:   " + before.valid);
+
+  // The CA publishes a CRL naming that serial. nextUpdate is required by RFC 5280 section 5.1.2.5
+  // and is what tells a relying party how long the list may be believed.
+  // The issuer argument names the CA through its certificate, so the spec does not repeat it: the
+  // name a CRL is signed under is the one in that certificate.
+  var crlDer = await pki.crl.sign({
+    thisUpdate: now,
+    nextUpdate: new Date(now.getTime() + pki.C.TIME.days(7)),
+    crlNumber: 1n,
+    revoked: [{
+      serialNumber: BigInt("0x" + leaf.serialNumberHex),
+      revocationDate: now,
+      reason: "keyCompromise",
+    }],
+  }, { key: caKey, cert: caDer });
+  var crl = pki.schema.crl.parse(crlDer);
+  console.log("crl entries:  " + crl.revokedCertificates.length +
+    ", next update in " + Math.round((crl.nextUpdate - crl.thisUpdate) / pki.C.TIME.days(1)) + " days");
+
+  // The same path, with the CRL supplied. Revocation is a pluggable hook rather than a built-in
+  // fetch: pki.path.crlChecker answers from the CRLs you hand it, and a validator given none
+  // cannot know a certificate was revoked. Supplying it is what changes the answer.
+  var after = await pki.path.validate([leafDer], {
+    time: now,
+    trustAnchors: anchor,
+    revocationChecker: pki.path.crlChecker([crlDer]),
+  });
+  console.log("after crl:    " + after.valid);
+  var reasons = [];
+  (after.results || []).forEach(function (r) {
+    (r.checks || []).forEach(function (c) { if (c.ok === false) reasons.push(c.code); });
+  });
+  console.log("refused for:  " + (reasons.join(", ") || "(nothing)"));
+}
+
+main().then(null, function (e) {
+  console.error(e && (e.code ? e.code + ": " + e.message : e.message));
+  process.exitCode = 1;
+});

package/examples/sign-and-verify-cms.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * Sign a document and verify the signature (CMS SignedData, RFC 5652).
+ *
+ *   node examples/sign-and-verify-cms.js
+ *
+ * Signs bytes into a SignedData, verifies it, and shows what changes when the content is
+ * detached and when the signature is over content that has since been altered. No network,
+ * nothing written to disk.
+ */
+
+var pki = require("@blamejs/pki");
+
+async function main() {
+  // A signer needs a key and a certificate naming it: a signature that no certificate binds to an
+  // identity proves only that someone held a key.
+  var keys = await pki.key.generate("ML-DSA-65");
+  var key = await pki.key.export(keys.privateKey);
+  var now = new Date();
+  var cert = await pki.x509.sign({
+    subject: pki.x509.parseDn("CN=signer.example").bytes,
+    subjectPublicKey: await pki.key.export(keys.publicKey),
+    notBefore: now,
+    notAfter: new Date(now.getTime() + pki.C.TIME.days(365)),
+    extensions: { keyUsage: ["digitalSignature"] },
+  }, { key: key });
+
+  var content = Buffer.from("the bytes under signature", "utf8");
+  var signed = await pki.cms.sign(content, { cert: cert, key: key });
+  console.log("signeddata:   " + signed.length + " bytes");
+
+  // Verifying against the signer certificate. `verify` answers about the signature; whether that
+  // certificate is trusted is what pki.path.validate answers, and they are separate questions.
+  var ok = await pki.cms.verify(signed, { certs: [cert] });
+  console.log("verified:     " + ok.valid);
+  console.log("signers:      " + ok.signers.length);
+
+  // Detached: the signature travels without the content, so the verifier is given the content it
+  // already has. This is how a signature over a large artifact is shipped.
+  var detached = await pki.cms.sign(content, { cert: cert, key: key }, { detached: true });
+  var okDetached = await pki.cms.verify(detached, { certs: [cert], content: content });
+  console.log("detached:     " + detached.length + " bytes, verified " + okDetached.valid);
+
+  // The same detached signature against content that changed by one byte. A signature is over
+  // bytes, so this is the answer that makes it worth having.
+  var altered = Buffer.from(content);
+  altered[0] ^= 0x01;
+  var verdict;
+  try {
+    var bad = await pki.cms.verify(detached, { certs: [cert], content: altered });
+    verdict = bad.valid ? "accepted (this would be a defect)" : "rejected";
+  } catch (e) {
+    verdict = "rejected (" + (e.code || "threw") + ")";
+  }
+  console.log("altered:      " + verdict);
+}
+
+main().then(null, function (e) {
+  console.error(e && (e.code ? e.code + ": " + e.message : e.message));
+  process.exitCode = 1;
+});

package/index.js

@@ -37,6 +37,10 @@ var schema    = require("./lib/schema-all");
 var path      = require("./lib/path-validate");
 var identity  = require("./lib/identity-match");
 var ct        = require("./lib/ct");
+var tuf       = require("./lib/tuf");
+var relatedCert = require("./lib/related-cert");
+var altSig    = require("./lib/alt-sig");
+var possession = require("./lib/possession");
 var tls       = require("./lib/tls-cert-compress");
 var cms       = require("./lib/cms-verify");
 var smime     = require("./lib/smime");
@@ -53,6 +57,7 @@ var key       = require("./lib/key");
 var pkcs12    = require("./lib/pkcs12-build");
 var pkcs11    = require("./lib/pkcs11-uri");
 var merkle    = require("./lib/merkle");
+var tlog      = require("./lib/tlog");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
 var compositeKem = require("./lib/composite-kem");
@@ -97,6 +102,10 @@ module.exports = {
   // SCT-list extension a certificate / OCSP response carries; the signature is
   // surfaced raw for external verification (pki.ct.reconstructSignedData).
   ct:        ct,
+  tuf:       tuf,
+  relatedCert: relatedCert,
+  altSig:    altSig,
+  possession: possession,
   // 'tls' is TLS handshake structures that carry certificates -- RFC 8879 compressed
   // certificate messages (zlib / brotli / zstd) and the RFC 8446 Certificate message
   // inside them, decoded to per-entry certificate DER. Structure only; no handshake.
@@ -166,15 +175,19 @@ module.exports = {
   // verifyConsistency fold an audit / consistency proof and constant-time-
   // compare to a checkpoint root. Pure sync hashing, fail-closed, transport-free.
   merkle:    merkle,
+  // `tlog` is the C2SP transparency-log envelope over those hashes: a signed
+  // note, the checkpoint body a log signs into one, and the tile paths a static
+  // log serves them beside. Verifying only; nothing signs and nothing fetches.
+  tlog:      tlog,
   // `shbs` verifies stateful hash-based signatures -- HSS/LMS (RFC 8554),
   // carried by RFC 9802 (X.509) and RFC 9708 (CMS), profiled by NIST SP 800-208.
   // VERIFY ONLY by design: stateful signing requires atomic one-time-key index
   // state that belongs in an HSM, so this module never mints a signature.
   shbs:      shbs,
-  // `hpke` is RFC 9180 Hybrid Public Key Encryption -- the KEM + HKDF key
-  // schedule + AEAD context construction behind TLS ECH / MLS / OHTTP. Pure
-  // composition over node:crypto; the four DHKEM suites and the three ML-KEM
-  // suites, all four modes.
+  // `hpke` is RFC 9180 Hybrid Public Key Encryption -- the KEM + key schedule +
+  // AEAD context construction behind TLS ECH / MLS / OHTTP. Pure composition over
+  // node:crypto; five DHKEM suites, three ML-KEM suites and three PQ/T hybrids,
+  // over the two-stage HKDF and single-stage SHAKE key schedules, all four modes.
   hpke:      hpke,
   // `kem` is composite ML-KEM key establishment (draft-ietf-lamps-pq-composite-kem):
   // pki.kem.encapsulate / decapsulate over a post-quantum ML-KEM hybridized with a
@@ -197,7 +210,7 @@ module.exports = {
   // rejectUnauthorized always on, a TLS floor, a streaming response cap, and a timeout.
   // Curated to the public `https` factory; the module's `isBlockedIp` classifier is an
   // internal helper pki.path.build reuses (require the module), not a public surface.
-  transport: { https: transport.https },
+  transport: { https: transport.https, peerChain: transport.peerChain },
   // `jose` is the RFC 7515 Flattened JWS + RFC 7638 JWK-thumbprint layer: a strict
   // base64url codec, a bounded duplicate-key-rejecting JSON reader, profiled
   // sign/verify (ACME-outer / EAB-inner / keyChange-inner), and an alg registry