Cryptography Bill of Materials

Update 2024-04-09: Upstream to CycloneDX 1.6

CBOM based on this repository has been integrated and upstreamed to the CycloneDX 1.6 specification. We thank the CycloneDX community for working with us integrating our CBOM specification. We recommend users to refer to the upstream specifciation of CycloneDX and the CycloneDX CBOM guide.

Open-source tooling developed at IBM Research related to CBOM is available here:

• CBOMkit: A toolset for dealing with Cryptography Bill of Materials (CBOM).
• Sonar Cryptography Plugin (CBOMkit-hyperion): A SonarQube Plugin that detects cryptographic assets in source code and generates CBOM.
• CBOM Viewer (CBOMkit-coeus): Visualize a generated or uploaded CBOM and access comprehensive statistics.
• CBOMkit-theia: A tool for detecting cryptographic assets in container images and directories, and generating CBOMs.
• CBOMkit-action: A GitHub action to generate CBOMs.

The CycloneDX Tool Center lists more tooling related to the CycloneDX SBOM standard.

Introduction

Cryptography Bill of Materials (CBOM) is an object model to describe cryptographic assets (short crypto-assets) and their dependencies. CBOM is an extension of the CycloneDX standard for Software Bill of Materials (SBOM), with notions to model crypto assets. CycloneDX was originally designed for use in application security and supply chain component analysis and is the SBOM format most aligned with the CBOM use case.

There is a need to discover, manage and report cryptography as the first step on the migration journey to quantum safe systems and applications. Cryptography is typically buried deep within components that are used to compose and build systems and applications. It makes sense to minimize this effort through alignment and reuse of concepts and components used to implement Software Supply Chain Security (SSCS).

Contents

• Cryptography Bill of Materials
  • Contents
  • Background: Software Bill of Materials
  • CBOM Design
  • CBOM Schema
    • crypto-asset
    • cryptoProperties
      • Algorithm
      • Certificate
      • RelatedCryptoMaterial
      • Protocol
      • Classical Security Level
      • Quantum Security Level
      • OID
      • Confidence levels
      • Scanner
      • Detection Context
      • General considerations
    • Dependencies
  • Examples
  • Schema Validation
  • Notes for future releases

Background: Software Bill of Materials

A Software Bill of Materials (SBOM) is a list of all the individual components that make up a piece of software and how its delivered. This can include not only the source code for the software, but also any libraries, frameworks, and other third-party components that are used in the software. An SBOM is based on a bill of materials (BOM) used in manufacturing, which lists all the components that are used to build a physical product. An SBOM typically includes a set of metadata that detail licensing information, identification and version numbers together with the component details. One of the main functions of SBOMs in a security context is to simplify the management of security events and automate remediation actions through adding sufficient context to an event. The benefits of standards based SBOM’s include:

• Facilitating the exchange of component composition in an industry.
• Visibility of components and dependencies in an application or system.
• Simpler Vulnerability Scanning through standardized identification of components.
• Better understanding of risk.
• Simpler management and remediation of vulnerabilities.

There are a number of common SBOM standards:

• CycloneDX
• Software Package Data Exchange (SPDX)
• SWID: Software Identification Tagging

CBOM Design

The overall design goal of CBOM is to provide an abstraction that allows modelling and representing crypto assets in a structured object format. This comprises the following points.

1. Modelling crypto assets

Crypto 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 crypto material like keys, tokens, secrets or passwords are other crypto assets to be modelled.

2. Capturing crypto asset properties

Crypto assets have properties that uniquely define them and that make them actionable for further reasoning. As an 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) is 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 crypto asset properties.

3. Capturing crypto asset dependencies

To understand the impact of a crypto asset, it is important to capture its dependencies. Crypto 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.

4. Applicability to various software components

CycloneDX supports various software components: applications, frameworks, libraries, containers, operating-systems, devices, firmware and files. CBOM allows to use these components and represent their dependency to crypto assets.

5. High compatibility to CycloneDX SBOM and related tooling

CBOM is an extension of the CycloneDX SBOM standard. It integrates crypto assets as an additional 'component' in the CycloneDX schema and further extends dependencies with the notion of 'dependencyType' to model 'uses' and 'implements' relationships. Besides these extensions, the CBOM schema is fully compatible to CycloneDX and allows access to the related tooling the ecosystem provides.

6. Enable automatic reasoning

CBOM enables tooling to automatically reason about crypto assets and their dependencies. This allows checking for compliance with policies that apply to cryptographic use and implementation.

CBOM Schema

The CBOM schema is available as a JSON schema.

File: bom-1.4-cbom-1.0.schema.json.

CBOM extends the CycloneDX standard (version 1.4) with the following properties that will be described in more detail:

• Component: crypto-asset
• Properties: cryptoProperties
• Dependencies: dependencyType

crypto-asset

Crypto-asset is a representation of a component type. The type and the name are required component properties.

"component": {
      "type": "object",
      "title": "Component Object",
      "required": [
        "type",
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "application",
            "framework",
            "library",
            "container",
            "operating-system",
            "device",
            "firmware",
            "file",
            "crypto-asset"
          ],
...

cryptoProperties

The cryptoProperties object describes the following assetTypes:

• algorithm
• certificate
• relatedCryptoMaterial
• protocol

Algorithm

Describes a cryptographic algorithm. If algorithm is selected, the object algorithmProperties shall be used to define further properties:

• primitive: an enum defining the cryptographic primitive (e.g. drbg, blockcipher).
• variant: defines the variant of an algorithm (e.g. AES-128-GCM).
• implementationPlatform: an enum defining the platform where the algorithm is implemented (e.g. x86_64), if known or applicable.
• certificationLevel: an enum defining the certification level in which the algorithm has been implemented (e.g. fips140-3-l1), if known or applicable.
• mode: the mode of operation of an algorithm of primitive blockcipher (e.g. cbc), if known or applicable.
• padding: the padding scheme used for the cryptographic algorithm (e.g. pkcs7 padding), if known or applicable.
• cryptoFunction: the associated crypto functions used or implemented for an algorithm (e.g. keygen), if known or applicable.

Note that some algorithmProperties fields may be redundant. For example, the variant description AES-128-GCM also contains information about the mode of operation gcm. Explicitly recording the mode properties will simplify the reasoning on the CBOM.

Certificate

Describes a cryptographic certificate. If certificate is selected, the object certificateProperties shall be used to define further properties:

• subjectName: subjectNa