Skip to content

Commit 5446c1c

Browse files
stevespringettstevespringett
committed
Content update
1 parent 9b5975e commit 5446c1c

10 files changed

+2189
-577
lines changed

‎CBOM/en/0x01-Frontispiece.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,9 @@ Version 1.0.0, xx February 2024
2828
\emptyparagraph
2929
</div>
3030

31-
| Version | Changes | Updated On | Updated By |
32-
|---------|-----------------|------------|------------------------------|
33-
| 0.0.0 | Initial Release | 2024-xx-xx | CycloneDX Core Working Group |
31+
| Version | Changes | Updated On | Updated By |
32+
|---------------|-----------------|------------|-------------------------------------------------|
33+
| First Edition | Initial Release | 2024-xx-xx | CycloneDX Feature Working Group on Cryptography |
3434

3535
<div style="page-break-after: always; visibility: hidden">
3636
\newpage

‎CBOM/en/0x30-Anatomy-of-a-CBOM.md

+159
Large diffs are not rendered by default.

‎CBOM/en/0x31-Dependencies.md

-26
This file was deleted.

‎CBOM/en/0x40-Anatomy-of-a-CBOM.md

-7
This file was deleted.

‎CBOM/en/0x30-Practical-Examples.md ‎CBOM/en/0x40-Practical-Examples.md

+23-79
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,7 @@ AES-128-GCM and SHA512withRSA.
5959
An example with the QSC Signature algorithm Dilithium5 is listed below.
6060

6161
```json
62-
"components": [
63-
{
62+
"components": [ {
6463
"name": "Dilithium5",
6564
"type": "cryptographic-asset",
6665
"cryptoProperties": {
@@ -75,12 +74,8 @@ An example with the QSC Signature algorithm Dilithium5 is listed below.
7574
},
7675
"oid": "1.3.6.1.4.1.2.267.7.8.7"
7776
}
78-
}
79-
]
77+
} ]
8078
```
81-
<div style="page-break-after: always; visibility: hidden">
82-
\newpage
83-
</div>
8479

8580
## Key
8681
The following example demonstrates how an RSA-2048 public key can be included in a CBOM.
@@ -107,45 +102,24 @@ The following example demonstrates how an RSA-2048 public key can be included in
107102
},
108103
"oid": "1.2.840.113549.1.1.1"
109104
}
110-
},
111-
{
105+
}, {
112106
"name": "RSA-2048",
113107
"type": "cryptographic-asset",
114108
"bom-ref": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
115-
"cryptoProperties": {
116-
"assetType": "algorithm",
117-
"algorithmProperties": {
118-
"parameterSetIdentifier": "2048",
119-
"executionEnvironment": "software-plain-ram",
120-
"implementationPlatform": "x86_64",
121-
"cryptoFunctions": [ "encapsulate", "decapsulate" ]
122-
},
123-
"oid": "1.2.840.113549.1.1.1"
124-
}
125-
},
126-
{
109+
"cryptoProperties": { ... }
110+
}, {
127111
"name": "AES-128-GCM",
128112
"type": "cryptographic-asset",
129113
"bom-ref": "crypto/algorithm/aes-128-gcm@2.16.840.1.101.3.4.1.6",
130-
"cryptoProperties": {
131-
"assetType": "algorithm",
132-
"algorithmProperties": {
133-
"parameterSetIdentifier": "128",
134-
"primitive": "ae",
135-
"mode": "gcm",
136-
"executionEnvironment": "software-plain-ram",
137-
"implementationPlatform": "x86_64",
138-
"cryptoFunctions": [ "keygen", "encrypt", "decrypt" ],
139-
"classicalSecurityLevel": 128,
140-
"nistQuantumSecurityLevel": 1
141-
},
142-
"oid": "2.16.840.1.101.3.4.1.6"
143-
}
144-
} ]
114+
"cryptoProperties": { ... }
115+
}
116+
]
145117
```
118+
A complete example can be found at [https://cyclonedx.org/shortcut/example/key](https://cyclonedx.org/shortcut/example/key)
119+
146120

147121
## Protocol
148-
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.
122+
The following example lists an instance of the TLS v1.2 protocol with a number of cipher suites.
149123

150124
```json
151125
"components": [
@@ -171,7 +145,7 @@ A cryptographic protocol is added to the components array of the BOM. The exampl
171145
}
172146
],
173147
"cryptoRefArray": [
174-
"crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4"
148+
"crypto/certificate/google.com@sha256:1e15...beb4"
175149
]
176150
},
177151
"oid": "1.3.18.0.2.32.104"
@@ -180,7 +154,7 @@ A cryptographic protocol is added to the components array of the BOM. The exampl
180154
{
181155
"name": "google.com",
182156
"type": "cryptographic-asset",
183-
"bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4",
157+
"bom-ref": "crypto/certificate/google.com@sha256:1e15...beb4",
184158
"cryptoProperties": {
185159
"assetType": "certificate",
186160
"certificateProperties": {
@@ -305,6 +279,11 @@ A cryptographic protocol is added to the components array of the BOM. The exampl
305279
}
306280
]
307281
```
282+
A complete example can be found at [https://cyclonedx.org/shortcut/example/protocol](https://cyclonedx.org/shortcut/example/protocol)
283+
284+
<div style="page-break-after: always; visibility: hidden">
285+
\newpage
286+
</div>
308287

309288
## Certificate
310289
The following example details an X.509 certificate in a CBOM.
@@ -314,7 +293,7 @@ The following example details an X.509 certificate in a CBOM.
314293
{
315294
"name": "google.com",
316295
"type": "cryptographic-asset",
317-
"bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4",
296+
"bom-ref": "crypto/certificate/google.com@sha256:1e15...beb4",
318297
"cryptoProperties": {
319298
"assetType": "certificate",
320299
"certificateProperties": {
@@ -333,59 +312,24 @@ The following example details an X.509 certificate in a CBOM.
333312
"name": "SHA512withRSA",
334313
"type": "cryptographic-asset",
335314
"bom-ref": "crypto/algorithm/sha-512-rsa@1.2.840.113549.1.1.13",
336-
"cryptoProperties": {
337-
"assetType": "algorithm",
338-
"algorithmProperties": {
339-
"parameterSetIdentifier": "512",
340-
"executionEnvironment": "software-plain-ram",
341-
"implementationPlatform": "x86_64",
342-
"certificationLevel": [ "none" ],
343-
"cryptoFunctions": [ "digest" ],
344-
"nistQuantumSecurityLevel": 0
345-
},
346-
"oid": "1.2.840.113549.1.1.13"
347-
}
315+
"cryptoProperties": { ... }
348316
},
349317
{
350318
"name": "RSA-2048",
351319
"type": "cryptographic-asset",
352320
"bom-ref": "crypto/key/rsa-2048@1.2.840.113549.1.1.1",
353-
"cryptoProperties": {
354-
"assetType": "related-crypto-material",
355-
"relatedCryptoMaterialProperties": {
356-
"type": "public-key",
357-
"id": "2e9ef09e-dfac-4526-96b4-d02f31af1b22",
358-
"state": "active",
359-
"size": 2048,
360-
"algorithmRef": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
361-
"securedBy": {
362-
"mechanism": "None"
363-
},
364-
"creationDate": "2016-11-21T08:00:00Z",
365-
"activationDate": "2016-11-21T08:20:00Z"
366-
},
367-
"oid": "1.2.840.113549.1.1.1"
368-
}
321+
"cryptoProperties": { ... }
369322
},
370323
{
371324
"name": "RSA-2048",
372325
"type": "cryptographic-asset",
373326
"bom-ref": "crypto/algorithm/rsa-2048@1.2.840.113549.1.1.1",
374-
"cryptoProperties": {
375-
"assetType": "algorithm",
376-
"algorithmProperties": {
377-
"parameterSetIdentifier": "2048",
378-
"executionEnvironment": "software-plain-ram",
379-
"implementationPlatform": "x86_64",
380-
"certificationLevel": [ "none" ],
381-
"cryptoFunctions": [ "encapsulate", "decapsulate" ]
382-
},
383-
"oid": "1.2.840.113549.1.1.1"
384-
}
327+
"cryptoProperties": { ... }
385328
}
386329
]
387330
```
388331

332+
A complete example can be found at [https://cyclonedx.org/shortcut/example/cert](https://cyclonedx.org/shortcut/example/cert)
389333

390334
<div style="page-break-after: always; visibility: hidden">
391335
\newpage

‎CBOM/en/0x41-Dependencies.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Dependencies
2+
CycloneDX provides the ability to describe components and their dependency on other components. This relies on a
3+
component's `bom-ref` to associate the component with the dependency element in the graph. The only requirement for bom-ref
4+
is that it is unique within the BOM. Package URL (PURL) is an ideal choice for bom-ref as it will be both unique and
5+
readable. If PURL is not an option or not all components represented in the BOM contain a PURL, then UUID is recommended.
6+
A dependency graph is typically one node deep and capable of representing both direct and transitive relationships.
7+
8+
Refer to the [CycloneDX Authoritative Guide to SBOM](https://cyclonedx.org/guides/) for additional details. In the
9+
context cryptographic dependencies, CycloneDX provides some additional capabilities.
10+
11+
As of CycloneDX v1.6, there are two types of dependencies, dependsOn and provides.
12+
13+
| Dependency Type | Description |
14+
| --------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
15+
| dependsOn | The bom-ref identifiers of the components or services that are dependencies of this dependency object. |
16+
| provides | The bom-ref identifiers of the components or services that define a given specification or standard, which are provided or implemented by this dependency object. For example, a cryptographic library which implements a cryptographic algorithm. A component which implements another component does not imply that the implementation is in use. |
17+
18+
19+
The dependency type, dependsOn, is leveraged by classic SBOMs to define a complete graph of direct and transitive
20+
dependencies. However, for cryptographic and similar assets, "provides" allows for many additional use cases.
21+
22+
![Dependencies](./images/dependencies.svg)
23+
24+
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.
25+
26+
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.
27+
28+
The following example illustrates a simple application with a dependency on a cryptographic library, which in turn,
29+
implements AES-128-GCM. The cryptographic library also has a dependency on another library.
30+
31+
```json
32+
"dependencies": [
33+
{
34+
"ref": "acme-application",
35+
"dependsOn": ["crypto-library"]
36+
},
37+
{
38+
"ref": "crypto-library",
39+
"provides": ["aes128gcm"],
40+
"dependsOn": ["some-library"]
41+
}
42+
]
43+
```
44+
45+
<div style="page-break-after: always; visibility: hidden">
46+
\newpage
47+
</div>

0 commit comments

Comments
 (0)