One profile against two formats
A PKIC CBOM profile is defined independently of any format. A mapping locates each attribute, and the interface count, within a concrete document. The target carrier is CycloneDX 2.0. The validator still reads CycloneDX 1.6 and 1.7 documents, as legacy, because the tools that produce CBOMs today emit 1.x. SPDX 3.0.1 has no cryptographic object model, so a CBOM is expressed in CycloneDX and referenced from an SPDX SBOM. SPDX 3 is not a target carrier, and the SPDX column of the mapping keeps its stated gaps.
Both formats permit the same information to be encoded in more than one valid way. The mapping therefore also normalizes the encoding. It defines a single, canonical location for each attribute. A consumer that relies on the mapping reads each required value from one place. It does not have to handle every valid variant, and this reduces parsing complexity. See Challenges.
The target carrier: CycloneDX 2.0
Every published example is a CycloneDX 2.0 document, except the two under examples/legacy/. The repository holds the pinned 2.0 schema in tests/schemas/cyclonedx-2.0/, and the test suite validates every 2.0 example and perspective against it. Every profile declares the carrier range "cyclonedx": { "min": "1.6", "tested": "2.0" }. See Versioning.
CycloneDX 2.0 changes where several facts sit. The profile attributes do not change. The changes that matter to the PKIC CBOM profiles are these:
| Fact | CycloneDX 2.0 | CycloneDX 1.6 / 1.7 (legacy) |
|---|---|---|
| The subject the document describes | inventories[0].subject | metadata.component |
| Services | components with type: "service" in inventories[0].components[] | a separate services[] list |
| Package URL | identifiers[], each asserted by a declared party | purl |
| Algorithms in use | relatedCryptographicAssets | cryptoRefArray, algorithmRef, signatureAlgorithmRef; 1.7 also offers relatedCryptographicAssets on protocols, certificates and key material |
| Algorithms supported (TLS) | cipherSuites, unchanged | cipherSuites |
| Module validation, product certification | certifications[] on the library and on the subject | properties, and a certification-report reference |
| Elliptic curve | ellipticCurve, enumerated (for example other/Curve25519) | curve, free text |
| Key rotation, certificate renewal | native rotation and renewal | not available |
| A note for human readers | a top-level $comment | a property in metadata.properties |
CycloneDX 2.0 also adds a root risks array: a risk register with status, owner, responses and target dates. These values are judgements, not product facts. The validator ignores risks for conformance, and a supplier's product record should not contain them (decisions 0002 and 0007).
Reading CycloneDX 1.6 and 1.7
The validator reads both carrier generations. For a 1.x document it takes the subject from metadata.component, the services from services[], and the in-use algorithms from cryptoRefArray and algorithmRef. For a 2.0 document it takes the same facts from their 2.0 locations. Both readings produce the same abstract record, so every rule is written once. The report places a 1.6 or 1.7 document in the legacy band and says so. The verdicts do not change. examples/legacy/cbom-keycloak-product-1.7.cdx.json holds the same facts as the Keycloak 2.0 product record, and it receives the same verdicts against all five product profiles.
A producer can convert a 1.6 or 1.7 CBOM to 2.0 with cdx17_to_20.py. The converter re-encodes existing facts and adds none. It moves the subject into inventories[0].subject, turns each service into a component of type service, moves package URLs into identifiers[] asserted by the document author, and replaces cryptoRefArray and algorithmRef with relatedCryptographicAssets. It also turns the 1.x property pkic:profile:subjectIdentifier into an identifier with the custom scheme tag-uri, and a library's module validation into a certifications[] entry. Its docstring lists every conversion. It targets the pinned commit and will need revisiting when 2.0 is released.
Two locations, two meanings
A concrete case shows why the mapping names one location for each fact. Take one interface from the worked example: TLS on Keycloak's main listener, port 8443. The JDK 21 in the image offers several key-exchange groups, with X25519 first, and X25519 is what the interface uses by default. CycloneDX can record X25519 in two places for the same interface, and both are valid. In the published example the cipher suites sit in a shared TLS configuration component that the interface references. The figure shows them inline for brevity.
cryptoRefArray.Neither location is wrong, and the Keycloak example uses both. The mapping gives each one a single meaning. cipherSuites lists the supported set. The validator reads its tlsGroups and tlsSignatureSchemes as the supported key-exchange groups and signature schemes, which the pqc-migration profile requires. relatedCryptographicAssets lists what the interface uses. Only entries that point to algorithm components count as in use. A TLS configuration that several interfaces share is one protocol component with the suites, and each interface references it with type: "protocol-configuration". The validator follows that reference for the supported set and does not treat it as in use.
The same pattern appears for authentication. A TLS interface usually reaches its signature algorithm through a certificate component. In 2.0 that link is the certificate's relatedCryptographicAssets. In 1.6 it is certificateProperties.signatureAlgorithmRef. A 1.7 document may use either, because 1.7 added relatedCryptographicAssets to certificates. The validator reads both. An SSH interface has no certificate, so the interface references the host key algorithm directly. Both forms satisfy the profile requirement for an authentication algorithm, and the mapping records which form applies in which case. At the implemented stage, Keycloak's server certificate is supplied by the operator, so the product record states authentication as deployment-defined and points to the guide where the operator sets it.
The mapping therefore does more than locate attributes. It also prevents a type of error in which a CBOM is complete but a consumer reports it as deficient, or reports an offered algorithm as one in use. Both errors arise only because the producer chose a different valid structure.
Representation of a cryptographic interface
A cryptographic interface, meaning a cryptographic relationship, is represented in one of two ways. A security protocol instance such as TLS is a cryptographic-asset component with assetType: protocol. An application protocol such as OIDC, SAML, the Keycloak Admin API or plain HTTP is a service. In CycloneDX 2.0 a service is a component with type: "service". The dependency graph carries the layering: OIDC depends on HTTPS, and HTTPS depends on TLS.
The profile's model and the format's model do not align at this point. The format treats a protocol as an asset, in the same category as an algorithm or a certificate. The profile treats the interface as a relationship between endpoints. The mapping bridges the two models. It uses the protocol component or service as the carrier for the relationship, meaning the object that holds the relationship's attributes. Those attributes are attached as pkic:profile: properties. SPDX 3.0.1 has no such carrier. For that reason the SPDX column reaches the same attributes through a linked CycloneDX document rather than natively. In both formats, attaching relationship attributes to the carrier is a convention agreed in the mapping. Neither format enforces it as a structure.
This arrangement has several consequences for an implementation:
- The document does not declare the set of interfaces directly. The validator derives the set by listing the components that carry
interfaceType, and counts them. Rules P1 and P2 are evaluated against that derived set, including the count of components withinterfaceType = management. - Nothing in the format prevents a protocol component or service from being used for something other than an interface. A producer may declare a service only for its layering, such as HTTPS under OIDC. The
interfaceTypeproperty distinguishes an interface from such a record. For this reason the profile requiresinterfaceTypeon every interface. - An interface is identified by its
bom-ref. References inside the document, such askeyStoreRef, use it. A reference from another document uses a BOM-Link,urn:cdx:<serial>/<version>#<bom-ref>. - The algorithms belonging to an interface are reached by reference, rather than being contained within it. If a reference is broken or missing, the attribute appears to be absent.
- A product and an operator each describe the same connection in their own records. The deployment record names the product interface it realises with
pkic:profile:correspondsTo, and the records are joined, not merged. See Inventory.
A format may later introduce a dedicated object for the relationship. If it does, this part of the mapping changes and the profile's requirements do not.
Mapping table
| # | Requirement | CycloneDX 2.0 | CycloneDX 1.6 / 1.7 (legacy) | SPDX 3.0.1 |
|---|---|---|---|---|
| P1 | ≥1 cryptographic interface | count of components carrying interfaceType | the same, over components[] and services[] | unresolved |
| P2 | a management interface, or a reason for none | count where interfaceType==management; or subject property managementInterfaceAbsence | the same | unresolved |
| P3 | subject identifier | inventories[0].subject.identifiers[]: scheme purl (product) or custom scheme tag-uri (deployment) | metadata.component.purl; property subjectIdentifier | unresolved |
| P4 | coverage | subject property coverage, or compositions[].aggregate | the same | unresolved |
| P5 | subjectType | subject property subjectType (product, deployment) | property on metadata.component | unresolved |
| P6 | one lifecycle stage | metadata.lifecycles[].phase (build, operations, discovery, design) | the same | unresolved |
| I1 | protocol | protocolProperties.type; service property protocol | the same | via linked CBOM |
| I2 | protocolVersion | protocolProperties.version; service property protocolVersion | the same | via linked CBOM |
| I3 | keyExchange | algorithm primitive=key-agree/kem in relatedCryptographicAssets or dependsOn; or a literal | the same via cryptoRefArray | via linked CBOM |
| I4 | encryption | algorithm primitive=ae, reached as for I3; or a literal | as for I3 | via linked CBOM |
| I5 | authentication | signature algorithm, directly or through a certificate's relatedCryptographicAssets; or a literal | certificate signatureAlgorithmRef (or, in 1.7, the certificate's relatedCryptographicAssets) or host key | via linked CBOM |
| I6 | endpointRoles | properties[endpointRole:*] (no edge object) | the same | unresolved |
| I7 | interfaceType | properties[interfaceType] (no native field) | the same | unresolved |
| I8 | lifecycleStage | the document stage (P6); an optional property must agree | the same | unresolved |
| I9 | implementationPurl | package URL in identifiers[] of the library that provides the interface | purl on that library | packageUrl on a Package |
| I10 | keyWrapping (storage) | securedBy of the keys the storage service depends on | the same | via linked CBOM |
| I11 | defaultState | properties[defaultState] | the same | unresolved |
| G1 | capabilityStatus, blockedBy, roadmapRef (per purpose) | properties[capabilityByPurpose:<purpose>:<attribute>] | the same | unresolved |
| — | module validation, product certification | certifications[] on the library; on the subject | properties; certification-report reference | unresolved |
| — | interface identity | bom-ref | the same | unresolved |
| — | correspondsTo, cited documents (deployment) | property correspondsTo (BOM-Link); externalReferences[type=bom] with context = cited-document and SHA-256 | the same | not mapped |
| R1–R6 | context pointers | externalReferences[] with properties pkic:profile:context and, for endpoints, pkic:profile:accessProtocol | the same | not mapped |
Property names in the table omit the pkic:profile: prefix. The full mapping, with every attribute of the family, is in mapping-cyclonedx-spdx.md.
Perspectives: informative companions
CycloneDX 2.0 adds perspectives. A perspective names a domain and lists JSONPath expressions into a document, each marked required, recommended or optional. Generic 2.0 tools can use a perspective to filter a document and check that expected fields are present, without the PKIC validator.
Each PKIC CBOM profile publishes one perspective, generated from its rules file by tools/build_perspectives.py, in perspectives/perspective-<profile>.cdx.json. A perspective cannot express conditions, vocabularies, groups, withholding, reference rules or extension. It is therefore informative only. The rules file is normative, and a document that satisfies a perspective may still fail the profile.
Two words that collide
CycloneDX 2.0 uses two of the methodology's words for its own concepts. Its root profiles element holds reusable data and threat characterisations. Its blueprint model defines an interface with types such as rest and cli. Neither is the concept used here. Wherever confusion is possible, the documentation writes "PKIC CBOM profile" for a rules file of this methodology, and "cryptographic interface" for a cryptographic boundary that a profile counts and describes (decision 0021).
Interpretation of the columns
In CycloneDX, the cryptographic assets (I1 to I5, I10 and the provider in I9) are represented in native fields. This is an area where the format is strong. CycloneDX 2.0 adds native homes for module validation and product certification, and the document stage sits in the native metadata.lifecycles. The profile also depends on interface-level classifiers: interfaceType (I7) and endpoint roles (I6), and on the subject type (P5). These have no native field. They are carried as properties under the pkic:profile: namespace. Rule P2 can only be evaluated because the interfaceType attribute is present.
In SPDX, version 3.0.1 has no cryptographic model, so most detail comes through the linked CycloneDX CBOM. SPDX is strong on provider identity (I9). It identifies the implementing library by packageUrl. A consumer cross-references that value against vulnerability feeds, as described in Vulnerabilities. As SPDX gains a cryptographic object model, entries in its column will move from the linked CBOM to native SPDX fields. The requirement numbers will stay the same. Stable requirement numbers are the reason for expressing the profile independently of the format.
The edge gap
Normalization
Normalization covers two separate questions: where a value is written in the document, and how the value itself is expressed. Both questions have to be settled before CBOMs from different producers can be compared. The second question, how the value is expressed, causes more difficulty in practice.
The mapping normalizes identity as well as encoding. Naming a canonical location settles where a value is read. It does not establish whether two documents that carry the value describe the same component, certificate, key, or interface. Where an identifier scheme exists the mapping can require it. Requirement P3 does so for the subject, I9 does so for the implementing library, and the registry does so for algorithms. Where no scheme exists, a mapping cannot supply an identity the formats do not define. Across documents, the deployment record supplies the link itself: correspondsTo names the product interface by BOM-Link. Identity normalization is still the harder of the two questions. The remaining work of matching records that describe the same asset is done in the inventory. See Challenges.
Why it matters
Every automated use of a CBOM depends on matching a value against something, whether a policy, a deprecation list, a vulnerability feed, or the same attribute in another CBOM. Those matches are exact. A value that means the right thing but is written differently will not match, and nothing in the process reports an error. A policy engine looking for AES-256-GCM that encounters AES256 finds no match. Depending on how the rule is written, it treats the interface either as compliant or as having no encryption at all. Both results are incorrect, and both look like ordinary output.
The problem grows with the size of the estate. A single supplier using an unusual spelling can be handled by hand. Across many suppliers and many interfaces, the same variation makes estate-wide questions impractical to answer. Examples are how many interfaces still use a deprecated algorithm, and which services an advisory affects. Inconsistent naming seen in real deployments is the reason the registry was introduced.
What the registry solves
CycloneDX 1.7 introduced the Cryptography Registry, which assigns stable identifiers to algorithm families and their parameters. Elliptic curve names show the problem clearly. The same curve is commonly written three ways, depending on which standards body or library the producer follows:
| As written by the producer | Origin | Refers to |
|---|---|---|
P-256 | NIST | The same curve. The three strings have no form in common, so a text comparison treats them as unrelated. |
secp256r1 | SECG | |
prime256v1 | ANSI, used by OpenSSL |
Compared as text, these are three distinct values. Compared as registry identifiers, they are one value. CycloneDX 2.0 goes a step further for curves: ellipticCurve takes an enumerated value, such as nist/P-256 or other/Curve25519, in place of the free-text curve. Symmetric algorithms raise a related difficulty: AES256, AES-256-GCM, and AES_256_GCM may or may not denote the same thing, because the first omits the mode that the others state. The registry also separates the algorithm from its parameters, so a query for deprecated key sizes does not depend on parsing a name.
For requirements I3, I4, and I5 a registry identifier is preferred wherever one exists. CBOMs written to version 1.6 carry free-text names. The working group recommends that an adapter normalize these names with a versioned name map, so that rules only ever see canonical values. See Versioning.
Protocols need normalizing too
Algorithm naming receives most of the attention, but protocol identity presents the same difficulty. The protocol and its version are recorded as free text in protocolProperties and in service properties, and producers write them inconsistently: TLS, tls, and TLSv1.3; a version given as 1.3, TLS 1.3, or 0x0304; SSH as 2.0 or SSH-2.0. Some protocols have more than one accepted name, such as MACsec and IEEE 802.1AE.
There are several practical reasons to normalize protocol names and versions.
- Profiles gate on protocol version. A rule requiring TLS 1.2 or higher has to compare versions, and comparison needs a defined ordering. Strings do not provide one:
1.10sorts before1.9as text, andTLSv1.3does not parse as a number at all. - Deprecation is expressed per protocol version. Guidance withdraws TLS 1.0 and 1.1, not TLS generally, so a policy cannot be applied unless the version is canonical.
- The protocol determines which algorithm roles exist. TLS authenticates with a certificate signature, SSH with a host key, IPsec through IKE negotiation. A consumer that misreads the protocol looks for the wrong attribute and reports it as missing, as the authentication case in “Two locations, two meanings” shows.
- Aggregation depends on it. Counting how many interfaces across an estate still run a given protocol version is a routine migration question. It cannot be answered by grouping on inconsistent strings.
- Sector vocabularies differ. The same interface may be named by a 3GPP reference point in one document and by its IETF protocol in another. Without a canonical protocol identity these do not reconcile.
The working group therefore keeps a short list of protocol names in Terms. Each name points to the protocol's own specification, and the version is written as that specification writes it, for example 1.3 for TLS. A protocol that is not on the list is recorded as other, with a pointer to its specification, and can be proposed for the list. An adapter normalizes what it receives before any rule is evaluated. Where a registry provides protocol identifiers, they are preferred, for the same reasons as for algorithms.