The cryptographic relationship model
A profile states which facts a CBOM must disclose. Those statements are only as precise as the terms they use. The terms defined here are used throughout the methodology, and they must be settled before a profile can be written.
Why this section exists
The questions that CBOMs are asked to answer are mostly questions about use, not about inventory. "Which algorithms does this product implement?" is an inventory question, and it is the easier one. "Which of our connections would still be readable if an adversary recorded them today?" is a question about where cryptography is applied, between whom, and under what negotiated terms. Migration planning, procurement conformance, and incident response all depend more on the second kind of question than on the first.
Current CBOM standards answer the first question well. They provide objects for algorithms, keys, certificates, and protocols, with fields for their parameters. They provide no object for the use of those assets between two parties. As a result, facts that belong to a connection have to be attached to the nearest asset. This works while a product has one obvious connection. It becomes unreliable as soon as a product has more than one.
This has a direct effect on profiles. The example profile requires a document to declare the product's cryptographic interfaces, and to declare a management interface or state that there is none. That requirement only works if three things are true. "Interface" must have an agreed definition. An interface must be clearly different from an algorithm or a port. And a producer and a consumer must count the same interfaces when they read the same document. Product rule P2 is a statement about relationships, and it is checkable only because the terms below are fixed.
The terms are fixed in five steps. First, the three terms are defined, together with what counts as one interface. Second, the boundary between them is drawn by showing what is not a relationship. Third, worked examples test the assumptions that a simple TLS session makes easy to hold. Fourth, the product record and the deployment record are set apart, and the join between them is defined. Fifth, one case that the current model does not cover is recorded.
What is binding. The definitions are normative: the three terms in the table below, what counts as one interface, and a connection as the join of its two ends. They are restated in Terms, and every requirement is written in them. A profile that uses these words must use them with these meanings. The rest of this section is informative. The worked examples, the taxonomy and the known limitations explain the definitions, and they can change without a new version of the definitions.
The three terms
| Term | Definition | In the example |
|---|---|---|
| Cryptographic relationship (edge / interface) | The location at which cryptography is applied between parties. It is not itself a cryptographic asset. | The TLS 1.3 session on Keycloak's HTTPS listener; the OIDC token signature carried inside it. |
| Endpoint (node) | A party to a relationship. | client (browser) and server (Keycloak) for TLS; issuer (Keycloak) and relying-party (client application) for the token. |
| Cryptographic asset | An algorithm, protocol, certificate, or key used by the relationship. | X25519, AES-256-GCM, RS256, the server certificate, and OpenJDK 21, which implements the TLS layer. |
Why the term is "relationship"
Two other terms were considered and set aside. Interface reads naturally for a network connection between two systems. However, it is too narrow. It suggests two parties communicating at the same moment over a link, and several of the cases below do not fit that description. The profile keeps the word in the attribute names interfaceType and interfaceId. Those attributes apply only to the relationships that are interfaces. The word is not used as the general term. Cryptographic context conflicts with established usage, where a context is the runtime state held by a cipher implementation. Cryptographic relationship has no prior technical meaning in this field, and it describes what the thing is. For these reasons it is the settled term.
Where the methodology does say interface, it means a cryptographic interface. CycloneDX 2.0 has its own blueprint "interface", with types such as rest and cli, which describes a deployed system for threat analysis. That is a different concept. Where the two could be confused, the methodology writes "cryptographic interface".
An interface is a logical boundary, not a port
A cryptographic interface is a logical boundary at which cryptography is applied. It is not a port, a listener or a socket. Two layers of cryptography can protect traffic on one port, and each layer is then its own interface. The producer describes each layer in its own terms.
Keycloak shows the usual case. Its HTTPS listener on port 8443 carries signed OIDC tokens and SAML assertions:
- The TLS layer is one interface, with protocol
TLS. Its key exchange comes from the JDK 21 in the container image, with X25519 first. - The OIDC token layer is another interface, with protocol
OIDC. Itsauthenticationis the token signature, RS256 by default. ItskeyExchangeis how a token encryption key would reach the recipient. Token encryption is off by default, so the value isnone. - The SAML layer is a third interface, with protocol
SAMLand RSA-SHA256 signatures.
The layers migrate on different timetables and depend on different standards. Keycloak's own TLS waits on the Java runtime (JEP 527). ML-DSA token signing is committed upstream (issue #43690), and it waits on the JOSE AKP key type, which is still an Internet-Draft. One entry for "port 8443" could not state both.
An application-layer interface counts as an interface when it applies cryptography of its own, or when anyone can reach it without transport protection. Keycloak's plaintext HTTP listener is reachable without protection, so it counts, and it declares none for every algorithm. Keycloak's health and metrics endpoints apply no cryptography of their own and ride the management listener, so the management listener's interface covers them. Without this rule, interface counts and the coverage statement would vary with how many services a producer chose to list. See decision 0022 (K2 and K7).
In CycloneDX 2.0, an application-layer interface such as OIDC, SAML, an administrative API or plain HTTP is a component of type: "service". CycloneDX's protocol types cover security protocols only, such as TLS, SSH and IPsec. The mapping records how a service is linked to the transport that carries it.
A fourth thing: what the cryptography is for
A relationship says where cryptography is applied and an asset says what is applied. Neither says what job the cryptography is doing. The job determines when the cryptography can change. A cryptographic purpose is that job: establishing a key, encrypting, proving identity, protecting a message from modification, signing something that must verify years later, protecting keys, deriving keys.
A purpose is not the same as an operation, and the two are easily confused. CycloneDX records operations in cryptoFunctions: sign, verify, encrypt, keyagreement. A TLS certificate signature and a firmware signature are both sign and verify. The TLS certificate signature proves identity during a session. It can change when the certificate hierarchy changes. The firmware signature must still verify long after it was written. It can change only when the last verifier in the field has been upgraded. The operation is the same, but the two signatures do different work and may change in different decades. An operation describes what the algorithm does. A purpose describes how the algorithm is used. Only the use determines a migration timetable.
Two consequences follow for anyone writing rules.
A purpose does not partition assets. AES-GCM serves encryption and data integrity at the same time, and a certificate signature can serve entity authentication in one deployment and non-repudiation in another. A rule written as "each algorithm has a purpose" is therefore wrong. An asset may serve several purposes. For the same reason, the number of purposes at an interface is not the number of algorithms it uses.
A purpose belongs to a relationship, not to a product. A product that terminates TLS and also signs firmware is doing different jobs at different boundaries, on different schedules. A purpose is attached where the cryptography is applied, which is the relationship. The same product may therefore hold one purpose in a settled state at one interface and in an unsettled state at another.
The vocabulary of purposes is listed in Terms. Terms also sets out the four-part test that an entry has to pass before it is added. The PQC Migration profile shows why the distinction matters. That profile states capability once for each purpose. It does so because key agreement and identity proof migrate on different timetables. A single answer covering both would have to report the worse of the two.
What is not a relationship
The distinction is easier to understand by looking at facts that do not belong to a relationship. Each row below pairs a node fact with the matching edge fact. A node fact is a property of a thing, such as a product, a library or a certificate. An edge fact is a property of one use of that thing between parties. The left column is what an asset inventory records. The right column is what a migration decision needs.
| Node fact (a property of a thing) | Edge fact (a property of a use) |
|---|---|
| The product supports AES-256-GCM. | This connection negotiated AES-256-GCM. |
| OpenJDK 21 is present in the Keycloak container image. | OpenJDK 21 performs the key exchange on this interface. |
| The certificate is signed with ECDSA P-384. | This session authenticates the server using that certificate. |
| The device holds an ML-KEM implementation. | This link to the peer falls back to a classical group. |
| The archive is encrypted with AES-256. | The key protecting the archive is wrapped with RSA-2048 and must survive the retention period. |
Both columns describe the product and how it is used. A CBOM may also say who can use a technical capability of the product. For example, updateAuthority names the parties from which the update mechanism accepts firmware. That is a property of the mechanism. A CBOM does not record commercial terms, such as support periods, service levels, prices or contract conditions. Those belong to the relationship between the parties, and the contract records them.
The most common modelling error is to record a left-column fact and treat it as though it answered a right-column question. Capability is not the same as use. The fact that a product can perform an operation is not evidence that any particular connection performs it.
Worked examples
A single TLS session makes the terms easy to state. It also makes them easy to underestimate, because the two parties are obvious and are present at the same moment. Each of the following examples breaks a different assumption that the TLS case makes seem true.
1 · One apparent connection is several relationships
A browser connects to a service through a content delivery network or a load balancer. The user sees one padlock. There are at least two relationships, and the cryptography on each is chosen independently. It is common for the public leg to be modern while the leg behind it uses an older protocol version, or none at all, on the reasoning that the network is private.
The Keycloak deployment example has exactly this shape. The illustrative operator, Example Org, ends TLS at an nginx ingress with OpenSSL 3.5 at sso.example.org. The ingress forwards plain HTTP to Keycloak on port 8080, with http-enabled=true. That is the normal configuration behind a TLS-terminating proxy. The operator's configured record declares both legs, and the hop to Keycloak carries tokens and credentials in clear inside the cluster.
2 · The parties are separated in time, not space
An encrypted backup or archive has two parties: the process that writes it and whatever reads it later. There is no session, and the second party may not exist yet. The relationship still has all the properties that matter, including a lifetime, which here is the retention period rather than the duration of a connection.
This case determines how urgent the harvest-now-decrypt-later risk is. The bulk encryption algorithm is usually adequate. The exposure is in the key wrapping. Whether that exposure matters depends on how long the data must stay confidential. That period is a property of the relationship, not of any algorithm used in it.
3 · The parties never interact
A publisher signs firmware or code. A relying party verifies the signature, possibly years afterwards, with no communication between them in either direction. The relationship is one of trust rather than exchange, and its failure has consequences.
For migration, the constraint in this case is at the verifying end. A publisher can adopt a post-quantum signature algorithm at any time. The publisher gains nothing if the deployed devices cannot verify the new signatures. The verifier therefore sets the upper limit for the relationship, meaning the strongest algorithm the relationship can use. The verifier may be a device with no update path.
4 · Relationships overlap on the same wire
Transport security and message-level security protect different spans of the path. For example, a signed token travels inside a TLS session, and the token and the session do not share endpoints. In the Keycloak deployment example, Keycloak signs an OIDC token. The token crosses the plain HTTP hop to the ingress, and then a TLS session from the ingress to the client application. The signature relationship runs from Keycloak, the issuer, to the relying party that verifies the token. It passes through the ingress untouched.
The overlap matters when a consumer asks what protects a given piece of data end to end. The answer differs for each layer. On the hop to Keycloak, the token signature still protects the token's integrity, but nothing protects its confidentiality, because token encryption is off. A model that records one relationship per connection cannot express that answer.
none for every algorithm.5 · One asset, many relationships
A gateway with a single IPsec implementation may hold tunnels to many peers. An operator's interconnect, a service mesh, and a partner VPN estate all have this shape. The implementation is one asset. The relationships are many, and their properties differ because each peer negotiates separately.
Post-quantum readiness is therefore not a property that a product can hold on its own. An organization may deploy a fully capable gateway and still have most of its tunnels running classical key exchange, because readiness on any given tunnel depends on the other side as well.
6 · Capability is not the negotiated outcome
Two systems both implement a post-quantum key exchange. The session between them uses a classical group, because of a configuration setting, an intermediary that rejects the larger handshake, or a policy on one side. Both node records are accurate. The connection is nevertheless not quantum-safe.
There is no node on which this fact can be stored. It belongs to the relationship, and it cannot be derived from either endpoint's inventory entry. This example gives the clearest reason to treat the relationship (the edge) as an object in its own right, rather than as an annotation on an asset.
The Keycloak deployment example records this case at its ingress. The configured record permits X25519MLKEM768 and X25519. The observed record, taken from 18 to 25 October 2026, shows that 29% of sessions still negotiated X25519 only. The readiness-gap policy classes this interface enabled-not-negotiated: the deployment permits the target, and the other endpoint or a fallback is the limit.
7 · The weaker party sets the upper limit
A modern gateway communicates with a controller installed twenty years ago. The gateway supports current algorithms. The controller supports what it shipped with and cannot be changed. The cryptography the relationship can use is fixed by the less capable end. No upgrade to the gateway changes it.
Planning that works from a product inventory will schedule an upgrade that cannot deliver the intended result. Planning that works from relationships identifies the controller as the item requiring replacement, which is a different and usually more expensive piece of work.
The same limit appears in the Keycloak deployment example on a smaller scale. Keycloak's connection to the corporate directory is LDAPS, and the directory accepts TLS 1.2 only. Whatever Keycloak supports, the directory fixes the protocol version on that interface. The product record anticipates this: it declares the directory connection's algorithms peer-defined.
8 · Relationships that carry no data
An application uses a key held in a hardware security module or a trusted execution environment. The key never leaves the module. What passes between them are requests to use the key and the results of those operations. The relationship is one of custody and control, and it crosses a hardware boundary rather than a network.
This distinction affects migration in practice. If the key material is confined to hardware, adopting a new algorithm may require the module to support it, which can mean replacement rather than reconfiguration.
Product records, deployment records and joins
Several examples above turn on the difference between what a product can do and what a deployment does. The methodology keeps those two facts in different documents, written by different parties.
| Record | Written by | Subject type | Stage | What a present-state value means | Subject identifier |
|---|---|---|---|---|---|
| Product record | the vendor | product | implemented | the product's default as shipped | a Package URL |
| Configured deployment record | the operator | deployment | configured | the set the deployment permits | a tag URI (RFC 4151) |
| Observed deployment record | the operator, or an assessor | deployment | observed | the set seen in the observation window | the same tag URI |
One document has one subject and one stage. The records are joined, not merged. Decision 0020 first applied that principle to vulnerability statements, and decision 0025 generalises it to records at different stages.
- A deployment record cites the records it builds on. Each citation is an external reference of type
bomwith the propertypkic:profile:context = cited-document, a BOM-Link (urn:cdx:<serial>/<version>) and a SHA-256 hash. The hash fixes which revision the operator cited. - Each deployment interface names the interface it realises. The property
pkic:profile:correspondsToholds a BOM-Link to one interface in a cited record:urn:cdx:<serial>/<version>#<bom-ref>. Where the supplier of that part publishes no CBOM, the value is the literalno-product-document. - Only implementation facts follow the join. A deployment interface inherits the implementing library (
implementationPurl) from the interface it realises, when it does not state one itself. Present-state facts never follow the join, because each belongs to one stage. - A missing cited record leaves a value open. If the evaluator is not given a cited record, it reports an inherited value as unresolved, not as failed.
The Keycloak example follows the library through two joins. The observed record's database interface names the configured record's database interface, and that interface names the product record's database interface, which states the OpenJDK library. The configured record's ingress interface states no-product-document, because the ingress is not part of the Keycloak product.
The readiness gap is computed from the join, never stored. The readiness-gap policy reads the three records, follows correspondsTo, and classes each interface and purpose (key establishment and entity authentication):
| Class | Meaning | Who acts |
|---|---|---|
target-met | Every value observed (or, without an observation, configured) meets the target. | – |
enabled-not-negotiated | The deployment permits the target, and at least one session still negotiated a classical value. | the other endpoint, or whoever controls the fallback path |
capable-not-enabled | The product can reach the target, and the deployment does not permit it. | the operator, by configuration |
capable | The product can reach the target. No deployment record was supplied, so nothing shows whether the target is enabled. | – |
not-capable | The product cannot reach the target. The product record says what blocks it. | the supplier, or the operator by upgrading or replacing the product |
unprotected | The interface applies no cryptography at all at the latest stage supplied. Its traffic is exposed whatever the product can do. | the operator |
not-deployed | The product has the interface, and the deployment records do not. | – |
not-applicable | No algorithm is applied for this purpose at this interface. | – |
unknown | A stage needed to decide is missing, or declares the value unknown. | – |
For the illustrative Keycloak deployment, evaluated on 25 October 2026, the ingress key establishment is enabled-not-negotiated. The plaintext proxy hop and the management port are unprotected. Token signing is not-capable: it is committed upstream and blocked by the JOSE standard (issue #43690). Keycloak's own TLS is not-capable: it is planned and blocked by the Java runtime (JEP 527). The product's HTTPS listener is not-deployed, because TLS ends at the ingress. The result names the policy version and digest, the evaluation date, and every record it read by SHA-256 digest. See Policy Evaluation.
A known limitation: one-to-many relationships
Every example above is pairwise. Some cryptography is not. A broadcast or multicast group, a mobile network serving many receivers, and a group chat all apply cryptography among more than two parties at once. The natural way to describe them is one relationship with many endpoints, not two.
One-to-many cryptography covers two different cases. Only the first requires a costly change to the model. The first case is a shared key held by n parties at once, as described above. No set of pairwise relationships describes it correctly, so the model has to change to carry it. The second case is a signature verified by a population. One party signs and many parties verify, each holding its own keys. Each signer-to-verifier leg can be described as a pairwise relationship without losing anything. The only thing missing was a way to name the verifiers, because the weakest of them sets the upper limit on what the signer can use. The attribute verifierPopulation now does this, with the values counterparty, scheme-members and public. The relationship stays pairwise, and nothing in the definitions changes. A related attribute, trustDomain, records whose credentials an interface accepts, and whether membership under that anchor is administered. Financial settlement and payment rails were first raised as an example of the shared-key case. They turn out to be covered by these two attributes instead. The reasoning is in the multi-party trust design note, and both attributes are defined in Terms.
Summary: a taxonomy of relationships
Taken together, the examples vary along four dimensions: how many parties there are, whether those parties exist at the same time, what passes between them, and how far the protection extends. Setting the examples out in one table shows that the model is more general than the network connection usually used to explain it. The table also gives a way to test the model against a case from a new sector.
| Relationship | Parties | Simultaneous | What passes | Span | Property it exercises |
|---|---|---|---|---|---|
| TLS session to a service | 2 | yes | data in transit | single hop | the base case |
| Termination at a proxy or CDN | 2 per leg | yes | data in transit | chained, multi-hop | one apparent connection is several relationships |
| Encrypted backup or archive | 2 | no | data at rest | single | parties separated in time; lifetime is the retention period |
| Code or firmware signing | 2 | no | a signed artifact is carried | single | parties never interact; the verifier sets the upper limit. When every customer verifies, verifierPopulation is public |
| Message-level security inside transport | 2 per layer | yes | data in transit | layered, overlapping | relationships overlap rather than partition the path |
| IPsec mesh or operator interconnect | 2 per tunnel, many tunnels | yes | data in transit | single hop, repeated | one asset supports many relationships of differing posture |
| Negotiated fallback between capable peers | 2 | yes | data in transit | single hop | capability is not the negotiated outcome |
| Modern gateway to legacy controller | 2 | yes | data in transit | single hop | the less capable party fixes the posture |
| Application to HSM or TEE | 2 | yes | operation requests; key material confined | crosses a hardware boundary | a relationship that transfers no protected data |
| Broadcast, multicast, or group messaging | n | yes | data in transit | one to many | not represented in v1, as described above |
| Signed message verified by a closed membership | 1 signer, many verifiers | no | a signed message is carried | one to many | described pairwise, one leg per verifier. The upper limit belongs to the membership, which verifierPopulation records as scheme-members |
The dimensions also indicate where a profile written for one sector will need rules that another does not. A profile concerned with data at rest has to address the retention period, which does not arise for a session. A profile concerned with signing has to address the population of verifiers, which has no counterpart in a transport profile. The same table appears in the profile specification at profile-interface-disclosure.md, where it defines the scope a profile applies to.