feat: add `cyclonedx.model.crypto.ProtocolProperties.crypto_ref_array`

[chistyakov]

Library Version: 7.6.1

Description:

Steps to Reproduce:

1. Use the example JSON provided in the CycloneDX bom-examples repository.
2. Run the following script:

import json
from cyclonedx.model.bom import Bom


# source: https://github.com/CycloneDX/bom-examples/blob/c0436d86cd60693f01d19fe1aacfd01e70e17036/CBOM/Protocol/bom.json

sample = '''{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:e8c355aa-2142-4084-a8c7-6d42c8610ba2",
  "version": 1,
  "metadata": {
    "timestamp": "2024-01-09T12:00:00Z",
    "component": {
      "type": "application",
      "name": "my application",
      "version": "1.0"
    }
  },
  "components": [
    {
      "name": "TLSv1.2",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/protocol/tls@1.2",
      "cryptoProperties": {
        "assetType": "protocol",
        "protocolProperties": {
          "type": "tls",
          "version": "1.2",
          "cipherSuites": [
            {
              "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
              "algorithms": [
                "crypto/algorithm/ecdh-curve25519@1.3.132.1.12",
                "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
                "crypto/algorithm/aes-256-gcm@2.16.840.1.101.3.4.1.46",
                "crypto/algorithm/sha-384@2.16.840.1.101.3.4.2.9"
              ],
              "identifiers": [ "0xC0", "0x30" ]
            }
          ],
          "cryptoRefArray": [
            "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4"
          ]
        },
        "oid": "1.3.18.0.2.32.104"
      }
    },
    {
      "name": "google.com",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4",
      "cryptoProperties": {
        "assetType": "certificate",
        "certificateProperties": {
          "subjectName": "CN = www.google.com",
          "issuerName": "C = US, O = Google Trust Services LLC, CN = GTS CA 1C3",
          "notValidBefore": "2016-11-21T08:00:00Z",
          "notValidAfter": "2017-11-22T07:59:59Z",
          "signatureAlgorithmRef": "crypto/algorithm/sha-512-rsa@1.2.840.113549.1.1.13",
          "subjectPublicKeyRef": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
          "certificateFormat": "X.509",
          "certificateExtension": "crt"
        }
      }
    },
    {
      "name": "SHA512withRSA",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/sha-512-rsa@1.2.840.113549.1.1.13",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "parameterSetIdentifier": "512",
          "executionEnvironment": "software-plain-ram",
          "implementationPlatform": "x86_64",
          "certificationLevel": [ "none" ],
          "cryptoFunctions": [ "digest" ],
          "nistQuantumSecurityLevel": 0
        },
        "oid": "1.2.840.113549.1.1.13"
      }
    },
    {
      "name": "RSA-2048",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
      "cryptoProperties": {
        "assetType": "related-crypto-material",
        "relatedCryptoMaterialProperties": {
          "type": "public-key",
          "id": "2e9ef09e-dfac-4526-96b4-d02f31af1b22",
          "state": "active",
          "size": 2048,
          "algorithmRef": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
          "securedBy": {
            "mechanism": "Software",
            "algorithmRef": "crypto/algorithm/aes-256-gcm@2.16.840.1.101.3.4.1.46"
          },
          "creationDate": "2016-11-21T08:00:00Z",
          "activationDate": "2016-11-21T08:20:00Z"
        },
        "oid": "1.2.840.113549.1.1.1"
      }
    },
    {
      "name": "ECDH",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/ecdh-curve25519@1.3.132.1.12",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "curve": "curve25519",
          "executionEnvironment": "software-plain-ram",
          "implementationPlatform": "x86_64",
          "certificationLevel": [ "none" ],
          "cryptoFunctions": [ "keygen" ]
        },
        "oid": "1.3.132.1.12"
      }
    },
    {
      "name": "RSA-2048",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "parameterSetIdentifier": "2048",
          "executionEnvironment": "software-plain-ram",
          "implementationPlatform": "x86_64",
          "certificationLevel": [ "none" ],
          "cryptoFunctions": [ "encapsulate", "decapsulate" ]
        },
        "oid": "1.2.840.113549.1.1.1"
      }
    },
    {
      "name": "AES-256-GCM",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/aes-256-gcm@2.16.840.1.101.3.4.1.46",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "parameterSetIdentifier": "256",
          "primitive": "ae",
          "mode": "gcm",
          "executionEnvironment": "software-plain-ram",
          "implementationPlatform": "x86_64",
          "certificationLevel": [ "none" ],
          "cryptoFunctions": [ "encrypt", "decrypt" ],
          "classicalSecurityLevel": 256,
          "nistQuantumSecurityLevel": 1
        },
        "oid": "2.16.840.1.101.3.4.1.46"
      }
    },
    {
      "name": "SHA384",
      "type": "cryptographic-asset",
      "bom-ref": "crypto/algorithm/sha-384@2.16.840.1.101.3.4.2.9",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "parameterSetIdentifier": "384",
          "executionEnvironment": "software-plain-ram",
          "implementationPlatform": "x86_64",
          "certificationLevel": [ "none" ],
          "cryptoFunctions": [ "digest" ],
          "nistQuantumSecurityLevel": 2
        },
        "oid": "2.16.840.1.101.3.4.2.9"
      }
    }
  ]
}'''


data = json.loads(sample)

Bom.from_json(data=data)

Observed Behavior:
The code fails with the following exception:

Traceback (most recent call last):
  ...
ValueError: Unexpected key cryptoRefArray/crypto_ref_array in data being serialized to cyclonedx.model.crypto.ProtocolProperties

Environment:

• Python version: 3.10
• Operating System: macOS
• Library version: 7.6.1

Let me know if this works!

[jkowalleck]

Not a bug, but a lack of a feature.

CycloneDX python library is a community effort, everybody is free to add the bits and pieces they need. see #633

In this case, it is the property cyclonedx.model.crypto.ProtocolProperties.crypto_ref_array that needs to be added.
near

cyclonedx-python-lib/cyclonedx/model/crypto.py

Line 1292 in 2aea159

class ProtocolProperties:

If you are interested in providing the missing feature, please let me know.
Then, you should follow our contributing guidelines, and you may open a pullrequest to add the missing feature.

[jkowalleck]

see also: #537

[indiVar0508]

Hi If no one has picked i'll be interested to contribute to this to help, i went through this thread and tried to apply what you suggested and that seems to work and get rid of the error that is raised for above mentioned MRC.

please let me know if this is correct specifically the docstring and xml_sequence, will raise a PR along with tests based on feedback if this is the correct direction to go.

diff --git a/cyclonedx/model/crypto.py b/cyclonedx/model/crypto.py
index d9fd810..9eebf8e 100644
--- a/cyclonedx/model/crypto.py
+++ b/cyclonedx/model/crypto.py
@@ -1309,11 +1309,13 @@ class ProtocolProperties:
         version: Optional[str] = None,
         cipher_suites: Optional[Iterable[ProtocolPropertiesCipherSuite]] = None,
         ikev2_transform_types: Optional[Ikev2TransformTypes] = None,
+        crypto_ref_array: Optional[BomRef] = None,
     ) -> None:
         self.type = type
         self.version = version
         self.cipher_suites = cipher_suites or []  # type:ignore[assignment]
         self.ikev2_transform_types = ikev2_transform_types
+        self.crypto_ref_array = crypto_ref_array
 
     @property
     @serializable.xml_sequence(10)
@@ -1376,13 +1378,29 @@ class ProtocolProperties:
     def ikev2_transform_types(self, ikev2_transform_types: Optional[Ikev2TransformTypes]) -> None:
         self._ikev2_transform_types = ikev2_transform_types
 
+
+    @property
+    @serializable.xml_sequence(40)
+    def crypto_ref_array(self) -> Optional[BomRef]:
+        """
+        A list of protocol-related cryptographic assets.
+
+        Returns:
+            `BomRef` or `None`
+        """
+        return self._crypto_ref_array
+
+    @crypto_ref_array.setter
+    def crypto_ref_array(self, crypto_ref_array: Optional[BomRef]) -> None:
+        self._crypto_ref_array = crypto_ref_array
+
     def __eq__(self, other: object) -> bool:
         if isinstance(other, ProtocolProperties):
             return hash(other) == hash(self)
         return False
 
     def __hash__(self) -> int:
-        return hash((self.type, self.version, tuple(self.cipher_suites), self.ikev2_transform_types))
+        return hash((self.type, self.version, tuple(self.cipher_suites), self.ikev2_transform_types), self.crypto_ref_array)
 
     def __repr__(self) -> str:
         return f'<ProtocolProperties type={self.type}, version={self.version}>'

[jkowalleck]

please let me know if this is correct specifically the docstring and xml_sequence

lets discuss this in the PR, where code can be annotated and changes can be suggested/plucked easily.

will raise a PR along with tests based on feedback if this is the correct direction to go.

👍 please do

[indiVar0508]

Raised the PR!

• feat: add cyclonedx.model.crypto.ProtocolProperties.crypto_refs #767