From 555294fd5523bf62e529d3ffeef9137c04687fdd Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Thu, 25 Jun 2026 14:23:31 +0200 Subject: [PATCH 1/6] Add protocol registry to cryptography-defs 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 --- schema/cryptography-defs.json | 112 +++++++++++++- schema/cryptography-defs.schema.json | 222 ++++++++++++++++++++++++++- 2 files changed, 329 insertions(+), 5 deletions(-) diff --git a/schema/cryptography-defs.json b/schema/cryptography-defs.json index 5e0d20480..77b01b0b7 100644 --- a/schema/cryptography-defs.json +++ b/schema/cryptography-defs.json @@ -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", @@ -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" + ] + } + ] + } + ] + } + ] + } ] -} +} \ No newline at end of file diff --git a/schema/cryptography-defs.schema.json b/schema/cryptography-defs.schema.json index e17815057..74eadf8f1 100644 --- a/schema/cryptography-defs.schema.json +++ b/schema/cryptography-defs.schema.json @@ -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": { @@ -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": { + "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": [ @@ -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": [ + "role", + "selection", + "algorithmSet" + ] + }, + "algorithmSet": { + "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" + ] + } + ] + } } } } \ No newline at end of file From 57c5985f3c5489d0730f39e9ee9ace89685893e4 Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Thu, 20 Aug 2026 14:03:38 +0200 Subject: [PATCH 2/6] Add sub-protocol references to the protocol registry 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 --- schema/cryptography-defs.json | 115 +++++++++++++++++++++++++++ schema/cryptography-defs.schema.json | 34 +++++++- 2 files changed, 146 insertions(+), 3 deletions(-) diff --git a/schema/cryptography-defs.json b/schema/cryptography-defs.json index 77b01b0b7..260143c4b 100644 --- a/schema/cryptography-defs.json +++ b/schema/cryptography-defs.json @@ -4331,6 +4331,121 @@ ] } ] + }, + { + "family": "ike", + "description": "Internet Key Exchange (IKE) negotiates security associations and keying material for IPsec.", + "standard": [ + { + "name": "RFC7296", + "url": "https://doi.org/10.17487/RFC7296" + } + ], + "version": [ + { + "version": "2", + "standard": [ + { + "name": "RFC7296", + "url": "https://doi.org/10.17487/RFC7296" + } + ], + "composition": [ + { + "role": "encryption", + "selection": "one-of", + "selectedBy": "negotiation", + "algorithmSet": [ + "AES-128-GCM", + "AES-256-GCM", + "AES-256-CBC", + "ChaCha20-Poly1305" + ] + }, + { + "role": "prf", + "selection": "one-of", + "selectedBy": "negotiation", + "algorithmSet": [ + "HMAC-SHA-256", + "HMAC-SHA-384", + "AES-CMAC-PRF-128" + ] + }, + { + "role": "integrity", + "selection": "one-of", + "selectedBy": "negotiation", + "algorithmSet": [ + "HMAC-SHA-256-128", + "HMAC-SHA-384-192" + ] + }, + { + "role": "key-exchange", + "selection": "any-of", + "selectedBy": "negotiation", + "algorithmSet": [ + "ECDH-secp256r1", + "ECDH-secp384r1", + "x25519", + "ML-KEM-768" + ] + } + ] + } + ] + }, + { + "family": "ipsec", + "description": "Internet Protocol Security (IPsec) secures IP traffic using a key management protocol and packet protection protocols.", + "standard": [ + { + "name": "RFC4301", + "url": "https://doi.org/10.17487/RFC4301" + } + ], + "version": [ + { + "version": "3", + "standard": [ + { + "name": "RFC4301", + "url": "https://doi.org/10.17487/RFC4301" + } + ], + "composition": [ + { + "role": "key-management", + "selection": "one-of", + "selectedBy": "configuration", + "algorithmSet": [ + { + "protocol": "ike", + "version": "1" + }, + { + "protocol": "ike", + "version": "2" + } + ] + }, + { + "role": "packet-protection", + "selection": "any-of", + "selectedBy": "configuration", + "algorithmSet": [ + { + "protocol": "esp" + }, + { + "protocol": "ah" + } + ] + } + ] + } + ] } ] } \ No newline at end of file diff --git a/schema/cryptography-defs.schema.json b/schema/cryptography-defs.schema.json index 74eadf8f1..24f6be10f 100644 --- a/schema/cryptography-defs.schema.json +++ b/schema/cryptography-defs.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://cyclonedx.org/schema/cryptography-defs.schema.json", - "$comment": "2026-08-07T13:10:42Z", + "$comment": "2026-08-20T12:03:27Z", "title": "Cryptographic Definitions", "description": "Enumerates cryptographic algorithm families, elliptic curves, and protocols with their specific metadata.", "type": "object", @@ -317,6 +317,7 @@ "A5/1", "A5/2", "AES", + "ANSI-KDF", "ARIA", "Argon2", "Ascon", @@ -372,6 +373,7 @@ "RC5", "RC6", "RIPEMD", + "RSA-X931", "RSAES-OAEP", "RSAES-PKCS1", "RSASSA-PKCS1", @@ -387,13 +389,16 @@ "SM9", "SNOW3G", "SP800-108", + "SP800-56C", "SPAKE2", "SPAKE2PLUS", "SRP", + "SSH-KDF", "Salsa20", "Serpent", "SipHash", "Skipjack", + "TLS-PRF", "TUAK", "Twofish", "UMAC", @@ -664,9 +669,11 @@ "description": "An enum for the protocol families.", "enum": [ "5g-aka", + "ah", "dtls", "eap-aka", "eap-aka-prime", + "esp", "ike", "ipsec", "prins", @@ -764,10 +771,10 @@ "algorithmSet": { "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.", + "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 the concrete name of an algorithm, a named bundle of algorithms, or a reference to a sub-protocol.", "items": { "title": "Algorithm Set Member", - "description": "A member of an algorithm set: an algorithm name, or a named bundle.", + "description": "A member of an algorithm set: an algorithm name, a named bundle, or a sub-protocol reference.", "oneOf": [ { "type": "string", @@ -800,6 +807,27 @@ "name", "algorithms" ] + }, + { + "type": "object", + "title": "Sub-Protocol Reference", + "description": "A reference to a sub-protocol, by protocol family and optionally version. The composition of the sub-protocol is given by its own protocol entry in this document, which may itself reference further sub-protocols.", + "additionalProperties": false, + "properties": { + "protocol": { + "$ref": "#/definitions/protocolFamiliesEnum", + "title": "Protocol Family", + "description": "The protocol family of the referenced sub-protocol." + }, + "version": { + "type": "string", + "title": "Version", + "description": "The version of the referenced sub-protocol." + } + }, + "required": [ + "protocol" + ] } ] } From 0e18e51b4cf989403ec9cfa3408a4c5726dd1843 Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Thu, 20 Aug 2026 14:07:08 +0200 Subject: [PATCH 3/6] Reference the protocol registry from protocolProperties.type 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 --- .../cyclonedx-cryptography-2.0.schema.json | 36 ++----------------- schema/cryptography-defs.schema.json | 20 +++++++++-- 2 files changed, 20 insertions(+), 36 deletions(-) diff --git a/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json b/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json index c89aedba9..6975ebdbe 100644 --- a/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json +++ b/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json @@ -742,41 +742,9 @@ "additionalProperties": false, "properties": { "type": { - "type": "string", + "$ref": "../../cryptography-defs.schema.json#/definitions/protocolFamiliesEnum", "title": "Type", - "description": "The concrete protocol type.", - "enum": [ - "tls", - "ssh", - "ipsec", - "ike", - "sstp", - "wpa", - "dtls", - "quic", - "eap-aka", - "eap-aka-prime", - "prins", - "5g-aka", - "other", - "unknown" - ], - "meta:enum": { - "tls": "Transport Layer Security", - "ssh": "Secure Shell", - "ipsec": "Internet Protocol Security", - "ike": "Internet Key Exchange", - "sstp": "Secure Socket Tunneling Protocol", - "wpa": "Wi-Fi Protected Access", - "dtls": "Datagram Transport Layer Security", - "quic": "Quick UDP Internet Connections", - "eap-aka": "Extensible Authentication Protocol variant", - "eap-aka-prime": "Enhanced version of EAP-AKA", - "prins": "Protection of Inter-Network Signaling", - "5g-aka": "Authentication and Key Agreement for 5G", - "other": "Another protocol type", - "unknown": "The protocol type is not known" - } + "description": "The concrete protocol type. If specified, this value shall be one of the enumeration of valid protocol families defined in the `cryptography-defs.schema.json` subschema." }, "version": { "type": "string", diff --git a/schema/cryptography-defs.schema.json b/schema/cryptography-defs.schema.json index 24f6be10f..87b818b6d 100644 --- a/schema/cryptography-defs.schema.json +++ b/schema/cryptography-defs.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://cyclonedx.org/schema/cryptography-defs.schema.json", - "$comment": "2026-08-20T12:03:27Z", + "$comment": "2026-08-20T12:04:10Z", "title": "Cryptographic Definitions", "description": "Enumerates cryptographic algorithm families, elliptic curves, and protocols with their specific metadata.", "type": "object", @@ -682,7 +682,23 @@ "sstp", "tls", "wpa" - ] + ], + "meta:enum": { + "5g-aka": "Authentication and Key Agreement for 5G", + "ah": "Authentication Header", + "dtls": "Datagram Transport Layer Security", + "eap-aka": "Extensible Authentication Protocol variant", + "eap-aka-prime": "Enhanced version of EAP-AKA", + "esp": "Encapsulating Security Payload", + "ike": "Internet Key Exchange", + "ipsec": "Internet Protocol Security", + "prins": "Protection of Inter-Network Signaling", + "quic": "Quick UDP Internet Connections", + "ssh": "Secure Shell", + "sstp": "Secure Socket Tunneling Protocol", + "tls": "Transport Layer Security", + "wpa": "Wi-Fi Protected Access" + } }, "standardRefs": { "type": "array", From 2e8b48a7413a320d4e27e814de95617e25344160 Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Wed, 9 Sep 2026 13:48:14 +0200 Subject: [PATCH 4/6] Split selectedBy into mechanism and selecting party 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 --- schema/cryptography-defs.json | 10 +++++++++- schema/cryptography-defs.schema.json | 29 +++++++++++++++++++--------- 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/schema/cryptography-defs.json b/schema/cryptography-defs.json index bc8478713..429a806ef 100644 --- a/schema/cryptography-defs.json +++ b/schema/cryptography-defs.json @@ -4249,6 +4249,7 @@ "role": "key-exchange", "selection": "one-of", "selectedBy": "negotiation", + "selectingParty": "server", "algorithmSet": [ "x25519", "x448", @@ -4281,6 +4282,7 @@ "role": "signature", "selection": "one-of", "selectedBy": "negotiation", + "selectingParty": "server", "algorithmSet": [ "ECDSA-secp256r1-SHA-256", "ECDSA-secp384r1-SHA-384", @@ -4292,7 +4294,8 @@ { "role": "cert-chain-signature", "selection": "any-of", - "selectedBy": "server-selected", + "selectedBy": "configuration", + "selectingParty": "server", "algorithmSet": [ "ECDSA-secp256r1-SHA-256", "RSA-PKCS1-1.5-SHA-256", @@ -4304,6 +4307,7 @@ "role": "encryption", "selection": "one-of", "selectedBy": "negotiation", + "selectingParty": "server", "algorithmSet": [ { "name": "TLS_AES_128_GCM_SHA256", @@ -4355,6 +4359,7 @@ "role": "encryption", "selection": "one-of", "selectedBy": "negotiation", + "selectingParty": "responder", "algorithmSet": [ "AES-128-GCM", "AES-256-GCM", @@ -4366,6 +4371,7 @@ "role": "prf", "selection": "one-of", "selectedBy": "negotiation", + "selectingParty": "responder", "algorithmSet": [ "HMAC-SHA-256", "HMAC-SHA-384", @@ -4376,6 +4382,7 @@ "role": "integrity", "selection": "one-of", "selectedBy": "negotiation", + "selectingParty": "responder", "algorithmSet": [ "HMAC-SHA-256-128", "HMAC-SHA-384-192" @@ -4385,6 +4392,7 @@ "role": "key-exchange", "selection": "any-of", "selectedBy": "negotiation", + "selectingParty": "responder", "algorithmSet": [ "ECDH-secp256r1", "ECDH-secp384r1", diff --git a/schema/cryptography-defs.schema.json b/schema/cryptography-defs.schema.json index eebd78d91..ac404c97c 100644 --- a/schema/cryptography-defs.schema.json +++ b/schema/cryptography-defs.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://cyclonedx.org/schema/cryptography-defs.schema.json", - "$comment": "2026-08-20T12:04:10Z", + "$comment": "2026-09-09T11:45:42Z", "title": "Cryptographic Definitions", "description": "Enumerates cryptographic algorithm families, elliptic curves, and protocols with their specific metadata.", "type": "object", @@ -233,7 +233,7 @@ "protocols": { "type": "array", "title": "Protocol Families", - "description": "An array of cryptographic protocol family definitions.", + "description": "An array of cryptographic protocol family definitions. Each protocol family shall appear at most once, and each version at most once within its family.", "items": { "type": "object", "title": "Protocol Family", @@ -271,7 +271,7 @@ "version": { "type": "string", "title": "Version", - "description": "The version identifier of the protocol." + "description": "The version identifier of the protocol. Together with the protocol family, it identifies this entry: a BOM references it by exact match of protocolProperties.type and protocolProperties.version." }, "standard": { "$ref": "#/definitions/standardRefs", @@ -762,16 +762,27 @@ "selectedBy": { "type": "string", "title": "Selected By", - "description": "Specifies the mechanism by which the algorithms used at runtime are selected from the set.", + "description": "Specifies the mechanism by which the algorithms used at runtime are selected from the set: fixed by the protocol specification itself (protocol-fixed), fixed when the software is built (build-time), chosen by configuration (configuration), agreed between the parties at runtime (negotiation), or not known (unknown).", "enum": [ "build-time", "configuration", - "hardware", "negotiation", - "server-selected", + "protocol-fixed", "unknown" ] }, + "selectingParty": { + "type": "string", + "title": "Selecting Party", + "description": "The party of the protocol that makes the selection, named by its role in the protocol.", + "examples": [ + "client", + "server", + "initiator", + "responder", + "group-creator" + ] + }, "algorithmSet": { "$ref": "#/definitions/algorithmSet", "title": "Algorithm Set", @@ -795,7 +806,7 @@ { "type": "string", "title": "Algorithm Name", - "description": "The concrete algorithm name, matching a variant pattern of an algorithm family defined in this document." + "description": "The concrete algorithm name. The name shall match at least one variant pattern of an algorithm family defined in this document; a name matching no variant pattern does not resolve against this registry." }, { "type": "object", @@ -815,7 +826,7 @@ "items": { "type": "string", "title": "Algorithm Name", - "description": "The concrete algorithm name, matching a variant pattern of an algorithm family defined in this document." + "description": "The concrete algorithm name. The name shall match at least one variant pattern of an algorithm family defined in this document; a name matching no variant pattern does not resolve against this registry." } } }, @@ -849,4 +860,4 @@ } } } -} +} \ No newline at end of file From 0f67c4a6c825e92565a02f6106c356f2a6d465b8 Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Wed, 9 Sep 2026 13:48:14 +0200 Subject: [PATCH 5/6] Document the registry join and add protocol type tests 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 --- .../cyclonedx-cryptography-2.0.schema.json | 2 +- ...nvalid-cryptography-protocol-type-2.0.json | 21 +++++++++++++++++++ .../valid-cryptography-protocol-type-2.0.json | 21 +++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 tools/src/test/resources/2.0/invalid-cryptography-protocol-type-2.0.json create mode 100644 tools/src/test/resources/2.0/valid-cryptography-protocol-type-2.0.json diff --git a/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json b/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json index 0ed0ef518..f25beb00f 100644 --- a/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json +++ b/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json @@ -761,7 +761,7 @@ "version": { "type": "string", "title": "Protocol Version", - "description": "The version of the protocol.", + "description": "The version of the protocol. Together with the type, it identifies the corresponding protocol entry, by exact match, in the `cryptography-defs.schema.json` subschema.", "examples": [ "1.0", "1.2", diff --git a/tools/src/test/resources/2.0/invalid-cryptography-protocol-type-2.0.json b/tools/src/test/resources/2.0/invalid-cryptography-protocol-type-2.0.json new file mode 100644 index 000000000..468a66623 --- /dev/null +++ b/tools/src/test/resources/2.0/invalid-cryptography-protocol-type-2.0.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "version": 1, + "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b7b", + "components": [ + { + "type": "cryptographic-asset", + "bom-ref": "protocol-other", + "name": "Unregistered protocol", + "cryptoProperties": { + "assetType": "protocol", + "protocolProperties": { + "type": "other", + "version": "1.0" + } + } + } + ] +} diff --git a/tools/src/test/resources/2.0/valid-cryptography-protocol-type-2.0.json b/tools/src/test/resources/2.0/valid-cryptography-protocol-type-2.0.json new file mode 100644 index 000000000..83b533853 --- /dev/null +++ b/tools/src/test/resources/2.0/valid-cryptography-protocol-type-2.0.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "version": 1, + "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b7a", + "components": [ + { + "type": "cryptographic-asset", + "bom-ref": "protocol-tls-1-3", + "name": "TLS", + "cryptoProperties": { + "assetType": "protocol", + "protocolProperties": { + "type": "tls", + "version": "1.3" + } + } + } + ] +} From c77c986abbe3db8d4e3bbcb054c97f9669a40d7f Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Thu, 10 Sep 2026 15:02:33 +0200 Subject: [PATCH 6/6] add some clarification Signed-off-by: Basil Hess --- schema/2.0/model/cyclonedx-cryptography-2.0.schema.json | 4 ++-- schema/cryptography-defs.schema.json | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json b/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json index f25beb00f..8c84fbc55 100644 --- a/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json +++ b/schema/2.0/model/cyclonedx-cryptography-2.0.schema.json @@ -771,7 +771,7 @@ "cipherSuites": { "type": "array", "title": "Cipher Suites", - "description": "A list of cipher suites related to the protocol.", + "description": "A list of cipher suites related to the protocol, as configured or observed for the subject of this BOM. The protocol entry in the `cryptography-defs.schema.json` subschema describes what the protocol version itself can support or negotiate.", "items": { "$ref": "#/$defs/cipherSuite", "title": "Cipher Suite" @@ -780,7 +780,7 @@ "ikev2TransformTypes": { "type": "object", "title": "IKEv2 Transform Types", - "description": "The IKEv2 transform types supported (types 1-4), defined in [RFC 7296 section 3.3.2](https://www.ietf.org/rfc/rfc7296.html#section-3.3.2), and additional properties.", + "description": "The IKEv2 transform types supported (types 1-4), defined in [RFC 7296 section 3.3.2](https://www.ietf.org/rfc/rfc7296.html#section-3.3.2), and additional properties, as configured or observed for the subject of this BOM. The protocol entry in the `cryptography-defs.schema.json` subschema describes what the protocol version itself can support or negotiate.", "additionalProperties": false, "properties": { "encr": { diff --git a/schema/cryptography-defs.schema.json b/schema/cryptography-defs.schema.json index ac404c97c..0c8c53fd7 100644 --- a/schema/cryptography-defs.schema.json +++ b/schema/cryptography-defs.schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://cyclonedx.org/schema/cryptography-defs.schema.json", - "$comment": "2026-09-09T11:45:42Z", + "$comment": "2026-09-10T12:56:32Z", "title": "Cryptographic Definitions", "description": "Enumerates cryptographic algorithm families, elliptic curves, and protocols with their specific metadata.", "type": "object", @@ -281,7 +281,7 @@ "composition": { "type": "array", "title": "Composition", - "description": "The algorithm composition of this protocol version, as a list of functional slots that all apply together.", + "description": "The algorithm composition of this protocol version, as a list of functional slots that all apply together. It describes the protocol as specified: the algorithms a conforming implementation can support or negotiate.", "items": { "$ref": "#/definitions/compositionSlot" } @@ -817,7 +817,7 @@ "name": { "type": "string", "title": "Bundle Name", - "description": "The common name of the bundle." + "description": "The common name of the bundle, preferably the identifier assigned by the registry of the protocol, such as the IANA-registered cipher suite or named group, so that names observed in a BOM resolve against this document." }, "algorithms": { "type": "array",