@cdxgen/cdxgen 13.3.0 → 13.4.0

package/lib/helpers/bomSigner.js

@@ -14,9 +14,36 @@ const JSF_ALGORITHMS = new Map([
   ["PS256", { keyType: "rsa-pss", hash: "sha256" }],
   ["PS384", { keyType: "rsa-pss", hash: "sha384" }],
   ["PS512", { keyType: "rsa-pss", hash: "sha512" }],
-  ["ES256", { keyType: "ec", hash: "sha256", curve: "prime256v1" }],
-  ["ES384", { keyType: "ec", hash: "sha384", curve: "secp384r1" }],
-  ["ES512", { keyType: "ec", hash: "sha512", curve: "secp521r1" }],
+  [
+    "ES256",
+    {
+      keyType: "ec",
+      hash: "sha256",
+      curve: "prime256v1",
+      order:
+        0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n,
+    },
+  ],
+  [
+    "ES384",
+    {
+      keyType: "ec",
+      hash: "sha384",
+      curve: "secp384r1",
+      order:
+        0xffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973n,
+    },
+  ],
+  [
+    "ES512",
+    {
+      keyType: "ec",
+      hash: "sha512",
+      curve: "secp521r1",
+      order:
+        0x01fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffa51868783bf2f966b7fcc0148f709a5d03bb5c9b8899c47aebb6fb71e91386409n,
+    },
+  ],
   ["Ed25519", { keyType: "ed25519", hash: null }],
   ["Ed448", { keyType: "ed448", hash: null }],
   ["HS256", { keyType: "secret", hash: "sha256" }],
@@ -28,6 +55,49 @@ const SIGNATURE_MODES = ["replace", "signers", "chain"];
 
 const NESTED_TARGETS = ["components", "services", "annotations"];
 
+/**
+ * Largest number of entries accepted in a `signers` or `chain` signature.
+ * Every entry is checked against the whole signed object, so the bound keeps
+ * the cost of verifying a document proportional to its size.
+ */
+export const MAX_SIGNATURE_ENTRIES = 32;
+
+/**
+ * Members the CycloneDX 1.4 to 1.7 and 2.0 schemas define at the root of a
+ * BOM. A root signature is only accepted on an object made of these members,
+ * so a signed component, service, or annotation cannot pass as a signed BOM.
+ */
+export const BOM_ROOT_MEMBERS = Object.freeze([
+  "$schema",
+  "bomFormat",
+  "specFormat",
+  "specVersion",
+  "serialNumber",
+  "version",
+  "metadata",
+  "components",
+  "services",
+  "externalReferences",
+  "dependencies",
+  "compositions",
+  "vulnerabilities",
+  "annotations",
+  "formulation",
+  "declarations",
+  "definitions",
+  "citations",
+  "properties",
+  "signature",
+]);
+
+const BOM_ROOT_MEMBER_SET = new Set(BOM_ROOT_MEMBERS);
+
+// Members that identify a BOM. Components, services, and annotations never hold
+// them, so a nested object carrying one is refused for signing and verification.
+const BOM_IDENTITY_MEMBERS = ["bomFormat", "specFormat", "specVersion"];
+
+const MAX_LISTED_MEMBERS = 10;
+
 // DER layouts tried when checking whether raw bytes are really a key.
 const DER_KEY_LAYOUTS = [
   [crypto.createPublicKey, "spki"],
@@ -59,6 +129,31 @@ function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function listMembers(names) {
+  const shown = names.slice(0, MAX_LISTED_MEMBERS).map(displayValue);
+  if (names.length > MAX_LISTED_MEMBERS) {
+    shown.push(`and ${names.length - MAX_LISTED_MEMBERS} more`);
+  }
+  return shown.join(", ");
+}
+
+// A BOM names its format with bomFormat (CycloneDX 1.x) or specFormat (2.0).
+function hasBomIdentity(bom) {
+  return (
+    (bom.bomFormat === "CycloneDX" || bom.specFormat === "CycloneDX") &&
+    ((typeof bom.specVersion === "string" && bom.specVersion !== "") ||
+      typeof bom.specVersion === "number")
+  );
+}
+
+function unexpectedRootMembers(bom) {
+  return Object.keys(bom).filter((name) => !BOM_ROOT_MEMBER_SET.has(name));
+}
+
+function bomIdentityMembers(item) {
+  return BOM_IDENTITY_MEMBERS.filter((name) => Object.hasOwn(item, name));
+}
+
 /**
  * Deterministic JSON canonicalizer following RFC 8785 (JCS), which JSF uses to
  * produce the signed data. Values are serialized the way JSON.stringify would
@@ -88,6 +183,44 @@ function canonicalize(value) {
   return `{${members.join(",")}}`;
 }
 
+/**
+ * Returns a function that produces the UTF-8 bytes of the canonical form of
+ * `{ ...content, signature }` for any signature value, canonicalizing the
+ * content members only once. Canonical members are ordered by name, so the
+ * `signature` member always sits between the members whose names sort before
+ * it and those that sort after it.
+ *
+ * @param {Object} content - The signed object without its signature member
+ * @returns {function(Object): Buffer} - Signed bytes for the given signature member
+ */
+function signedViewSerializer(content) {
+  if (typeof content.toJSON === "function") {
+    return (signature) =>
+      Buffer.from(canonicalize({ ...content, signature }), "utf8");
+  }
+  const before = [];
+  const after = [];
+  for (const name of Object.keys(content).sort()) {
+    const member = canonicalize(content[name]);
+    if (member !== undefined) {
+      (name < "signature" ? before : after).push(
+        `${JSON.stringify(name)}:${member}`,
+      );
+    }
+  }
+  const head = Buffer.from(
+    before.length ? `{${before.join(",")},` : "{",
+    "utf8",
+  );
+  const tail = Buffer.from(after.length ? `,${after.join(",")}}` : "}", "utf8");
+  return (signature) =>
+    Buffer.concat([
+      head,
+      Buffer.from(`"signature":${canonicalize(signature)}`, "utf8"),
+      tail,
+    ]);
+}
+
 function getAlgorithm(alg) {
   const spec = typeof alg === "string" ? JSF_ALGORITHMS.get(alg) : undefined;
   if (!spec) {
@@ -308,16 +441,33 @@ function signatureOptions(key, spec) {
   return options;
 }
 
-function computeSignature(canonicalData, key, spec) {
-  const data = Buffer.from(canonicalData, "utf8");
+/**
+ * Returns the ECDSA signature (r || s) with s in the lower half of the curve
+ * order. (r, s) and (r, n - s) both verify, so emitting only the low form gives
+ * each signature a single encoding.
+ */
+function toLowS(signature, order) {
+  const size = signature.length / 2;
+  const s = BigInt(`0x${signature.subarray(size).toString("hex")}`);
+  if (s <= order >> 1n) {
+    return signature;
+  }
+  const lowS = Buffer.from(
+    (order - s).toString(16).padStart(size * 2, "0"),
+    "hex",
+  );
+  return Buffer.concat([signature.subarray(0, size), lowS]);
+}
+
+function computeSignature(data, key, spec) {
   if (spec.keyType === "secret") {
     return crypto.createHmac(spec.hash, key).update(data).digest();
   }
-  return crypto.sign(spec.hash, data, signatureOptions(key, spec));
+  const signature = crypto.sign(spec.hash, data, signatureOptions(key, spec));
+  return spec.order ? toLowS(signature, spec.order) : signature;
 }
 
-function signatureMatches(canonicalData, key, spec, signature) {
-  const data = Buffer.from(canonicalData, "utf8");
+function signatureMatches(data, key, spec, signature) {
   if (spec.keyType === "secret") {
     const expected = crypto.createHmac(spec.hash, key).update(data).digest();
     return (
@@ -385,6 +535,15 @@ function readSignatureEntries(signature) {
   }
   const form = hasSigners ? "signers" : "chain";
   const { [form]: entries, ...wrapper } = signature;
+  const wrapperMembers = Object.keys(wrapper);
+  if (wrapperMembers.includes("excludes")) {
+    throw new Error("Signatures that use JSF excludes are not supported.");
+  }
+  if (wrapperMembers.length) {
+    throw new Error(
+      `A ${form} signature may only hold the ${form} array, but it also holds ${listMembers(wrapperMembers)}.`,
+    );
+  }
   if (
     !Array.isArray(entries) ||
     !entries.length ||
@@ -392,6 +551,11 @@ function readSignatureEntries(signature) {
   ) {
     throw new Error(`The ${form} array must contain signature objects.`);
   }
+  if (entries.length > MAX_SIGNATURE_ENTRIES) {
+    throw new Error(
+      `The ${form} array has ${entries.length} entries; at most ${MAX_SIGNATURE_ENTRIES} are supported.`,
+    );
+  }
   return { form, entries, wrapper };
 }
 
@@ -401,26 +565,26 @@ function withoutValue(entry) {
 }
 
 /**
- * Builds the object whose canonical form is signed for entry `index`.
+ * Builds the signature member that is signed for entry `index`.
  *
  * Following JSF, only the `value` of the entry being processed is removed.
  * Other `signers` are removed entirely, while a `chain` entry keeps every
  * earlier entry (including its value) and drops the later ones.
  */
-function jsfSignedView(content, form, entries, wrapper, index) {
+function jsfSignedSignature(form, entries, wrapper, index) {
   if (form === "single") {
-    return { ...content, signature: withoutValue(entries[index]) };
+    return withoutValue(entries[index]);
   }
   const kept =
     form === "signers"
       ? [withoutValue(entries[index])]
       : [...entries.slice(0, index), withoutValue(entries[index])];
-  return { ...content, signature: { ...wrapper, [form]: kept } };
+  return { ...wrapper, [form]: kept };
 }
 
-function candidateViews(content, parsed, index) {
-  const views = [
-    jsfSignedView(content, parsed.form, parsed.entries, parsed.wrapper, index),
+function candidateSignatures(parsed, index) {
+  const signatures = [
+    jsfSignedSignature(parsed.form, parsed.entries, parsed.wrapper, index),
   ];
   // Appending a signers or chain entry to a single signature moves that
   // signature into the new array. It was signed in the single signature form,
@@ -430,9 +594,29 @@ function candidateViews(content, parsed, index) {
     (parsed.form === "signers" || (parsed.form === "chain" && index === 0)) &&
     !Object.keys(parsed.wrapper).length
   ) {
-    views.push(jsfSignedView(content, "single", parsed.entries, {}, index));
+    signatures.push(jsfSignedSignature("single", parsed.entries, {}, index));
   }
-  return views;
+  return signatures;
+}
+
+/**
+ * Parses a node's signature and returns a function that builds the signed bytes
+ * of an entry. The node content is canonicalized once, on first use.
+ *
+ * @param {Object} node - A signed BOM, component, service, or annotation
+ * @returns {{ parsed: Object, signedData: function(number): Buffer[] }}
+ */
+function prepareSignedNode(node) {
+  const parsed = readSignatureEntries(node.signature);
+  const { signature: _signature, ...content } = node;
+  let serialize;
+  return {
+    parsed,
+    signedData(index) {
+      serialize ??= signedViewSerializer(content);
+      return candidateSignatures(parsed, index).map(serialize);
+    },
+  };
 }
 
 function decodeSignatureValue(value) {
@@ -446,14 +630,14 @@ function decodeSignatureValue(value) {
   return signature;
 }
 
-function verifyEntry(content, parsed, index, key) {
-  const entry = parsed.entries[index];
+/**
+ * Checks one signature entry with one key. `signedData` returns the bytes the
+ * entry may cover; it is only called once the entry and key are compatible.
+ */
+function verifyEntry(entry, key, signedData) {
   const spec = getAlgorithm(entry.algorithm);
   const signature = decodeSignatureValue(entry.value);
-  if (
-    Object.hasOwn(entry, "excludes") ||
-    Object.hasOwn(parsed.wrapper, "excludes")
-  ) {
+  if (Object.hasOwn(entry, "excludes")) {
     throw new Error("Signatures that use JSF excludes are not supported.");
   }
   assertKeyMatchesAlgorithm(key, entry.algorithm, spec);
@@ -467,13 +651,117 @@ function verifyEntry(content, parsed, index, key) {
       );
     }
   }
-  return candidateViews(content, parsed, index).some((view) =>
-    signatureMatches(canonicalize(view), key, spec, signature),
+  return signedData().some((data) =>
+    signatureMatches(data, key, spec, signature),
   );
 }
 
 function mismatchReason(entry) {
-  return `The ${entry.algorithm} signature does not verify with this key: the signed content changed, or a different key made it.`;
+  return `The ${displayValue(entry.algorithm)} signature does not verify with this key: the signed content changed, or a different key made it.`;
+}
+
+/**
+ * Checks every entry of a node's signature against the trusted keys.
+ *
+ * @param {Object} node - The signed object
+ * @param {crypto.KeyObject[]} keys - Loaded verification keys
+ * @param {Object} [options]
+ * @param {boolean} [options.requireAll] - The node verifies only when every entry does
+ * @param {boolean} [options.requireEveryKey] - With requireAll, every key must also verify at least one entry
+ * @param {boolean} [options.firstMatch] - Stop at the first entry that verifies
+ * @returns {{ form: string|undefined, verified: boolean, match: Object|null, reasons: string[], entries: Object[], keysMatched: boolean[] }}
+ *   `reasons` explains a signature that could not be read; each entry carries its own reasons.
+ *   `keysMatched[i]` tells whether `keys[i]` verified at least one entry.
+ */
+function checkNode(node, keys, options = {}) {
+  const result = {
+    form: undefined,
+    verified: false,
+    match: null,
+    reasons: [],
+    entries: [],
+    keysMatched: keys.map(() => false),
+  };
+  let prepared;
+  try {
+    prepared = prepareSignedNode(node);
+  } catch (err) {
+    result.reasons.push(err.message);
+    return result;
+  }
+  const { parsed } = prepared;
+  result.form = parsed.form;
+  for (const [index, entry] of parsed.entries.entries()) {
+    const reasons = [];
+    let verified = false;
+    // The signed bytes of one entry are built at most once and released before
+    // the next entry, so memory stays proportional to the node size.
+    let data;
+    const signedData = () => {
+      data ??= prepared.signedData(index);
+      return data;
+    };
+    for (const [keyIndex, key] of keys.entries()) {
+      try {
+        if (verifyEntry(entry, key, signedData)) {
+          verified = true;
+          result.keysMatched[keyIndex] = true;
+          if (!options.requireAll) {
+            break;
+          }
+          continue;
+        }
+        reasons.push(mismatchReason(entry));
+      } catch (err) {
+        reasons.push(err.message);
+      }
+    }
+    result.entries.push({
+      index,
+      algorithm: entry.algorithm,
+      keyId: entry.keyId,
+      verified,
+      reasons: verified ? [] : [...new Set(reasons)],
+    });
+    if (verified && !result.match) {
+      result.match = entry;
+      if (options.firstMatch) {
+        break;
+      }
+    }
+  }
+  result.verified = options.requireAll
+    ? result.entries.length === parsed.entries.length &&
+      result.entries.every((entry) => entry.verified) &&
+      (!options.requireEveryKey || result.keysMatched.every(Boolean))
+    : Boolean(result.match);
+  return result;
+}
+
+function entryReasons(result) {
+  if (result.reasons.length) {
+    return result.reasons;
+  }
+  return result.entries.flatMap((entry) =>
+    entry.reasons.map((reason) =>
+      result.form === "single"
+        ? reason
+        : `${result.form}[${entry.index}]: ${reason}`,
+    ),
+  );
+}
+
+function nestedLabel(field, index, item) {
+  let name = index;
+  if (isPlainObject(item)) {
+    name =
+      item["bom-ref"] ||
+      item.name ||
+      (Array.isArray(item.subjects) && item.subjects.length
+        ? item.subjects
+        : index);
+  }
+  return `${field}[${index}] '${displayValue(name)}'`;
 }
 
 function signatureLayout(target, mode) {
@@ -486,13 +774,17 @@ function signatureLayout(target, mode) {
     };
   }
   const parsed = readSignatureEntries(existing);
-  if (parsed.form === "single") {
-    return { form: mode, entries: parsed.entries, wrapper: {} };
-  }
-  if (parsed.form !== mode) {
+  if (parsed.form !== "single" && parsed.form !== mode) {
     throw new Error("Cannot mix signature chains and multi-signers.");
   }
-  return parsed;
+  if (parsed.entries.length >= MAX_SIGNATURE_ENTRIES) {
+    throw new Error(
+      `Cannot append another ${mode} entry: a signature holds at most ${MAX_SIGNATURE_ENTRIES} entries.`,
+    );
+  }
+  return parsed.form === "single"
+    ? { form: mode, entries: parsed.entries, wrapper: {} }
+    : parsed;
 }
 
 function addSignature(target, key, spec, template, layout) {
@@ -500,22 +792,27 @@ function addSignature(target, key, spec, template, layout) {
   const entry = structuredClone(template);
   const entries = [...layout.entries, entry];
   const index = entries.length - 1;
-  const view = jsfSignedView(
-    content,
-    layout.form,
-    entries,
-    layout.wrapper,
-    index,
-  );
-  entry.value = computeSignature(canonicalize(view), key, spec).toString(
-    "base64url",
+  const signedData = signedViewSerializer(content)(
+    jsfSignedSignature(layout.form, entries, layout.wrapper, index),
   );
+  entry.value = computeSignature(signedData, key, spec).toString("base64url");
   target.signature =
     layout.form === "single"
       ? entry
       : { ...layout.wrapper, [layout.form]: entries };
 }
 
+function signatureTemplate(algorithm, publicKey, keyId) {
+  const template = { algorithm };
+  if (publicKey) {
+    template.publicKey = publicKey;
+  }
+  if (keyId !== null && keyId !== undefined && keyId !== "") {
+    template.keyId = String(keyId);
+  }
+  return template;
+}
+
 /**
  * Applies JSF signatures to the BOM and, optionally, its components, services,
  * and annotations.
@@ -525,11 +822,18 @@ function addSignature(target, key, spec, template, layout) {
  * skipped by default, because changing them would invalidate the existing root
  * signature; explicitly requesting nested signing in that case is an error.
  *
+ * The BOM root must carry `bomFormat` (or `specFormat`) and `specVersion`, and
+ * only members that CycloneDX defines at the root. A nested element that
+ * carries `bomFormat`, `specFormat`, or `specVersion` is refused. Verification
+ * rejects signatures over either shape.
+ *
  * @param {Object} bomJson - CycloneDX BOM Object
  * @param {Object} options - Signing options
  * @param {string|Buffer|Object|crypto.KeyObject} options.privateKey - Private key (PEM or KeyObject), or the shared secret for HS* algorithms
  * @param {string} [options.algorithm] - JSF algorithm identifier (default RS512). It must match the key type.
  * @param {Object} [options.publicKeyJwk] - JWK of the signing key's public key to embed
+ * @param {boolean} [options.embedPublicKey] - Embed the public key derived from the signing key when publicKeyJwk is not given. Ignored for HS* algorithms and for keys without a JWK form, such as rsa-pss.
+ * @param {boolean} [options.embedPublicKeyNested] - Also embed the public key in nested signatures (default true)
  * @param {string} [options.keyId] - Key ID to embed
  * @param {string} [options.mode] - 'replace' (default), 'signers', or 'chain'
  * @param {boolean} [options.signComponents] - Sign each component
@@ -542,6 +846,7 @@ export function signBom(bomJson, options = {}) {
     privateKey,
     algorithm = "RS512",
     publicKeyJwk = null,
+    embedPublicKeyNested = true,
     keyId = null,
     mode = "replace",
   } = options;
@@ -554,16 +859,37 @@ export function signBom(bomJson, options = {}) {
       `Unsupported signature mode: ${mode}. Use one of ${SIGNATURE_MODES.join(", ")}.`,
     );
   }
+  if (!isPlainObject(bomJson)) {
+    throw new Error("The BOM must be a JSON object.");
+  }
+  if (!hasBomIdentity(bomJson)) {
+    throw new Error(
+      'Only a CycloneDX BOM can be signed: its root needs bomFormat (or specFormat) "CycloneDX" and a specVersion.',
+    );
+  }
+  const unexpected = unexpectedRootMembers(bomJson);
+  if (unexpected.length) {
+    throw new Error(
+      `The BOM has members that CycloneDX does not define at the root of a BOM: ${listMembers(unexpected)}. Remove them before signing.`,
+    );
+  }
   const spec = getAlgorithm(algorithm);
   const signingKey = loadSigningKey(privateKey, algorithm, spec);
-  const template = { algorithm };
-  const publicKey = embeddablePublicKey(publicKeyJwk, signingKey, algorithm);
-  if (publicKey) {
-    template.publicKey = publicKey;
-  }
-  if (keyId !== null && keyId !== undefined && keyId !== "") {
-    template.keyId = String(keyId);
+  let publicKey = embeddablePublicKey(publicKeyJwk, signingKey, algorithm);
+  if (!publicKey && options.embedPublicKey && signingKey.type !== "secret") {
+    try {
+      publicKey = crypto.createPublicKey(signingKey).export({ format: "jwk" });
+    } catch {
+      // Some key types, such as rsa-pss, have no JWK form and are not embedded.
+      publicKey = undefined;
+    }
   }
+  const rootTemplate = signatureTemplate(algorithm, publicKey, keyId);
+  const nestedTemplate = signatureTemplate(
+    algorithm,
+    embedPublicKeyNested ? publicKey : undefined,
+    keyId,
+  );
 
   const appending = mode !== "replace" && bomJson.signature !== undefined;
   const requested = {
@@ -586,17 +912,24 @@ export function signBom(bomJson, options = {}) {
         `Cannot sign ${field} while appending a ${mode} signature, because that changes content covered by the existing root signature. Sign the root only (for example, --no-sign-${field}).`,
       );
     }
-    for (const item of items) {
-      if (isPlainObject(item)) {
-        plan.push([item, signatureLayout(item, mode)]);
+    for (const [index, item] of items.entries()) {
+      if (!isPlainObject(item)) {
+        continue;
       }
+      const identity = bomIdentityMembers(item);
+      if (identity.length) {
+        throw new Error(
+          `Cannot sign ${nestedLabel(field, index, item)}: it carries ${identity.join(", ")}, which only the root of a BOM may hold.`,
+        );
+      }
+      plan.push([item, signatureLayout(item, mode)]);
     }
   }
   const rootLayout = signatureLayout(bomJson, mode);
   for (const [item, layout] of plan) {
-    addSignature(item, signingKey, spec, template, layout);
+    addSignature(item, signingKey, spec, nestedTemplate, layout);
   }
-  addSignature(bomJson, signingKey, spec, template, rootLayout);
+  addSignature(bomJson, signingKey, spec, rootTemplate, rootLayout);
   return bomJson;
 }
 
@@ -609,6 +942,9 @@ export function signBom(bomJson, options = {}) {
  * embedded publicKey (if any) is the verification key, and its value covers the
  * node content plus the signature metadata as JSF defines.
  *
+ * This checks one object only. To verify a BOM, use {@link verifyBomSignatures}
+ * or {@link verifyBom}, which also require the signed root to be a BOM.
+ *
  * @param {Object} node - The BOM or granular object to verify
  * @param {string|Buffer|Object|crypto.KeyObject} publicKey - Verification key. Strings and Buffers are parsed as public keys; use loadSharedSecret() for HMAC.
  * @param {Object} [options]
@@ -620,35 +956,189 @@ export function verifyNode(node, publicKey, options = {}) {
     return false;
   }
   const key = loadVerificationKey(publicKey);
-  const reasons = Array.isArray(options.reasons) ? options.reasons : undefined;
-  let parsed;
-  try {
-    parsed = readSignatureEntries(node.signature);
-  } catch (err) {
-    reasons?.push(err.message);
-    return false;
+  const result = checkNode(node, [key], { firstMatch: true });
+  if (result.match) {
+    return result.match;
   }
-  const { signature: _signature, ...content } = node;
-  const rejected = [];
-  for (let index = 0; index < parsed.entries.length; index++) {
-    const label = parsed.form === "single" ? "" : `${parsed.form}[${index}]: `;
-    try {
-      if (verifyEntry(content, parsed, index, key)) {
-        return parsed.entries[index];
+  if (Array.isArray(options.reasons)) {
+    options.reasons.push(...entryReasons(result));
+  }
+  return false;
+}
+
+/**
+ * Verifies the signatures of a BOM against one or more trusted keys and reports
+ * the outcome for every signature entry.
+ *
+ * The BOM verifies when:
+ * - its root carries `bomFormat` (or `specFormat`) "CycloneDX" and
+ *   `specVersion`, and only members that CycloneDX defines at the root of a BOM;
+ * - its root signature verifies, meaning at least one entry verifies with one
+ *   of the keys. With `requireAll`, every entry must verify with one of the
+ *   keys, and every key must verify at least one entry;
+ * - with `deep`, every signed component, service, and annotation verifies the
+ *   same way and carries none of `bomFormat`, `specFormat`, and `specVersion`.
+ *
+ * A BOM without a root signature fails unless `allowNestedOnly` is set. Then
+ * every component, service, and annotation must carry a signature that
+ * verifies, and `notices` lists the members that no signature covers.
+ *
+ * Parse untrusted BOM text with `parseStrictJson()` from
+ * `lib/parsers/strictJson.js` before calling this function, so that the
+ * verified values are the values every JSON parser reads.
+ *
+ * @param {Object} bom - CycloneDX BOM Object
+ * @param {Array<string|Buffer|Object|crypto.KeyObject>|string|Buffer|Object|crypto.KeyObject} keys - Trusted verification keys (see verifyNode)
+ * @param {Object} [options]
+ * @param {boolean} [options.deep] - Also verify nested signatures (default true)
+ * @param {boolean} [options.allowNestedOnly] - Accept a BOM without a root signature when every nested element is signed
+ * @param {boolean} [options.requireAll] - Require every entry of each signature to verify, and every key to verify an entry of the root signature
+ * @returns {{ verified: boolean, errors: string[], notices: string[], root: Object|null, nested: Object[] }}
+ *   `root` and each `nested` item hold `label`, `form`, `verified`, `match` (the first verified entry),
+ *   `reasons` (why the signature could not be read), `entries` (`index`, `algorithm`, `keyId`, `verified`, `reasons`),
+ *   and `keysMatched` (whether each key verified an entry).
+ */
+export function verifyBomSignatures(bom, keys, options = {}) {
+  const deep = options.deep !== false;
+  const allowNestedOnly = Boolean(options.allowNestedOnly);
+  const requireAll = Boolean(options.requireAll);
+  const trustedKeys = (Array.isArray(keys) ? keys : [keys]).map((key) =>
+    loadVerificationKey(key),
+  );
+  if (!trustedKeys.length) {
+    throw new Error("At least one verification key is required.");
+  }
+  const report = {
+    verified: false,
+    errors: [],
+    notices: [],
+    root: null,
+    nested: [],
+  };
+  if (!isPlainObject(bom)) {
+    report.errors.push("The BOM must be a JSON object.");
+    return report;
+  }
+  if (!hasBomIdentity(bom)) {
+    report.errors.push(
+      'The signed object is not a CycloneDX BOM: its root needs bomFormat (or specFormat) "CycloneDX" and a specVersion.',
+    );
+  }
+  const unexpected = unexpectedRootMembers(bom);
+  if (unexpected.length) {
+    report.errors.push(
+      `The BOM has members that CycloneDX does not define at the root of a BOM: ${listMembers(unexpected)}.`,
+    );
+  }
+  const nestedOnly = bom.signature === undefined;
+  if (!nestedOnly) {
+    report.root = {
+      label: "BOM",
+      ...checkNode(bom, trustedKeys, { requireAll, requireEveryKey: true }),
+    };
+    const unmatched = report.root.keysMatched.flatMap((matched, index) =>
+      matched ? [] : [`#${index + 1}`],
+    );
+    if (requireAll && report.root.form && unmatched.length) {
+      report.errors.push(
+        `No entry of the root signature verifies with key ${unmatched.join(", ")}, so a signature expected from that key is missing.`,
+      );
+    }
+  } else if (!allowNestedOnly) {
+    report.errors.push(
+      "The BOM has no root signature, so no signature covers the BOM as a whole.",
+    );
+  } else if (!deep) {
+    report.errors.push(
+      "The BOM has no root signature, and nested signatures were not checked.",
+    );
+  }
+  if (deep) {
+    let signedCount = 0;
+    for (const field of NESTED_TARGETS) {
+      const items = bom[field];
+      if (items === undefined) {
+        continue;
+      }
+      if (!Array.isArray(items)) {
+        if (nestedOnly) {
+          report.errors.push(`${field} is not an array of signed objects.`);
+        }
+        continue;
+      }
+      const unsigned = [];
+      for (const [index, item] of items.entries()) {
+        const label = nestedLabel(field, index, item);
+        if (!isPlainObject(item) || item.signature === undefined) {
+          unsigned.push(label);
+          continue;
+        }
+        signedCount++;
+        const identity = bomIdentityMembers(item);
+        if (identity.length) {
+          report.errors.push(
+            `${label} carries ${identity.join(", ")}, which only the root of a BOM may hold.`,
+          );
+        }
+        report.nested.push({
+          label,
+          ...checkNode(item, trustedKeys, { requireAll }),
+        });
+      }
+      if (nestedOnly && unsigned.length) {
+        report.errors.push(
+          `${unsigned.length} of ${items.length} ${field} are not signed, starting with ${unsigned[0]}.`,
+        );
       }
-      rejected.push(`${label}${mismatchReason(parsed.entries[index])}`);
-    } catch (err) {
-      rejected.push(`${label}${err.message}`);
+    }
+    if (nestedOnly && allowNestedOnly) {
+      if (!signedCount) {
+        report.errors.push("The BOM has no signatures.");
+      }
+      const uncovered = Object.keys(bom).filter(
+        (name) => !NESTED_TARGETS.includes(name),
+      );
+      report.notices.push(
+        uncovered.length
+          ? `Without a root signature, no signature covers ${listMembers(uncovered)}, or which components, services, and annotations the BOM lists and in what order.`
+          : "Without a root signature, no signature covers which components, services, and annotations the BOM lists or in what order.",
+      );
     }
   }
-  reasons?.push(...rejected);
-  return false;
+  report.verified =
+    !report.errors.length &&
+    (report.root ? report.root.verified : allowNestedOnly && deep) &&
+    report.nested.every((item) => item.verified);
+  return report;
+}
+
+/**
+ * Flattens a {@link verifyBomSignatures} report into the reasons it did not
+ * verify: policy errors first, then each rejected root entry, then each
+ * rejected nested entry prefixed with the element it belongs to.
+ *
+ * @param {Object} report - Result of verifyBomSignatures
+ * @returns {string[]} - Reasons, empty when the report verified
+ */
+export function signatureReportReasons(report) {
+  const reasons = [...report.errors];
+  if (report.root && !report.root.verified) {
+    reasons.push(...entryReasons(report.root));
+  }
+  for (const item of report.nested) {
+    if (!item.verified) {
+      reasons.push(
+        ...entryReasons(item).map((reason) => `${item.label}: ${reason}`),
+      );
+    }
+  }
+  return reasons;
 }
 
 /**
  * Verifies a BOM's top-level signature, as well as nested components, services,
- * and annotations. Returns the root match only if the root signature is valid
- * AND every signed nested element is valid for the same key.
+ * and annotations, with one key. Returns the root match only if the BOM verifies
+ * as {@link verifyBomSignatures} defines with `deep` enabled.
  *
  * @param {Object} bom - CycloneDX BOM Object
  * @param {string|Buffer|Object|crypto.KeyObject} publicKey - Verification key (see verifyNode)
@@ -656,44 +1146,25 @@ export function verifyNode(node, publicKey, options = {}) {
  * @returns {boolean|Object} - Signature object if valid. False otherwise.
  */
 export function verifyBom(bom, publicKey, options = {}) {
-  if (!bom?.signature) {
+  if (!isPlainObject(bom) || !bom.signature) {
     return false;
   }
-  const key = loadVerificationKey(publicKey);
-  const reasons = Array.isArray(options.reasons) ? options.reasons : undefined;
-  const rootMatch = verifyNode(bom, key, options);
-  if (!rootMatch) {
-    return false;
+  const report = verifyBomSignatures(bom, [publicKey]);
+  if (report.verified) {
+    return report.root.match;
   }
-  for (const field of NESTED_TARGETS) {
-    if (!Array.isArray(bom[field])) {
-      continue;
-    }
-    for (const [index, item] of bom[field].entries()) {
-      if (!item?.signature) {
-        continue;
-      }
-      const nestedReasons = [];
-      if (!verifyNode(item, key, { ...options, reasons: nestedReasons })) {
-        const name = displayValue(
-          item["bom-ref"] || item.name || item.subject || index,
-        );
-        for (const reason of nestedReasons) {
-          reasons?.push(`${field}[${index}] '${name}': ${reason}`);
-        }
-        return false;
-      }
-    }
+  if (Array.isArray(options.reasons)) {
+    options.reasons.push(...signatureReportReasons(report));
   }
-  return rootMatch;
+  return false;
 }
 
 /**
  * Checks every signature entry of a node against a set of trusted keys. An
  * entry is verified when one of the keys verifies that entry.
  *
- * `cdx-sign` uses this before appending to a signature chain, because the new
- * chain entry vouches for every earlier entry.
+ * `cdx-sign` uses this before appending a `signers` or `chain` entry, to check
+ * that the content still carries the earlier signatures.
  *
  * @param {Object} node - The BOM or granular object whose signature is checked
  * @param {Array<string|Buffer|Object|crypto.KeyObject>} [keys] - Trusted verification keys (see verifyNode)
@@ -704,40 +1175,17 @@ export function checkSignatureEntries(node, keys = []) {
     return [];
   }
   const trustedKeys = keys.map((key) => loadVerificationKey(key));
-  let parsed;
-  try {
-    parsed = readSignatureEntries(node.signature);
-  } catch (err) {
+  const result = checkNode(node, trustedKeys);
+  if (result.reasons.length) {
     return [
       {
         index: 0,
         algorithm: undefined,
         keyId: undefined,
         verified: false,
-        reasons: [err.message],
+        reasons: result.reasons,
       },
     ];
   }
-  const { signature: _signature, ...content } = node;
-  return parsed.entries.map((entry, index) => {
-    const reasons = [];
-    const verified = trustedKeys.some((key) => {
-      try {
-        if (verifyEntry(content, parsed, index, key)) {
-          return true;
-        }
-        reasons.push(mismatchReason(entry));
-      } catch (err) {
-        reasons.push(err.message);
-      }
-      return false;
-    });
-    return {
-      index,
-      algorithm: entry.algorithm,
-      keyId: entry.keyId,
-      verified,
-      reasons: verified ? [] : [...new Set(reasons)],
-    };
-  });
+  return result.entries;
 }