Skip to content

README.md

Latest commit

 

History

History
305 lines (226 loc) · 14 KB

README.md

File metadata and controls

305 lines (226 loc) · 14 KB
Raw

wolfSSL CRA Kit

Example project and scripts for teams that ship products containing wolfSSL and need EU Cyber Resilience Act (CRA)-style software transparency artifacts.

This kit does not make your product “CRA compliant.” It shows how to obtain and nest wolfSSL component evidence inside your product SBOM and auditor packet.

Not legal advice. Map obligations to your product class and role with counsel.

wolfSSL's own CRA posture. wolfSSL Inc. is itself a manufacturer under the CRA for libraries it places on the EU market. We publish our own security.txt and CVD policy, and the manufacturer-side filings we ship under CRA — Annex III/IV classification, conformity assessment route, declaration of conformity template, EU Authorised Representative status, support-period policy, and vulnerability-handling process — are in wolfssl-inc-auditor-packet/. Use them as reference templates for your product.

Document Use
CRA-Compliance-Shortlist.md Four pillars towards CRA (components, secure boot, data in transfer, vulnerability handling)
CRA-Cheat-Sheet.md Who provides what — you vs wolfSSL (print/PDF)
CRA-Supply-Chain-Glossary.md Full terminology (self-contained in this kit)
SKILL.md AI playbook — agent checklist, scripts, Cursor install
ROADMAP.md SBOM / CBOM / VEX / bomsh / CSAF — today vs roadmap
auditor-packet/ Customer-side worked example — fictional Acme Connect Gateway + wolfSSL SBOM samples
wolfssl-inc-auditor-packet/ Manufacturer-side filings — what wolfSSL Inc. itself ships under CRA

Self-contained: all customer-facing docs live in this directory. You only need a separate wolfSSL source tree (with SBOM support) to regenerate component SBOMs.

Prerequisites

  • wolfSSL source with SBOM support (see wolfSSL SBOM feature (upstream) below). Typical layout:

    wolf/
├── wolfssl/              ← WOLFSSL_DIR (default: ../../wolfssl from here)
└── wolfssl-examples/
    └── cra-kit/          ← you are here

  • Python 3 for scripts/gen-sbom (embedded path) and scripts/validate.sh.

  • pcpp (optional for embedded): install on the same interpreter as python3: python3 -m pip install pcpp. If pip install pcpp used conda but your shell runs /usr/local/bin/python3, use CRA_PYTHON=python or rely on the script's automatic compiler -dM -E fallback (no pcpp required).

  • Cross-compile note for embedded (-dM -E fallback only): the script defaults to host cc. For target-accurate macros set CC=arm-none-eabi-gcc (or your toolchain) before running so the SBOM reflects target __ARM_ARCH, __SIZEOF_LONG__, etc. rather than your laptop's. Skip this if you have pcpp installed.

  • Optional schema validators (used by validate.sh if installed):

All the “BOMs” (today vs roadmap)

Name What it lists Who owns it wolfSSL today Roadmap
Product SBOM Entire shipped product You — —
Component SBOM wolfSSL only wolfSSL (you integrate) Yes — SPDX 2.3 + CycloneDX 1.6 Ongoing
VEX Does CVE X apply to our build? You Advisories (VEX inputs) Templates / automation
CBOM Crypto algorithms / modules You; we signal Partial — wolfssl:build:* in CycloneDX Formal cryptographic-asset
OmniBOR / bomsh How the library binary was built wolfSSL (optional) Yes — Linux host only Same

Details: ROADMAP.md.

Plain summary: SBOM = what’s inside. Crypto build properties = what crypto you compiled in (CBOM direction). bomsh = how the library was built (optional). Product SBOM = your job.

Which path are you?

Profile Build Generate wolfSSL SBOM
A. Linux / server / Yocto / package ./configure && make make sbom in wolfSSL tree
B. Embedded / RTOS / IDE user_settings.h + your Makefile / Keil / Zephyr / ESP-IDF ./scripts/generate-embedded-sbom.sh (kit demo) or upstream gen-sbom
C. Commercial license Either CRA_LICENSE_OVERRIDE=LicenseRef-wolfSSL-Commercial CRA_LICENSE_TEXT=/path/to/commercial-license.txt ./scripts/generate-wolfssl-sbom.sh

Commercial (LicenseRef-*) overrides require CRA_LICENSE_TEXT pointing at the plain-text licence you received from wolfSSL. SPDX 2.3 §10.1 requires the licence text to be embedded for any LicenseRef-*; both gen-sbom and make sbom hard-fail without it. A stock SPDX id (e.g. Apache-2.0) needs no text. If you don't have the text file handy, use scripts/make-commercial-sample.sh to derive a commercial sample from the pinned GPL samples instead.

Every manufacturer still:

  1. Maintains a product SBOM (all components).
  2. References or copies wolfSSL’s .spdx.json / .cdx.json into it.
  3. Regenerates wolfSSL SBOM when user_settings.h or your source list changes.
  4. Owns vulnerability handling (process + owner).
  5. Uses bomsh only if an auditor or contract requires build proof — on a Linux host.

Quick start

1. Validate the bundled sample (no wolfSSL build required)

cd wolfssl-examples/cra-kit
./scripts/validate.sh

2. Regenerate component SBOMs (requires wolfSSL with make sbom)

export WOLFSSL_DIR=../../wolfssl
./scripts/refresh-samples.sh    # make sbom + auto-fix product SPDX checksum

Or without updating the product stub checksum:

./scripts/generate-wolfssl-sbom.sh          # default: autotools if Makefile exists
CRA_SBOM_MODE=embedded ./scripts/generate-wolfssl-sbom.sh   # rarely used for packet/
./scripts/generate-embedded-sbom.sh         # writes wolfssl-component-embedded/

CRA_LICENSE_OVERRIDE=LicenseRef-wolfSSL-Commercial \
    CRA_LICENSE_TEXT=/path/to/wolfssl-commercial-license.txt \
    ./scripts/generate-wolfssl-sbom.sh      # commercial-license sample (text required)
./scripts/make-commercial-sample.sh         # derive from pinned GPL samples (no rebuild)

Pinned samples in auditor-packet/wolfssl-component/ are from make sbom (autotools), with a sibling *.commercial.{cdx,spdx}.json showing the override pattern. Embedded regen produces a different SBOM (watermarked wolfssl:sbom:demo=true) — see auditor-packet/wolfssl-component/SAMPLE-PROVENANCE.md.

3. Study the sample product packet

Open auditor-packet/00-INDEX.md — fictional Acme Connect Gateway shows CycloneDX bom external reference and SPDX externalDocumentRefs pointing at wolfSSL’s files.

4. Integrate into your real product SBOM

Copy the pattern from product-acme-connect-gateway.* in auditor-packet/ — both SPDX externalDocumentRefs and CycloneDX bom external references are shown end-to-end. For the upstream technical reference on make sbom flags, output formats, and SBOM_LICENSE_OVERRIDE for commercial licensees, see wolfssl/doc/SBOM.md.

make bomsh — Linux host only (simple explanation)

make bomsh is optional for most CRA transparency needs. Use it when someone asks: “Prove this libwolfssl.so was built from these exact sources.”

Why only Linux? Bomsh runs bomtrace3 — a patched strace that watches every compiler call during a full rebuild. That program is built and tested on Linux build machines (normal ptrace, no kernel patches).

Your situation What to do
Build on Linux make bomsh after make sbom in wolfSSL
Build on macOS / Windows Run bomsh in Linux CI, WSL2, or a container
Ship firmware to MCU / RTOS Target OS does not matter — tracing runs on the build host
Embedded, no Linux in house Use gen-sbom for SBOM on any OS; skip bomsh unless required

The sample packet does not ship omnibor/ (large). See auditor-packet/wolfssl-component/README-bomsh.md.

Full detail: wolfssl/doc/SBOM.md §3.

wolfSSL SBOM feature (upstream)

SBOM and optional bomsh provenance are developed in the main wolfSSL repository:

Item Location
Generator wolfssl/scripts/gen-sbom
Autotools make sbom, make bomsh
CI wolfssl/.github/workflows/sbom.yml
Reference (flags, formats, OmniBOR) doc/SBOM.md
Customer-facing CRA narrative, glossary, auditor packet, AI playbook this kit (you are here)

Use a wolfSSL tree where the make sbom (and optionally make bomsh) targets are available before running the scripts here. Once these targets land on master, any recent wolfSSL checkout works; until then, use the integration branch / PR.

Pinned sample version: see VERSION (default 5.9.1).

Embedded demo settings

user_settings.h in this directory is included when WOLFSSL_USER_SETTINGS is defined for ./scripts/generate-embedded-sbom.sh. Production SBOMs must use your project's user_settings.h and your full --srcs list (every wolfSSL .c you compile).

Presentation

15-minute co-sponsor slide track: presentations/SLIDE-OUTLINE.md.

Handouts: CRA-Cheat-Sheet.md + CRA-Supply-Chain-Glossary.md; point AI users at SKILL.md (copy to .cursor/skills/wolfssl-cra-kit/).

Agent skill

SKILL.md is a customer deliverable (not internal-only) — see presentations/SLIDE-OUTLINE.md. Copy to .cursor/skills/wolfssl-cra-kit/ for Cursor.

FAQ

Do we need our own SBOM?
Yes — for the whole product you place on the EU market.

Is wolfSSL’s SBOM enough alone?
No — nest or reference it in your product SBOM (see auditor-packet/).

SPDX or CycloneDX?
wolfSSL ships both; use what your tools expect.

Do we need bomsh for CRA?
Usually no. SBOM alone covers most transparency asks.

What about CBOM?
Many RFQs ask for crypto inventory. Today: wolfssl:build:* properties in CycloneDX from your real config. Formal CycloneDX CBOM: roadmap — see ROADMAP.md.

FIPS builds?
The SBOM generator does not change validated module code; your FIPS boundary documentation remains separate.

What does this kit NOT cover?
Software transparency only. Structural CRA obligations are out of scope: appointing an EU Authorised Representative (Art. 18), product classification (Annex III/IV), conformity assessment + CE marking, full technical documentation per Annex VII, the support-period commitment, and importer / distributor obligations. See CRA-Compliance-Shortlist.md "Beyond this kit" for the list. Engage CRA counsel or consultant — these are legal/structural decisions, not artefacts.

Are we outside the EU? (US / Asia / etc.)
Then you almost certainly need an EU Authorised Representative (Art. 18) appointed in writing before placing your product on the EU market. Either contract a third-party AR service or use an existing EU subsidiary. This is a long-lead item — start now, do not wait for September 2026.

Further reading

OpenSSF guidance

  • CRA Brief Guide for OSS Developers — When the CRA applies to open source projects and what obligations fall on manufacturers integrating OSS components into commercial products.
  • SBOM in Compliance — OpenSSF SBOM Everywhere SIG survey of the global regulatory landscape: CRA, NTIA minimum elements, US EO 14028, Germany TR-03183, others.
  • Getting Started with SBOMs — OpenSSF guidance on SBOM generation approaches (build-integrated vs. separate tooling), phase selection, publication. wolfSSL's make sbom follows the build-integrated approach.
  • OpenSSF CRA Policy Hub — Ongoing OpenSSF coverage of CRA developments and community responses.
  • SBOM Everywhere Wiki — tooling catalog, working group resources, naming conventions, cross-format guidance for SPDX and CycloneDX.

Standards

Support

Questions about this kit: support@wolfssl.com

Security reports: see security.txt and our Coordinated Vulnerability Disclosure policy. Do not send vulnerability details to support@ — use the security contact listed in security.txt.