Skip to content

feat(cryptography): add cryptographic agility plane to CBOM #947

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bhess wants to merge 2 commits into
base: 2.0-dev
Choose a base branch
from
+118 −0
Open

feat(cryptography): add cryptographic agility plane to CBOM #947

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92a0604
feat(cryptography): add cryptographic agility plane to CBOM
bhess Jun 3, 2026
92c9827
Move agility to component level, unify rotation and renewal object
bhess Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions schema/2.0/model/cyclonedx-component-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,9 @@
"$ref": "cyclonedx-cryptography-2.0.schema.json#/$defs/cryptoProperties",
"title": "Cryptographic Properties"
},
"agility": {
"$ref": "#/$defs/agility"
},
"tags": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/tags",
"title": "Tags"
Expand Down Expand Up @@ -733,6 +736,67 @@
"$ref": "cyclonedx-data-2.0.schema.json#/$defs/dataGovernance"
}
}
},
"agility": {
"type": "object",
"title": "Agility",
"description": "Properties describing how this component's configuration was determined and how a change to it can be applied. These properties support change management and, for cryptographic assets, cryptographic-agility.",
"additionalProperties": false,
"properties": {
"configurationSource": {
"type": "string",
"title": "Configuration Source",
"description": "Describes how this component's configuration was determined, ordered from least to most agile.",

@Mehrn0ush Mehrn0ush Jun 6, 2026

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.

One question I had while reading this: the description says these values are “ordered from least to most agile.” Could this be softened unless consumers are expected to treat enum order as normative?

Some values seem to describe configuration origin or authority, while “negotiated” describes runtime selection. For example, a TLS deployment may have an administrator- or policy-managed set of allowed algorithms, while the final selection is negotiated at runtime. A short note on how producers should choose a value in that case would help avoid inconsistent modeling.

"enum": [
"hardcoded",
"product-default",
"administrator-configured",
"policy-managed",
"negotiated",
"other",
"unknown"
],
"meta:enum": {
"hardcoded": "The configuration is fixed in code or firmware and is not intended to be changed.",
"product-default": "The configuration is inherited from product or vendor defaults and can typically be overridden.",
"administrator-configured": "The configuration is explicitly set by an administrator through external configuration.",
"policy-managed": "The configuration is determined by a policy or governance engine.",
"negotiated": "The configuration is agreed at runtime with a peer, such as during a protocol handshake.",
"other": "Another configuration source applies.",
"unknown": "The configuration source is not known."
}
},
"configurationRef": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
"title": "Configuration Reference",
"description": "The bom-ref of the configuration that determines this component's configuration. Typically points to a component of type 'data' whose data type is 'configuration'."
},
"changeMechanism": {
"type": "string",
"title": "Change Mechanism",
"description": "Describes how a change to this component's configuration is applied, ordered from least to most agile.",

@Mehrn0ush Mehrn0ush Jun 6, 2026

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.

One more question: is changeMechanism intended to capture the type of change required, the way the change becomes active, or the least disruptive supported path?
Some values describe what must be changed, such as hardware-replacement, firmware-update, or software-update, while others describe operational impact, such as restart-required or runtime-config.

Maybe a short note could help producers model common cases consistently, for example a software update that also requires a restart, or a TLS configuration reload that does not require a full process restart. If multiple steps apply, would the intended pattern be to record the least disruptive supported path for the intended change and use configurationRef or evidence for additional context?

"enum": [
"not-possible",
"hardware-replacement",
"firmware-update",
"software-update",
"restart-required",
"runtime-config",
"other",
"unknown"
],
"meta:enum": {
"not-possible": "The configuration cannot be changed through any supported means.",
"hardware-replacement": "The change requires replacing or adding hardware.",
"firmware-update": "The change requires a firmware update.",
"software-update": "The change requires a software or package update.",
"restart-required": "The change can be applied through configuration but requires restarting software or service processes.",
"runtime-config": "The change can be applied at runtime without a restart.",
"other": "Another change mechanism applies.",
"unknown": "The change mechanism is not known."
}
}
}
}
}
}
54 changes: 54 additions & 0 deletions schema/2.0/model/cyclonedx-cryptography-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -521,6 +521,11 @@
"title": "Destruction Date",
"description": "The date and time (timestamp) when the certificate was destroyed."
},
"renewal": {
"$ref": "#/$defs/lifecycleControl",
"title": "Certificate Renewal",
"description": "How this certificate is renewed or re-enrolled."
},
"certificateExtensions": {
"type": "array",
"title": "Certificate Extensions",
Expand Down Expand Up @@ -673,6 +678,11 @@
"destroyed"
]
},
"rotation": {
"$ref": "#/$defs/lifecycleControl",
"title": "Key Rotation",
"description": "How this cryptographic material is rotated under the same algorithm."
},
"creationDate": {
"type": "string",
"format": "date-time",
Expand Down Expand Up @@ -1088,6 +1098,50 @@
"unknown": "The cryptographic function is not known."
}
},
"lifecycleControl": {
"type": "object",
"title": "Lifecycle Control",
"description": "How a cryptographic lifecycle operation, such as key rotation or certificate renewal, is performed.",
"additionalProperties": false,
"properties": {
"automation": {
"type": "string",
"title": "Automation",
"description": "The degree of automation with which the operation is performed, ordered from least to most agile.",

@Mehrn0ush Mehrn0ush Jun 6, 2026

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.

I like the shared lifecycleControl shape. Would it be useful to clarify that automation captures the degree of automation, while mechanism carries the concrete renewal or rotation method?

For example, is the intended modeling pattern something like:

  • automatic + mechanism: "ACME"
  • automatic + mechanism: "AWS KMS (provider-managed)"
  • manual + mechanism: "M-of-N key ceremony"
  • automatic or on-demand + mechanism: "ephemeral session key"

I think a short note like this would keep the enum compact while still giving implementers guidance for the additional cases discussed in #892, such as provider-managed rotation, protocol-driven renewal, quorum ceremonies, and ephemeral material.

"enum": [
"not-supported",
"manual",
"on-demand",
"automatic",
"other",
"unknown"
],
"meta:enum": {
"not-supported": "The operation is not supported.",
"manual": "The operation is initiated and executed manually.",
"on-demand": "The operation can be triggered on demand, for example through an API call.",
"automatic": "The operation is performed automatically based on policy or schedule.",
"other": "Another mechanism applies.",
"unknown": "The mechanism is not known."
}
},
"mechanism": {
"type": "string",
"title": "Lifecycle Mechanism",
"description": "The protocol, system, or interface used to perform the operation, such as the ACME (RFC 8555), EST (RFC 7030), SCEP (RFC 8894), CMP (RFC 4210), or CMC (RFC 5272) certificate protocols, or KMIP, PKCS#11, and cloud key-management services for key rotation.",
"examples": [
"ACME",
"EST",
"SCEP",
"CMP",
"CMC",
"KMIP",
"PKCS#11",
"HashiCorp Vault Transit"
]
}
}
},
"relatedCryptographicAssets": {
"type": "array",
"title": "Related Cryptographic Assets",
Expand Down
Loading