feat(crypto): CBOM model metadata

[qkaiser]

Description

This branch expands the cryptographic asset model with CycloneDX 1.7 certificate metadata. Certificates can now include serial numbers, preferred file extensions, fingerprints, lifecycle dates, predefined or custom lifecycle states, and standardized or custom X.509 extensions. Related cryptographic material also gains fingerprints, while both certificates and related material can express typed relationships to other cryptographic assets such as algorithms and public keys.

All new fields are version-gated to CycloneDX 1.7 and support deterministic comparison, hashing, and JSON/XML round-tripping. Existing CycloneDX 1.6 fields (including deprecated certificate extensions and direct asset references) remain intact for backward compatibility, with expanded schema-validation, enum, snapshot, and serialization tests covering the new behavior.

AI Tool Disclosure

• My contribution does not include any AI-generated content
• My contribution includes AI-generated content, as disclosed below:
  • AI Tools: codex
  • LLMs and versions: codex-5.6-sol xhigh
  • Prompts: see below

LLM prompt

## Complete CycloneDX 1.7 cryptography models
Summary
Extend cyclonedx.model.crypto to model and round-trip every requested CycloneDX 1.7 CBOM field in JSON and XML. Preserve all existing 1.6 APIs and deprecated reference fields; the already-implemented key-wrap primitive and 1.7 protocol types require verification rather than duplication.
Public API and model changes

Add reusable RelatedCryptographicAsset(type, ref) and related_cryptographic_assets collections to certificate, related-material, and protocol properties.
Extend CertificateProperties with:
serial_number, certificate_file_extension, and fingerprint: HashType.
certificate_states, using CertificateLifecycleState, CertificatePredefinedState, and CertificateCustomState.
Creation, activation, deactivation, revocation, and destruction timestamps.
certificate_extensions, using common/custom extension models and a schema-backed common-extension-name enum.
Extend RelatedCryptoMaterialProperties with fingerprint and related_cryptographic_assets.
Keep signature_algorithm_ref, subject_public_key_ref, certificate_extension, algorithm_ref, and crypto_refs operational for both 1.6 and 1.7.

Serialization behavior

Gate new fields and structured models to SchemaVersion1Dot7, with exact CycloneDX JSON names, XML element names, ordering, nested arrays, and date/hash mappings.
Add union serialization helpers for certificate states and extensions so JSON and XML deserialize into the correct predefined/custom model.
Include every new property in comparison, hashing, sorting, and representation behavior where applicable.

Test plan

Add enum completeness tests against the bundled 1.7 schemas, including algorithm families, elliptic curves, certificate states/extensions, key-wrap, and protocol types.
Add model tests for construction, equality, hashing, sorting, union discrimination, and mixed-IKEv2 rejection.
Expand representative crypto BOM fixtures and JSON/XML snapshots with every new field.
Validate 1.7 output against strict bundled schemas and test JSON/XML round-trip deserialization.
Verify 1.6 output remains schema-valid, retains legacy fields, omits 1.7-only fields, and preserves protocol-type downgrade behavior.
Run the full unittest suite plus mypy and flake8.

Assumptions

This change targets the upstream library only; Inspector’s temporary extension properties and dependency-graph compatibility relationships remain until it upgrades to a release containing these models.
Existing deprecated CycloneDX fields are not removed or automatically translated into preferred 1.7 relationships.
Schema arrays follow the library convention of deterministic SortedSet storage.

Affirmation

• My code follows the CONTRIBUTING.md guidelines

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 126 complexity · 8 duplication

Metric	Results
Complexity	126
Duplication	8

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[read-the-docs-community]

Documentation build overview

📚 CycloneDX Python Library | 🛠️ Build #34046252 | 📁 Comparing ea7d2ca against latest (cf392e0)

  🔍 Preview build  

2 files changed

± genindex.html
± autoapi/cyclonedx/model/crypto/index.html

[CAOShurong]

Thanks for the thorough 1.7 coverage. I found one remaining protocol-level round-trip gap on 546d0b49 (AI-assisted review; reproduced locally).

ProtocolProperties still models only the deprecated cryptoRefArray; the 1.7 JSON/XML schemas also define protocolProperties.relatedCryptographicAssets. A strict-valid 1.7 BOM containing that preferred field is accepted, but Bom.from_json(...).as_json(view_=SchemaVersion1Dot7) silently drops it:

component["cryptoProperties"]["protocolProperties"] = {
    "type": "tls",
    "version": "1.3",
    "relatedCryptographicAssets": [{"type": "algorithm", "ref": "alg-1"}],
}
assert JsonStrictValidator(SchemaVersion.V1_7).validate_str(json.dumps(bom)) is None
round_trip = json.loads(Bom.from_json(bom).as_json(view_=SchemaVersion1Dot7))
# round_trip protocolProperties is now only {"type": "tls", "version": "1.3"}

Could this PR add the same 1.7-gated RelatedCryptographicAsset collection to ProtocolProperties, include it in comparison/hash behavior, and cover JSON/XML round trips while retaining crypto_refs for 1.6 compatibility? I also ran tests.test_model_crypto and tests.test_enums at this head: 722 tests passed.

[qkaiser]

@CAOShurong done. Note that:

The XML model intentionally deviates from the bundled CycloneDX 1.7 XSD: protocol relatedCryptographicAssets are serialized and deserialized even though that XSD omits the field. This provides model parity with the JSON specification and requested round-trip behavior, but strict XML schema validation cannot cover the field until the upstream XSD is corrected.

Maybe worth reporting it to CycloneDX ?

[qkaiser]

To be a bit more precise:

The JSON schema allows relatedCryptographicAssets in:

• certificateProperties
• relatedCryptoMaterialProperties
• protocolProperties

The XSD allows it in:

• certificateProperties
• relatedCryptoMaterialProperties

So the JSON and XML schemas are inconsistent. The model in this branch supports the protocol field for both formats to avoid losing data and maintain model parity, but XML containing that field will not pass strict validation against the current 1.7 XSD.

[CAOShurong]

Confirmed. The official 1.7 JSON schema defines
protocolProperties.relatedCryptographicAssets, while the 1.7 XSD omits that
element under protocolProperties and only permits cryptoRef. I reproduced
the mismatch: strict JSON validation passes, the model round-trips the field,
and strict XML validation rejects the generated element.

I reported the specification defect as
CycloneDX/specification#1018.

I also checked the updated ea7d2ca head: the 770 related model/JSON/enum tests
and the full 6,994-test suite pass with PYTHONUTF8=1. Thanks for implementing
the review feedback and for calling out the schema boundary.

[CAOShurong]

I re-reviewed the updated head ea7d2ca93198d85fdd34e40b963b7e3bb1c7c7bd. The protocol-level relatedCryptographicAssets round-trip gap from my earlier review is now addressed, including the intended CycloneDX 1.7 behavior and the documented XML-schema limitation tracked in CycloneDX/specification#1018.

Verification I ran on this exact head:

• the related crypto model/JSON/enum test set: 770 tests passed
• the full test suite with PYTHONUTF8=1: 6,994 tests passed

I also confirmed the upstream schema inconsistency separately and followed it through to the specification issue and an independently tested schema fix path. I did not rerun mypy or flake8 for this approval, so this review does not claim those checks.

OpenAI Codex assisted with the test execution and comparison; I reviewed the implementation and observed outputs and take responsibility for this approval.

[jkowalleck]

re: #1016 (review)

I think we will wait until the fix is out:

• [Defect]: 1.7 XML schema omits protocol relatedCryptographicAssets specification#1018
• fix(xml): allow protocol cryptographic relationships specification#1019