CBOM: add protocol registry schema by bhess · Pull Request #1010 · CycloneDX/specification

bhess · 2026-08-07T13:33:22Z

Summary

This adds a protocol registry to cryptography-defs, alongside the existing algorithm families and elliptic curves. Protocols are defined per family and version, each with its algorithm composition, so tools can answer questions like "can this protocol version negotiate a post-quantum key exchange?" without every CBOM re-describing the protocol.

The TLS 1.3 entry is illustrative for now; the list will be populated further (TLS 1.2, SSH, IKEv2, ...).

What's added

A new top-level protocols array. Each protocol version carries a composition: a list of functional slots that all apply together.

role: what the slot does (key-exchange, signature, ...); open string with examples, like variant.primitive.
selection: how many algorithms of the set are used at runtime: all-of, any-of, or one-of.
selectedBy: how that choice is made: negotiation, configuration, server-selected, ...
algorithmSet: algorithm names matching the variant patterns of the algorithm registry, or named bundles {name, algorithms[]} for cipher suites and hybrid key exchange groups.

Example, TLS 1.3 key exchange:

{
  "role": "key-exchange",
  "selection": "one-of",
  "selectedBy": "negotiation",
  "algorithmSet": [
    "x25519",
    { "name": "X25519MLKEM768", "algorithms": ["x25519", "ML-KEM-768"] }
  ]
}

Backwards compatibility

No breaking changes, protocols is optional. protocolFamiliesEnum uses the same tokens as protocolProperties.type, so a BOM references a registry entry via protocolProperties.type plus version.. no new field in the core schema needed.

Defines protocols by family and version, alongside the existing algorithm families and elliptic curves. Each version carries a composition: a list of functional slots that all apply. A slot holds an algorithm set; "selection" states whether all, one or more, or exactly one of the set are used at runtime, and "selectedBy" how that choice is made (negotiation, configuration, ...). Set members are algorithm names that resolve against the variant patterns of the algorithm registry, or named bundles of such names (cipher suites, hybrid key exchange groups). The TLS 1.3 entry is illustrative for now; the list will be populated further. Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

Mehrn0ush

Hi,
The composition model and TLS 1.3 example make sense to me. I left a few inline questions on join semantics, pattern resolution, and selectedBy; all minor while this is draft.
One more thing I didn’t inline is: the registry looks like “what a protocol version can negotiate,” while existing protocolProperties.cipherSuites / IKEv2 fields describe this instance. A short note on that layering (and how registry names relate to IANA-style identifiers in CBOMs) would make the split clearer for implementers.

Mehrn0ush · 2026-08-14T14:10:11Z

+              "description": "Defines a specific protocol version and its algorithm composition.",
+              "additionalProperties": false,
+              "properties": {
+                "version": {


How should tools join this to a BOM? Is the lookup an exact match on protocolProperties.type + protocolProperties.version → family + this version string (e.g. "1.3" only)? Worth documenting, since there’s no schema $ref or uniqueness constraint on the pair.

Yes, that's the idea: protocolProperties.type == family and protocolProperties.version == version. This is now documented on both version descriptions, together with the rule that family/version pairs shall be unique.

Mehrn0ush · 2026-08-14T14:12:06Z

+        "algorithmSet"
+      ]
+    },
+    "algorithmSet": {


Pattern matching isn’t enforced by JSON Schema here — only plain strings. right? For PQ-readiness queries, should there be a short resolution rule (or CI check) so bad names don’t silently fail lookup?

If you refer to the algorithm names in the set: right, JSON Schema only sees plain strings and can't enforce the pattern match. The rule is now stated in the descriptions ("a name shall match at least one variant pattern; a name matching no pattern does not resolve").

Mehrn0ush · 2026-08-14T14:14:57Z

+          "description": "The set of algorithms that can fill this slot."
+        }
+      },
+      "required": [


selectedBy is in the PR description and all TLS examples, but it’s not required here. Intentional, or should it be required when selection is one-of / any-of?

The mechanism might be unknown at the registry level, so omission means "unstated"; the field has meanwhile been refined into selectedBy (mechanism only, including a new protocol-fixed for selections pinned by the specification itself) plus an open selectingParty, so every positive claim has an explicit value.

A member of an algorithm set can now reference another protocol by family and optionally version, so composite protocols can be expressed: IPsec selects IKEv1 or IKEv2 for key management and uses ESP or AH for packet protection. The reference is depth one; the composition of the referenced protocol is given by its own registry entry, which may again reference sub-protocols. Adds the esp and ah protocol families, an ipsec entry, and an IKEv2 entry whose slots carry the IKEv2 transform types (encryption, prf, integrity, key exchange), including ML-KEM-768 as an additional key exchange per RFC 9370. Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

The protocol type in the cryptography model now references protocolFamiliesEnum from cryptography-defs, the same way algorithmFamily and ellipticCurve do. The family descriptions move to meta:enum on the registry enum, so the registry is the single source of the protocol vocabulary, and new families (esp, ah) become valid protocol types automatically. The other and unknown values are dropped; as with algorithmFamily, an unknown protocol type is expressed by omitting the field. Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

jkowalleck · 2026-08-24T15:24:00Z

could you add new valid/invalid test cases, if needed?

Added.. one simple positive and a negative test case.

selectedBy now only names the mechanism: protocol-fixed, build-time, configuration, negotiation, or unknown. The new optional selectingParty names who selects (client, server, initiator, responder, ...), which also covers multi-party protocols. server-selected and hardware are dropped. Also documents the registry join (exact match on family and version) and the algorithm name resolution rule. Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

protocolProperties.type plus version identify the registry entry by exact match. Adds a valid and an invalid test case for the protocol type. Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

Mehrn0ush · 2026-09-09T18:42:56Z

One small thing I'd still like to add is a note saying that the registry is describing what a protocol version can support/negotiate and that the protocolProperties.cipherSuites / IKEv2 fields are describing this BOM instance.

It might also be worth saying something about how bundle names here are intended to map to IANA-style identifiers used in CBOMs.

Other than that, I think the join docs and the selectedBy/selectingParty split look good to me.

Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

bhess · 2026-09-10T13:02:57Z

One small thing I'd still like to add is a note saying that the registry is describing what a protocol version can support/negotiate and that the protocolProperties.cipherSuites / IKEv2 fields are describing this BOM instance.

It might also be worth saying something about how bundle names here are intended to map to IANA-style identifiers used in CBOMs.

Other than that, I think the join docs and the selectedBy/selectingParty split look good to me.

Thank you, and good points. I've added a commit clarifying some of the descriptions.

bhess · 2026-09-10T13:56:12Z

+  "specVersion": "2.0",
+  "version": 1,
+  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b7a",
+  "components": [


wrap components in a definitions object

bhess · 2026-09-10T13:57:47Z

+  "specVersion": "2.0",
+  "version": 1,
+  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b7b",
+  "components": [


wrap components in a definitions object

bhess · 2026-09-10T13:59:19Z

            "type": {
-              "type": "string",
+              "$ref": "../../cryptography-defs.schema.json#/definitions/protocolFamiliesEnum",
              "title": "Type",


Rename: "Protocol type"

jkowalleck · 2026-09-10T14:59:58Z

just merged in latest base branch(2.0-dev), which adds some QA tools for the non-core schemas, like cryptography-defs.

this PR introduces some new issues.
see https://github.com/CycloneDX/specification/actions/runs/34492663259/job/102923108162?pr=1010
and the issues/findings: https://github.com/CycloneDX/specification/actions/runs/34492663259/artifacts/10158402600

bhess · 2026-09-10T15:01:42Z

just merged in latest base branch(2.0-dev), which adds some QA tools for the non-core schemas, like cryptography-defs.

this PR introduces some new issues. see https://github.com/CycloneDX/specification/actions/runs/34492663259/job/102923108162?pr=1010 and the issues/findings: https://github.com/CycloneDX/specification/actions/runs/34492663259/artifacts/10158402600

Thanks! I'll have a look.

bhess requested a review from a team as a code owner August 7, 2026 13:33

bhess added the cap: cryptography Capability: Cryptography (CBOM) label Aug 13, 2026

stevespringett marked this pull request as draft August 13, 2026 13:43

Mehrn0ush reviewed Aug 14, 2026

View reviewed changes

bhess added 2 commits August 20, 2026 14:03

stevespringett added this to the 2.0 milestone Aug 20, 2026

stevespringett added the proposed core enhancement label Aug 20, 2026

Merge branch '2.0-dev' into bhe-protocol-registry

f578871

jkowalleck reviewed Aug 24, 2026

View reviewed changes

jkowalleck and others added 3 commits September 1, 2026 16:10

Merge branch '2.0-dev' into bhe-protocol-registry

ea34c2d

Document the registry join and add protocol type tests

0f67c4a

protocolProperties.type plus version identify the registry entry by exact match. Adds a valid and an invalid test case for the protocol type. Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

add some clarification

c77c986

Signed-off-by: Basil Hess <bhe@zurich.ibm.com>

bhess force-pushed the bhe-protocol-registry branch from a9519f1 to c77c986 Compare September 10, 2026 13:02

bhess marked this pull request as ready for review September 10, 2026 13:53

bhess commented Sep 10, 2026

View reviewed changes

jkowalleck added 2 commits September 10, 2026 16:55

Merge branch '2.0-dev' into bhe-protocol-registry

ffc4845

Merge branch '2.0-dev' into bhe-protocol-registry

dcd8f24

Uh oh!

Uh oh!

Conversation

bhess commented Aug 7, 2026

Summary

What's added

Backwards compatibility

Uh oh!

Mehrn0ush left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mehrn0ush commented Sep 9, 2026

Uh oh!

bhess commented Sep 10, 2026

Uh oh!

bhess Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkowalleck commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bhess commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bhess Sep 10, 2026 •

edited

Loading

jkowalleck commented Sep 10, 2026 •

edited

Loading