diff --git a/CBOM/en/0x10-Introduction.md b/CBOM/en/0x10-Introduction.md index f215592..ab4d332 100644 --- a/CBOM/en/0x10-Introduction.md +++ b/CBOM/en/0x10-Introduction.md @@ -23,8 +23,8 @@ using and facilitate the assessment of the risk posture to provide a starting po CBOM for this purpose. ## CBOM Design -The overall design goal of CBOM is to provide an abstraction that allows modeling and representing crypto assets in a -structured object format. This comprises the following points. +The overall design goal of CBOM is to provide an abstraction that allows modeling and representing cryptographic assets +in a structured object format. This comprises the following points. 1. Modelling cryptographic assets Cryptographic assets occur in several forms. Algorithms and protocols are most commonly implemented in specialized cryptographic libraries. They may, however, also be 'hardcoded' in software components. Certificates and related cryptographic material like keys, tokens, secrets, or passwords are other cryptographic assets to be modeled. diff --git a/CBOM/en/0x30-Practical-Examples.md b/CBOM/en/0x30-Practical-Examples.md index db5421b..1b99669 100644 --- a/CBOM/en/0x30-Practical-Examples.md +++ b/CBOM/en/0x30-Practical-Examples.md @@ -1,6 +1,390 @@ # Practical Examples -TODO +Examples of assets typically cataloged within a CBOM include algorithms, keys, protocols, and certificates, each with +associated metadata crucial for effective management and security. Algorithms refer to the mathematical functions +utilized for encryption, hashing, and digital signatures, while keys encompass cryptographic keys used for encryption, +decryption, and authentication. Protocols delineate the rules and procedures governing secure communication between +entities and certificates authenticate the identities of entities within a cryptographic system. Associated CBOM metadata +includes details such as algorithm versions, key lengths, protocol configurations, and certificate attributes, providing +comprehensive insights necessary for the management and security of cryptographic assets. +## Algorithm +A cryptographic algorithm is added in the components array of the BOM. The examples below lists the algorithm +AES-128-GCM and SHA512withRSA. + +```json +"components": [ + { + "type": "cryptographic-asset", + "name": "AES-128-GCM", + "cryptoProperties": { + "assetType": "algorithm", + "algorithmProperties": { + "primitive": "ae", + "parameterSetIdentifier": "128", + "mode": "gcm", + "executionEnvironment": "software-plain-ram", + "implementationPlatform": "x86_64", + "certificationLevel": [ "none" ], + "cryptoFunctions": [ "keygen", "encrypt", "decrypt", "tag" ], + "classicalSecurityLevel": 128, + "nistQuantumSecurityLevel": 1 + }, + "oid": "2.16.840.1.101.3.4.1.6" + } + }, + { + "name": "SHA512withRSA", + "type": "cryptographic-asset", + "cryptoProperties": { + "assetType": "algorithm", + "algorithmProperties": { + "primitive": "signature", + "parameterSetIdentifier": "512", + "executionEnvironment": "software-plain-ram", + "implementationPlatform": "x86_64", + "certificationLevel": [ "none" ], + "cryptoFunctions": [ "sign", "verify" ], + "nistQuantumSecurityLevel": 0 + }, + "oid": "1.2.840.113549.1.1.13" + } + } +] +``` + +
+\newpage +
+ +An example with the QSC Signature algorithm Dilithium5 is listed below. + +```json +"components": [ + { + "name": "Dilithium5", + "type": "cryptographic-asset", + "cryptoProperties": { + "assetType": "algorithm", + "algorithmProperties": { + "primitive": "signature", + "executionEnvironment": "software-plain-ram", + "implementationPlatform": "x86_64", + "certificationLevel": [ "none" ], + "cryptoFunctions": ["keygen", "sign", "verify"], + "nistQuantumSecurityLevel": 5 + }, + "oid": "1.3.6.1.4.1.2.267.7.8.7" + } + } +] +``` +
+\newpage +
+ +## Key +The following example demonstrates how an RSA-2048 public key can be included in a CBOM. + +```json +"components": [ { + "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-128-gcm@2.16.840.1.101.3.4.1.6" + }, + "creationDate": "2016-11-21T08:00:00Z", + "activationDate": "2016-11-21T08:20:00Z" + }, + "oid": "1.2.840.113549.1.1.1" + } + }, + { + "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", + "cryptoFunctions": [ "encapsulate", "decapsulate" ] + }, + "oid": "1.2.840.113549.1.1.1" + } + }, + { + "name": "AES-128-GCM", + "type": "cryptographic-asset", + "bom-ref": "crypto/algorithm/aes-128-gcm@2.16.840.1.101.3.4.1.6", + "cryptoProperties": { + "assetType": "algorithm", + "algorithmProperties": { + "parameterSetIdentifier": "128", + "primitive": "ae", + "mode": "gcm", + "executionEnvironment": "software-plain-ram", + "implementationPlatform": "x86_64", + "cryptoFunctions": [ "keygen", "encrypt", "decrypt" ], + "classicalSecurityLevel": 128, + "nistQuantumSecurityLevel": 1 + }, + "oid": "2.16.840.1.101.3.4.1.6" + } + } ] +``` + +## Protocol +A cryptographic protocol is added to the components array of the BOM. The example below lists an instance of the protocol TLS v1.2 with a number of TLS cipher suites. + +```json +"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-128-gcm@2.16.840.1.101.3.4.1.6", + "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/sha512-rsa@1.2.840.113549.1.1.13", + "subjectPublicKeyRef": "crypto/key/rsa2048@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-128-gcm@2.16.840.1.101.3.4.1.6" + }, + "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": 128, + "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" + } + } +] +``` + +## Certificate +The following example details an X.509 certificate in a CBOM. + +```json +"components": [ + { + "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": "None" + }, + "creationDate": "2016-11-21T08:00:00Z", + "activationDate": "2016-11-21T08:20:00Z" + }, + "oid": "1.2.840.113549.1.1.1" + } + }, + { + "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" + } + } +] +```
diff --git a/CBOM/en/0x31-Dependencies.md b/CBOM/en/0x31-Dependencies.md new file mode 100644 index 0000000..b834216 --- /dev/null +++ b/CBOM/en/0x31-Dependencies.md @@ -0,0 +1,26 @@ +# Dependencies +Dependencies between components in the components array are added to the dependencies array. + +The two dependency types are: + +implements: refers to crypto assets implemented, or statically available in a component. Examples are the algorithms provided by crypto libraries. A crypto asset 'implemented' by a component does not imply that it is in use. +uses: refers to crypto assets in use, or being referenced by other components. The referencing can be done by explicit function calls or by configuration at run time. Usage may change over time, so CBOMs always represent a snapshot at a given point in time. +A component can have a dependencies of both types implements and uses. A crypto asset A is considered as 'used' by component C if there is a used dependency path from C to A. + +Note: In classic SBOM, a component represents a library, application, service, etc. that is used as a dependency within the application. Since for some crypto, e.g. the relationship between a protocol and the algorithms used, this relationship is not external but internal, we decided to express this relationship differently by using specific properties to reference assets rather than using the classical dependency implementation. + + +![Dependencies](./images/dependencies.svg) + + +The example shows an application (nginx) that uses the libssl cryptographic library. This library implements the TLSv1.2 protocol. The relationship between the application, the library and the protocol can be expressed by using the depenedencies properties of the SBOM standard. + +Since a TLS protocol supports different cipher suites that include multiple algorithms, there should be a way to represent these relationships as part of the CBOM. Compared to adding the algorithms as "classic" dependencies to the protocol, we defined special property fields that allow referencing the deployment with additional meaning. The protocolProperties allow adding an array of algorithms to a cipher suite as part of the cipher suite array. By modeling and then referencing these algorithms, we can still have only one classical component at the SBOM level, but a subtree of crypto dependencies within the crypto asset components. + +```json +TODO +``` + +
+\newpage +
\ No newline at end of file diff --git a/CBOM/en/images/dependencies.drawio b/CBOM/en/images/dependencies.drawio new file mode 100644 index 0000000..2d77987 --- /dev/null +++ b/CBOM/en/images/dependencies.drawio @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/CBOM/en/images/dependencies.svg b/CBOM/en/images/dependencies.svg new file mode 100644 index 0000000..32c0340 --- /dev/null +++ b/CBOM/en/images/dependencies.svg @@ -0,0 +1,797 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +