Add CRA Evidence Kit for customer SBOM integration

.github/workflows/cra-evidence.yml

@@ -0,0 +1,22 @@
+name: CRA Evidence Kit
+
+on:
+  push:
+    paths:
+      - 'cra-evidence/**'
+      - '.github/workflows/cra-evidence.yml'
+  pull_request:
+    paths:
+      - 'cra-evidence/**'
+      - '.github/workflows/cra-evidence.yml'
+
+jobs:
+  validate-auditor-packet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Validate pinned auditor packet
+        run: ./cra-evidence/scripts/validate.sh

README.md

@@ -413,6 +413,25 @@ Please see the
 for further usage and details.
 
 
+<br />
+
+#### cra-evidence (CRA / SBOM evidence kit)
+
+This directory is **not** a TLS/crypto tutorial. It demonstrates how to
+generate wolfSSL **component SBOMs** (SPDX + CycloneDX), nest them in a
+**fictional product SBOM**, and understand optional **bomsh** build provenance
+(Linux host only) for EU Cyber Resilience Act-style software transparency.
+
+Includes a one-page [Evidence Map](cra-evidence/EVIDENCE-MAP.md), full
+[glossary](cra-evidence/CRA-Supply-Chain-Glossary.md), sample
+[auditor packet](cra-evidence/auditor-packet/), and helper scripts (`validate.sh`
+runs without building wolfSSL). Regenerating component SBOMs requires a wolfSSL
+tree with SBOM support — see [cra-evidence/README.md](cra-evidence/README.md).
+
+Please see the [cra-evidence/README.md](cra-evidence/README.md) for further
+usage and details.
+
+
 <br />
 
 #### uefi-library (wolfCrypt UEFI boot module and test app)

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

@@ -0,0 +1,111 @@
+# CRA & Supply Chain Terminology — Customer Cheat Sheet
+
+One-page reference for teams shipping products that include wolfSSL.  
+**Not legal advice.** Map obligations to your product class and role with counsel.
+
+This kit is **self-contained** in [wolfssl-examples `cra-evidence/`](https://github.com/wolfSSL/wolfssl-examples/tree/master/cra-evidence).
+Upstream wolfSSL integration detail (requires a wolfSSL source tree with SBOM support):
+
+- [CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md)
+- [SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md)
+
+Handout (shorter): [`EVIDENCE-MAP.md`](EVIDENCE-MAP.md) · Worked example: [`auditor-packet/`](auditor-packet/)
+
+---
+
+## The big picture (30 seconds)
+
+```mermaid
+flowchart LR
+  subgraph you["Your company (manufacturer)"]
+    PSBOM["Product SBOM\n(all components)"]
+  end
+  subgraph wolf["wolfSSL (component)"]
+    WSBOM["wolfSSL SBOM\n(SPDX + CycloneDX)"]
+    BOMSH["OmniBOR / bomsh\n(optional)"]
+  end
+  PSBOM -->|"references or contains"| WSBOM
+  WSBOM -.->|"optional deeper proof"| BOMSH
+```
+
+| Question | Short answer |
+|----------|--------------|
+| Do we need **our own** SBOM? | **Yes** — for the **whole product** you place on the EU market. |
+| Is wolfSSL’s SBOM enough by itself? | **No** (unless you only redistribute wolfSSL). Use it **inside** your product SBOM. |
+| Do we need **bomsh**? | **Usually no.** SBOM alone covers most CRA transparency needs; bomsh adds build traceability if you want it. |
+| SPDX or CycloneDX? | **Both are fine.** wolfSSL ships both; use whichever your tools expect (many teams keep both). |
+
+---
+
+## Glossary
+
+| Term | Stands for / means | Plain English |
+|------|-------------------|---------------|
+| **CRA** | EU **Cyber Resilience Act** | EU law for products with digital elements: inventory, security, vulnerability handling. |
+| **SBOM** | **Software Bill of Materials** | Machine-readable “ingredients list” of software in a product (name, version, supplier, license, IDs, relationships). |
+| **Product SBOM** | — | **Yours:** every OSS/third-party component in the **shipped product**. |
+| **Component SBOM** | — | **wolfSSL’s:** inventory of **wolfSSL only** (`make sbom` or `gen-sbom`). |
+| **SPDX** | **Software Package Data Exchange** | A standard **format** for SBOMs (Linux Foundation). Files: `*.spdx.json`, `*.spdx`. |
+| **CycloneDX** | (project name) | Another standard **format** for SBOMs (OWASP ecosystem). File: `*.cdx.json`. |
+| **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. |
+| **PURL** | **Package URL** | Standard ID like `pkg:generic/wolfssl@5.9.1` — helps tools match components. |
+| **CPE** | **Common Platform Enumeration** | Standard ID like `cpe:2.3:a:wolfssl:wolfssl:…` — used by many vulnerability databases. |
+| **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. |
+| **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). |
+| **bomsh** | wolfSSL **make** target | Runs **OmniBOR** provenance: proves **how** the library binary was built from sources (**Linux host only**). |
+| **OmniBOR** | Omni **Bill of Resources** | Merkle DAG of build inputs/outputs; stored under `omnibor/`. |
+| **gitoid** | Git-object-style ID | Hash pointer (`gitoid:blob:sha1:…`) into the OmniBOR graph; appears in `omnibor.*.spdx.json`. |
+| **Manufacturer** | CRA role | Entity that places the product on the EU market — **owns** product SBOM and vulnerability process. |
+| **Integrator / OEM** | Industry term | You build a device/app containing wolfSSL → you typically act as **manufacturer** for your product. |
+| **externalDocumentRefs** | SPDX feature | Your product SPDX **points to** wolfSSL’s SPDX file without copying every file entry. |
+| **SOURCE_DATE_EPOCH** | Reproducible builds | Fixed timestamp so two `make sbom` runs produce **byte-identical** SBOMs (useful in CI/attestation). |
+
+---
+
+## wolfSSL artefacts (what we ship)
+
+| Command | Outputs | Answers |
+|---------|---------|---------|
+| `make sbom` | `wolfssl-<ver>.spdx.json`, `.cdx.json`, `.spdx` | **What** is in wolfSSL (version, license, hashes, config flags). |
+| `make bomsh` *(optional)* | `omnibor/`, `omnibor.wolfssl-<ver>.spdx.json` | **How** wolfSSL was built (source → binary traceability). |
+
+Embedded/custom builds: `scripts/gen-sbom` with **your** `user_settings.h` and source list — see kit
+[`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).
+
+---
+
+## Your checklist
+
+1. **Product SBOM** in release CI (SPDX and/or CycloneDX).
+2. **wolfSSL component** — reference our SBOM (`externalDocumentRefs` / CycloneDX `bom` ref) or copy the package entry; link with `STATIC_LINK` / `DYNAMIC_LINK` / `CONTAINS`.
+3. **Match your build** — if `user_settings.h` or source set differs from stock, regenerate wolfSSL’s SBOM for **your** build.
+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).
+5. **Vulnerabilities** — document your process; wolfSSL disclosure: [SECURITY-POLICY.md](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md).
+6. **bomsh** — only if auditors or contracts ask for build-level proof beyond the SBOM (Linux CI).
+
+---
+
+## SPDX vs CycloneDX (same job, different tools)
+
+| | **SPDX** | **CycloneDX** |
+|---|----------|----------------|
+| **Typical use** | License compliance, legal review, nested documents | Security scanners, VEX, commercial SBOM platforms |
+| **wolfSSL file** | `wolfssl-<ver>.spdx.json` | `wolfssl-<ver>.cdx.json` |
+| **Nesting wolfSSL** | `externalDocumentRefs` + relationship | Component + `externalReferences` type `bom` |
+
+You do **not** choose “CRA format” — you provide an SBOM that meets NTIA-style expectations; SPDX and CycloneDX are both widely accepted encodings.
+
+---
+
+## Who provides what to an auditor
+
+| Evidence | Provided by |
+|----------|-------------|
+| Product SBOM (full inventory) | **Customer** |
+| wolfSSL SBOM files | **wolfSSL** (customer integrates or references) |
+| OmniBOR / bomsh bundle | **wolfSSL** *(optional)* |
+| Vulnerability disclosure & advisories | **wolfSSL** ([security page](https://www.wolfssl.com/docs/security-vulnerabilities/)); **customer** owns product incident process |
+
+---
+
+*wolfSSL · Part of the [CRA Evidence Kit](README.md). Questions: support@wolfssl.com*

cra-evidence/EVIDENCE-MAP.md

@@ -0,0 +1,70 @@
+# wolfSSL CRA Evidence Map (one page)
+
+**Not legal advice.** You are the **manufacturer** for your product on the EU
+market; wolfSSL provides **component evidence** for the wolfSSL library only.
+
+---
+
+## Three questions → three layers of evidence
+
+| Question | Layer | wolfSSL today |
+|----------|-------|---------------|
+| What software is in the product? | **SBOM** | `make sbom` / `gen-sbom` → SPDX + CycloneDX |
+| What crypto is actually enabled? | **Crypto signals** (→ CBOM) | `wolfssl:build:*` in CycloneDX |
+| How was the library binary built? | **Provenance** (optional) | `make bomsh` (Linux host only) |
+
+**Product SBOM** (all components) = **yours**. **wolfSSL SBOM** = nest or reference ours.
+
+---
+
+## All the “BOMs” (today vs roadmap)
+
+| Name | What it lists | Owner | wolfSSL today | Roadmap |
+|------|----------------|-------|---------------|---------|
+| Product SBOM | Whole shipped product | **You** | — | — |
+| Component SBOM | wolfSSL only | **wolfSSL** (you integrate) | **Yes** | CI / validation |
+| VEX | CVE applies to your build? | **You** (+ tools) | Advisories + policy | Examples / automation |
+| CBOM | Crypto algorithms / modules | **You**; we signal | **Partial** (build properties) | Formal `cryptographic-asset` |
+| OmniBOR / bomsh | Source → binary graph | **wolfSSL** (optional) | **Yes** (Linux **host**) | Same |
+
+---
+
+## Four decisions
+
+| Question | Answer |
+|----------|--------|
+| Need our own SBOM? | **Yes** — entire product |
+| wolfSSL SBOM enough alone? | **No** — reference or embed in yours |
+| Need bomsh for CRA? | **Usually no** |
+| SPDX or CycloneDX? | **Both shipped** — use what your tools consume |
+
+---
+
+## Your first week (Friday path)
+
+| When | Action |
+|------|--------|
+| **Today (~15 min)** | Generate wolfSSL SBOM (`make sbom` or `gen-sbom`) |
+| **This week** | Add wolfSSL to **product** SBOM (see `auditor-packet/` example) |
+| **Before release** | Product SBOM in CI; vulnerability owner + process |
+| **If contract requires** | `make bomsh` on **Linux** CI (not macOS/Windows native) |
+
+---
+
+## bomsh in one sentence
+
+**Optional.** Traces the build on a **Linux machine** (patched strace); your firmware
+can run anywhere. macOS/Windows hosts → use Linux CI, WSL2, or a container.
+
+---
+
+## Example + docs
+
+| Resource | Location |
+|----------|----------|
+| This kit | `wolfssl-examples/cra-evidence/` |
+| Sample auditor folder | [`auditor-packet/`](auditor-packet/) |
+| Full guide | [wolfssl/doc/CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md) |
+| Full glossary | [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) |
+
+**CTA:** 30-min CRA readiness — bring your `user_settings.h` → support@wolfssl.com

cra-evidence/GLOSSARY.md

@@ -0,0 +1,7 @@
+# Glossary
+
+The full terminology reference lives in this kit:
+
+**[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)**
+
+For a one-page handout, use **[EVIDENCE-MAP.md](EVIDENCE-MAP.md)**.