Skip to content

Protocol registry: populate the TLS 1.3 protocol entry and add x509 - #1211

Open
bhess wants to merge 1 commit into
CycloneDX:2.0-devfrom
bhess:feat/protocol-registry-tls13-x509
Open

bhess wants to merge 1 commit into
CycloneDX:2.0-devfrom
bhess:feat/protocol-registry-tls13-x509

Conversation

@bhess

@bhess bhess commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Summary

Populates the protocol registry with TLS 1.3 (RFC 9846) and adds x509 as a registry entry. The TLS 1.3 placeholder from #1010 is replaced by an entry that covers every IANA TLS codepoint valid for TLS 1.3; all names follow the algorithm registry's variant patterns.

What's changed

  • protocolFamiliesEnum: adds x509. That is the only schema change.
  • TLS 1.3: key exchange (24 members, incl. ML-KEM and 7 hybrids), server and client signature (26 and 29), cipher suites (13), certificate chain via x509. The version's standard lists every document that registers an included codepoint.
  • X.509 v3: one signature slot, chosen by the issuer, 55 members from RFC 5280 and its algorithm RFCs. Protocols reference it instead of repeating the list:
{ "role": "cert-chain-signature", "selection": "all-of", "selectedBy": "protocol-fixed",
  "algorithmSet": [{ "protocol": "x509", "version": "3" }] }

Method

  • A codepoint is included if it is registered (IANA; for X.509, an OID assigned in an RFC), valid for the version, and nameable.
  • Document maturity doesn't affect inclusion; expired drafts are in.
  • Names state every parameter the codepoint fixes, e.g. AES-128-GCM-128-96, ECDHE-secp256r1.

Challenges

  • Repeating X.509 signatures in every protocol, solved by the x509 entry.
  • RFC 9846 obsoletes RFC 8446 and renumbers its sections.
  • X.509 signature OIDs have no IANA registry.
  • Missing families or pattern gaps, so these are left out for now: AEGIS, GOST, SM2 signature, HSS, composite ML-DSA, among others.
  • Expired drafts still hold IANA codepoints (SLH-DSA, curveSM2MLKEM768).

Backwards compatibility

The change is additive, and the BOM side is unchanged. IKEv2 and IPsec follow in a separate PR.

Generate the TLS 1.3 composition and a new x509 entry from per-protocol
worksheets (tools/src/main/resources/protocol-worksheets) with
tools/src/main/python/protocolRegistryGeneration.py.

- TLS 1.3: every codepoint of the IANA Supported Groups, SignatureScheme
  and Cipher Suites registries is accounted for, with a citation; names
  follow the variant patterns of the algorithm registry; based on RFC 9846.
- x509 3: the certificate signature algorithms of RFC 5280 and its
  algorithm RFCs. TLS references it for the certificate chain instead of
  repeating the list.
- protocolFamiliesEnum: add x509.

Signed-off-by: Basil Hess <bhe@zurich.ibm.com>
@bhess
bhess requested a review from a team as a code owner November 12, 2026 14:03
@bhess bhess changed the title Populate the TLS 1.3 protocol entry and add x509 Protocol registry: populate the TLS 1.3 protocol entry and add x509 Nov 12, 2026
@bhess bhess added the cap: cryptography-registry Capability: Cryptography Registry label Nov 12, 2026
"algorithmSet": [
"x25519",
"x448",
"ECDHE-secp256r1",

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.

Single-algorithm members carry only the registry name, not the protocol's own identifier. Cipher suites and hybrid groups are named bundles with the IANA name, but single groups and all signature schemes are plain strings (ECDHE-secp256r1, not secp256r1; ECDSA-secp256r1-SHA-256, not ecdsa_secp256r1_sha256).

With #1213 a BOM writes { "name": "secp256r1", "algorithms": ["ECDHE-secp256r1"] }. For cipher suites and hybrids a checker can verify that pair against this entry. For single groups and signature schemes it cannot, because the registry has no secp256r1. A BOM stating { "name": "secp256r1", "algorithms": ["ECDHE-secp384r1"] } would go unnoticed, and a consumer assessing algorithms would be judging something other than what is on the wire.

The six IANA codepoints rsa_pss_rsae_* and rsa_pss_pss_* also collapse into three names here.

Suggestion: use named bundles for single members too, so every member carries the IANA identifier.

]
},
{
"role": "cert-chain-signature",

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.

Referencing x509 v3 as a whole makes this slot broader than TLS 1.3 permits. The x509 entry includes RSA-PKCS1-1.5-MD5, and RFC 9846 section 4.5.1.3 says: "Any endpoint receiving any certificate which it would need to validate using any signature algorithm using an MD5 hash MUST abort the handshake". MD2, DSA, XMSS and HashSLH-DSA are also in the list and have no TLS SignatureScheme codepoint, so they cannot be offered in signature_algorithms_cert.

This departs from the Method rule in the description (registered and valid for the version). A consumer reading this entry as "what a conforming TLS 1.3 implementation can use" would accept an MD5-signed chain. (Trust anchor self-signatures are not validated, but that does not cover the chain.)

There is also a naming gap: x509 names omit the curve (ECDSA-SHA-256), while the TLS example in 1213 uses ECDSA-secp256r1-SHA-256 in this slot, which does not resolve against x509 .

Could the slot keep a TLS-valid subset, or restrict the reference ?

#1213 (generic composition)

"tls",
"wpa"
"wpa",
"x509"

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.

Adding x509 to this enum also changes what a BOM accepts. protocolProperties.type in the 2.0 cryptography module references protocolFamiliesEnum, so a protocol asset with "type": "x509" becomes valid. The PR description says the BOM side is unchanged.

Is a protocol asset of type x509 intended? Certificates are modelled as certificate assets, so two ways to describe the same thing would exist. If it is meant for registry references only, could the description say so?

@beatquantum

Copy link
Copy Markdown

Thank you for this. A populated TLS 1.3 entry will help consumers a great deal.

One request on scope. The inclusion rule (registered with IANA and valid for the version) works well for describing the protocol. It would help to state that the entry describes registered codepoints, rather than limiting what a CBOM may record.

Production services and interoperability testing also negotiate groups on codepoints outside the IANA registry, for example pure and hybrid groups with HQC, BIKE or FrodoKEM. If a checker treats this entry as the complete set, those groups will read as unknown or invalid, although they are exactly what an inventory should capture.

Two small additions would cover it. First, a rule for members that are not in the entry: recorded and reported as unregistered, not rejected. Second, an optional codepoint on each member. For groups outside the IANA registry it is the only stable identifier, since their names can differ between implementations and change between releases.

This connects to #1214: such groups can only be named once their algorithm families are in the registry.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cap: cryptography-registry Capability: Cryptography Registry

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants