@blamejs/pki 0.4.15 → 0.5.0

package/lib/oid.js

@@ -132,7 +132,65 @@ var FAMILIES = {
   // name->OID reverse stays unambiguous next to the id-kp "timeStamping" purpose (a distinct arc).
   adAccess: { base: [1, 3, 6, 1, 5, 5, 7, 48], of: { ocsp: 1, caIssuers: 2,
     "id-ad-timeStamping": 3, "id-ad-caRepository": 5, "id-ad-rpkiManifest": 10,
-    "id-ad-signedObject": 11, "id-ad-rpkiNotify": 13 } },
+    "id-ad-signedObject": 11, "id-ad-rpkiNotify": 13, "id-ad-cmc": 12 } },
+
+  // CMC control attributes -- id-cmc ::= {id-pkix 7} (RFC 5272 sec. 6, extended by RFC 6402
+  // sec. 2.2/2.8). The whole registry is declared, not just the controls used today: a control
+  // this side does not act on must still be RECOGNIZED to be reported by name, and a decoder that
+  // meets an unknown OID cannot tell "control this build ignores" from "attacker-supplied filler".
+  //
+  // The gaps are the specification's own: 12/13/14 (identityProof/popLinkRandom/popLinkWitness's
+  // superseded siblings are retained below where RFC 6402 kept them) and 20 are unassigned in
+  // RFC 5272 Appendix A. V2 forms exist because RFC 6402 replaced the originals to fix a hash
+  // agility gap -- BOTH are registered, since a v1 message is still legal to receive.
+  idCmc: { base: [1, 3, 6, 1, 5, 5, 7, 7], of: {
+    "id-cmc-statusInfo": 1, "id-cmc-identification": 2, "id-cmc-identityProof": 3,
+    "id-cmc-dataReturn": 4, "id-cmc-transactionId": 5, "id-cmc-senderNonce": 6,
+    "id-cmc-recipientNonce": 7, "id-cmc-addExtensions": 8, "id-cmc-encryptedPOP": 9,
+    "id-cmc-decryptedPOP": 10, "id-cmc-lraPOPWitness": 11,
+    "id-cmc-getCert": 15, "id-cmc-getCRL": 16, "id-cmc-revokeRequest": 17,
+    "id-cmc-regInfo": 18, "id-cmc-responseInfo": 19,
+    "id-cmc-queryPending": 21, "id-cmc-popLinkRandom": 22, "id-cmc-popLinkWitness": 23,
+    "id-cmc-confirmCertAcceptance": 24, "id-cmc-statusInfoV2": 25, "id-cmc-trustedAnchors": 26,
+    "id-cmc-authData": 27, "id-cmc-batchRequests": 28, "id-cmc-batchResponses": 29,
+    "id-cmc-publishCert": 30, "id-cmc-modCertTemplate": 31, "id-cmc-controlProcessed": 32,
+    // ---------------------------------------------------------------------
+    // 33 / 34 -- the specification assigns these two OIDs BOTH ways, and no
+    // erratum resolves it. Counted across every place either document states an
+    // assignment, it is not an even split:
+    //
+    //   identityProofV2 = 34, popLinkWitnessV2 = 33
+    //     rfc5272.txt:1494 / :1504   the sec. 6 control summary table
+    //     rfc5272.txt:1846           sec. 6.2.1 body
+    //     rfc5272.txt:2037           sec. 6.3.1.1 body
+    //     rfc5272.txt:4041 / :4049   RFC 5272's own ASN.1 module
+    //     rfc6402.txt:1228 / :1245   RFC 6402 Appendix A.1 (1988 module)
+    //
+    //   identityProofV2 = 33, popLinkWitnessV2 = 34
+    //     rfc6402.txt:1938 / :1949   RFC 6402 Appendix A.2 (2008 module) ONLY
+    //
+    // The rows below therefore follow the base specification's normative body
+    // text and its module, which RFC 6402's own 1988 module agrees with. The
+    // 2008 module is the lone outlier and is treated as its typo.
+    //
+    // This binds what the toolkit EMITS, and it is load-bearing because the two
+    // controls cannot be told apart by SHAPE: both are SEQUENCE {
+    // AlgorithmIdentifier, AlgorithmIdentifier, OCTET STRING } (rfc6402.txt:1238,
+    // :1246), so the OID is the only discriminator. Emitting the A.2 reading
+    // would hand a peer built on RFC 5272 an Identity Proof it reads as a POP
+    // Link Witness. A CONSUMER must still not infer meaning from these names
+    // alone -- a peer built against A.2 means the other one, and nothing on the
+    // wire says which module it read.
+    "id-cmc-identityProofV2": 34, "id-cmc-popLinkWitnessV2": 33,
+    "id-cmc-raIdentityWitness": 35, "id-cmc-changeSubjectName": 36, "id-cmc-responseBody": 37,
+  } },
+
+  // CMC content types -- id-cct ::= {id-pkix 12} (RFC 5272 Appendix A). The eContentType a CMC
+  // message rides under inside its CMS SignedData wrapper. RFC 5272 Appendix B repeatedly writes
+  // "id-ct-PKIData"; that is erratum 4775 (Verified) and the correct prefix is id-cct-.
+  idCct: { base: [1, 3, 6, 1, 5, 5, 7, 12], of: {
+    "id-cct-PKIData": 2, "id-cct-PKIResponse": 3,
+  } },
 
   // id-on -- RFC 5280 sec. 4.2.1.6 otherName type-ids the C509 sec. 8.13 registry gives their own
   // negative ints: id-on-hardwareModuleName (RFC 4108), id-on-SmtpUTF8Mailbox (RFC 9598),
@@ -312,6 +370,11 @@ var FAMILIES = {
   // identifiers (RFC 9802 sec. 4). HSS/LMS additionally has the SMIME
   // id-alg-hss-lms-hashsig OID above (RFC 9708 / RFC 9802 share it).
   pkixAlg: { base: [1, 3, 6, 1, 5, 5, 7, 6], of: {
+    // id-alg-noSignature (RFC 6402 sec. 2.4, {id-pkix id-alg(6) 2}): the CMC
+    // "signature" algorithm for a request whose signer has no key yet -- the
+    // SignerInfo carries a MAC-based proof instead. Registered so a decoder can
+    // NAME it and refuse it deliberately, rather than meeting an unknown OID.
+    "id-alg-noSignature": 2,
     "id-alg-xmss-hashsig": 34, "id-alg-xmssmt-hashsig": 35,
     // Composite ML-DSA signature algorithms (draft-ietf-lamps-pq-composite-sigs
     // sec. 6): a PQ ML-DSA paired with a traditional RSA / ECDSA / EdDSA so the
@@ -348,6 +411,11 @@ var FAMILIES = {
     receiptRequest: 1, eSSSecurityLabel: 2, mlExpansionHistory: 3, contentHints: 4,
     msgSigDigest: 5, contentIdentifier: 7, equivalentLabels: 9, contentReference: 10,
     signingCertificate: 12, timeStampToken: 14, decryptKeyID: 37, signingCertificateV2: 47,
+    // id-aa-cmc-unsignedData (RFC 6402 sec. 2.7, {id-aa 34}): the CMC unsigned
+    // attribute that carries body parts too large to sit inside the signed
+    // PKIData -- unsigned by design, so a consumer must treat its contents as
+    // untrusted data rather than as part of the authenticated message.
+    cmcUnsignedData: 34,
     asymmDecryptKeyID: 54, certificationRequestInfoTemplate: 61, extensionReqTemplate: 62 } },
 
   // ANSI X9.62 EC public key, named curve, and ECDSA signatures.

package/lib/path-validate.js

@@ -1107,7 +1107,7 @@ function validateCriticalExtensionStructure(cert) {
  * @primitive  pki.path.validate
  * @signature  pki.path.validate(path, opts) -> Promise<result>
  * @since      0.1.16
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280
  * @related    pki.schema.x509.parse, pki.path.crlChecker
  *
@@ -1134,6 +1134,10 @@ function validateCriticalExtensionStructure(cert) {
  * throws a typed `PathError`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2019-01-01T00:00:00Z"), notAfter: new Date("2029-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cert = pki.schema.x509.parse(der);
  *   var res = await pki.path.validate([cert], {
  *     time: new Date("2020-01-01T00:00:00Z"),
@@ -1769,7 +1773,7 @@ function selectDelta(candidates) {
  * @primitive  pki.path.crlChecker
  * @signature  pki.path.crlChecker(crls, opts?) -> RevocationChecker
  * @since      0.1.16
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280
  * @related    pki.path.validate, pki.schema.crl.parse
  *
@@ -2212,7 +2216,7 @@ cmpSession.setEngine({ build: build, validate: validate, toAnchor: toAnchor, coe
  * @primitive  pki.path.ocspChecker
  * @signature  pki.path.ocspChecker(responses) -> RevocationChecker
  * @since      0.1.32
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6960
  * @related    pki.path.validate, pki.schema.ocsp.parseResponse, pki.path.crlChecker
  *
@@ -2291,7 +2295,7 @@ function ocspChecker(responses) {
  * @primitive  pki.path.verifyOcspResponse
  * @signature  pki.path.verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts?) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, reason }>
  * @since       0.2.22
- * @status      experimental
+ * @status      stable
  * @spec        RFC 6960
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
@@ -2318,6 +2322,20 @@ function ocspChecker(responses) {
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: caKey });
+ *   var der = await pki.ocsp.sign(
+ *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
+ *     { cert: caDer, key: caKey });
+ *   var cert = pki.schema.x509.parse(leafDer), issuerCert = pki.schema.x509.parse(caDer);
  *   var resp = pki.schema.ocsp.parseResponse(der);
  *   var v = await pki.path.verifyOcspResponse(resp, cert, issuerCert, new Date());
  *   v.status;   // "good" | "revoked" | "unknown"
@@ -2674,6 +2692,11 @@ async function _fetchAiaIssuers(current, aia) {
  * @opts  maxResponseBytes       Per-fetch response size cap, forwarded to the transport (tightenable downward only).
  * @opts  (validate options)     Every `pki.path.validate` option (`requiredEku`, `revocationChecker`, `checkPurpose`, the initial policy inputs, ...) is forwarded unchanged.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemString = await pki.x509.sign({ subject: "Example Root", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: await pki.key.export(pair.privateKey) }, { pem: true });
  *   var result = await pki.path.build(pemString, {
  *     candidates: [],              // untrusted intermediates (the openssl -untrusted set)
  *     trustAnchors: [pemString],   // a self-signed root, or a { name, publicKey, algorithm } tuple

package/lib/pkcs12-build.js

@@ -469,6 +469,10 @@ function _normalizeSpec(spec, opts) {
  *   - `recipientCerts` -- (public-key privacy convenience) `[certDer|PEM, ...]`; the convenience-form cert + key are placed in one recipient-enveloped safe (a plaintext keyBag). For the full form, set per-`safeContents` `recipients: [{ cert }, ...]` -- CERTIFICATE recipients only (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM, dispatched off the cert key); a password or KEK recipient is not public-key privacy and is rejected -- with an optional `contentEncryptionAlgorithm` (`aes-128|192|256-cbc`, default 256; GCM/AEAD rejected). `encrypt` (password) and `recipients` (public-key) on the same safe is rejected; privacy is independent of integrity.
  *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p12 = await pki.pkcs12.build({ safeContents: [{ bags: [
  *     { type: 'cert', cert: signerCertDer },
  *     { type: 'shroudedKey', key: signerKeyPkcs8, encrypt: { password: 'changeit' } } ] }] },
@@ -526,6 +530,10 @@ async function build(spec, opts) {
  * or public-key-integrity store, or an unsupported MAC algorithm (never a falsy verdict standing in for an error).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
  *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
  */
@@ -614,6 +622,10 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  *   - `keys` (string) -- `der` (default) or `crypto` (also `pki.key.import` each private key to a CryptoKey).
  *   - `importAlgorithm` -- forwarded to `pki.key.import` for the ambiguous RSA / EC arms when `keys: crypto`.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
  *   var store = await pki.pkcs12.open(p12, 'changeit');
  *   var keyDer = store.keys[0].pkcs8, certDer = store.certs[0].cert;

package/lib/schema-all.js

@@ -50,6 +50,15 @@ var attrcert = require("./schema-attrcert");
 // SEQUENCE) so it is deliberately absent from FORMATS / the detect-and-route
 // `parse`; it is reached only by explicit OID dispatch on a CMS attribute.
 var smime = require("./schema-smime");
+// cmc is likewise a COMPANION decoder, for the same reason arrived at from the
+// other direction: a CMC message's outer DER root IS a CMS ContentInfo, which
+// `cms.matches` already claims below. A `cmc` FORMATS row would either shadow CMS
+// or be shadowed by it, and there is no structurally disjoint root to detect --
+// the discriminator is the encapsulated content type, one layer in. So it is
+// reached by explicit call, or by dispatching on
+// `pki.schema.cms.parse(der).encapContentInfo.eContentType`, and exports no
+// `matches` for nobody to call.
+var cmc = require("./schema-cmc");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -276,6 +285,10 @@ function all() { return FORMATS.map(function (f) { return f.name; }); }
  * errors of the matched format propagate unchanged.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var parsed = pki.schema.parse(der);  // cert -> the pki.schema.x509 shape
  */
 function parse(input) {
@@ -294,7 +307,7 @@ function parse(input) {
  * @primitive  pki.schema.detectFormat
  * @signature  pki.schema.detectFormat(input) -> string | null
  * @since       0.3.8
- * @status      experimental
+ * @status      stable
  * @spec        RFC 5280
  * @related     pki.schema.parse, pki.schema.all
  *
@@ -307,6 +320,10 @@ function parse(input) {
  * same coercion / decode error `parse` throws.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   pki.schema.detectFormat(der);  // "x509" | "crl" | "csr" | "cms" | ... | null
  */
 function detectFormat(input) {
@@ -339,6 +356,7 @@ module.exports = {
   csrattrs: { parse: csrattrs.parse },
   attrcert: { parse: attrcert.parse, pemDecode: attrcert.pemDecode, pemEncode: attrcert.pemEncode },
   smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
+  cmc: { parse: cmc.parse, parsePkiData: cmc.parsePkiData, parsePkiResponse: cmc.parsePkiResponse },
   all: all,
   parse: parse,
   detectFormat: detectFormat,

package/lib/schema-attrcert.js

@@ -340,6 +340,15 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
  * and `Asn1Error` when the underlying DER is malformed.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var der = await pki.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key });
  *   var ac = pki.schema.attrcert.parse(der);
  *   ac.attributes[0].name;   // "role"
  *   ac.validity.notAfterTime;// Date
@@ -383,6 +392,15 @@ function parseV1(input) {
  * `PemError` on a missing / mismatched envelope or a non-base64 body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var pemText = await pki.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key }, { pem: true });
  *   var der = pki.schema.attrcert.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? null : (label || "ATTRIBUTE CERTIFICATE"), PemError); }
@@ -399,6 +417,15 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? n
  * same default `pemDecode` reads). Throws `PemError` on a malformed label.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var der = await pki.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key });
  *   var pem = pki.schema.attrcert.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "ATTRIBUTE CERTIFICATE", PemError); }

package/lib/schema-c509.js

@@ -2327,6 +2327,12 @@ function _encodeC509Array(r) {
  *     only for the DER -> type-3 path; ignored when re-emitting a parse result.
  *
  * @example
+ *   // the type-3 (natively signed) encoding covers ECDSA-signed X.509 v3 certificates
+ *   var pair = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var signerCertDer = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { keyUsage: ["digitalSignature"] } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cbor = pki.schema.c509.encode(signerCertDer);   // a DER cert -> a compact type-3 C509
  *   pki.schema.c509.parse(cbor).certificateType;        // 3
  */