-
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
9b5975e
commit 5446c1c
Showing
10 changed files
with
2,189 additions
and
577 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -59,8 +59,7 @@ AES-128-GCM and SHA512withRSA. | |
| An example with the QSC Signature algorithm Dilithium5 is listed below. | ||
|
|
||
| ```json | ||
| "components": [ | ||
| { | ||
| "components": [ { | ||
| "name": "Dilithium5", | ||
| "type": "cryptographic-asset", | ||
| "cryptoProperties": { | ||
|
|
@@ -75,12 +74,8 @@ An example with the QSC Signature algorithm Dilithium5 is listed below. | |
| }, | ||
| "oid": "1.3.6.1.4.1.2.267.7.8.7" | ||
| } | ||
| } | ||
| ] | ||
| } ] | ||
| ``` | ||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> | ||
|
|
||
| ## Key | ||
| 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 | |
| }, | ||
| "oid": "1.2.840.113549.1.1.1" | ||
| } | ||
| }, | ||
| { | ||
| }, { | ||
| "name": "RSA-2048", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/algorithm/[email protected]", | ||
| "cryptoProperties": { | ||
| "assetType": "algorithm", | ||
| "algorithmProperties": { | ||
| "parameterSetIdentifier": "2048", | ||
| "executionEnvironment": "software-plain-ram", | ||
| "implementationPlatform": "x86_64", | ||
| "cryptoFunctions": [ "encapsulate", "decapsulate" ] | ||
| }, | ||
| "oid": "1.2.840.113549.1.1.1" | ||
| } | ||
| }, | ||
| { | ||
| "cryptoProperties": { ... } | ||
| }, { | ||
| "name": "AES-128-GCM", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/algorithm/[email protected]", | ||
| "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" | ||
| } | ||
| } ] | ||
| "cryptoProperties": { ... } | ||
| } | ||
| ] | ||
| ``` | ||
| A complete example can be found at [https://cyclonedx.org/shortcut/example/key](https://cyclonedx.org/shortcut/example/key) | ||
|
|
||
|
|
||
| ## 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. | ||
| The following example lists an instance of the TLS v1.2 protocol with a number of cipher suites. | ||
|
|
||
| ```json | ||
| "components": [ | ||
|
|
@@ -171,7 +145,7 @@ A cryptographic protocol is added to the components array of the BOM. The exampl | |
| } | ||
| ], | ||
| "cryptoRefArray": [ | ||
| "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4" | ||
| "crypto/certificate/google.com@sha256:1e15...beb4" | ||
| ] | ||
| }, | ||
| "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 | |
| { | ||
| "name": "google.com", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4", | ||
| "bom-ref": "crypto/certificate/google.com@sha256:1e15...beb4", | ||
| "cryptoProperties": { | ||
| "assetType": "certificate", | ||
| "certificateProperties": { | ||
|
|
@@ -305,6 +279,11 @@ A cryptographic protocol is added to the components array of the BOM. The exampl | |
| } | ||
| ] | ||
| ``` | ||
| A complete example can be found at [https://cyclonedx.org/shortcut/example/protocol](https://cyclonedx.org/shortcut/example/protocol) | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> | ||
|
|
||
| ## Certificate | ||
| 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. | |
| { | ||
| "name": "google.com", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/certificate/google.com@sha256:1e15e0fbd3ce95bde5945633ae96add551341b11e5bae7bba12e98ad84a5beb4", | ||
| "bom-ref": "crypto/certificate/google.com@sha256:1e15...beb4", | ||
| "cryptoProperties": { | ||
| "assetType": "certificate", | ||
| "certificateProperties": { | ||
|
|
@@ -333,59 +312,24 @@ The following example details an X.509 certificate in a CBOM. | |
| "name": "SHA512withRSA", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/algorithm/[email protected]", | ||
| "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" | ||
| } | ||
| "cryptoProperties": { ... } | ||
| }, | ||
| { | ||
| "name": "RSA-2048", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/key/[email protected]", | ||
| "cryptoProperties": { | ||
| "assetType": "related-crypto-material", | ||
| "relatedCryptoMaterialProperties": { | ||
| "type": "public-key", | ||
| "id": "2e9ef09e-dfac-4526-96b4-d02f31af1b22", | ||
| "state": "active", | ||
| "size": 2048, | ||
| "algorithmRef": "crypto/algorithm/[email protected]", | ||
| "securedBy": { | ||
| "mechanism": "None" | ||
| }, | ||
| "creationDate": "2016-11-21T08:00:00Z", | ||
| "activationDate": "2016-11-21T08:20:00Z" | ||
| }, | ||
| "oid": "1.2.840.113549.1.1.1" | ||
| } | ||
| "cryptoProperties": { ... } | ||
| }, | ||
| { | ||
| "name": "RSA-2048", | ||
| "type": "cryptographic-asset", | ||
| "bom-ref": "crypto/algorithm/[email protected]", | ||
| "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" | ||
| } | ||
| "cryptoProperties": { ... } | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| A complete example can be found at [https://cyclonedx.org/shortcut/example/cert](https://cyclonedx.org/shortcut/example/cert) | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Dependencies | ||
| CycloneDX provides the ability to describe components and their dependency on other components. This relies on a | ||
| component's `bom-ref` to associate the component with the dependency element in the graph. The only requirement for bom-ref | ||
| 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 | ||
| readable. If PURL is not an option or not all components represented in the BOM contain a PURL, then UUID is recommended. | ||
| A dependency graph is typically one node deep and capable of representing both direct and transitive relationships. | ||
|
|
||
| Refer to the [CycloneDX Authoritative Guide to SBOM](https://cyclonedx.org/guides/) for additional details. In the | ||
| context cryptographic dependencies, CycloneDX provides some additional capabilities. | ||
|
|
||
| As of CycloneDX v1.6, there are two types of dependencies, dependsOn and provides. | ||
|
|
||
| | Dependency Type | Description | | ||
| | --------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | dependsOn | The bom-ref identifiers of the components or services that are dependencies of this dependency object. | | ||
| | 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. | | ||
|
|
||
|
|
||
| The dependency type, dependsOn, is leveraged by classic SBOMs to define a complete graph of direct and transitive | ||
| dependencies. However, for cryptographic and similar assets, "provides" allows for many additional use cases. | ||
|
|
||
|  | ||
|
|
||
| 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. | ||
|
|
||
| The following example illustrates a simple application with a dependency on a cryptographic library, which in turn, | ||
| implements AES-128-GCM. The cryptographic library also has a dependency on another library. | ||
|
|
||
| ```json | ||
| "dependencies": [ | ||
| { | ||
| "ref": "acme-application", | ||
| "dependsOn": ["crypto-library"] | ||
| }, | ||
| { | ||
| "ref": "crypto-library", | ||
| "provides": ["aes128gcm"], | ||
| "dependsOn": ["some-library"] | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> |
Oops, something went wrong.