Skip to content

CBOM: add protocol registry schema #1010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bhess wants to merge 1 commit into
base: 2.0-dev
Choose a base branch
from
+329 −5
Draft

CBOM: add protocol registry schema #1010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 110 additions & 2 deletions schema/cryptography-defs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"$schema": "http://cyclonedx.org/schema/cryptography-defs.schema.json",
"lastUpdated": "2026-02-24T00:00:00Z",
"lastUpdated": "2026-08-06T00:00:00Z",
"algorithms": [
{
"family": "RSASSA-PKCS1",
Expand Down Expand Up @@ -4224,5 +4224,113 @@
}
]
}
],
"protocols": [
{
"family": "tls",
"description": "Transport Layer Security (TLS) provides confidentiality, integrity, and authentication for communication over a network.",
"standard": [
{
"name": "IANA TLS Parameters",
"url": "https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml"
}
],
"version": [
{
"version": "1.3",
"standard": [
{
"name": "RFC8446",
"url": "https://doi.org/10.17487/RFC8446"
}
],
"composition": [
{
"role": "key-exchange",
"selection": "one-of",
"selectedBy": "negotiation",
"algorithmSet": [
"x25519",
"x448",
"ECDHE-secp256r1",
"ECDHE-secp384r1",
{
"name": "X25519MLKEM768",
"algorithms": [
"x25519",
"ML-KEM-768"
]
},
{
"name": "SecP256r1MLKEM768",
"algorithms": [
"ECDHE-secp256r1",
"ML-KEM-768"
]
},
{
"name": "SecP384r1MLKEM1024",
"algorithms": [
"ECDHE-secp384r1",
"ML-KEM-1024"
]
}
]
},
{
"role": "signature",
"selection": "one-of",
"selectedBy": "negotiation",
"algorithmSet": [
"ECDSA-secp256r1-SHA-256",
"ECDSA-secp384r1-SHA-384",
"RSA-PSS-SHA-256",
"Ed25519",
"ML-DSA-65"
]
},
{
"role": "cert-chain-signature",
"selection": "any-of",
"selectedBy": "server-selected",
"algorithmSet": [
"ECDSA-secp256r1-SHA-256",
"RSA-PKCS1-1.5-SHA-256",
"RSA-PSS-SHA-256",
"ML-DSA-65"
]
},
{
"role": "encryption",
"selection": "one-of",
"selectedBy": "negotiation",
"algorithmSet": [
{
"name": "TLS_AES_128_GCM_SHA256",
"algorithms": [
"AES-128-GCM",
"HKDF-SHA-256"
]
},
{
"name": "TLS_AES_256_GCM_SHA384",
"algorithms": [
"AES-256-GCM",
"HKDF-SHA-384"
]
},
{
"name": "TLS_CHACHA20_POLY1305_SHA256",
"algorithms": [
"ChaCha20-Poly1305",
"HKDF-SHA-256"
]
}
]
}
]
}
]
}
]
}
}
222 changes: 219 additions & 3 deletions schema/cryptography-defs.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://cyclonedx.org/schema/cryptography-defs.schema.json",
"$comment": "2026-03-05T14:27:50Z",
"title": "Cryptographic Algorithm Family Definitions",
"description": "Enumerates cryptographic algorithm families and their specific metadata.",
"$comment": "2026-08-07T13:10:42Z",
"title": "Cryptographic Definitions",
"description": "Enumerates cryptographic algorithm families, elliptic curves, and protocols with their specific metadata.",
"type": "object",
"additionalProperties": false,
"properties": {
Expand Down Expand Up @@ -229,6 +229,76 @@
"curves"
]
}
},
"protocols": {
"type": "array",
"title": "Protocol Families",
"description": "An array of cryptographic protocol family definitions.",
"items": {
"type": "object",
"title": "Protocol Family",
"description": "Defines a cryptographic protocol family and its metadata.",
"additionalProperties": false,
"properties": {
"family": {
"$ref": "#/definitions/protocolFamiliesEnum",
"title": "Protocol Family",
"description": "The name of the cryptographic protocol family."
},
"description": {
"type": [
"string",
"null"
],
"title": "Description",
"description": "A description of the protocol family."
},
"standard": {
"$ref": "#/definitions/standardRefs",
"title": "Standards",
"description": "List of standards defining or relating to the protocol family."
},
"version": {
"type": "array",
"title": "Versions",
"description": "List of versions of the protocol family, each with its algorithm composition.",
"items": {
"type": "object",
"title": "Protocol Version",
"description": "Defines a specific protocol version and its algorithm composition.",
"additionalProperties": false,
"properties": {
"version": {

@Mehrn0ush Mehrn0ush Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"type": "string",
"title": "Version",
"description": "The version identifier of the protocol."
},
"standard": {
"$ref": "#/definitions/standardRefs",
"title": "Standards",
"description": "List of standards defining or relating to this protocol version."
},
"composition": {
"type": "array",
"title": "Composition",
"description": "The algorithm composition of this protocol version, as a list of functional slots that all apply together.",
"items": {
"$ref": "#/definitions/compositionSlot"
}
}
},
"required": [
"version",
"composition"
]
}
}
},
"required": [
"family",
"version"
]
}
}
},
"required": [
Expand Down Expand Up @@ -587,6 +657,152 @@
"x963/ansit571k1",
"x963/ansit571r1"
]
},
"protocolFamiliesEnum": {
"type": "string",
"title": "Protocol Families",
"description": "An enum for the protocol families.",
"enum": [
"5g-aka",
"dtls",
"eap-aka",
"eap-aka-prime",
"ike",
"ipsec",
"prins",
"quic",
"ssh",
"sstp",
"tls",
"wpa"
]
},
"standardRefs": {
"type": "array",
"title": "Standards",
"description": "List of references to standards or registries.",
"items": {
"type": "object",
"title": "Standard Reference",
"description": "Reference to a standard or registry, including its name and URL.",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"title": "Standard Name",
"description": "The name or identifier of the standard."
},
"url": {
"type": "string",
"format": "iri-reference",
"title": "Standard URL",
"description": "A URL pointing to the standard's official documentation."
}
},
"required": [
"name",
"url"
]
}
},
"compositionSlot": {
"type": "object",
"title": "Composition Slot",
"description": "A functional slot of a protocol, holding the set of algorithms that can fill it. All slots of a composition apply together; within a slot, the selection states how many algorithms of the set are used at runtime.",
"additionalProperties": false,
"properties": {
"role": {
"type": "string",
"title": "Role",
"description": "The functional role this slot fills within the protocol.",
"examples": [
"authentication",
"cert-chain-signature",
"encryption",
"integrity",
"kdf",
"key-exchange",
"prf",
"signature"
]
},
"selection": {
"type": "string",
"title": "Selection",
"description": "Specifies how many algorithms of the set are used at runtime: all of them together (all-of), one or more, possibly simultaneously (any-of), or exactly one (one-of).",
"enum": [
"all-of",
"any-of",
"one-of"
]
},
"selectedBy": {
"type": "string",
"title": "Selected By",
"description": "Specifies the mechanism by which the algorithms used at runtime are selected from the set.",
"enum": [
"build-time",
"configuration",
"hardware",
"negotiation",
"server-selected",
"unknown"
]
},
"algorithmSet": {
"$ref": "#/definitions/algorithmSet",
"title": "Algorithm Set",
"description": "The set of algorithms that can fill this slot."
}
},
"required": [

@Mehrn0ush Mehrn0ush Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

"role",
"selection",
"algorithmSet"
]
},
"algorithmSet": {

@Mehrn0ush Mehrn0ush Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

"type": "array",
"title": "Algorithm Set",
"description": "The set of algorithms that can fill a composition slot. How many of them are used at runtime is stated by the slot's selection. Each member is either the concrete name of an algorithm, matching a variant pattern of an algorithm family defined in this document, or a named bundle of such algorithms.",
"items": {
"title": "Algorithm Set Member",
"description": "A member of an algorithm set: an algorithm name, or a named bundle.",
"oneOf": [
{
"type": "string",
"title": "Algorithm Name",
"description": "The concrete algorithm name, matching a variant pattern of an algorithm family defined in this document."
},
{
"type": "object",
"title": "Named Bundle",
"description": "A named bundle of algorithms, such as a cipher suite or a hybrid key exchange group: it is selected as one unit, and all bundled algorithms are used together.",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"title": "Bundle Name",
"description": "The common name of the bundle."
},
"algorithms": {
"type": "array",
"title": "Bundled Algorithms",
"description": "The concrete names of the algorithms composing this bundle, each matching a variant pattern of an algorithm family defined in this document.",
"items": {
"type": "string",
"title": "Algorithm Name",
"description": "The concrete algorithm name, matching a variant pattern of an algorithm family defined in this document."
}
}
},
"required": [
"name",
"algorithms"
]
}
]
}
}
}
}
Loading