wolfSSL · sameehj · May 18, 2026
diff --git a/.github/workflows/cra-evidence.yml b/.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
diff --git a/README.md b/README.md
@@ -413,6 +413,26 @@ 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 [CRA compliance shortlist](cra-evidence/CRA-Compliance-Shortlist.md), an
+[Evidence Map cheat sheet](cra-evidence/CRA-Cheat-Sheet.md), full
+[glossary](cra-evidence/CRA-Supply-Chain-Glossary.md), [AI playbook](cra-evidence/SKILL.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)

diff --git a/cra-evidence/CRA-Cheat-Sheet.md b/cra-evidence/CRA-Cheat-Sheet.md
@@ -0,0 +1,103 @@
+# wolfSSL CRA Supply Chain Cheat Sheet
+
+**Evidence Map** — what **you** provide vs what **wolfSSL** provides  
+Print this page; use **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** for full definitions (SBOM, SPDX, CycloneDX, CBOM, VEX, bomsh, PURL, …).
+
+**Not legal advice.** You are the **manufacturer** for your product on the EU market.
+wolfSSL provides **component evidence** for the **wolfSSL library only**.
+
+Requires a wolfSSL tree with SBOM support (`make sbom` / `scripts/gen-sbom`).
+`make sbom` also needs `pyspdxtools` (`pip install spdx-tools`).
+
+**Kit:** `wolfssl-examples/cra-evidence/` · **AI playbook:** [SKILL.md](SKILL.md)  
+**Product-level CRA shortlist (3 pillars):** [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)
+
+---
+
+## CRA compliance shortlist (three pillars)
+
+| Pillar | You | wolfSSL |
+|--------|-----|---------|
+| **1. Know your components** | Product SBOM + vuln process for whole product | Component SBOMs, advisories, updates — **this kit** |
+| **2. Secure boot** | Trusted firmware + update path | **wolfBoot** |
+| **3. Data in transfer** | Secure protocols for remote/cloud traffic | **TLS**, **SSH**, **MQTTS**, … |
+
+Detail: [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)
+
+---
+
+## Evidence Map (you vs wolfSSL)
+
+| | **You (product manufacturer)** | **wolfSSL (library supplier)** |
+|---|-------------------------------|--------------------------------|
+| **Inventory** | **Product SBOM** — OS, apps, all third-party code | **Component SBOM** — wolfSSL only (SPDX + CycloneDX) |
+| **How you connect** | Nest or reference our files in your product SBOM | Ship `wolfssl-*.spdx.json` and `wolfssl-*.cdx.json` |
+| **Vulnerabilities** | Your process + owner for the shipped product | Advisories + [SECURITY-POLICY](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md) |
+| **Optional build proof** | Only if your contract/auditor asks | `make bomsh` / OmniBOR (**Linux build host** only) |
+
+**Worked example:** [`auditor-packet/`](auditor-packet/) — fictional *Acme Connect Gateway* + wolfSSL SBOMs nested.
+
+---
+
+## Three questions auditors ask
+
+| Question | Term | wolfSSL today |
+|----------|------|---------------|
+| What software is in the product? | **SBOM** | `make sbom` or `gen-sbom` → SPDX + CycloneDX |
+| What crypto is enabled in *your* build? | **CBOM** (path) | `wolfssl:build:*` in CycloneDX — not full `cryptographic-asset` yet |
+| How was the library binary built? | **Provenance** | `make bomsh` (**Linux** host, optional) |
+
+*See glossary for SPDX vs CycloneDX, VEX, PURL, OmniBOR.*
+
+---
+
+## BOMs at a glance
+
+| Name | Owner | wolfSSL today |
+|------|-------|---------------|
+| **Product SBOM** | **You** | — |
+| **Component SBOM** | **wolfSSL** (you nest) | **Yes** |
+| **CBOM** | **You** document; we signal config | **Partial** (build properties) |
+| **VEX** | **You** (+ scanner) | Advisories only |
+| **bomsh** | **wolfSSL** (optional) | **Yes**, Linux host only |
+
+Details: [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) · roadmap: [ROADMAP.md](ROADMAP.md)
+
+---
+
+## Four decisions
+
+| Question | Answer |
+|----------|--------|
+| Need **our own** SBOM? | **Yes** |
+| wolfSSL SBOM **enough alone**? | **No** — nest or reference in yours |
+| Need **bomsh** for CRA? | **Usually no** |
+| **SPDX** or **CycloneDX**? | **Both** — use what your tools consume |
+
+---
+
+## Friday plan (first week)
+
+| When | Action |
+|------|--------|
+| **Today** | `make sbom` or `./scripts/generate-wolfssl-sbom.sh` |
+| **This week** | **Product SBOM** — nest wolfSSL (see `auditor-packet/`) |
+| **Before release** | Product SBOM in CI; vulnerability owner |
+| **If contract requires** | **bomsh** on **Linux CI** only (not macOS/Windows native) |
+| **With AI assistants** | Use [SKILL.md](SKILL.md) in Cursor / your agent — copy to `.cursor/skills/wolfssl-cra-evidence/` |
+
+**bomsh:** optional Linux build trace; firmware can target any OS.
+
+---
+
+## What to read next
+
+| Resource | File |
+|----------|------|
+| Full glossary | [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) |
+| Integration guide | [README.md](README.md) |
+| Sample auditor folder | [auditor-packet/](auditor-packet/) |
+| AI + scripts playbook | [SKILL.md](SKILL.md) |
+| Upstream deep dive | [wolfssl/doc/CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md) |
+
+**Questions:** support@wolfssl.com
diff --git a/cra-evidence/CRA-Compliance-Shortlist.md b/cra-evidence/CRA-Compliance-Shortlist.md
@@ -0,0 +1,72 @@
+# Shortlist towards CRA compliance
+
+**Not legal advice.** The EU Cyber Resilience Act applies to **your product** as a whole.
+wolfSSL helps on **specific pillars** below; you remain the **manufacturer** for market obligations.
+
+This page is the **product-level shortlist** (what to do). For **software transparency evidence**
+(SBOM, nesting, sample auditor folder), use the **[CRA Evidence Kit](README.md)** cheat sheet and
+[`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md).
+
+---
+
+## 1. Know your software components
+
+| **Your job (manufacturer)** | **wolfSSL can help** |
+|----------------------------|----------------------|
+| Run a **survey** of every component in your embedded system or product: What is it? Who maintains it? Is it actively developed? How do you learn about vulnerabilities, fixes, and releases? | **Component SBOMs** (SPDX + CycloneDX) for wolfSSL libraries you ship — `make sbom` / `gen-sbom` |
+| Build and maintain a **product SBOM** for the whole thing you place on the EU market | **Continuous vulnerability management**: security advisories, coordinated disclosure, updates — see [SECURITY-POLICY](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md) |
+| Own vulnerability **process**, owners, and fix timelines for **your** release | Nest or reference our component SBOM in yours — worked example: [`auditor-packet/`](auditor-packet/) |
+
+**Evidence Kit focus:** pillar 1 — Evidence Map, glossary, Friday plan, [`SKILL.md`](SKILL.md).
+
+---
+
+## 2. Implement secure boot
+
+| **Your job (manufacturer)** | **wolfSSL can help** |
+|----------------------------|----------------------|
+| Treat secure boot as one of the **most influential actions** you can take now: firmware that boots **trusted**, with a defined path to **update** when needed | **[wolfBoot](https://www.wolfssl.com/products/wolfboot/)** — secure bootloader for embedded systems |
+| Align update mechanics with your **complaint / incident** procedures and required **timelines** under CRA | Integration with wolfSSL/wolfCrypt; see wolfBoot docs and support |
+
+Secure boot is **product architecture**, not something an SBOM file alone satisfies.
+
+---
+
+## 3. Bring remote data processing and data-in-transfer up to compliance
+
+CRA is **not only about software inventory** — it also concerns **data** moving between the device and the network.
+
+| **Your job (manufacturer)** | **wolfSSL can help** |
+|----------------------------|----------------------|
+| Map **remote processing** and **connectivity** in your product (cloud, OTA, admin interfaces, telemetry) | Implementations of **state-of-the-art** secure protocols, for example: |
+| Use **current cryptography** and **secure protocols** for data in transfer; document what is enabled in **your** build | **TLS** (wolfSSL), **SSH** (wolfSSH), **MQTTS** (wolfMQTT), and related stacks |
+| Reflect enabled algorithms in **your** product documentation / SBOM / crypto inventory | Build properties in CycloneDX today (`wolfssl:build:*`); formal CBOM profile: **roadmap** — [ROADMAP.md](ROADMAP.md) |
+
+---
+
+## How this maps to the Evidence Kit
+
+| Shortlist pillar | Kit deliverable |
+|------------------|-----------------|
+| Know your components | Cheat sheet (Evidence Map), glossary, `auditor-packet/`, generate/validate scripts |
+| Secure boot | Out of scope for SBOM files — evaluate **wolfBoot** separately |
+| Data in transfer | Configure and document **your** protocol stack; wolfSSL ships crypto libraries, not your full product compliance |
+
+**You will leave with (presentation Promise):**
+
+1. **Evidence Map** — [`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md)  
+2. **Worked example** — [`auditor-packet/`](auditor-packet/)  
+3. **Friday plan** — product SBOM, nest wolfSSL, optional bomsh on **Linux CI** + [`SKILL.md`](SKILL.md)
+
+---
+
+## Related wolfSSL products (beyond this kit)
+
+| Area | Product / doc |
+|------|----------------|
+| TLS / wolfCrypt | [wolfssl.com](https://www.wolfssl.com/) · [doc/CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md) |
+| Secure boot | [wolfBoot](https://www.wolfssl.com/products/wolfboot/) |
+| SSH | wolfSSH |
+| MQTT | wolfMQTT |
+
+**Questions:** support@wolfssl.com
diff --git a/cra-evidence/CRA-Customer-One-Pager.md b/cra-evidence/CRA-Customer-One-Pager.md
@@ -0,0 +1,3 @@
+# Renamed
+
+This file is now **[CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md)** (CRA Supply Chain Cheat Sheet / Evidence Map).
diff --git a/cra-evidence/CRA-Supply-Chain-Glossary.md b/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)
+
+CRA shortlist (3 pillars): [`CRA-Compliance-Shortlist.md`](CRA-Compliance-Shortlist.md) · Evidence Map: [`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md) · AI playbook: [`SKILL.md`](SKILL.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*
diff --git a/cra-evidence/EVIDENCE-MAP.md b/cra-evidence/EVIDENCE-MAP.md
@@ -0,0 +1,7 @@
+# Evidence Map → cheat sheet
+
+The **Evidence Map** (what you provide vs what wolfSSL provides) is:
+
+**[CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md)**
+
+Full terminology: **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** · AI playbook: **[SKILL.md](SKILL.md)**
diff --git a/cra-evidence/GLOSSARY.md b/cra-evidence/GLOSSARY.md
@@ -0,0 +1,8 @@
+# Glossary
+
+| Layer | File |
+|-------|------|
+| **CRA shortlist** (3 pillars) | **[CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)** |
+| **Evidence Map** (1-page cheat sheet) | **[CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md)** |
+| **Full glossary** (SBOM, SPDX, CycloneDX, CBOM, VEX, bomsh, …) | **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** |
+| **AI playbook** (Friday plan + scripts) | **[SKILL.md](SKILL.md)** |
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Renamed

		This file is now [CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md) (CRA Supply Chain Cheat Sheet / Evidence Map).