Skip to content

Commit ed3aa88

Browse files
bhessbhess
committed
Initial upload
1 parent 57902e2 commit ed3aa88

8 files changed

+3573
-2
lines changed

‎EXAMPLES.md

+350
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,350 @@
1+
# Cryptography Bill of Materials - Examples
2+
3+
This document provides examples for using Cryptography Bills of Materials (CBOMs).
4+
5+
- [Cryptography Bill of Materials - Examples](#cryptography-bill-of-materials---examples)
6+
- [Components](#components)
7+
- [Algorithm](#algorithm)
8+
- [Protocol](#protocol)
9+
- [Library](#library)
10+
- [Application](#application)
11+
- [Certificate](#certificate)
12+
- [Releated Crypto Material](#releated-crypto-material)
13+
- [CBOM Project Metadata](#cbom-project-metadata)
14+
- [Dependencies](#dependencies)
15+
- [Dependencies viewed from an application](#dependencies-viewed-from-an-application)
16+
- [Dependencies viewed from a library](#dependencies-viewed-from-a-library)
17+
18+
# Components
19+
20+
## Algorithm
21+
22+
A crypto algorithm is added in the `components` array of the BOM. The example below lists the algorithm `AES-128-GCM`. As reference key (`bom-ref`), the algorithm OID is chosen.
23+
24+
```
25+
"components": [
26+
...
27+
{
28+
"type": "crypto-asset",
29+
"bom-ref": "oid:2.16.840.1.101.3.4.1.6",
30+
"name": "AES",
31+
"cryptoProperties": {
32+
"assetType": "algorithm",
33+
"algorithmProperties": {
34+
"variant": "AES-128-GCM",
35+
"primitive": "ae",
36+
"mode": "gcm",
37+
"implementationLevel": "softwarePlainRam",
38+
"implementationPlatform": "x86_64",
39+
"certificationLevel": "none",
40+
"cryptoFunctions": ["keygen", "encrypt", "decrypt", "tag"]
41+
},
42+
"classicalSecurityLevel": 128,
43+
"quantumSecurityLevel": 1
44+
}
45+
}
46+
...
47+
]
48+
```
49+
50+
An example with the QSC Signature algorithm `Dilithium-5` is listed below. As reference key (`bom-ref`), the algorithm OID is chosen:
51+
52+
```
53+
"components": [
54+
...
55+
{
56+
"type": "crypto-asset",
57+
"bom-ref": "oid:1.3.6.1.4.1.2.267.7.8.7",
58+
"name": "Dilithium",
59+
"cryptoProperties": {
60+
"assetType": "algorithm",
61+
"algorithmProperties": {
62+
"variant": "Dilithium-5",
63+
"primitive": "signature",
64+
"implementationLevel": "softwarePlainRam",
65+
"implementationPlatform": "x86_64",
66+
"certificationLevel": "none",
67+
"cryptoFunctions": ["keygen", "sign", "verify"]
68+
},
69+
"quantumSecurityLevel": 5
70+
}
71+
}
72+
...
73+
]
74+
```
75+
76+
77+
## Protocol
78+
79+
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.
80+
81+
```
82+
"components": [
83+
...
84+
{
85+
"type": "crypto-asset",
86+
"bom-ref": "oid:1.3.18.0.2.32.104",
87+
"name": "tlsv12",
88+
"cryptoProperties": {
89+
"assetType": "protocol",
90+
"protocolProperties": {
91+
"tlsCipherSuites" : [
92+
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (ecdh_x25519)", "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (ecdh_x25519)", "TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048)", "TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048)"
93+
]
94+
}
95+
}
96+
}
97+
...
98+
]
99+
```
100+
101+
## Library
102+
103+
Crypto libraries use the standard CycloneDX type `library`. A way to declare the bom-ref is to use [CPE](https://nvd.nist.gov/products/cpe). The example below lists the OpenSSL 1.1.1q library:
104+
105+
```
106+
"components": [
107+
...
108+
{
109+
"type": "library",
110+
"bom-ref": "cpe:2.3:a:openssl:openssl:1.1.1q:*:*:*:*:*:*:*",
111+
"name": "openssl",
112+
"version": "1.1.1q"
113+
}
114+
...
115+
]
116+
```
117+
118+
## Application
119+
120+
Applications use the standard CycloneDX type `application`. A way to declare the bom-ref is to use [CPE](https://nvd.nist.gov/products/cpe). The example below lists the nginx 1.23.2 application:
121+
122+
```
123+
"components": [
124+
...
125+
{
126+
"type": "application",
127+
"bom-ref": "cpe:2.3:a:f5:nginx:1.23.2:*:*:*:*:*:*:*",
128+
"name": "nginx",
129+
"version": "1.23.2"
130+
}
131+
...
132+
]
133+
```
134+
135+
## Certificate
136+
137+
A crypto algorithm is added in the `components` array of the BOM. The example below lists a X.509 certificate.
138+
139+
```
140+
"components": [
141+
...
142+
{
143+
"type": "crypto-asset",
144+
"bom-ref": "ref:10:e6:fc:62:b7:41:8a:d5:00:5e:45:b6",
145+
"name": "cert-wikipedia-10:e6:fc:62:b7:41:8a:d5:00:5e:45:b6",
146+
"cryptoProperties": {
147+
"assetType": "certificate",
148+
"certificateProperties": {
149+
"subjectName": "C=US, ST=California, L=San Francisco, O=Wikimedia Foundation, Inc., CN=*.wikipedia.org",
150+
"issuerName": "C=BE, O=GlobalSign nv-sa, CN=GlobalSign Organization Validation CA - SHA256 - G2",
151+
"notValidBefore": "Nov 21 08:00:00 2016 GMT",
152+
"notValidAfter": "Nov 22 07:59:59 2017 GMT",
153+
"certificateAlgorithm": "prime256v1",
154+
"certificateSignatureAlgorithm": "sha256WithRSAEncryption",
155+
"certificateFormat": "X.509"
156+
}
157+
}
158+
}
159+
...
160+
]
161+
```
162+
163+
## Releated Crypto Material
164+
165+
Related crypto material is added in the `components` array of the BOM. The example below lists a public key in PEM format:
166+
167+
```
168+
"components": [
169+
...
170+
{
171+
"type": "crypto-asset",
172+
"bom-ref": "ref:10:e6:fc:62:b7:41:8a:d5:00:5e:45:b6",
173+
"name": "cert-wikipedia-10:e6:fc:62:b7:41:8a:d5:00:5e:45:b6",
174+
"cryptoProperties": {
175+
"assetType": "relatedCryptoMaterial",
176+
"relatedCryptoMaterialProperties": {
177+
"relatedCryptoMaterialType": "publicKey",
178+
"size": 3608,
179+
"format": "PEM",
180+
"secured": false
181+
182+
}
183+
}
184+
}
185+
...
186+
]
187+
```
188+
189+
## CBOM Project Metadata
190+
191+
The `metadata` property of CBOM is used to describe the main project component.
192+
193+
```
194+
"bomFormat": "CBOM",
195+
"specVersion": "1.4-cbom-1.0",
196+
"serialNumber": "urn:uuid:63304c0b-0d43-43cb-b0a7-f75b4b7ecf98",
197+
"version": 1,
198+
"metadata": {
199+
"timestamp": "2022-11-30T10:22:42.812881+00:00",
200+
"component": {
201+
"type": "application",
202+
"bom-ref": "cpe:2.3:a:f5:nginx:1.23.2:*:*:*:*:*:*:*",
203+
"name": "nginx",
204+
"version": "1.23.2"
205+
}
206+
},
207+
"components": [
208+
...
209+
]
210+
```
211+
212+
# Dependencies
213+
214+
Dependencies between components in the `components` array are added to the `dependencies` array.
215+
216+
The two dependency types are:
217+
218+
- `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.
219+
- `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.
220+
221+
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.
222+
223+
## Dependencies viewed from an application
224+
225+
The chart below shows a partial dependency graph from a CBOM of the application `nginx`. Dependency types `uses` are marked with `u` and dependency types `implements` are marked with `i`.
226+
227+
![Dependency graph of an application](img/app-cbom.png "Dependency graph of an application")
228+
229+
Key conclusions from the dependency graph:
230+
- A `uses` path exists from nginx to TLS v1.3, AES-128-GCM, SHA256 and HMAC-DRBG. These crypto assets can be considered used by nginx.
231+
- No `uses` paths from nginx to TLS v1.2, SSL v3 and MD5 exists. These crypto assets can be considered implemented by libraries (libssl.so, libcrypto.so) but not used by nginx.
232+
233+
Note: Suppose that SSL v3 uses MD5. The dependency graph will still show no `uses` dependency from libcrypto.so to MD5 since there is no `uses` dependency from any component to SSL v3.
234+
235+
The dependency array of the CBOM will look as follows (for simplicity, we use the crypto asset names as the `bom-ref` property. In practice, one use CPE, purl and OID identifiers):
236+
237+
```
238+
"dependencies": [
239+
{
240+
"ref": "nginx",
241+
"dependsOn": [
242+
"libssl"
243+
],
244+
"dependencyType": "uses"
245+
},
246+
{
247+
"ref": "libssl.so",
248+
"dependsOn": [
249+
"TLS v1.3", "TLS v1.2", "SSL v3"
250+
],
251+
"dependencyType": "implements"
252+
},
253+
{
254+
"ref": "libssl.so",
255+
"dependsOn": [
256+
"TLS v1.3"
257+
],
258+
"dependencyType": "uses"
259+
},
260+
{
261+
"ref": "TLS v1.3",
262+
"dependsOn": [
263+
"libcrypto.so"
264+
],
265+
"dependencyType": "uses"
266+
},
267+
{
268+
"ref": "TLS v1.2",
269+
"dependsOn": [
270+
"libcrypto.so"
271+
],
272+
"dependencyType": "uses"
273+
},
274+
{
275+
"ref": "SSL v3",
276+
"dependsOn": [
277+
"libcrypto.so"
278+
],
279+
"dependencyType": "uses"
280+
},
281+
{
282+
"ref": "libcrypto.so",
283+
"dependsOn": [
284+
"MD5", "AES-128-GCM", "SHA256", "HMAC-DRBG"
285+
],
286+
"dependencyType": "implements"
287+
},
288+
{
289+
"ref": "libcrypto.so",
290+
"dependsOn": [
291+
"AES-128-GCM", "SHA256", "HMAC-DRBG"
292+
],
293+
"dependencyType": "uses"
294+
}
295+
]
296+
```
297+
298+
## Dependencies viewed from a library
299+
300+
The chart below shows a partial dependency graph from a CBOM of crypto library `libssl.so`.
301+
302+
![Dependency graph of a library](img/lib-cbom.png "Dependency graph of a library")
303+
304+
Key conclusions from the dependency graph:
305+
- libssl.so implements TLS protocol versions TLS v1.3, TLS v1.2 and SSL v3
306+
- The TLS protocols versions TLS v1.3, TLS v1.2 and SSL v3 use libcrypto.so
307+
308+
Note that, in contrast to the dependencies viewed from the application, there are no `uses` dependencies from libcrypto.so to any algorithm. This is because there is no `uses` dependency to any of the TLS protocol versions. If, for example, SSL v3 is the top level component, `uses` dependencies to the algorithms used by SSL v3 are added.
309+
310+
The dependency array of the CBOM will look as follows (for simplicity, we use the crypto asset names as the `bom-ref` property. In practice, one use CPE, purl and OID identifiers):
311+
312+
```
313+
"dependencies": [
314+
{
315+
"ref": "libssl.so",
316+
"dependsOn": [
317+
"TLS v1.3", "TLS v1.2", "SSL v3"
318+
],
319+
"dependencyType": "implements"
320+
},
321+
{
322+
"ref": "TLS v1.3",
323+
"dependsOn": [
324+
"libcrypto.so"
325+
],
326+
"dependencyType": "uses"
327+
},
328+
{
329+
"ref": "TLS v1.2",
330+
"dependsOn": [
331+
"libcrypto.so"
332+
],
333+
"dependencyType": "uses"
334+
},
335+
{
336+
"ref": "SSL v3",
337+
"dependsOn": [
338+
"libcrypto.so"
339+
],
340+
"dependencyType": "uses"
341+
},
342+
{
343+
"ref": "libcrypto.so",
344+
"dependsOn": [
345+
"MD5", "AES-128-GCM", "SHA256", "HMAC-DRBG"
346+
],
347+
"dependencyType": "implements"
348+
}
349+
]
350+
```

‎NOTICE

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Copyright 2022 IBM Corporation. All rights reserved.
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.
14+
15+
--
16+
This repository contains third-party code licensed under Apache-2.0:
17+
18+
- bom-1.4-cbom-1.0.schema.json: based on CycloneDX JSON schema, extended for CBOM
19+
- jsf-0.82.schema.json
20+
- spdx.schema.json
21+
22+
"CycloneDX Specification is Copyright (c) OWASP Foundation. All Rights Reserved.
23+
24+
Permission to modify and redistribute is granted under the terms of the Apache License 2.0."

0 commit comments

Comments
 (0)