Skip to content

Commit cd36928

Browse files
stevespringettstevespringett
committedFeb 3, 2024
Added CBOM examples
1 parent 92eaa75 commit cd36928

File tree

11 files changed

+486
-0
lines changed

11 files changed

+486
-0
lines changed
 

‎CBOM/Algorithm/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# CBOM Algorithm Example
2+
3+
A cryptographic algorithm is added in the components array of the BOM. This example lists the algorithm
4+
AES-128-GCM and SHA512withRSA.

‎CBOM/Algorithm/bom.json

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
{
2+
"bomFormat": "CycloneDX",
3+
"specVersion": "1.6",
4+
"serialNumber": "urn:uuid:e8c355aa-2142-4084-a8c7-6d42c8610ba2",
5+
"version": 1,
6+
"metadata": {
7+
"timestamp": "2024-01-09T12:00:00Z",
8+
"component": {
9+
"type": "application",
10+
"name": "my application",
11+
"version": "1.0"
12+
}
13+
},
14+
"components": [
15+
{
16+
"type": "cryptographic-asset",
17+
"name": "AES-128-GCM",
18+
"cryptoProperties": {
19+
"assetType": "algorithm",
20+
"algorithmProperties": {
21+
"primitive": "ae",
22+
"parameterSetIdentifier": "128",
23+
"mode": "gcm",
24+
"executionEnvironment": "software-plain-ram",
25+
"implementationPlatform": "x86_64",
26+
"certificationLevel": [ "none" ],
27+
"cryptoFunctions": [ "keygen", "encrypt", "decrypt", "tag" ],
28+
"classicalSecurityLevel": 128,
29+
"nistQuantumSecurityLevel": 1
30+
},
31+
"oid": "2.16.840.1.101.3.4.1.6"
32+
}
33+
},
34+
{
35+
"name": "SHA512withRSA",
36+
"type": "cryptographic-asset",
37+
"cryptoProperties": {
38+
"assetType": "algorithm",
39+
"algorithmProperties": {
40+
"primitive": "signature",
41+
"parameterSetIdentifier": "512",
42+
"executionEnvironment": "software-plain-ram",
43+
"implementationPlatform": "x86_64",
44+
"certificationLevel": [ "none" ],
45+
"cryptoFunctions": [ "sign", "verify" ],
46+
"nistQuantumSecurityLevel": 0
47+
},
48+
"oid": "1.2.840.113549.1.1.13"
49+
}
50+
}
51+
]
52+
}

‎CBOM/Certificate/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Certificate Example
2+
This example details an X.509 certificate in a CBOM.

‎CBOM/Certificate/bom.json

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
{
2+
"bomFormat": "CycloneDX",
3+
"specVersion": "1.6",
4+
"serialNumber": "urn:uuid:e8c355aa-2142-4084-a8c7-6d42c8610ba2",
5+
"version": 1,
6+
"metadata": {
7+
"timestamp": "2024-01-09T12:00:00Z",
8+
"component": {
9+
"type": "application",
10+
"name": "my application",
11+
"version": "1.0"
12+
}
13+
},
14+
"components": [
15+
{
16+
"name": "google.com",
17+
"type": "cryptographic-asset",
18+
"bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4",
19+
"cryptoProperties": {
20+
"assetType": "certificate",
21+
"certificateProperties": {
22+
"subjectName": "CN = www.google.com",
23+
"issuerName": "C = US, O = Google Trust Services LLC, CN = GTS CA 1C3",
24+
"notValidBefore": "2016-11-21T08:00:00Z",
25+
"notValidAfter": "2017-11-22T07:59:59Z",
26+
"signatureAlgorithmRef": "crypto/algorithm/sha-512-rsa@1.2.840.113549.1.1.13",
27+
"subjectPublicKeyRef": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
28+
"certificateFormat": "X.509",
29+
"certificateExtension": "crt"
30+
}
31+
}
32+
},
33+
{
34+
"name": "SHA512withRSA",
35+
"type": "cryptographic-asset",
36+
"bom-ref": "crypto/algorithm/sha-512-rsa@1.2.840.113549.1.1.13",
37+
"cryptoProperties": {
38+
"assetType": "algorithm",
39+
"algorithmProperties": {
40+
"parameterSetIdentifier": "512",
41+
"executionEnvironment": "software-plain-ram",
42+
"implementationPlatform": "x86_64",
43+
"certificationLevel": [ "none" ],
44+
"cryptoFunctions": [ "digest" ],
45+
"nistQuantumSecurityLevel": 0
46+
},
47+
"oid": "1.2.840.113549.1.1.13"
48+
}
49+
},
50+
{
51+
"name": "RSA-2048",
52+
"type": "cryptographic-asset",
53+
"bom-ref": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
54+
"cryptoProperties": {
55+
"assetType": "related-crypto-material",
56+
"relatedCryptoMaterialProperties": {
57+
"type": "public-key",
58+
"id": "2e9ef09e-dfac-4526-96b4-d02f31af1b22",
59+
"state": "active",
60+
"size": 2048,
61+
"algorithmRef": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
62+
"securedBy": {
63+
"mechanism": "None"
64+
},
65+
"creationDate": "2016-11-21T08:00:00Z",
66+
"activationDate": "2016-11-21T08:20:00Z"
67+
},
68+
"oid": "1.2.840.113549.1.1.1"
69+
}
70+
},
71+
{
72+
"name": "RSA-2048",
73+
"type": "cryptographic-asset",
74+
"bom-ref": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
75+
"cryptoProperties": {
76+
"assetType": "algorithm",
77+
"algorithmProperties": {
78+
"parameterSetIdentifier": "2048",
79+
"executionEnvironment": "software-plain-ram",
80+
"implementationPlatform": "x86_64",
81+
"certificationLevel": [ "none" ],
82+
"cryptoFunctions": [ "encapsulate", "decapsulate" ]
83+
},
84+
"oid": "1.2.840.113549.1.1.1"
85+
}
86+
}
87+
]
88+
}

‎CBOM/Example-With-Dependencies/bom.json

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
{
2+
"bomFormat": "CycloneDX",
3+
"specVersion": "1.6",
4+
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
5+
"version": 1,
6+
"metadata": {
7+
"component": {
8+
"type": "application",
9+
"bom-ref": "acme-application",
10+
"name": "Acme Application",
11+
"version": "1.0"
12+
}
13+
},
14+
"components": [
15+
{
16+
"type": "cryptographic-asset",
17+
"bom-ref": "aes128gcm",
18+
"name": "AES",
19+
"cryptoProperties": {
20+
"assetType": "algorithm",
21+
"algorithmProperties": {
22+
"primitive": "ae",
23+
"parameterSetIdentifier": "128",
24+
"executionEnvironment": "software-plain-ram",
25+
"implementationPlatform": "x86_64",
26+
"certificationLevel": [ "none" ],
27+
"mode": "gcm",
28+
"cryptoFunctions": ["keygen", "encrypt", "decrypt", "tag"],
29+
"classicalSecurityLevel": 128,
30+
"nistQuantumSecurityLevel": 1
31+
},
32+
"oid": "2.16.840.1.101.3.4.1.6"
33+
}
34+
},
35+
{
36+
"type": "library",
37+
"bom-ref": "crypto-library",
38+
"name": "Crypto library",
39+
"version": "1.0.0"
40+
},
41+
{
42+
"type": "library",
43+
"bom-ref": "some-library",
44+
"name": "Some library",
45+
"version": "1.0.0"
46+
}
47+
],
48+
"dependencies": [
49+
{
50+
"ref": "acme-application",
51+
"dependsOn": ["crypto-library"]
52+
},
53+
{
54+
"ref": "crypto-library",
55+
"provides": ["aes128gcm"],
56+
"dependsOn": ["some-library"]
57+
}
58+
]
59+
}

‎CBOM/Key/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Key Example
2+
The following example demonstrates how an RSA-2048 public key can be included in a CBOM.

‎CBOM/Key/bom.json

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
{
2+
"bomFormat": "CycloneDX",
3+
"specVersion": "1.6",
4+
"serialNumber": "urn:uuid:e8c355aa-2142-4084-a8c7-6d42c8610ba2",
5+
"version": 1,
6+
"metadata": {
7+
"timestamp": "2024-01-09T12:00:00Z",
8+
"component": {
9+
"type": "application",
10+
"name": "my application",
11+
"version": "1.0"
12+
}
13+
},
14+
"components": [
15+
{
16+
"name": "RSA-2048",
17+
"type": "cryptographic-asset",
18+
"bom-ref": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
19+
"cryptoProperties": {
20+
"assetType": "related-crypto-material",
21+
"relatedCryptoMaterialProperties": {
22+
"type": "public-key",
23+
"id": "2e9ef09e-dfac-4526-96b4-d02f31af1b22",
24+
"state": "active",
25+
"size": 2048,
26+
"algorithmRef": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
27+
"securedBy": {
28+
"mechanism": "Software",
29+
"algorithmRef": "crypto/algorithm/aes-128-gcm@2.16.840.1.101.3.4.1.6"
30+
},
31+
"creationDate": "2016-11-21T08:00:00Z",
32+
"activationDate": "2016-11-21T08:20:00Z"
33+
},
34+
"oid": "1.2.840.113549.1.1.1"
35+
}
36+
},
37+
{
38+
"name": "RSA-2048",
39+
"type": "cryptographic-asset",
40+
"bom-ref": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
41+
"cryptoProperties": {
42+
"assetType": "algorithm",
43+
"algorithmProperties": {
44+
"parameterSetIdentifier": "2048",
45+
"executionEnvironment": "software-plain-ram",
46+
"implementationPlatform": "x86_64",
47+
"cryptoFunctions": [ "encapsulate", "decapsulate" ]
48+
},
49+
"oid": "1.2.840.113549.1.1.1"
50+
}
51+
},
52+
{
53+
"name": "AES-128-GCM",
54+
"type": "cryptographic-asset",
55+
"bom-ref": "crypto/algorithm/aes-128-gcm@2.16.840.1.101.3.4.1.6",
56+
"cryptoProperties": {
57+
"assetType": "algorithm",
58+
"algorithmProperties": {
59+
"parameterSetIdentifier": "128",
60+
"primitive": "ae",
61+
"mode": "gcm",
62+
"executionEnvironment": "software-plain-ram",
63+
"implementationPlatform": "x86_64",
64+
"cryptoFunctions": [ "keygen", "encrypt", "decrypt" ],
65+
"classicalSecurityLevel": 128,
66+
"nistQuantumSecurityLevel": 1
67+
},
68+
"oid": "2.16.840.1.101.3.4.1.6"
69+
}
70+
}
71+
]
72+
}

‎CBOM/Protocol/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Protocol Example
2+
A cryptographic protocol is added to the components array of the BOM. This example lists an instance of the
3+
protocol TLS v1.2 with a number of TLS cipher suites.

‎CBOM/Protocol/bom.json

+170
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
{
2+
"bomFormat": "CycloneDX",
3+
"specVersion": "1.6",
4+
"serialNumber": "urn:uuid:e8c355aa-2142-4084-a8c7-6d42c8610ba2",
5+
"version": 1,
6+
"metadata": {
7+
"timestamp": "2024-01-09T12:00:00Z",
8+
"component": {
9+
"type": "application",
10+
"name": "my application",
11+
"version": "1.0"
12+
}
13+
},
14+
"components": [
15+
{
16+
"name": "TLSv1.2",
17+
"type": "cryptographic-asset",
18+
"bom-ref": "crypto/protocol/tls@1.2",
19+
"cryptoProperties": {
20+
"assetType": "protocol",
21+
"protocolProperties": {
22+
"type": "tls",
23+
"version": "1.2",
24+
"cipherSuites": [
25+
{
26+
"name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
27+
"algorithms": [
28+
"crypto/algorithm/ecdh-curve25519@1.3.132.1.12",
29+
"crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
30+
"crypto/algorithm/aes-128-gcm@2.16.840.1.101.3.4.1.6",
31+
"crypto/algorithm/sha-384@2.16.840.1.101.3.4.2.9"
32+
],
33+
"identifiers": [ "0xC0", "0x30" ]
34+
}
35+
],
36+
"cryptoRefArray": [
37+
"crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4"
38+
]
39+
},
40+
"oid": "1.3.18.0.2.32.104"
41+
}
42+
},
43+
{
44+
"name": "google.com",
45+
"type": "cryptographic-asset",
46+
"bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4",
47+
"cryptoProperties": {
48+
"assetType": "certificate",
49+
"certificateProperties": {
50+
"subjectName": "CN = www.google.com",
51+
"issuerName": "C = US, O = Google Trust Services LLC, CN = GTS CA 1C3",
52+
"notValidBefore": "2016-11-21T08:00:00Z",
53+
"notValidAfter": "2017-11-22T07:59:59Z",
54+
"signatureAlgorithmRef": "crypto/algorithm/sha512-rsa@1.2.840.113549.1.1.13",
55+
"subjectPublicKeyRef": "crypto/key/rsa2048@1.2.840.113549.1.1.1",
56+
"certificateFormat": "X.509",
57+
"certificateExtension": "crt"
58+
}
59+
}
60+
},
61+
{
62+
"name": "SHA512withRSA",
63+
"type": "cryptographic-asset",
64+
"bom-ref": "crypto/algorithm/sha-512-rsa@1.2.840.113549.1.1.13",
65+
"cryptoProperties": {
66+
"assetType": "algorithm",
67+
"algorithmProperties": {
68+
"parameterSetIdentifier": "512",
69+
"executionEnvironment": "software-plain-ram",
70+
"implementationPlatform": "x86_64",
71+
"certificationLevel": [ "none" ],
72+
"cryptoFunctions": [ "digest" ],
73+
"nistQuantumSecurityLevel": 0
74+
},
75+
"oid": "1.2.840.113549.1.1.13"
76+
}
77+
},
78+
{
79+
"name": "RSA-2048",
80+
"type": "cryptographic-asset",
81+
"bom-ref": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
82+
"cryptoProperties": {
83+
"assetType": "related-crypto-material",
84+
"relatedCryptoMaterialProperties": {
85+
"type": "public-key",
86+
"id": "2e9ef09e-dfac-4526-96b4-d02f31af1b22",
87+
"state": "active",
88+
"size": 2048,
89+
"algorithmRef": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
90+
"securedBy": {
91+
"mechanism": "Software",
92+
"algorithmRef": "crypto/algorithm/aes-128-gcm@2.16.840.1.101.3.4.1.6"
93+
},
94+
"creationDate": "2016-11-21T08:00:00Z",
95+
"activationDate": "2016-11-21T08:20:00Z"
96+
},
97+
"oid": "1.2.840.113549.1.1.1"
98+
}
99+
},
100+
{
101+
"name": "ECDH",
102+
"type": "cryptographic-asset",
103+
"bom-ref": "crypto/algorithm/ecdh-curve25519@1.3.132.1.12",
104+
"cryptoProperties": {
105+
"assetType": "algorithm",
106+
"algorithmProperties": {
107+
"curve": "curve25519",
108+
"executionEnvironment": "software-plain-ram",
109+
"implementationPlatform": "x86_64",
110+
"certificationLevel": [ "none" ],
111+
"cryptoFunctions": [ "keygen" ]
112+
},
113+
"oid": "1.3.132.1.12"
114+
}
115+
},
116+
{
117+
"name": "RSA-2048",
118+
"type": "cryptographic-asset",
119+
"bom-ref": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
120+
"cryptoProperties": {
121+
"assetType": "algorithm",
122+
"algorithmProperties": {
123+
"parameterSetIdentifier": "2048",
124+
"executionEnvironment": "software-plain-ram",
125+
"implementationPlatform": "x86_64",
126+
"certificationLevel": [ "none" ],
127+
"cryptoFunctions": [ "encapsulate", "decapsulate" ]
128+
},
129+
"oid": "1.2.840.113549.1.1.1"
130+
}
131+
},
132+
{
133+
"name": "AES-256-GCM",
134+
"type": "cryptographic-asset",
135+
"bom-ref": "crypto/algorithm/aes-256-gcm@2.16.840.1.101.3.4.1.46",
136+
"cryptoProperties": {
137+
"assetType": "algorithm",
138+
"algorithmProperties": {
139+
"parameterSetIdentifier": "256",
140+
"primitive": "ae",
141+
"mode": "gcm",
142+
"executionEnvironment": "software-plain-ram",
143+
"implementationPlatform": "x86_64",
144+
"certificationLevel": [ "none" ],
145+
"cryptoFunctions": [ "encrypt", "decrypt" ],
146+
"classicalSecurityLevel": 128,
147+
"nistQuantumSecurityLevel": 1
148+
},
149+
"oid": "2.16.840.1.101.3.4.1.46"
150+
}
151+
},
152+
{
153+
"name": "SHA384",
154+
"type": "cryptographic-asset",
155+
"bom-ref": "crypto/algorithm/sha-384@2.16.840.1.101.3.4.2.9",
156+
"cryptoProperties": {
157+
"assetType": "algorithm",
158+
"algorithmProperties": {
159+
"parameterSetIdentifier": "384",
160+
"executionEnvironment": "software-plain-ram",
161+
"implementationPlatform": "x86_64",
162+
"certificationLevel": [ "none" ],
163+
"cryptoFunctions": [ "digest" ],
164+
"nistQuantumSecurityLevel": 2
165+
},
166+
"oid": "2.16.840.1.101.3.4.2.9"
167+
}
168+
}
169+
]
170+
}

‎CBOM/README.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Cryptography Bill of Materials (CBOM)
2+
3+
A Cryptography Bill of Materials (CBOM) is an object model to describe cryptographic assets and their dependencies.
4+
Support for CBOM is included in CycloneDX v1.6 and higher. Discovering, managing, and reporting on cryptographic assets
5+
is necessary as the first step on the migration journey to quantum-safe systems and applications.
6+
7+
- As of v1.6, CycloneDX supports `cryptographic-asset` as a first-class component type
8+
9+
## CBOM Design
10+
The overall design goal of CBOM is to provide an abstraction that allows modeling and representing crypto assets in a
11+
structured object format. This comprises the following points.
12+
13+
1. Modelling cryptographic assets
14+
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.
15+
16+
2. Capturing cryptographic asset properties
17+
Cryptographic assets have properties that uniquely define them and that make them actionable for further reasoning. For example, it makes a difference if one knows the algorithm family (e.g. AES) or the specific variant or instantiation (e.g. AES-128-GCM). This is because the security level and the algorithm primitive (authenticated encryption) are only defined by the definition of the algorithm variant. The presence of a weak cryptographic algorithm like SHA1 vs. HMAC-SHA1 also makes a difference. Therefore, the goal of CBOM is to capture relevant cryptographic asset properties.
18+
19+
3. Capturing crypto asset dependencies
20+
To understand the impact of a cryptographic asset, it is important to capture its dependencies. Cryptographic libraries 'implement' certain algorithms and protocols, but their implementation alone does not reflect their usage by applications. CBOM, therefore, differentiates between 'implements' and 'uses' dependencies. It is possible to model algorithms or protocols that use other algorithms (e.g., TLS 1.3 uses ECDH/secp256r1), libraries that implement algorithms, and applications that 'use' algorithms from a library.
21+
22+
4. Applicability to various software components
23+
CycloneDX supports various components such as applications, frameworks, libraries, containers, operating systems, devices, firmware, and files. CBOM extends this model and can communicate a component's dependency on cryptographic assets.
24+
25+
5. High compatibility to CycloneDX SBOM and related tooling
26+
CBOM is native to the CycloneDX standard. It integrates cryptographic assets as an additional component type in the CycloneDX schema and further extends dependencies with the ability to specify dependency usage and implementation details. CBOM data can be present in existing SBOMs or externalized into dedicated CBOMs, thus creating modularity, which may optionally have varying authentication and authorization requirements.
27+
28+
6. Enable automatic reasoning
29+
CBOM enables tooling to reason about cryptographic assets and their dependencies automatically. This allows checking for compliance with policies that apply to cryptographic use and implementation.
30+
31+
32+
## High Level Object Model
33+
![CycloneDX Object Model Swimlane](https://cyclonedx.org/theme/assets/images/CycloneDX-Object-Model-Swimlane.svg)

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ are categorized by different BOM types including:
1313

1414
| BOM Type | Description |
1515
|--------------------|-----------------------------------------|
16+
| [CBOM](CBOM) | Cryptography Bill of Materials |
1617
| [HBOM](HBOM) | Hardware Bill of Materials |
1718
| [OBOM](OBOM) | Operations Bill of Materials |
1819
| [SaaSBOM](SaaSBOM) | Software-as-a-Service Bill of Materials |

0 commit comments

Comments
 (0)
Please sign in to comment.