From 555294fd5523bf62e529d3ffeef9137c04687fdd Mon Sep 17 00:00:00 2001 From: Basil Hess Date: Thu, 25 Jun 2026 14:23:31 +0200 Subject: [PATCH 1/3] 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/3] 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/3] 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",