@blamejs/pki 0.6.51 → 0.6.52

package/lib/cmp-verify.js

@@ -32,6 +32,10 @@ var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var cmpBuild = require("./cmp-build");
 var cmp = require("./schema-cmp");
+var cms = require("./schema-cms");
+var cmsVerify = require("./cms-verify");
+var cmsDecrypt = require("./cms-decrypt");
+var pkcs8 = require("./schema-pkcs8");
 var pkix = require("./schema-pkix");
 var pbes2 = require("./pbes2");
 var x509 = require("./schema-x509");
@@ -840,6 +844,315 @@ async function _verify(message, opts) {
   return _verifySignature(m, protectedPart, protectionAlg, protection, opts);
 }
 
+var KNOWN_OPEN_KEY_PACKAGE_OPTS = intrinsic.assign(intrinsic.create(null), {
+  key: 1, cert: 1, password: 1, trustAnchors: 1, intermediates: 1, time: 1,
+  authorizedBySharedSecret: 1,
+});
+var OID_A_KEY_PACKAGE = oid.byName("aKeyPackage");
+var OID_SIGNED_DATA = oid.byName("signedData");
+var OID_ENVELOPED_DATA = oid.byName("envelopedData");
+var OID_CM_KGA = oid.byName("cmKGA");
+
+function _keyPackageErr(reason, cause) { return _err("cmp/bad-key-package", reason, cause); }
+
+/** @internal The three shapes sec. 4.1.6 profiles out of an EnvelopedData, read from the parsed
+ * container before anything is decrypted: the structure is an EnvelopedData, exactly one party can
+ * open it, and what it holds is a SignedData. */
+function _assertKeyPackageContainer(parsed) {
+  if (parsed.contentTypeName !== "envelopedData") {
+    throw _keyPackageErr("a delivered key package is carried in a CMS EnvelopedData, and this container is a " +
+      parsed.contentTypeName + " (RFC 9483 sec. 4.1.6)");
+  }
+  var ris = parsed.recipientInfos;
+  if (!_isArray(ris) || ris.length !== 1) {
+    throw _keyPackageErr("a delivered key package names exactly one RecipientInfo, and this container names " +
+      guard.text.showValue(ris && ris.length) +
+      "; a second recipient is a second party able to open a key generated for this entity (RFC 9483 sec. 4.1.6)");
+  }
+  /** @internal A `KeyAgreeRecipientInfo` wraps the content-encryption key once per entry in its
+   * `recipientEncryptedKeys` (RFC 5652 sec. 6.2.2), each for a different recipient under one
+   * originator, so counting RecipientInfos alone would admit a second party under one of them. */
+  var reks = ris[0].recipientEncryptedKeys;
+  if (_isArray(reks) && reks.length !== 1) {
+    throw _keyPackageErr("the key agreement RecipientInfo of a delivered key package wraps the content-encryption key once, and this one wraps it " +
+      reks.length + " times; each is a party able to open a key generated for this entity (RFC 9483 sec. 4.1.6, RFC 5652 sec. 6.2.2)");
+  }
+  var eci = parsed.encryptedContentInfo;
+  if (!eci || eci.contentType !== OID_SIGNED_DATA) {
+    throw _keyPackageErr("the encrypted content of a delivered key package is declared id-signedData, and this container declares " +
+      guard.text.showValue(eci && eci.contentType) + " (RFC 9483 sec. 4.1.6)");
+  }
+}
+
+/** @internal RFC 5958 sec. 2: AsymmetricKeyPackage ::= SEQUENCE SIZE (1..MAX) OF OneAsymmetricKey.
+ * Each element is surfaced as its own DER buffer, which is what a PKCS#8 `PrivateKeyInfo` is
+ * (`PrivateKeyInfo ::= OneAsymmetricKey`), so a caller imports it without re-encoding. Copied off the
+ * decrypted content rather than sliced from it, so holding one key does not hold the package. */
+var ASYMMETRIC_KEY_PACKAGE = schema.seqOf(
+  schema.decode(function (n, ctx) {
+    if (!(n.tagClass === "universal" && n.tagNumber === asn1.TAGS.SEQUENCE && n.children && n.children.length >= 1)) {
+      throw ctx.E("cmp/bad-key-package", "an AsymmetricKeyPackage element must be a OneAsymmetricKey SEQUENCE (RFC 5958 sec. 2)");
+    }
+    /** @internal OneAsymmetricKey and a PKCS#8 PrivateKeyInfo are the same structure (RFC 5958
+     * sec. 2), so the shipped strict parser decides whether an element is one; a SEQUENCE that merely
+     * looks like a container is not a delivered key. */
+    try { pkcs8.parse(n.bytes); }
+    catch (e) { throw ctx.E("cmp/bad-key-package", "an AsymmetricKeyPackage element is not a OneAsymmetricKey (RFC 5958 sec. 2)", e); }
+    return _bufferFrom(n.bytes);
+  }),
+  { assert: "sequence", min: 1, code: "cmp/bad-key-package", what: "AsymmetricKeyPackage",
+    build: function (m) { return _map(m.items, function (it) { return it.value; }); } });
+
+function _readKeyPackage(der) {
+  var node;
+  try { node = asn1.decode(der); }
+  catch (e) { throw _keyPackageErr("the signed content is not DER", e); }
+  return schema.walk(ASYMMETRIC_KEY_PACKAGE, node, NS).result;
+}
+
+function _fixOpenKeyPackageOptions(opts, made) {
+  opts = guard.identifier.optionsObject(opts, _err, "cmp/bad-input", "pki.cmp.openKeyPackage options");
+  guard.identifier.assertKnownKeys(opts, KNOWN_OPEN_KEY_PACKAGE_OPTS, _err, "cmp/bad-input", "unknown opts field ");
+  var f = {
+    key: opts.key,
+    cert: _fixByteish(opts.cert, "cert"),
+    password: _fixSecret(opts.password, made, "password"),
+    trustAnchors: _fixCertList(opts.trustAnchors, "trustAnchors"),
+    intermediates: _fixPoolCerts(opts.intermediates, "intermediates"),
+    time: _fixTime(opts.time),
+    exempt: opts.authorizedBySharedSecret === true,
+  };
+  if (opts.authorizedBySharedSecret != null && typeof opts.authorizedBySharedSecret !== "boolean") {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret is a boolean stating that this entity protected its request with the shared secret");
+  }
+  if (f.key == null && f.password == null) {
+    throw _err("cmp/bad-input", "opening a delivered key package needs the key material the content-encryption key was protected to: opts.key (with opts.cert) for the key transport and key agreement techniques, or opts.password for the password technique (RFC 9483 sec. 4.1.6.1 to 4.1.6.3)");
+  }
+  if (f.key != null && f.password != null) {
+    throw _err("cmp/bad-input", "a delivered key package is opened by one key management technique: pass opts.key or opts.password, not both");
+  }
+  /** @internal sec. 4.1.6 offers the shared-secret exemption only to an entity that protected its
+   * request with a MAC, which is the entity opening this container with that secret. Stating it
+   * alongside a private key claims the exemption for a signature-protected exchange, where the
+   * section's requirement to validate the signer stands. */
+  if (f.exempt && f.password == null) {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret authorizes the key generation authority by the secret that protected the request, so it applies only to a container opened with opts.password (RFC 9483 sec. 4.1.6)");
+  }
+  if (f.exempt && f.trustAnchors != null) {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret and opts.trustAnchors state two different rules for authorizing the key generation authority; supply one");
+  }
+  if (!f.exempt && f.trustAnchors == null) {
+    throw _err("cmp/bad-input", "authorizing the key generation authority needs opts.trustAnchors, or opts.authorizedBySharedSecret when this entity protected its request with the shared secret (RFC 9483 sec. 4.1.6)");
+  }
+  return f;
+}
+
+async function _openKeyPackage(container, opts) {
+  var bytes = _asContentInfo(
+    guard.bytes.snapshotSource(_coerceKeyPackageBytes(container), CmpError, "cmp/bad-input", "the delivered key package container"),
+    OID_ENVELOPED_DATA, "the delivered key package container");
+  var parsed;
+  try { parsed = cms.parse(bytes); }
+  catch (e) { throw _keyPackageErr("the delivered key package container is not a CMS ContentInfo", e); }
+  _assertKeyPackageContainer(parsed);
+
+  /** @internal The profile fixes the recipient count at one, so the arm to open is named instead of
+   * matched: a caller holding only the private key need not supply the certificate as well. */
+  /** @internal Every way the container fails to open reports the one code, so the verdict carries no
+   * more than "it did not open": `pki.cms.decrypt` already collapses each secret-dependent failure to
+   * a single uniform result, and splitting that back out here would rebuild the oracle it removes. */
+  var opened;
+  try {
+    opened = await cmsDecrypt.decrypt(bytes, opts.password != null ? { password: opts.password } : { key: opts.key, cert: opts.cert },
+      { recipientIndex: 0 });
+  } catch (e) {
+    throw _keyPackageErr("the delivered key package could not be opened under the supplied key material", e);
+  }
+
+  var verdict;
+  var signedData = _asContentInfo(opened.content, OID_SIGNED_DATA, "the encrypted content");
+  try { verdict = await cmsVerify.verify(signedData, _signedDataVerifyOpts(opts)); }
+  catch (e) { throw _keyPackageErr("the SignedData wrapping the key package could not be verified", e); }
+  if (!verdict.valid) {
+    throw _keyPackageErr("the signature over the delivered key package does not verify; the SignedData reports [" +
+      intrinsic.join(_map(verdict.signers, function (s) { return s.code || "a signature mismatch"; }), ", ") + "]");
+  }
+  if (verdict.eContentType !== OID_A_KEY_PACKAGE) {
+    throw _keyPackageErr("the signed content type is " + verdict.eContentType + ", not id-ct-KP-aKeyPackage; the signature must bind what it covers to a key package (RFC 9483 sec. 4.1.6, RFC 5958 sec. 2)");
+  }
+  var signerCert = verdict.signers[0] && verdict.signers[0].cert;
+  if (!signerCert) throw _keyPackageErr("the SignedData names no signer certificate to authorize as the key generation authority");
+  _authorizeKga(verdict, signerCert, opts);
+  if (verdict.eContent == null) throw _keyPackageErr("the SignedData carries no encapsulated content, so no key package was delivered");
+  return { keys: _readKeyPackage(verdict.eContent), kga: _bufferFrom(signerCert), trusted: opts.exempt ? false : true };
+}
+
+/** @internal sec. 4.1.6: the entity "MUST use a certificate containing the additional extended key
+ * usage extension id-kp-cmKGA in order to be accepted by the EE as a legitimate key generation
+ * authority", and the EE "MUST validate the signer certificate". `pki.path.validate`'s `requiredEku`
+ * answers the RFC 5280 sec. 4.2.1.12 question (does this certificate PERMIT the purpose), which an
+ * absent extension satisfies, so the assertion is checked here as well as the chain. */
+function _authorizeKga(verdict, signerCert, opts) {
+  if (opts.exempt) return;
+  if (!verdict.trusted) {
+    throw _err("cmp/unauthorized-kga", "the certificate that signed the delivered key package does not chain to an accepted trust anchor (RFC 9483 sec. 4.1.6)");
+  }
+  var parsedSigner;
+  try { parsedSigner = x509.parse(signerCert); }
+  catch (e) { throw _err("cmp/unauthorized-kga", "the certificate that signed the delivered key package could not be read", e); }
+  if (!pkix.assertsPurpose(NS, parsedSigner, OID_CM_KGA)) {
+    throw _err("cmp/unauthorized-kga", "the certificate that signed the delivered key package does not assert the id-kp-cmKGA extended key usage, which is what a key generation authority uses to show it is one (RFC 9483 sec. 4.1.6, RFC 9480 sec. 2.2)");
+  }
+}
+
+function _signedDataVerifyOpts(opts) {
+  if (opts.exempt) return {};
+  var v = { trustAnchors: opts.trustAnchors, requiredEku: [OID_CM_KGA] };
+  if (opts.intermediates != null) v.certs = opts.intermediates;
+  if (opts.time != null) v.time = opts.time;
+  return v;
+}
+
+/** @internal The certificate options here take one certificate or a list of them, as DER or PEM, which
+ * is the shape `pki.cmp.verify` takes. `pki.cms.verify` takes `certs` as a list of DER, so the pool is
+ * normalized at the door: a single certificate forwarded unwrapped would be walked as a sequence of
+ * its own bytes and contribute nothing, and a PEM string would not be read at all. */
+function _fixPoolCerts(v, label) {
+  if (v == null) return v;
+  var list = _fixCertList(_isArray(v) ? v : [v], label);
+  return _map(list, function (c, i) {
+    if (typeof c !== "string") return c;
+    try { return x509.pemDecode(c); }
+    catch (e) { throw _err("cmp/bad-input", "opts." + label + "[" + i + "] PEM could not be decoded", e); }
+  });
+}
+
+/** @internal Both CMS layers arrive in either of two forms, and the two are structurally exclusive so
+ * neither is guessed at. A ContentInfo opens with an OBJECT IDENTIFIER naming its content type; the
+ * bare structure opens with its own `CMSVersion` INTEGER. Both forms are seen in practice. A CMP
+ * `EncryptedKey` carries the `EnvelopedData` itself (RFC 9810 sec. 5.2.2), and RFC 5652 sec. 6.1
+ * encrypts the CONTENT rather than a ContentInfo around it, so the plaintext under an `id-signedData`
+ * `encryptedContentInfo` is a `SignedData`. Each is wrapped so one code path reads both. Anything
+ * else is left alone for the ContentInfo parse to refuse by name. */
+function _asContentInfo(der, contentTypeOid, what) {
+  var node;
+  try { node = asn1.decode(der); }
+  catch (e) { throw _keyPackageErr(what + " is not DER", e); }
+  var first = node.constructed && node.children ? node.children[0] : null;
+  if (!first || first.tagClass !== "universal" || first.tagNumber !== asn1.TAGS.INTEGER) return der;
+  return b.sequence([b.oid(contentTypeOid), b.explicit(0, b.raw(der))]);
+}
+
+function _coerceKeyPackageBytes(container) {
+  if (typeof container === "string") {
+    try { return cms.pemDecode(container); }
+    catch (e) { throw _err("cmp/bad-input", "the delivered key package container PEM could not be decoded", e); }
+  }
+  return container;
+}
+
+/**
+ * @primitive pki.cmp.openKeyPackage
+ * @signature pki.cmp.openKeyPackage(container, opts) -> Promise<{ keys, kga, trusted }>
+ * @since 0.6.52
+ * @status stable
+ * @spec RFC 9483 sec. 4.1.6, RFC 5958, RFC 5652, RFC 9480 sec. 2.2
+ * @defends unauthorized-key-generation-authority (CWE-863)
+ * @related pki.cmp.session, pki.cms.decrypt, pki.cms.verify
+ *
+ * Open a centrally generated private key delivered in a CMP response (RFC 9483 sec. 4.1.6). A CA that
+ * generates the key pair on the end entity's behalf puts it in the `privateKey` field of the granted
+ * `CertifiedKeyPair`: an RFC 5958 `AsymmetricKeyPackage`, signed by the Key Generation Authority in a
+ * CMS `SignedData`, sealed to this entity in a CMS `EnvelopedData`. `container` is those
+ * `EnvelopedData` bytes (DER `Buffer` or PEM), which `pki.cmp.session` surfaces as
+ * `deliveredKey` when the session is told to accept one.
+ *
+ * The two layers are undone in order and the authority is authorized BEFORE any key material is
+ * returned. Which key management technique opens the container follows the protection of the request
+ * that asked for the key: `opts.key` (with `opts.cert`) for the key transport and key agreement
+ * techniques a signature-protected request selects (sec. 4.1.6.1, sec. 4.1.6.2), `opts.password` for
+ * the password technique a MAC-protected request selects (sec. 4.1.6.3).
+ *
+ * Authorization is the point of the verb. The section requires the signer's certificate to carry the
+ * `id-kp-cmKGA` extended key usage "in order to be accepted by the EE as a legitimate key generation
+ * authority", so a certificate that merely PERMITS the purpose by carrying no `extendedKeyUsage` at
+ * all does not authorize: the assertion must be present, and the certificate must chain to an anchor
+ * in `opts.trustAnchors`. The one exception is the section's own: an entity that protected its request
+ * with a shared secret "MAY omit the validation" and authorize the authority by that secret instead.
+ * That is stated with `opts.authorizedBySharedSecret`, it applies only to a container opened with
+ * `opts.password`, and the result then reports `trusted: false`.
+ *
+ * Returns `{ keys, kga, trusted }`. `keys` is every `OneAsymmetricKey` in the package, in order, each
+ * as its own DER `Buffer` that is a PKCS#8 `PrivateKeyInfo` ready for `pki.key.import`. `kga` is the
+ * signer certificate whose signature was checked. `trusted` says whether that certificate chained.
+ * Malformed input, an unopenable container, an unverifiable signature, or an unauthorized authority
+ * all throw a typed `CmpError`; no key material is returned on any of them.
+ *
+ * The container's shape is held to the profile where the shape decides who reads the key or what the
+ * signature covers: it must be an `EnvelopedData`, it must name exactly one `RecipientInfo`, its
+ * encrypted content type must be `id-signedData`, and the signed content type must be
+ * `id-ct-KP-aKeyPackage`. The profile's CMS version literals are not enforced, because RFC 5652
+ * sec. 5.1 and sec. 6.1 derive those from the signer and recipient forms in use and a conforming
+ * sender reaches different values. Its choice-of-form rules, the signer identifier form and the
+ * ordering of the certificates the SignedData carries, are not judged either. Both live inside the
+ * encrypted SignedData rather than in the `container` bytes, and the result carries only the signer
+ * certificate, so a caller holding a stricter profile cannot judge them from this verdict.
+ *
+ * `keys` is the whole RFC 5958 `AsymmetricKeyPackage`, which is `SIZE (1..MAX)`, so a package carrying
+ * several is opened and every key returned. RFC 9483 sec. 4.1.6 profiles that to a sequence of one,
+ * and where the count decides something it is held: a `pki.cmp.session` enrollment requires exactly
+ * one, since one grant certifies one key and every further key is one the issued certificate says
+ * nothing about. A caller using this verb on its own owns that binding.
+ *
+ * @opts
+ *   - `key` (Buffer|PEM|CryptoKey) -- this entity's private key, for a container opened by the key
+ *     transport or key agreement technique.
+ *   - `cert` (Buffer|PEM) -- the certificate for `key`. Optional: the profile fixes the recipient
+ *     count at one, so the arm is named rather than matched.
+ *   - `password` (string|Buffer) -- the shared secret, for a container opened by the password
+ *     technique. Copied at the door and wiped when the call returns.
+ *   - `trustAnchors` (Buffer|Buffer[]|PEM) -- the roots this entity accepts for the key generation
+ *     authority. REQUIRED unless `authorizedBySharedSecret` is set.
+ *   - `intermediates` (Buffer|Buffer[]|PEM) -- extra untrusted pool certificates for path building.
+ *   - `time` (Date) -- the validity instant for path validation. Defaults to the current time.
+ *   - `authorizedBySharedSecret` (boolean) -- authorize the authority by the secret that protected
+ *     the request rather than by a chain, which sec. 4.1.6 permits a MAC-protected exchange. Requires
+ *     `opts.password` and refuses `opts.trustAnchors`.
+ * @example
+ *   var nb = new Date("2026-01-01T00:00:00Z"), na = new Date("2036-01-01T00:00:00Z");
+ *   var kgaPair = await pki.key.generate("Ed25519");                       // the key generation authority
+ *   var kgaKey = await pki.key.export(kgaPair.privateKey);
+ *   var kgaCert = await pki.x509.sign({ subject: "Key Generation Authority",
+ *     subjectPublicKey: await pki.key.export(kgaPair.publicKey), notBefore: nb, notAfter: na,
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["digitalSignature", "keyCertSign"],
+ *       extendedKeyUsage: ["cmKGA"], subjectKeyIdentifier: true } }, { key: kgaKey });
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var eePair = await pki.key.generate(rsa);                              // the enrolling end entity
+ *   var eeKey = await pki.key.export(eePair.privateKey);
+ *   var eeCert = await pki.x509.sign({ subject: "Enrolling client",
+ *     subjectPublicKey: await pki.key.export(eePair.publicKey), notBefore: nb, notAfter: na,
+ *     extensions: { keyUsage: ["keyEncipherment"] } }, { key: eeKey });
+ *   var generated = await pki.key.export((await pki.key.generate("Ed25519")).privateKey);
+ *   var signedPackage = await pki.cms.sign(pki.asn1.build.sequence([pki.asn1.build.raw(generated)]),
+ *     [{ key: kgaKey, cert: kgaCert }], { eContentType: "aKeyPackage", sid: "ski" });
+ *   var deliveredKeyDer = await pki.cms.encrypt(signedPackage, [{ cert: eeCert }],
+ *     { contentEncryptionAlgorithm: "aes-256-cbc", contentType: "signedData" });
+ *   var opened = await pki.cmp.openKeyPackage(deliveredKeyDer,
+ *     { key: eeKey, cert: eeCert, trustAnchors: [kgaCert] });
+ *   opened.keys.length;                                   // 1
+ *   var privateKey = await pki.key.import(opened.keys[0]);
+ */
+function openKeyPackage(container, opts) {
+  var made = [];
+  return guard.async.deferred(async function () {
+    try {
+      return await _openKeyPackage(container, _fixOpenKeyPackageOptions(opts, made));
+    } finally {
+      guard.secret.zeroizeAll(made, CmpError, "cmp/bad-input", "the copied key package shared secret");
+    }
+  });
+}
+
 /**
  * @primitive  pki.cmp.verify
  * @signature  pki.cmp.verify(message, opts?) -> Promise<verdict>
@@ -929,6 +1242,7 @@ module.exports = {
   transfer: cmpBuild.transfer,
   wellKnownUrl: cmpBuild.wellKnownUrl,
   verify: verify,
+  openKeyPackage: openKeyPackage,
   setEngine: setEngine,
   senderBoundToCert: _senderBoundToCert,
 };

package/lib/guard-name.js

@@ -332,6 +332,55 @@ function _hostConstraintBody(s) {
   return _charAt(h, 0) === "." ? _strSlice(h, 1) : h;
 }
 
+/** @internal A label with nothing in it, which is what makes a subtree base unmatchable. The
+ * comparisons in lib/path-validate.js compare a base against a name by suffix, so a base carrying an
+ * empty label asks for a name carrying one, and a name that carries one is not a name. */
+function _hasEmptyLabel(s) {
+  if (s.length === 0) return true;
+  if (_charAt(s, 0) === "." || _charAt(s, s.length - 1) === ".") return true;
+  return _indexOf(s, "..") !== -1;
+}
+
+/** @internal Whether the comparison can read a constraint base at all, which is a narrower question
+ * than whether a caller may state one. The door holds a caller to a well-formed host name; the
+ * comparison asks only whether an empty label leaves the base matching no name, and answers such a
+ * base with no verdict rather than with no match, since an excluded subtree that matches nothing
+ * excludes nothing. The two differ in both directions. A label carrying an underscore or edged with a
+ * hyphen is not a host name the door accepts, and the suffix comparison still applies it to exactly
+ * the names it names, so it stays enforced. The reduction here is the comparison's own, so the two
+ * cannot part company over a base like "..", whose body is empty only once a leading dot the
+ * comparison keeps has been taken off.
+ *
+ * The rule follows the comparison's own branches rather than the tag alone, since one tag can be
+ * compared two ways. An rfc822Name base carrying an at-sign is matched exactly and is read as a
+ * mailbox; one without an at-sign constrains the host and is read as a subtree, as a dNSName base is.
+ *
+ * A base that reduces to nothing is read by tag, because the comparisons do not agree on it. For
+ * dNSName it names the root of the namespace and `hostConstraintMatch` matches every name, so it is
+ * readable. For rfc822Name the same reduction leaves no domain to compare and `emailMatch` matches no
+ * mailbox, and for uniformResourceIdentifier `uriMatch` reads no host, so both are unreadable.
+ * @enforced-by behavioral -- the rule has no rename-proof code shape, and the RED vectors in
+ * path-validate.test.js driving a CA's own nameConstraints extension are the guard. */
+function constraintBaseUnreadable(tag, base) {
+  if (typeof base !== "string") return true;
+  /** @internal A base carrying an at-sign names one mailbox, and `emailMatch` compares it to a name
+   * exactly, local part and domain alike, rather than as a subtree. Each half is therefore read on
+   * its own terms: the local part by the RFC 5321 sec. 4.1.2 Dot-string or Quoted-string rule, which
+   * admits an underscore and refuses an empty atom, and the domain by the empty-label rule. A
+   * bracketed address literal carries no empty label in either accepted form, so the domain rule
+   * passes it through to the comparison, which reads it whole. */
+  if (tag === 1 && _lastIndexOf(base, "@") !== -1) {
+    var mb = splitMailbox(base);
+    if (mb === null || mb === "ambiguous") return true;
+    if (!_isMailboxLocal(mb[0])) return true;
+    return _hasEmptyLabel(stripTrailingDot(mb[1]));
+  }
+  var body = stripTrailingDot(base);
+  if (body === "") return tag !== 2;
+  if (_charAt(body, 0) === ".") body = _strSlice(body, 1);
+  return _hasEmptyLabel(body);
+}
+
 /** @internal Why a name-constraint base cannot be enforced, or null when it can. A base outside the
  * form its tag names is not a narrower namespace: an empty dNSName base matches every name, and a
  * base holding characters no host name can hold matches none, so the same value that reads as a
@@ -358,11 +407,19 @@ function constraintBaseRefusal(tag, base) {
     return _isHostName(_hostConstraintBody(base)) ? null
       : "must be a host name, optionally written as a subtree with a leading dot";
   }
+  /** @internal RFC 5280 sec. 4.2.1.10 says of a URI constraint: "The constraint MUST be specified as
+   * a fully qualified domain name and MAY specify a host or a domain. Examples would be
+   * host.example.com and .example.com." Its dNSName paragraph states no such requirement, so a single
+   * label is a valid dNSName base and is not a valid URI base. A caller meets this rule at the door,
+   * whether through `pki.trust.anchor` or through the validator's subtree seeds. A base a certificate
+   * carries in its own extension never reaches a door, and `uriMatch` is what holds it to the rule
+   * there, answering `path/name-constraint-unsupported` for a host it cannot read as fully qualified.
+   * `constraintBaseUnreadable` does not judge label count and does not stand in for that check. */
   if (tag === 6) {
     var h = _hostConstraintBody(_toLowerCase(base));
     var dotted = _isHostName(h) && _indexOf(h, ".") !== -1 && !_allCharsIn(h, _DIGDOT_TABLE);
     return dotted ? null
-      : "must be a dotted host name, which is the part of a URI a certificate is compared by";
+      : "must be a fully qualified domain name, which RFC 5280 sec. 4.2.1.10 requires of a URI constraint and not of a dNSName one";
   }
   return null;
 }
@@ -473,4 +530,5 @@ module.exports = intrinsic.freeze({
   lowerAscii: lowerAscii,
   stripTrailingDot: stripTrailingDot, isFqdnHost: isFqdnHost, splitMailbox: splitMailbox,
   constraintBaseRefusal: constraintBaseRefusal,
+  constraintBaseUnreadable: constraintBaseUnreadable,
 });

package/lib/guard-parsed.js

@@ -193,6 +193,22 @@ function isRecordedAsProduced(obj) {
   return true;
 }
 
+/**
+ * The bytes a recorded parse result came from, for a consumer that has to hand DER on to a verb taking
+ * bytes rather than a parsed object. A copy, so the caller cannot reach the recorded source.
+ *
+ * Null for anything not recorded, and for a result whose fields no longer match what the parse
+ * produced: the bytes are the truth, so handing them on for an object a caller has since edited would
+ * silently discard the edit and forward something the caller did not mean.
+ *
+ * @enforced-by behavioral -- an accessor has no rename-proof shape to detect; its contract is pinned by
+ * the vectors that drive it on an unrecorded object, a recorded one, and an edited one.
+ */
+function sourceOf(obj) {
+  if (!isRecordedAsProduced(obj)) return null;
+  return _bufferFrom(_weakGet(PROVENANCE, obj).source);
+}
+
 function _shapeOf(obj) {
   var shape = _create(null);
   var keys = _allNames(obj);
@@ -278,5 +294,5 @@ module.exports = _freezeExports({
   fromTrustedSource: fromTrustedSource, recordingParser: recordingParser,
   recordingWalker: recordingWalker,
   isCert: certShape, isCrl: crlShape, isRecorded: isRecorded,
-  isRecordedAsProduced: isRecordedAsProduced,
+  isRecordedAsProduced: isRecordedAsProduced, sourceOf: sourceOf,
 });

package/lib/key.js

@@ -340,6 +340,164 @@ async function publicFromPrivate(privateKey, opts) {
   return opts.pem ? pkix.pemEncode(spki, "PUBLIC KEY", PemError) : spki;
 }
 
+/**
+ * @internal Whether a private key and a SubjectPublicKeyInfo are the two halves of one key pair, for a
+ * caller deciding whether a private key it was handed goes with a certificate it was handed.
+ *
+ * Deriving the public key and comparing does NOT answer this. A key structure states its own public
+ * half and the key engine reads what it is told: RFC 5958 sec. 2 gives a OneAsymmetricKey an optional
+ * `publicKey`, an EC key's RFC 5915 `ECPrivateKey` carries its own public point, and an RSA private
+ * key carries the modulus and public exponent outright. A structure whose private components were
+ * replaced while its stored public ones were left alone therefore derives to exactly the public key
+ * that was planted in it, and the comparison accepts a private key that cannot use the certificate.
+ *
+ * So the pair is proven by USING it, on whichever operation the key type can perform: a signature the
+ * public half verifies, a Diffie-Hellman agreement that reaches the same secret from both sides, or a
+ * key encapsulation the private half decapsulates to the same secret. Each fails for a key that merely
+ * claims the public half.
+ *
+ * What a true answer means is exactly that: the private key WORKS with this public key, on the
+ * operation its type performs. It is not a statement that every field of the private structure is
+ * internally consistent, which no operation reveals. A component the algorithm ignores, such as a bit
+ * an X25519 scalar clamps away or an ML-KEM implicit-rejection secret, is not exercised by a
+ * correspondence that succeeds, and does not stop the key from being usable with the certificate.
+ * A caller needing structural consistency has a different question, and this is not it.
+ */
+var _PAIR_DIGEST = Object.assign(Object.create(null), { rsa: "sha256", ec: "sha256" });
+var _PAIR_AGREE = Object.assign(Object.create(null), { x25519: 1, x448: 1 });
+var _PAIR_KEM = Object.assign(Object.create(null),
+  { "ml-kem-512": 1, "ml-kem-768": 1, "ml-kem-1024": 1 });
+/** @internal RFC 4055 sec. 1.2: ONE RSA key pair may be identified either by `rsaEncryption` or by
+ * `id-RSASSA-PSS`, and a delivered private key and the certificate that certifies it need not have
+ * chosen the same one. The key engine reports those two encodings as different types, so comparing
+ * types alone would call a usable pair no pair at all. They name one algorithm and are exercised
+ * together, under PSS, which is the padding the restricted encoding permits. */
+var _PAIR_RSA = Object.assign(Object.create(null), { rsa: 1, "rsa-pss": 1 });
+var _PAIR_PROBE = Buffer.from("pki.js key pair correspondence", "utf8");
+
+function _sameKeyFamily(priv, pub) {
+  if (priv.asymmetricKeyType === pub.asymmetricKeyType) return true;
+  return !!(_PAIR_RSA[guard.text.keyOf(priv.asymmetricKeyType)] &&
+    _PAIR_RSA[guard.text.keyOf(pub.asymmetricKeyType)]);
+}
+
+/** @internal How to exercise a signing pair: the digest, and any padding the encoding requires. An
+ * `id-RSASSA-PSS` key may pin the hash and salt length it is usable with, and the engine refuses any
+ * other, so a pinned value from either half is what proves the pair. */
+function _pairSignOptions(priv, pub) {
+  var privPss = priv.asymmetricKeyType === "rsa-pss", pubPss = pub.asymmetricKeyType === "rsa-pss";
+  if (!privPss && !pubPss) {
+    return { digest: _PAIR_DIGEST[guard.text.keyOf(priv.asymmetricKeyType)] || null, options: null };
+  }
+  var privDetails = _pssRestrictionOf(priv, privPss);
+  var pubDetails = _pssRestrictionOf(pub, pubPss);
+  /** @internal A half that pins nothing constrains nothing, so only two halves that BOTH pin can
+   * disagree. Both encodings pinning incompatible parameters describes no operation this pair can
+   * perform together, which is not the same as being different keys: it is reported as unexercisable
+   * rather than as a false "not a pair". Where one pins and the other does not, the pinned half
+   * supplies the parameters below and the engine enforces it against its own key. */
+  if (_pssConflict(privDetails, pubDetails)) return null;
+  var digest = privDetails.hashAlgorithm || pubDetails.hashAlgorithm || "sha256";
+  /** @internal The engine derives MGF1 from the digest and takes no separate option for it, so a half
+   * that pins a mask generator other than its own hash names an operation this pair cannot perform
+   * together. That is the same "cannot be decided" verdict two conflicting halves get, not a false
+   * report that the halves are different keys. */
+  var mgf1 = privDetails.mgf1HashAlgorithm || pubDetails.mgf1HashAlgorithm;
+  if (mgf1 != null && mgf1 !== digest) return null;
+  var salt = _pssSalt(privDetails.saltLength, pubDetails.saltLength);
+  /** @internal Null-prototype, because the engine READS this object by name. A plain object would
+   * let an inherited `saltLength` reach the signature as a restriction neither half stated. */
+  var options = Object.create(null);
+  options.padding = nodeCrypto.constants.RSA_PKCS1_PSS_PADDING;
+  if (salt != null) options.saltLength = salt;
+  return { digest: digest, options: options };
+}
+
+var _PSS_PINS = ["hashAlgorithm", "mgf1HashAlgorithm", "saltLength"];
+
+/** @internal What a half pins, as a null-prototype record carrying only what the key itself states.
+ * A half pins nothing when it is not an id-RSASSA-PSS key at all, and equally when it is one whose
+ * parameters are absent, which RFC 4055 sec. 3.1 leaves optional. Reading either through a plain
+ * object would let an inherited `saltLength` or `hashAlgorithm` answer as a restriction the key never
+ * carried, and refuse a genuine pair. */
+function _pssRestrictionOf(key, isPss) {
+  var out = Object.create(null);
+  var details = isPss ? key.asymmetricKeyDetails : null;
+  if (details == null) return out;
+  for (var i = 0; i < _PSS_PINS.length; i++) {
+    var name = _PSS_PINS[i];
+    if (Object.prototype.hasOwnProperty.call(details, name) && details[name] != null) out[name] = details[name];
+  }
+  return out;
+}
+
+/** @internal Whether two halves state a restriction that cannot be satisfied at once. RFC 4055
+ * sec. 3.3 requires the signature's hash and mask generator to match the key's, so two halves naming
+ * different ones describe no shared operation. It treats the salt length differently: "The saltLength
+ * field in the signature parameters MUST be greater or equal to that in the key parameters field",
+ * and sec. 3.1 says the field "does not need to be fixed for a given RSA key pair". Two halves naming
+ * different salt lengths are therefore both satisfied by the larger, and do not conflict. A field
+ * only one half states constrains only that half, so it cannot disagree with anything. */
+function _pssConflict(a, b) {
+  if (a.hashAlgorithm != null && b.hashAlgorithm != null && a.hashAlgorithm !== b.hashAlgorithm) return true;
+  if (a.mgf1HashAlgorithm != null && b.mgf1HashAlgorithm != null && a.mgf1HashAlgorithm !== b.mgf1HashAlgorithm) return true;
+  return false;
+}
+
+/** @internal The smallest salt length both halves accept, which is the larger of the two floors. */
+function _pssSalt(a, b) {
+  if (a == null) return b;
+  if (b == null) return a;
+  return a > b ? a : b;
+}
+
+async function correspondsTo(privateKey, spkiDer) {
+  var privDer = await _toPrivateKeyDer(privateKey);
+  var priv, pub;
+  try { priv = nodeCrypto.createPrivateKey({ key: privDer, format: "der", type: "pkcs8" }); }
+  catch (e) { throw _err("key/bad-input", "the private key could not be read", e); }
+  try { pub = nodeCrypto.createPublicKey({ key: Buffer.from(spkiDer), format: "der", type: "spki" }); }
+  catch (e) { throw _err("key/bad-input", "the public key could not be read", e); }
+  if (!_sameKeyFamily(priv, pub)) return false;
+  var kind = guard.text.keyOf(priv.asymmetricKeyType);
+  try {
+    if (_PAIR_KEM[kind]) {
+      var sealed = nodeCrypto.encapsulate(pub);
+      return guard.crypto.constantTimeEqual(nodeCrypto.decapsulate(priv, sealed.ciphertext), sealed.sharedKey);
+    }
+    if (_PAIR_AGREE[kind]) {
+      var ephemeral = nodeCrypto.generateKeyPairSync(priv.asymmetricKeyType);
+      if (!guard.crypto.constantTimeEqual(
+        nodeCrypto.diffieHellman({ privateKey: priv, publicKey: ephemeral.publicKey }),
+        nodeCrypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: pub }))) return false;
+      /** @internal The agreement proves the SCALAR, not the encoding it was handed. RFC 7748 masks the
+       * top bit of an X25519 u-coordinate before the ladder, so a public value differing from the real
+       * one only in a masked bit reaches the same secret from both sides. The certificate would then
+       * carry bytes this key does not produce, and its subjectKeyIdentifier and any pinning of it
+       * would name a key the holder does not have. These types store no public copy in the private
+       * structure for an attacker to plant, so what the scalar generates IS the canonical answer and
+       * comparing against it adds a bound the agreement alone does not give. */
+      return guard.crypto.constantTimeEqual(
+        nodeCrypto.createPublicKey(priv).export({ format: "der", type: "spki" }),
+        pub.export({ format: "der", type: "spki" }));
+    }
+    var how = _pairSignOptions(priv, pub);
+    if (how === null) {
+      throw _err("key/unsupported-algorithm", "the two halves pin incompatible RSASSA-PSS parameters, so no operation exercises them together and whether they are a pair cannot be decided");
+    }
+    var signKey = how.options ? Object.assign(Object.create(null), { key: priv }, how.options) : priv;
+    var verifyKey = how.options ? Object.assign(Object.create(null), { key: pub }, how.options) : pub;
+    return nodeCrypto.verify(how.digest, _PAIR_PROBE, verifyKey,
+      nodeCrypto.sign(how.digest, _PAIR_PROBE, signKey)) === true;
+  } catch (e) {
+    /** @internal The incompatible-parameters verdict is decided rather than caught, so it is passed
+     * through with the reason it was raised for. Rewrapping it would tell an operator the pair could
+     * not be exercised without saying that the two encodings pin conflicting parameters. */
+    if (e && e.code === "key/unsupported-algorithm" && e.isPkiError === true) throw e;
+    throw _err("key/unsupported-algorithm", "the key pair could not be exercised to decide whether its two halves correspond", e);
+  }
+}
+
 
 function _detectKeyInput(input) {
   var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: KeyError, prefix: "key" });
@@ -397,4 +555,5 @@ module.exports = {
   import: import_,
   generate: generate,
   publicFromPrivate: publicFromPrivate,
+  correspondsTo: correspondsTo,   // @internal
 };

package/lib/oid.js

@@ -174,6 +174,8 @@ var FAMILIES = Object.assign(Object.create(null), {
     countersignature: 6, challengePassword: 7, extensionRequest: 14,
     smimeCapabilities: 15, friendlyName: 20, localKeyId: 21 } },
 
+  keyPackageContentTypes: { base: [2, 16, 840, 1, 101, 2, 1, 2, 78], of: { aKeyPackage: 5 } },
+
   pkcs9CertTypes: { base: [1, 2, 840, 113549, 1, 9, 22], of: { x509Certificate: 1, sdsiCertificate: 2 } },
   pkcs9CrlTypes:  { base: [1, 2, 840, 113549, 1, 9, 23], of: { x509CRL: 1 } },
 

package/lib/path-validate.js

@@ -486,8 +486,16 @@ function ipMatch(constraint, addr) {
   return true;
 }
 
+/** @internal The one place a constraint base meets a name, so the base's form is read here and
+ * nowhere else. A caller's base met `guard.name.constraintBaseRefusal` at the door; a base a
+ * certificate carries in its own nameConstraints extension met no door, and the same rule decides it
+ * here. Answering a base outside its tag's form with no match rather than no verdict would make an
+ * excluded subtree that covers nothing exclude nothing. */
 function nameMatchesConstraint(gnTag, gnValue, base) {
   if (base.tagNumber !== gnTag) return null;
+  if (gnTag === 1 || gnTag === 2 || gnTag === 6) {
+    if (guard.name.constraintBaseUnreadable(gnTag, base.value)) return "unsupported";
+  }
   switch (gnTag) {
     case 1: return emailMatch(base.value, gnValue);
     case 2: return hostConstraintMatch(base.value, gnValue);