From 711e2ff6dc00f8c986a65d58646aee63072808e1 Mon Sep 17 00:00:00 2001 From: Quentin Kaiser Date: Tue, 14 Jul 2026 11:02:33 +0200 Subject: [PATCH] feat(crypto): support standardized algorithm identifiers CycloneDX 1.7 distinguishes schema-defined families and curves while older consumers still depend on free-form curve metadata. Derive the accepted cases from the bundled schema and gate standardized serialization to the new view. Preserve the legacy value through comparison and rendering, then exercise strict schema output and downgrade behavior. Signed-off-by: Quentin Kaiser --- cyclonedx/model/crypto.py | 81 ++++++++++++++++--- tests/_data/models.py | 2 + ...om_v1_6_with_crypto_algorithm-1.7.json.bin | 2 + ...bom_v1_6_with_crypto_algorithm-1.7.xml.bin | 2 + tests/test_deserialize_json.py | 10 +++ tests/test_deserialize_xml.py | 12 +++ tests/test_model_crypto.py | 73 +++++++++++++++++ 7 files changed, 170 insertions(+), 12 deletions(-) diff --git a/cyclonedx/model/crypto.py b/cyclonedx/model/crypto.py index 44bdc182f..cffd7223d 100644 --- a/cyclonedx/model/crypto.py +++ b/cyclonedx/model/crypto.py @@ -344,8 +344,10 @@ class AlgorithmProperties: def __init__( self, *, primitive: Optional[CryptoPrimitive] = None, + algorithm_family: Optional[str] = None, parameter_set_identifier: Optional[str] = None, curve: Optional[str] = None, + elliptic_curve: Optional[str] = None, execution_environment: Optional[CryptoExecutionEnvironment] = None, implementation_platform: Optional[CryptoImplementationPlatform] = None, certification_levels: Optional[Iterable[CryptoCertificationLevel]] = None, @@ -356,8 +358,10 @@ def __init__( nist_quantum_security_level: Optional[int] = None, ) -> None: self.primitive = primitive + self.algorithm_family = algorithm_family self.parameter_set_identifier = parameter_set_identifier self.curve = curve + self.elliptic_curve = elliptic_curve self.execution_environment = execution_environment self.implementation_platform = implementation_platform self.certification_levels = certification_levels or [] @@ -392,7 +396,30 @@ def primitive(self, primitive: Optional[CryptoPrimitive]) -> None: self._primitive = primitive @property + @serializable.view(SchemaVersion1Dot7) @serializable.xml_sequence(2) + def algorithm_family(self) -> Optional[str]: + """ + The standardized family identifier for the algorithm. + + Use an identifier from ``algorithmFamiliesEnum`` in the bundled + ``cryptography-defs.SNAPSHOT.schema.json``. The library does not validate this value; + arbitrary strings can fail strict JSON schema validation. + + .. note:: + Introduced in CycloneDX v1.7. Omitted when serializing to older schema versions. + + Returns: + `str` or `None` + """ + return self._algorithm_family + + @algorithm_family.setter + def algorithm_family(self, algorithm_family: Optional[str]) -> None: + self._algorithm_family = algorithm_family + + @property + @serializable.xml_sequence(3) def parameter_set_identifier(self) -> Optional[str]: """ An identifier for the parameter set of the cryptographic algorithm. Examples: in AES128, '128' identifies the @@ -409,7 +436,7 @@ def parameter_set_identifier(self, parameter_set_identifier: Optional[str]) -> N self._parameter_set_identifier = parameter_set_identifier @property - @serializable.xml_sequence(3) + @serializable.xml_sequence(4) def curve(self) -> Optional[str]: """ The specific underlying Elliptic Curve (EC) definition employed which is an indicator of the level of security @@ -417,6 +444,10 @@ def curve(self) -> Optional[str]: of curve names as defined at https://neuromancer.sk/std/, the source from which can be found at https://github.com/J08nY/std-curves. + .. note:: + Deprecated in CycloneDX v1.7 in favor of :attr:`elliptic_curve`. + Set this property explicitly to retain curve information in CycloneDX v1.6 output. + Returns: `str` or `None` """ @@ -427,7 +458,32 @@ def curve(self, curve: Optional[str]) -> None: self._curve = curve @property - @serializable.xml_sequence(4) + @serializable.view(SchemaVersion1Dot7) + @serializable.xml_sequence(5) + def elliptic_curve(self) -> Optional[str]: + """ + The standardized identifier of the elliptic curve used by the algorithm. + + Use an identifier from ``ellipticCurvesEnum`` in the bundled + ``cryptography-defs.SNAPSHOT.schema.json``. The library does not validate this value; + arbitrary strings can fail strict JSON schema validation. + + .. note:: + Introduced in CycloneDX v1.7. Omitted when serializing to older schema versions. + This value is not copied to :attr:`curve`; set :attr:`curve` explicitly to retain + curve information in CycloneDX v1.6 output. + + Returns: + `str` or `None` + """ + return self._elliptic_curve + + @elliptic_curve.setter + def elliptic_curve(self, elliptic_curve: Optional[str]) -> None: + self._elliptic_curve = elliptic_curve + + @property + @serializable.xml_sequence(6) def execution_environment(self) -> Optional[CryptoExecutionEnvironment]: """ The target and execution environment in which the algorithm is implemented in. @@ -442,7 +498,7 @@ def execution_environment(self, execution_environment: Optional[CryptoExecutionE self._execution_environment = execution_environment @property - @serializable.xml_sequence(4) + @serializable.xml_sequence(7) def implementation_platform(self) -> Optional[CryptoImplementationPlatform]: """ The target platform for which the algorithm is implemented. The implementation can be 'generic', running on @@ -462,7 +518,7 @@ def implementation_platform(self, implementation_platform: Optional[CryptoImplem @serializable.view(SchemaVersion1Dot6) @serializable.view(SchemaVersion1Dot7) @serializable.xml_array(serializable.XmlArraySerializationType.FLAT, child_name='certificationLevel') - @serializable.xml_sequence(5) + @serializable.xml_sequence(8) def certification_levels(self) -> 'SortedSet[CryptoCertificationLevel]': """ The certification that the implementation of the cryptographic algorithm has received, if any. Certifications @@ -478,7 +534,7 @@ def certification_levels(self, certification_levels: Iterable[CryptoCertificatio self._certification_levels = SortedSet(certification_levels) @property - @serializable.xml_sequence(6) + @serializable.xml_sequence(9) def mode(self) -> Optional[CryptoMode]: """ The mode of operation in which the cryptographic algorithm (block cipher) is used. @@ -493,7 +549,7 @@ def mode(self, mode: Optional[CryptoMode]) -> None: self._mode = mode @property - @serializable.xml_sequence(8) + @serializable.xml_sequence(10) def padding(self) -> Optional[CryptoPadding]: """ The padding scheme that is used for the cryptographic algorithm. @@ -509,7 +565,7 @@ def padding(self, padding: Optional[CryptoPadding]) -> None: @property @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, child_name='cryptoFunction') - @serializable.xml_sequence(9) + @serializable.xml_sequence(11) def crypto_functions(self) -> 'SortedSet[CryptoFunction]': """ The cryptographic functions implemented by the cryptographic algorithm. @@ -524,7 +580,7 @@ def crypto_functions(self, crypto_functions: Iterable[CryptoFunction]) -> None: self._crypto_functions = SortedSet(crypto_functions) @property - @serializable.xml_sequence(10) + @serializable.xml_sequence(12) def classical_security_level(self) -> Optional[int]: """ The classical security level that a cryptographic algorithm provides (in bits). @@ -539,7 +595,7 @@ def classical_security_level(self, classical_security_level: Optional[int]) -> N self._classical_security_level = classical_security_level @property - @serializable.xml_sequence(11) + @serializable.xml_sequence(13) def nist_quantum_security_level(self) -> Optional[int]: """ The NIST security strength category as defined in @@ -564,9 +620,10 @@ def nist_quantum_security_level(self, nist_quantum_security_level: Optional[int] def __comparable_tuple(self) -> _ComparableTuple: return _ComparableTuple(( - self.primitive, self._parameter_set_identifier, self.curve, self.execution_environment, - self.implementation_platform, _ComparableTuple(self.certification_levels), self.mode, self.padding, - _ComparableTuple(self.crypto_functions), self.classical_security_level, self.nist_quantum_security_level, + self.primitive, self.algorithm_family, self.parameter_set_identifier, self.curve, self.elliptic_curve, + self.execution_environment, self.implementation_platform, _ComparableTuple(self.certification_levels), + self.mode, self.padding, _ComparableTuple(self.crypto_functions), self.classical_security_level, + self.nist_quantum_security_level, )) def __eq__(self, other: object) -> bool: diff --git a/tests/_data/models.py b/tests/_data/models.py index e2052878f..81d469c7f 100644 --- a/tests/_data/models.py +++ b/tests/_data/models.py @@ -171,8 +171,10 @@ def get_crypto_properties_algorithm() -> CryptoProperties: asset_type=CryptoAssetType.ALGORITHM, algorithm_properties=AlgorithmProperties( primitive=CryptoPrimitive.KEM, + algorithm_family='ML-KEM', parameter_set_identifier='a-parameter-set-id', curve='9n8y2oxty3ao83n8qc2g2x3qcw4jt4wj', + elliptic_curve='nist/P-256', execution_environment=CryptoExecutionEnvironment.SOFTWARE_PLAIN_RAM, implementation_platform=CryptoImplementationPlatform.GENERIC, certification_levels=[ diff --git a/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.json.bin b/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.json.bin index 819b1821b..bb9215d8d 100644 --- a/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.json.bin +++ b/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.json.bin @@ -4,6 +4,7 @@ "bom-ref": "8182921e-0588-472e-b8f9-9c527c68f067", "cryptoProperties": { "algorithmProperties": { + "algorithmFamily": "ML-KEM", "certificationLevel": [ "fips140-1-l1", "fips140-2-l3", @@ -15,6 +16,7 @@ "unknown" ], "curve": "9n8y2oxty3ao83n8qc2g2x3qcw4jt4wj", + "ellipticCurve": "nist/P-256", "executionEnvironment": "software-plain-ram", "implementationPlatform": "generic", "mode": "ecb", diff --git a/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.xml.bin b/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.xml.bin index a31cf67d7..73db0a46d 100644 --- a/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.xml.bin +++ b/tests/_data/snapshots/get_bom_v1_6_with_crypto_algorithm-1.7.xml.bin @@ -11,8 +11,10 @@ algorithm kem + ML-KEM a-parameter-set-id 9n8y2oxty3ao83n8qc2g2x3qcw4jt4wj + nist/P-256 software-plain-ram generic fips140-1-l1 diff --git a/tests/test_deserialize_json.py b/tests/test_deserialize_json.py index 85f8b11aa..5fd04c371 100644 --- a/tests/test_deserialize_json.py +++ b/tests/test_deserialize_json.py @@ -27,6 +27,7 @@ from cyclonedx.model.bom import Bom from cyclonedx.model.license import DisjunctiveLicense, LicenseExpression, LicenseRepository +from cyclonedx.output import make_outputter from cyclonedx.schema import OutputFormat, SchemaVersion from tests import OWN_DATA_DIRECTORY, DeepCompareMixin, SnapshotMixin, mksname from tests._data.models import ( @@ -53,6 +54,15 @@ def test_prepared(self, get_bom: Callable[[], Bom], *_: Any, **__: Any) -> None: self.assertBomDeepEqual(expected, bom, fuzzy_deps=get_bom in all_get_bom_funct_with_incomplete_deps) + def test_crypto_algorithm_identifiers_round_trip(self) -> None: + snapshot_name = mksname('get_bom_v1_6_with_crypto_algorithm', _LATEST_SCHEMA, OutputFormat.JSON) + bom = Bom.from_json(json_loads(self.readSnapshot(snapshot_name))) + output = json_loads(make_outputter(bom, OutputFormat.JSON, _LATEST_SCHEMA).output_as_string()) + properties = output['components'][0]['cryptoProperties']['algorithmProperties'] + + self.assertEqual('ML-KEM', properties['algorithmFamily']) + self.assertEqual('nist/P-256', properties['ellipticCurve']) + def test_empty_supplier(self) -> None: """Regression for issue #600 See: https://github.com/CycloneDX/cyclonedx-python-lib/issues/600 diff --git a/tests/test_deserialize_xml.py b/tests/test_deserialize_xml.py index 8ad0f31cd..a24025480 100644 --- a/tests/test_deserialize_xml.py +++ b/tests/test_deserialize_xml.py @@ -16,6 +16,7 @@ # Copyright (c) OWASP Foundation. All Rights Reserved. from collections.abc import Callable +from json import loads as json_loads from os.path import join from typing import Any from unittest import TestCase @@ -24,6 +25,7 @@ from ddt import ddt, named_data from cyclonedx.model.bom import Bom +from cyclonedx.output import make_outputter from cyclonedx.schema import OutputFormat, SchemaVersion from tests import OWN_DATA_DIRECTORY, DeepCompareMixin, SnapshotMixin, mksname from tests._data.models import ( @@ -50,6 +52,16 @@ def test_prepared(self, get_bom: Callable[[], Bom], *_: Any, **__: Any) -> None: self.assertBomDeepEqual(expected, bom, fuzzy_deps=get_bom in all_get_bom_funct_with_incomplete_deps) + def test_crypto_algorithm_identifiers_round_trip(self) -> None: + snapshot_name = mksname('get_bom_v1_6_with_crypto_algorithm', _LATEST_SCHEMA, OutputFormat.XML) + with open(self.getSnapshotFile(snapshot_name), encoding='utf-8') as snapshot: + bom = Bom.from_xml(snapshot) + output = json_loads(make_outputter(bom, OutputFormat.JSON, _LATEST_SCHEMA).output_as_string()) + properties = output['components'][0]['cryptoProperties']['algorithmProperties'] + + self.assertEqual('ML-KEM', properties['algorithmFamily']) + self.assertEqual('nist/P-256', properties['ellipticCurve']) + def test_component_evidence_identity(self) -> None: xml_file = join(OWN_DATA_DIRECTORY, 'xml', SchemaVersion.V1_6.to_version(), diff --git a/tests/test_model_crypto.py b/tests/test_model_crypto.py index 12265ee19..70be8b372 100644 --- a/tests/test_model_crypto.py +++ b/tests/test_model_crypto.py @@ -15,7 +15,10 @@ # SPDX-License-Identifier: Apache-2.0 # Copyright (c) OWASP Foundation. All Rights Reserved. +from json import loads as json_loads from unittest import TestCase +from unittest.mock import patch +from xml.etree.ElementTree import fromstring from cyclonedx.model.bom_ref import BomRef from cyclonedx.model.crypto import ( @@ -29,6 +32,7 @@ RelatedCryptoMaterialSecuredBy, RelatedCryptoMaterialType, ) +from cyclonedx.schema.schema import SchemaVersion1Dot6, SchemaVersion1Dot7 class TestModelAlgorithmProperties(TestCase): @@ -44,6 +48,75 @@ def test_algorithm_properties_sorting(self) -> None: sorted_algos = sorted(algo_list) self.assertEqual(len(sorted_algos), 3) + def test_new_algorithm_identifiers_and_legacy_curve(self) -> None: + properties = AlgorithmProperties( + algorithm_family='AES', + curve='legacy-curve', + elliptic_curve='nist/P-256', + ) + data_1_7 = json_loads(properties.as_json(view_=SchemaVersion1Dot7)) + self.assertEqual('AES', data_1_7['algorithmFamily']) + self.assertEqual('nist/P-256', data_1_7['ellipticCurve']) + self.assertEqual('legacy-curve', data_1_7['curve']) + + data_1_6 = json_loads(properties.as_json(view_=SchemaVersion1Dot6)) + self.assertNotIn('algorithmFamily', data_1_6) + self.assertNotIn('ellipticCurve', data_1_6) + self.assertEqual('legacy-curve', data_1_6['curve']) + xml_1_6 = fromstring(properties.as_xml(view_=SchemaVersion1Dot6)) + self.assertIsNone(xml_1_6.find('algorithmFamily')) + self.assertIsNone(xml_1_6.find('ellipticCurve')) + self.assertEqual('legacy-curve', xml_1_6.findtext('curve')) + + def test_algorithm_identifier_equality_and_hashing(self) -> None: + for field, value, other_value in ( + ('algorithm_family', 'AES', 'ML-KEM'), + ('elliptic_curve', 'nist/P-256', 'nist/P-384'), + ): + with self.subTest(field=field): + first = AlgorithmProperties() + same = AlgorithmProperties() + different = AlgorithmProperties() + setattr(first, field, value) + setattr(same, field, value) + setattr(different, field, other_value) + + self.assertEqual(first, same) + self.assertEqual(hash(first), hash(same)) + self.assertNotEqual(first, different) + self.assertEqual(2, len({first, same, different})) + with patch('cyclonedx.model.crypto.hash', wraps=hash, create=True) as hash_function: + hash(first) + self.assertIn(value, hash_function.call_args.args[0]) + + def test_algorithm_identifier_sorting(self) -> None: + for field, lower, higher in ( + ('algorithm_family', 'AES', 'ML-KEM'), + ('elliptic_curve', 'nist/P-256', 'nist/P-384'), + ): + with self.subTest(field=field): + first = AlgorithmProperties() + second = AlgorithmProperties() + unset = AlgorithmProperties() + setattr(first, field, lower) + setattr(second, field, higher) + self.assertEqual([first, second, unset], sorted([unset, second, first])) + + def test_algorithm_family_sorts_before_parameter_set_identifier(self) -> None: + first = AlgorithmProperties(algorithm_family='AES', parameter_set_identifier='256') + second = AlgorithmProperties(algorithm_family='ML-KEM', parameter_set_identifier='128') + self.assertEqual([first, second], sorted([second, first])) + + def test_elliptic_curve_downgrade_does_not_populate_legacy_curve(self) -> None: + properties = AlgorithmProperties(elliptic_curve='nist/P-256') + data = json_loads(properties.as_json(view_=SchemaVersion1Dot6)) + self.assertNotIn('ellipticCurve', data) + self.assertNotIn('curve', data) + xml = fromstring(properties.as_xml(view_=SchemaVersion1Dot6)) + self.assertIsNone(xml.find('ellipticCurve')) + self.assertIsNone(xml.find('curve')) + self.assertIsNone(properties.curve) + class TestModelCertificateProperties(TestCase):