Skip to content

Commit 9cd0c71

Browse files
sameehjsameehj
committed
Add CRA Evidence Kit for customer SBOM integration
Self-contained cra-evidence/ with glossary, Evidence Map, fictional auditor packet, autotools/embedded SBOM scripts, and CI validation. Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
1 parent 9bc3022 commit 9cd0c71

27 files changed

Lines changed: 1749 additions & 0 deletions

‎.github/workflows/cra-evidence.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CRA Evidence Kit
2+
3+
on:
4+
push:
5+
paths:
6+
- 'cra-evidence/**'
7+
- '.github/workflows/cra-evidence.yml'
8+
pull_request:
9+
paths:
10+
- 'cra-evidence/**'
11+
- '.github/workflows/cra-evidence.yml'
12+
13+
jobs:
14+
validate-auditor-packet:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: '3.x'
21+
- name: Validate pinned auditor packet
22+
run: ./cra-evidence/scripts/validate.sh

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -413,6 +413,25 @@ Please see the
413413
for further usage and details.
414414

415415

416+
<br />
417+
418+
#### cra-evidence (CRA / SBOM evidence kit)
419+
420+
This directory is **not** a TLS/crypto tutorial. It demonstrates how to
421+
generate wolfSSL **component SBOMs** (SPDX + CycloneDX), nest them in a
422+
**fictional product SBOM**, and understand optional **bomsh** build provenance
423+
(Linux host only) for EU Cyber Resilience Act-style software transparency.
424+
425+
Includes a one-page [Evidence Map](cra-evidence/EVIDENCE-MAP.md), full
426+
[glossary](cra-evidence/CRA-Supply-Chain-Glossary.md), sample
427+
[auditor packet](cra-evidence/auditor-packet/), and helper scripts (`validate.sh`
428+
runs without building wolfSSL). Regenerating component SBOMs requires a wolfSSL
429+
tree with SBOM support — see [cra-evidence/README.md](cra-evidence/README.md).
430+
431+
Please see the [cra-evidence/README.md](cra-evidence/README.md) for further
432+
usage and details.
433+
434+
416435
<br />
417436

418437
#### uefi-library (wolfCrypt UEFI boot module and test app)

‎cra-evidence/CRA-Supply-Chain-Glossary.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# CRA & Supply Chain Terminology — Customer Cheat Sheet
2+
3+
One-page reference for teams shipping products that include wolfSSL.
4+
**Not legal advice.** Map obligations to your product class and role with counsel.
5+
6+
This kit is **self-contained** in [wolfssl-examples `cra-evidence/`](https://github.com/wolfSSL/wolfssl-examples/tree/master/cra-evidence).
7+
Upstream wolfSSL integration detail (requires a wolfSSL source tree with SBOM support):
8+
9+
- [CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md)
10+
- [SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md)
11+
12+
Handout (shorter): [`EVIDENCE-MAP.md`](EVIDENCE-MAP.md) · Worked example: [`auditor-packet/`](auditor-packet/)
13+
14+
---
15+
16+
## The big picture (30 seconds)
17+
18+
```mermaid
19+
flowchart LR
20+
subgraph you["Your company (manufacturer)"]
21+
PSBOM["Product SBOM\n(all components)"]
22+
end
23+
subgraph wolf["wolfSSL (component)"]
24+
WSBOM["wolfSSL SBOM\n(SPDX + CycloneDX)"]
25+
BOMSH["OmniBOR / bomsh\n(optional)"]
26+
end
27+
PSBOM -->|"references or contains"| WSBOM
28+
WSBOM -.->|"optional deeper proof"| BOMSH
29+
```
30+
31+
| Question | Short answer |
32+
|----------|--------------|
33+
| Do we need **our own** SBOM? | **Yes** — for the **whole product** you place on the EU market. |
34+
| Is wolfSSL’s SBOM enough by itself? | **No** (unless you only redistribute wolfSSL). Use it **inside** your product SBOM. |
35+
| Do we need **bomsh**? | **Usually no.** SBOM alone covers most CRA transparency needs; bomsh adds build traceability if you want it. |
36+
| SPDX or CycloneDX? | **Both are fine.** wolfSSL ships both; use whichever your tools expect (many teams keep both). |
37+
38+
---
39+
40+
## Glossary
41+
42+
| Term | Stands for / means | Plain English |
43+
|------|-------------------|---------------|
44+
| **CRA** | EU **Cyber Resilience Act** | EU law for products with digital elements: inventory, security, vulnerability handling. |
45+
| **SBOM** | **Software Bill of Materials** | Machine-readable “ingredients list” of software in a product (name, version, supplier, license, IDs, relationships). |
46+
| **Product SBOM** | — | **Yours:** every OSS/third-party component in the **shipped product**. |
47+
| **Component SBOM** | — | **wolfSSL’s:** inventory of **wolfSSL only** (`make sbom` or `gen-sbom`). |
48+
| **SPDX** | **Software Package Data Exchange** | A standard **format** for SBOMs (Linux Foundation). Files: `*.spdx.json`, `*.spdx`. |
49+
| **CycloneDX** | (project name) | Another standard **format** for SBOMs (OWASP ecosystem). File: `*.cdx.json`. |
50+
| **NTIA minimum elements** | US NTIA guidance | Checklist of what a “good” SBOM must include (supplier, name, version, unique ID, deps, author, timestamp). CRA practice aligns with this. |
51+
| **PURL** | **Package URL** | Standard ID like `pkg:generic/wolfssl@5.9.1` — helps tools match components. |
52+
| **CPE** | **Common Platform Enumeration** | Standard ID like `cpe:2.3:a:wolfssl:wolfssl:…` — used by many vulnerability databases. |
53+
| **VEX** | **Vulnerability Exploitability eXchange** | CycloneDX-side signal: “this CVE does/doesn’t apply to our build.” Often layered on top of SBOM in security tools. |
54+
| **CBOM** | **Cryptographic Bill of Materials** | Inventory of **crypto algorithms/keys/modules** (beyond generic SBOM). Today: `wolfssl:build:*` in CycloneDX; formal CBOM: see [`ROADMAP.md`](ROADMAP.md). |
55+
| **bomsh** | wolfSSL **make** target | Runs **OmniBOR** provenance: proves **how** the library binary was built from sources (**Linux host only**). |
56+
| **OmniBOR** | Omni **Bill of Resources** | Merkle DAG of build inputs/outputs; stored under `omnibor/`. |
57+
| **gitoid** | Git-object-style ID | Hash pointer (`gitoid:blob:sha1:…`) into the OmniBOR graph; appears in `omnibor.*.spdx.json`. |
58+
| **Manufacturer** | CRA role | Entity that places the product on the EU market — **owns** product SBOM and vulnerability process. |
59+
| **Integrator / OEM** | Industry term | You build a device/app containing wolfSSL → you typically act as **manufacturer** for your product. |
60+
| **externalDocumentRefs** | SPDX feature | Your product SPDX **points to** wolfSSL’s SPDX file without copying every file entry. |
61+
| **SOURCE_DATE_EPOCH** | Reproducible builds | Fixed timestamp so two `make sbom` runs produce **byte-identical** SBOMs (useful in CI/attestation). |
62+
63+
---
64+
65+
## wolfSSL artefacts (what we ship)
66+
67+
| Command | Outputs | Answers |
68+
|---------|---------|---------|
69+
| `make sbom` | `wolfssl-<ver>.spdx.json`, `.cdx.json`, `.spdx` | **What** is in wolfSSL (version, license, hashes, config flags). |
70+
| `make bomsh` *(optional)* | `omnibor/`, `omnibor.wolfssl-<ver>.spdx.json` | **How** wolfSSL was built (source → binary traceability). |
71+
72+
Embedded/custom builds: `scripts/gen-sbom` with **your** `user_settings.h` and source list — see kit
73+
[`scripts/generate-embedded-sbom.sh`](scripts/generate-embedded-sbom.sh) and upstream [SBOM.md §1](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md).
74+
75+
---
76+
77+
## Your checklist
78+
79+
1. **Product SBOM** in release CI (SPDX and/or CycloneDX).
80+
2. **wolfSSL component** — reference our SBOM (`externalDocumentRefs` / CycloneDX `bom` ref) or copy the package entry; link with `STATIC_LINK` / `DYNAMIC_LINK` / `CONTAINS`.
81+
3. **Match your build** — if `user_settings.h` or source set differs from stock, regenerate wolfSSL’s SBOM for **your** build.
82+
4. **Commercial license** — override GPL in SBOM (`SBOM_LICENSE_OVERRIDE`) or in **your** product SBOM entry for wolfSSL; see upstream [CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md).
83+
5. **Vulnerabilities** — document your process; wolfSSL disclosure: [SECURITY-POLICY.md](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md).
84+
6. **bomsh** — only if auditors or contracts ask for build-level proof beyond the SBOM (Linux CI).
85+
86+
---
87+
88+
## SPDX vs CycloneDX (same job, different tools)
89+
90+
| | **SPDX** | **CycloneDX** |
91+
|---|----------|----------------|
92+
| **Typical use** | License compliance, legal review, nested documents | Security scanners, VEX, commercial SBOM platforms |
93+
| **wolfSSL file** | `wolfssl-<ver>.spdx.json` | `wolfssl-<ver>.cdx.json` |
94+
| **Nesting wolfSSL** | `externalDocumentRefs` + relationship | Component + `externalReferences` type `bom` |
95+
96+
You do **not** choose “CRA format” — you provide an SBOM that meets NTIA-style expectations; SPDX and CycloneDX are both widely accepted encodings.
97+
98+
---
99+
100+
## Who provides what to an auditor
101+
102+
| Evidence | Provided by |
103+
|----------|-------------|
104+
| Product SBOM (full inventory) | **Customer** |
105+
| wolfSSL SBOM files | **wolfSSL** (customer integrates or references) |
106+
| OmniBOR / bomsh bundle | **wolfSSL** *(optional)* |
107+
| Vulnerability disclosure & advisories | **wolfSSL** ([security page](https://www.wolfssl.com/docs/security-vulnerabilities/)); **customer** owns product incident process |
108+
109+
---
110+
111+
*wolfSSL · Part of the [CRA Evidence Kit](README.md). Questions: support@wolfssl.com*

‎cra-evidence/EVIDENCE-MAP.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# wolfSSL CRA Evidence Map (one page)
2+
3+
**Not legal advice.** You are the **manufacturer** for your product on the EU
4+
market; wolfSSL provides **component evidence** for the wolfSSL library only.
5+
6+
---
7+
8+
## Three questions → three layers of evidence
9+
10+
| Question | Layer | wolfSSL today |
11+
|----------|-------|---------------|
12+
| What software is in the product? | **SBOM** | `make sbom` / `gen-sbom` → SPDX + CycloneDX |
13+
| What crypto is actually enabled? | **Crypto signals** (→ CBOM) | `wolfssl:build:*` in CycloneDX |
14+
| How was the library binary built? | **Provenance** (optional) | `make bomsh` (Linux host only) |
15+
16+
**Product SBOM** (all components) = **yours**. **wolfSSL SBOM** = nest or reference ours.
17+
18+
---
19+
20+
## All the “BOMs” (today vs roadmap)
21+
22+
| Name | What it lists | Owner | wolfSSL today | Roadmap |
23+
|------|----------------|-------|---------------|---------|
24+
| Product SBOM | Whole shipped product | **You** | — | — |
25+
| Component SBOM | wolfSSL only | **wolfSSL** (you integrate) | **Yes** | CI / validation |
26+
| VEX | CVE applies to your build? | **You** (+ tools) | Advisories + policy | Examples / automation |
27+
| CBOM | Crypto algorithms / modules | **You**; we signal | **Partial** (build properties) | Formal `cryptographic-asset` |
28+
| OmniBOR / bomsh | Source → binary graph | **wolfSSL** (optional) | **Yes** (Linux **host**) | Same |
29+
30+
---
31+
32+
## Four decisions
33+
34+
| Question | Answer |
35+
|----------|--------|
36+
| Need our own SBOM? | **Yes** — entire product |
37+
| wolfSSL SBOM enough alone? | **No** — reference or embed in yours |
38+
| Need bomsh for CRA? | **Usually no** |
39+
| SPDX or CycloneDX? | **Both shipped** — use what your tools consume |
40+
41+
---
42+
43+
## Your first week (Friday path)
44+
45+
| When | Action |
46+
|------|--------|
47+
| **Today (~15 min)** | Generate wolfSSL SBOM (`make sbom` or `gen-sbom`) |
48+
| **This week** | Add wolfSSL to **product** SBOM (see `auditor-packet/` example) |
49+
| **Before release** | Product SBOM in CI; vulnerability owner + process |
50+
| **If contract requires** | `make bomsh` on **Linux** CI (not macOS/Windows native) |
51+
52+
---
53+
54+
## bomsh in one sentence
55+
56+
**Optional.** Traces the build on a **Linux machine** (patched strace); your firmware
57+
can run anywhere. macOS/Windows hosts → use Linux CI, WSL2, or a container.
58+
59+
---
60+
61+
## Example + docs
62+
63+
| Resource | Location |
64+
|----------|----------|
65+
| This kit | `wolfssl-examples/cra-evidence/` |
66+
| Sample auditor folder | [`auditor-packet/`](auditor-packet/) |
67+
| Full guide | [wolfssl/doc/CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md) |
68+
| Full glossary | [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) |
69+
70+
**CTA:** 30-min CRA readiness — bring your `user_settings.h` → support@wolfssl.com

‎cra-evidence/GLOSSARY.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Glossary
2+
3+
The full terminology reference lives in this kit:
4+
5+
**[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)**
6+
7+
For a one-page handout, use **[EVIDENCE-MAP.md](EVIDENCE-MAP.md)**.

0 commit comments

Comments
 (0)