sbom,bomsh: hash the bomsh-traced binary, fix doc/SBOM.md

make bomsh previously left the SHA-256 in checksums[] (post-libtool-
relink, hashed by `make sbom`'s private staging install) and the
OmniBOR gitoid in externalRefs (pre-relink, traced by bomtrace3)
describing two different files inside the same SPDX document.

Add SBOM_LIB_OVERRIDE to Makefile.am: the bomsh recipe now discovers
the traced library under src/.libs/ and passes it to the nested
`make sbom` invocation, so checksums[] hashes the same artefact that
bomsh_sbom.py enriches with OmniBOR ExternalRefs.

doc/SBOM.md:
  - §3.5 rewritten to match bomsh_verify.py reality (gates A and B
    only).  The previously documented gate (C) "Artefact correspondence
    -- gitoid == git-blob hash of libwolfssl.{so,dylib,a}" was never
    implementable: bomsh attaches the OmniBOR Input Manifest bom_id,
    not the binary's content gitoid, so that check would always fail.
    New "Identity of the SHA-256" subsection explains the
    SBOM_LIB_OVERRIDE binding instead.
  - §3.2 step ordering corrected (clean before bomtrace3, override
    plumbing in step 5).
  - Intro NTIA claim qualified to point at .github/workflows/sbom.yml
    for the actual validator set.
  - §2.4 "Third-party deps: none" qualified to mention --with-libz /
    --with-liboqs and the host C runtime.
  - §2.4 PURL row updated to the new pkg:github shape.

Author: sameehj

Makefile.am

@@ -395,6 +395,17 @@ WOLFSSL_LIB_DSO_BASENAMES = \
 #                          their own URL should set this to a URI they
 #                          actually serve (e.g.
 #                          https://example.com/sbom/wolfssl-X.Y.Z.spdx.json).
+#   SBOM_LIB_OVERRIDE      Absolute path to the library artefact whose
+#                          SHA-256 should land in the SBOM, INSTEAD of
+#                          discovering one via a private staging install.
+#                          Set by `make bomsh` so the SBOM hash and the
+#                          OmniBOR enrichment refer to the SAME bomsh-
+#                          traced binary; without this override `make
+#                          sbom` would re-link via `make install` and
+#                          hash a different artefact than `bomsh_sbom.py`
+#                          fingerprints, leaving the SHA-256 in
+#                          `checksums[]` and the gitoid in `externalRefs`
+#                          describing two unrelated files.
 sbom:
 	@if test -z "$(PYTHON3)"; then \
 	    echo ""; \
@@ -412,24 +423,34 @@ sbom:
 	@rm -rf $(abs_builddir)/_sbom_staging
 	@set -e; \
 	trap 'rm -rf $(abs_builddir)/_sbom_staging' EXIT INT TERM HUP; \
-	$(MAKE) install DESTDIR=$(abs_builddir)/_sbom_staging; \
-	sbom_lib=""; \
-	for lib in \
-	    $(addprefix "$(abs_builddir)/_sbom_staging$(libdir)"/,$(WOLFSSL_LIB_DSO_BASENAMES)) \
-	    "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.dll \
-	    "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.dll.a \
-	    "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.lib \
-	    "$(abs_builddir)/_sbom_staging$(libdir)"/wolfssl.lib \
-	    "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.a; do \
-	    if test -f "$$lib"; then sbom_lib="$$lib"; break; fi; \
-	done; \
-	if test -z "$$sbom_lib"; then \
-	    echo ""; \
-	    echo "ERROR: No installed wolfSSL library artifact found for SBOM."; \
-	    echo "       Searched in $(abs_builddir)/_sbom_staging$(libdir)"; \
-	    echo "       (configure with --enable-shared or --enable-static)"; \
-	    echo ""; \
-	    exit 1; \
+	if test -n "$(SBOM_LIB_OVERRIDE)"; then \
+	    if test ! -f "$(SBOM_LIB_OVERRIDE)"; then \
+	        echo ""; \
+	        echo "ERROR: SBOM_LIB_OVERRIDE=$(SBOM_LIB_OVERRIDE) does not exist."; \
+	        echo ""; \
+	        exit 1; \
+	    fi; \
+	    sbom_lib="$(SBOM_LIB_OVERRIDE)"; \
+	else \
+	    $(MAKE) install DESTDIR=$(abs_builddir)/_sbom_staging; \
+	    sbom_lib=""; \
+	    for lib in \
+	        $(addprefix "$(abs_builddir)/_sbom_staging$(libdir)"/,$(WOLFSSL_LIB_DSO_BASENAMES)) \
+	        "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.dll \
+	        "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.dll.a \
+	        "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.lib \
+	        "$(abs_builddir)/_sbom_staging$(libdir)"/wolfssl.lib \
+	        "$(abs_builddir)/_sbom_staging$(libdir)"/libwolfssl.a; do \
+	        if test -f "$$lib"; then sbom_lib="$$lib"; break; fi; \
+	    done; \
+	    if test -z "$$sbom_lib"; then \
+	        echo ""; \
+	        echo "ERROR: No installed wolfSSL library artifact found for SBOM."; \
+	        echo "       Searched in $(abs_builddir)/_sbom_staging$(libdir)"; \
+	        echo "       (configure with --enable-shared or --enable-static)"; \
+	        echo ""; \
+	        exit 1; \
+	    fi; \
 	fi; \
 	echo "SBOM: hashing $$sbom_lib"; \
 	if test -z "$${SOURCE_DATE_EPOCH:-}" && test -n "$(GIT)" && \
@@ -484,6 +505,17 @@ bomshdir          = $(datadir)/doc/$(PACKAGE)
 # also what makes the combined workflow correct: `make sbom` writes the SPDX,
 # but `make bomsh` issues `make clean` (which removes it via CLEANFILES), so
 # the only reliable way to enrich is to regenerate after the traced build.
+#
+# After the traced rebuild we discover the bomsh-traced library in
+# $(abs_builddir)/src/.libs/ and pass it to the nested `make sbom` call as
+# SBOM_LIB_OVERRIDE.  Without the override `make sbom` would `make install
+# DESTDIR=...` into a private tree, which triggers a libtool relink and
+# produces a binary whose SHA-256 differs from the one bomtrace3 traced.
+# That left the gitoid in `externalRefs` (which IS for the traced binary)
+# and the SHA-256 in `checksums[]` (which was NOT) describing two different
+# files in the same SPDX document.  With the override they describe the
+# same artefact, which is the invariant any auditor reading the document
+# expects.
 bomsh:
 	@if test -z "$(BOMTRACE3)"; then \
 	    echo ""; \
@@ -503,13 +535,7 @@ bomsh:
 	@printf 'raw_logfile=%s\n' '$(BOMSH_RAWLOG_BASE)' > '$(BOMSH_CONF)'
 	$(BOMTRACE3) -c '$(BOMSH_CONF)' $(MAKE)
 	$(BOMSH_CREATE_BOM) -r '$(BOMSH_RAWLOG)' -b '$(BOMSH_OMNIBORDIR)'
-	$(MAKE) sbom
-	@if test -z "$(BOMSH_SBOM)"; then \
-	    echo "NOTE: bomsh_sbom.py not in PATH; skipping SPDX enrichment."; \
-	    echo "      The OmniBOR graph in $(BOMSH_OMNIBORDIR) is still produced."; \
-	    exit 0; \
-	fi; \
-	bomsh_artifact=""; \
+	@bomsh_artifact=""; \
 	for lib in \
 	    $(addprefix "$(abs_builddir)/src/.libs"/,$(WOLFSSL_LIB_DSO_BASENAMES)) \
 	    "$(abs_builddir)/src/.libs/libwolfssl.a" \
@@ -518,7 +544,16 @@ bomsh:
 	done; \
 	if test -z "$$bomsh_artifact"; then \
 	    echo "NOTE: no built libwolfssl artifact found in $(abs_builddir)/src/.libs/"; \
-	    echo "      OmniBOR graph produced; SPDX enrichment skipped."; \
+	    echo "      OmniBOR graph produced; SBOM regeneration + SPDX"; \
+	    echo "      enrichment skipped."; \
+	    exit 0; \
+	fi; \
+	echo "bomsh: traced binary -> $$bomsh_artifact"; \
+	$(MAKE) sbom SBOM_LIB_OVERRIDE="$$bomsh_artifact"; \
+	if test -z "$(BOMSH_SBOM)"; then \
+	    echo "NOTE: bomsh_sbom.py not in PATH; skipping SPDX enrichment."; \
+	    echo "      The OmniBOR graph in $(BOMSH_OMNIBORDIR) is still produced."; \
+	    echo "      The base SBOM in $(SBOM_SPDX) already hashes the bomsh-traced binary."; \
 	    exit 0; \
 	fi; \
 	echo "Enriching SPDX with OmniBOR ExternalRefs (artifact: $$bomsh_artifact)..."; \

doc/SBOM.md

@@ -21,9 +21,12 @@ covered:
 | `python3 scripts/gen-sbom …` (standalone) | Embedded / RTOS customers building with their own Makefile, Keil, IAR, STM32CubeIDE, ESP-IDF, Zephyr, plain CMake, etc. | Any |
 | `make sbom` (autotools wrapper) | Linux server / Debian / RPM / Yocto / FIPS-Ready customers running `./configure && make` | Autotools |
 
-Both call the same Python core and produce SBOMs that pass the same SPDX
-2.3 / CycloneDX 1.6 / NTIA validators.  Pick whichever matches your build
-flow.
+Both call the same Python core and produce SBOMs that pass SPDX 2.3
+(`pyspdxtools`) and CycloneDX 1.6 (`cyclonedx-bom` strict JSON validator)
+schema validation.  The autotools `make sbom` integration job
+additionally runs `ntia-conformance-checker` against NTIA Minimum
+Elements 2021; see `.github/workflows/sbom.yml` for the exact set of
+validators run on every PR.  Pick whichever matches your build flow.
 
 ---
 
@@ -415,9 +418,9 @@ Both formats contain the same information:
 | Copyright | `Copyright (C) 2006-<year> wolfSSL Inc.` |
 | SHA-256 | hash of the installed `libwolfssl.so.X.Y.Z` |
 | CPE | `cpe:2.3:a:wolfssl:wolfssl:<version>:*:*:*:*:*:*:*` |
-| PURL | `pkg:generic/wolfssl@<version>` |
+| PURL | `pkg:github/wolfSSL/wolfssl@v<version>` (resolves directly in OSV / GHSA / Snyk / Trivy without per-vendor mapping) |
 | Download location | `https://github.com/wolfSSL/wolfssl` |
-| Third-party deps | none (wolfssl has no runtime dependencies in a default build) |
+| Third-party deps | none in a default build; `--with-libz` adds zlib and `--with-liboqs` adds liboqs (recorded as `DEPENDS_ON` packages with their own purl/CPE/supplier).  All builds depend transitively on the host C runtime; this is not enumerated as an SBOM component since it is system-supplied and varies per runtime target. |
 
 #### License detection
 
@@ -578,19 +581,25 @@ Place `bomsh_create_bom.py` (and optionally `bomsh_sbom.py`) from the bomsh
 
 ### 3.2 What make bomsh does
 
-1. Writes a build-local `_bomsh.conf` redirecting the raw logfile out of
+1. Runs `make clean` to ensure a full rebuild.  This is necessary because
+   `bomtrace3` intercepts syscalls live during compilation and cannot
+   post-process an already-built tree.  This step also removes any prior
+   `wolfssl-<version>.{cdx,spdx}.json` from a stand-alone `make sbom`,
+   which is intentional: the document `make bomsh` enriches must come
+   from the *traced* rebuild, not from a stale pre-trace one.
+2. Writes a build-local `_bomsh.conf` redirecting the raw logfile out of
    `/tmp/` to the build directory (avoids collisions between concurrent
    builds).
-2. Runs `make clean` to ensure a full rebuild.  This is necessary because
-   `bomtrace3` intercepts syscalls live during compilation and cannot
-   post-process an already-built tree.
 3. Runs `bomtrace3 -c _bomsh.conf make` — rebuilds wolfSSL under strace
    tracing, recording every compiler invocation with its inputs and outputs.
 4. Runs `bomsh_create_bom.py` to process the raw logfile and produce the
    OmniBOR artifact graph in `omnibor/`.
-5. If `bomsh_sbom.py` is available **and** `wolfssl-<version>.spdx.json`
-   exists (from `make sbom`), annotates that SPDX document with OmniBOR
-   `ExternalRef` identifiers, producing `omnibor.wolfssl-<version>.spdx.json`.
+5. Discovers the bomsh-traced library under `src/.libs/` and runs
+   `make sbom SBOM_LIB_OVERRIDE=<traced-library>` so the regenerated
+   SPDX hashes the same binary that bomsh traced (see § 3.5).
+6. If `bomsh_sbom.py` is available, annotates the regenerated SPDX
+   document with OmniBOR `ExternalRef` identifiers, producing
+   `omnibor.wolfssl-<version>.spdx.json`.
 
 ### 3.3 Output files
 
@@ -632,27 +641,43 @@ The raw logfile (`bomsh_raw_logfile.sha1`) and conf file (`_bomsh.conf`)
 are written to the build directory and removed by `make clean`.  The
 `omnibor/` tree is also removed by `make clean`.
 
+#### Identity of the SHA-256 in the enriched SPDX
+
+`make bomsh` discovers the bomsh-traced library under
+`$(abs_builddir)/src/.libs/` and passes it to the nested `make sbom`
+invocation as `SBOM_LIB_OVERRIDE`, so the SHA-256 in the SPDX
+`checksums[]` is the SHA-256 of the **exact binary that `bomtrace3`
+traced**.  Without that override `make sbom` would re-link via `make
+install DESTDIR=...` and hash a libtool-relinked artefact whose
+SHA-256 differs from the traced library, leaving the SHA-256 in
+`checksums[]` and the OmniBOR `externalRefs` describing two different
+files in the same SPDX document.
+
 #### CI verifiability gates
 
-The bomsh CI job enforces three independent self-consistency properties
+The bomsh CI job enforces two independent self-consistency properties
 on every PR, in addition to schema validation of the enriched SPDX
 through `pyspdxtools`:
 
 1. **Resolvability** — every `gitoid` listed in the SPDX `externalRefs`
    resolves to a blob present at `omnibor/objects/<aa>/<rest>`.
 2. **Object-store integrity** — every blob in `omnibor/objects/`
-   round-trips through `sha1(b"blob <len>\0" + content)`, so a corrupt or
-   truncated object store is caught at PR time, not by a downstream
+   round-trips through `sha1(b"blob <len>\0" + content)`, so a corrupt
+   or truncated object store is caught at PR time, not by a downstream
    verifier weeks later.
-3. **Artefact correspondence** — the `gitoid` recorded against the
-   `wolfssl` SPDX package equals the git-blob hash of the actual
-   `libwolfssl.{so,dylib,a}` that `make bomsh` traced.  This is what
-   makes the SBOM a true attestation of the binary that would ship,
-   rather than a plausible-looking but fictional reference.
 
-If any of these fail, the PR fails — the bomsh provenance bundle that a
+If either fails, the PR fails — the bomsh provenance bundle that a
 CRA reviewer would download is never published with a broken bridge.
 
+A third gate is **not** implemented: the gitoid that `bomsh_sbom.py`
+attaches to the SPDX is the bom_id of the OmniBOR Input Manifest for
+the traced artefact, not the git-blob hash of the binary itself.  The
+two are different by design (the bom_id summarises the build inputs,
+not the linked output bytes), so a "gitoid == sha1 of the binary"
+check would always fail.  What ties the SBOM to the binary today is
+the SHA-256 in `checksums[]`, which the `SBOM_LIB_OVERRIDE` plumbing
+described above guarantees is the SHA-256 of the bomsh-traced library.
+
 The verifier itself lives at `scripts/bomsh_verify.py` (importable, with
 synthetic-fixture unit tests in `scripts/test_gen_sbom.py`).  Run it
 against any local `make bomsh` output with: