Content updates

Author: stevespringett

CBOM/en/0x01-Frontispiece.md

@@ -11,6 +11,8 @@ supply chain security field. This guide would not be possible without valuable f
 Working Group (IWG), the CycloneDX Core Working Group (CWG), the many CycloneDX Feature Working Groups (FWG), 
 CycloneDX maintainers and a global network of contributors and supporters.
 
+Portions of this guide were contributed by IBM under the Apache License Version 2.0.
+
 ## Copyright and License
 
 ![license](../../images/license.svg)

CBOM/en/0x02-Preface.md

@@ -2,8 +2,6 @@
 
 Secure supply chains are the foundational building block of modern cyber security. Without being able to describe a system’s components in a machine-consumable way, organizations and software consumers are in the dark if they are at risk of exploitation of known defects or vulnerabilities.
 
-Innovation drives the evolution of Software Bill of Materials (SBOM). I was lucky enough to attend one of the meetings held between the CycloneDX and SPDX teams at a Linux Foundation conference moderated by the fine folks at CISA. The drivers for CycloneDX 1.5 include improvements in interoperability and transparency.
-
 Software authors, from hobbyists to software vendors, can quickly adopt CycloneDX in their tooling, producing artifacts that will help consumers understand and manage the risk of the multitude of software that most organizations rely on daily.
 
 A few years ago, I was involved in a project to review 1700 business-critical applications in 90 days for known software vulnerabilities. If the organization had access to CycloneDX SBOMs, this would have been a trivial task, time that could have been more usefully spent on remediation rather than discovery. Sadly, most of the time was spent working out what software had old faulty components rather than addressing the very real risk of known software vulnerabilities. We were plagued with false positives from the tooling we used simply because scanning software without SBOMs is a heuristic-driven discovery process that is inefficient and wastes a great deal of time we didn’t have. SBOMs resolve these issues, reduce costs, and reduce risk to all involved.

CBOM/en/0x10-Introduction.md

@@ -1,65 +1,33 @@
 # Introduction
 
-CBOM:
-NIST:
-SP: https://www.nccoe.nist.gov/sites/default/files/2023-12/pqc-migration-nist-sp-1800-38b-preliminary-draft.pdf
-Lines 536 and 952 onwards
-as part of NCCOE effort
-Apache 2.0 - attribute IBM
+A Cryptography Bill of Materials (CBOM) is an object model to describe cryptographic assets and their dependencies.
+Support for CBOM is included in CycloneDX v1.6 and higher. Discovering, managing, and reporting on cryptographic assets
+is necessary 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 the Software Supply Chain
+Security (SSCS).
 
+## CBOM Design
+The overall design goal of CBOM is to provide an abstraction that allows modeling and representing crypto assets in a
+structured object format. This comprises the following points.
 
+1. Modelling cryptographic assets
+   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.
 
+2. Capturing cryptographic asset properties
+   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.
 
+3. Capturing crypto asset dependencies
+   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.
 
-CycloneDX Attestations is a modern standard for security compliance. CycloneDX Attestations enable organizations with a machine-readable format for communication about security standards, claims and evidence about security requirements, and attestations to the veracity and completeness of those claims. You can think of Attestations as a way to manage "compliance as code." The Attestations project began in 2023 as part of the broader CycloneDX project.
+4. Applicability to various software components
+   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.
 
-CycloneDX Attestations is a part of the OWASP CycloneDX project. CycloneDX is an OWASP flagship project, has a formal standardization process and governance model, and is supported by the global information security community.
+5. High compatibility to CycloneDX SBOM and related tooling
+   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.
 
-## Intended Audience
-CycloneDX Attestations is intended for use by:
-* Software development teams that want to meet security requirements and automate security evidence generation and communication
-* Security teams that want to ensure the security and compliance of software projects being created, and manage the compliance process with assessors.
-* Executives who are required to attest to their compliance with security standards.
-* Security assessors that want to have a standard way of processing compliance documentation and tracking compliance.
-* Security tool providers that build software for managing compliance processes.
-* Security standard creators that want to create a machine-readable version of their requirements.
-
-## Problem Statement
-Currently, organizations use a variety of paper-based and non-standard electronic documents to communicate about security requirements, evidence, and attestation. The labor required to create, process, manage, update, and track these documents is expensive, labor-intensive, and often overwhelming. Not surprisingly, the results are generally underwhelming. There are often large gaps between what the original requirement envisioned and the argument presented by the software producer.  Similarly, assessors often misinterpret requirements and focus on minutae instead of the intent of the original requirement.
-
-The problem is so bad there are endless [articles](https://www.google.com/search?q=compliance+is+not+security) explaining why compliance is not the same as security. This is unfortunate.  If the security requirements really represented the shared security interests of all stakeholders, then security and compliance would be aligned. Unfortunately, in most cases, at least some of the requirements make no sense to apply to the product, and many critical aspects of security are not reflected in the requirements.
-
-The root cause of these issues is a fundamental communications problem. Security requirements don't often match up well with the expected threats for a particular real-world system and its defenses. Further, security requirements are often far too abstract for development organizations to clearly understand what they must do with their particular organization, processes, and technologies. The assessors that should be facilitating the interpretation of the requirements in the context of the actual system are often relegated to strict interpretation of the words in vague, high-level requirements.
-
-Our challenge is to encourage standards bodies, builders, and assessors to communicate effectively. All the parties need a way to ensure that the *intent* of each requirement is applied appropriately to a particular product or system and achieved with confidence.
-
-## How CycloneDX Attestations Addresses Challenge
-Of course, CycloneDX Attestations can't solve this problem entirely. However, by allowing all parties to communicate in a standard machine-readable format, we hope to encourage more productive interaction and far less paperwork.
-
-We believe:
-
-* The use of machine-readable standards in Attestations format will encourage faster and deeper understanding by all parties.
-* The Attestations claims and evidence approach will allow development organizations to articulate their compliance rationale quickly and clearly
-* The use of Attestations will enable all forms of assessors, certifiers, and accreditors to more quickly evaluate compliance and provide feedback to producers
-* Attestations will enable faster compliance feedback loops and less surprises and delays
-
-## Intended Use Cases
-// TODO
-// * Supplier to consumer use case where the consumer requires adherence to something (e.g. SSDF)
-// * Internal use case where an internal policy is created from requirements defined in CDXA
-// * Regulatory and industry compliance requirements
-
-## Tool Support
-
-Over time, we expect better tools for managing all aspects of security attestation to emerge. As a producer, imagine being able to select appropriate standards for a project, eliminate duplication, articulate compliance rationales, automatically generate and include supporting evidence, manage reviews, and digitally sign attestations. From the assessor point of view, imagine being able to quickly evaluate claims and evidence, easily identify changes, point out gaps, and digitally sign approvals.
-
-## Join Us
-
-If you are interested in using CycloneDX Attestations or want to help us realize our vision, please join us!
-
-https://www.youtube.com/@CycloneDX
-https://owasp.org/www-project-cyclonedx/
-https://cyclonedx.org/about/participate/
+6. Enable automatic reasoning
+   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.
 
 <div style="page-break-after: always; visibility: hidden">
 \newpage

CBOM/en/0x20-Use-Cases.md

@@ -1,7 +1,41 @@
 # Use Cases
 
-TODO
+## Cryptography Asset Management
+The Cryptography Bill of Materials (CBOM) is a comprehensive inventory of cryptographic assets, encompassing keys, 
+certificates, tokens, and more. CBOM provides a structured framework for organizations to catalog and track their 
+cryptographic resources, facilitating efficient management and ensuring security and compliance standards are met. 
+By maintaining a detailed record of cryptographic assets, including their usage, expiration dates, and associated 
+metadata, CBOM enables proactive monitoring and streamlined auditing processes. With CBOM, organizations can effectively
+safeguard their cryptographic infrastructure, mitigate risks associated with unauthorized access or misuse, and maintain
+the integrity and confidentiality of sensitive data across diverse digital environments.
 
+## Identifying Weak Algorithms
+CBOM enables organizations to conduct thorough assessments and discover weak algorithms or flawed implementations that 
+could compromise security. Through analysis of CBOM data, including cryptographic algorithms, key management practices, 
+and usage patterns, organizations can pinpoint areas of concern and prioritize remediation efforts. CBOM facilitates 
+proactive identification of weaknesses and vulnerabilities, allowing organizations to enhance the resilience of their 
+cryptographic infrastructure and mitigate the risk of exploitation, thereby bolstering overall cybersecurity posture and
+safeguarding sensitive data against potential threats.
+
+## Post-Quantum Cryptography (PQC) Readiness
+CBOM is crucial in preparing applications and systems for an impending post-quantum reality, aligning with 
+guidance from the National Security Agency (NSA) and the National Institute of Standards and Technology (NIST). As 
+quantum computing advancements threaten the security of current cryptographic standards, CBOM provides a structured 
+approach to inventorying cryptographic assets and evaluating their resilience against quantum threats. By cataloging 
+cryptographic algorithms and their respective parameters, CBOM enables organizations to identify vulnerable or weak 
+components that require mitigation or replacement with quantum-resistant alternatives recommended by NSA and NIST. 
+Through comprehensive analysis and strategic planning facilitated by CBOM, organizations can proactively transition to 
+post-quantum cryptographic primitives, ensuring the long-term security and integrity of their systems and applications 
+in the face of evolving technological landscapes.
+
+## Cryptographic Requirements and Certifications
+CBOM facilitates the assessment of whether cryptographic implementations meet the stringent criteria outlined by 
+FIPS 140-2, FIPS 140-3, and Common Criteria. This includes ensuring the proper selection and configuration of 
+cryptographic algorithms and protocols to align with certification requirements. CBOM enables organizations to streamline
+the certification process by providing clear documentation of cryptographic practices and facilitating communication 
+between stakeholders, auditors, and certification bodies, ultimately accelerating the attainment of compliance and 
+bolstering confidence in the security of cryptographic systems. Suppliers whose products include cryptographic assets
+are encouraged to communicate certifications that have been obtained.
 
 <div style="page-break-after: always; visibility: hidden">
 \newpage

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

@@ -0,0 +1,8 @@
+# Practical Examples
+TODO
+
+
+
+<div style="page-break-after: always; visibility: hidden">
+\newpage
+</div>