fix(sbom): emit urn:uuid documentNamespace; validate override; drop unhosted wolfssl.com URLs

The previous output asserted `https://wolfssl.com/sbom/...` URLs the
project does not serve.  Default `documentNamespace` to a deterministic
`urn:uuid` (SPDX 2.3 §6.5 requires uniqueness, not resolvability) and
add `--document-namespace` / `SBOM_DOCUMENT_NAMESPACE` with RFC 3986
validation; the uuid5 seed is unchanged so derived UUIDs stay byte-stable.

Author: sameehj

Makefile.am

@@ -387,6 +387,13 @@ WOLFSSL_LIB_DSO_BASENAMES = \
 #                          for SPDX 2.3 conformance whenever a custom
 #                          LicenseRef is in use; `make sbom` exits with an
 #                          error if it is missing.
+#   SBOM_DOCUMENT_NAMESPACE Override the SPDX documentNamespace.  Default
+#                          is a deterministic urn:uuid (SPDX 2.3 §6.5
+#                          requires only uniqueness, not resolvability).
+#                          Downstream packagers re-hosting the SBOM under
+#                          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:
 	@if test -z "$(PYTHON3)"; then \
 	    echo ""; \
@@ -438,6 +445,7 @@ sbom:
 	    --license-file $(srcdir)/LICENSING \
 	    $(if $(SBOM_LICENSE_OVERRIDE),--license-override '$(SBOM_LICENSE_OVERRIDE)') \
 	    $(if $(SBOM_LICENSE_TEXT),--license-text '$(SBOM_LICENSE_TEXT)') \
+	    $(if $(SBOM_DOCUMENT_NAMESPACE),--document-namespace '$(SBOM_DOCUMENT_NAMESPACE)') \
 	    --options-h $(abs_builddir)/wolfssl/options.h \
 	    --lib "$$sbom_lib" \
 	    --dep-libz $(ENABLED_LIBZ) \

doc/CRA.md

@@ -101,12 +101,20 @@ Reference wolfSSL's SPDX document from your product's SPDX document using
 `externalDocumentRefs`.  This keeps the documents separate and lets wolfSSL's
 SBOM stand as an independently verifiable artefact.
 
+wolfSSL ships the generated SBOM with the source distribution and does not
+currently publish it at a fixed, resolvable URL.  In the `spdxDocument`
+field below, substitute the URI under which your distribution mirrors
+`wolfssl-<version>.spdx.json` (e.g. an artifact server, OCI registry, or
+distribution mirror you control).  SPDX 2.3 §6.5 only requires the value
+be a unique URI; if you do not re-host, the `urn:uuid:<uuid5-derived>`
+form that `make sbom` emits by default is acceptable.
+
 ```json
 {
   "externalDocumentRefs": [
     {
       "externalDocumentId": "DocumentRef-wolfssl",
-      "spdxDocument": "https://wolfssl.com/sbom/wolfssl-<version>.spdx.json",
+      "spdxDocument": "<URI where your distribution serves wolfssl-<version>.spdx.json>",
       "checksum": {
         "algorithm": "SHA256",
         "checksumValue": "<sha256-of-wolfssl-spdx.json>"
@@ -136,7 +144,11 @@ directly into your own SPDX document and add the `DYNAMIC_LINK` /
 ### CycloneDX: component reference
 
 Include wolfSSL as a component in your CycloneDX BOM, referencing the
-wolfSSL CycloneDX document via an external reference of type `bom`:
+wolfSSL CycloneDX document via an external reference of type `bom`.
+
+As with the SPDX `spdxDocument` URI above, wolfSSL does not currently
+publish CycloneDX SBOMs at a fixed, resolvable URL; substitute the URI
+under which your distribution mirrors `wolfssl-<version>.cdx.json`.
 
 ```json
 {
@@ -149,7 +161,7 @@ wolfSSL CycloneDX document via an external reference of type `bom`:
   "externalReferences": [
     {
       "type": "bom",
-      "url": "https://wolfssl.com/sbom/wolfssl-<version>.cdx.json",
+      "url": "<URI where your distribution serves wolfssl-<version>.cdx.json>",
       "hashes": [
         {
           "alg": "SHA-256",

doc/SBOM.md

@@ -78,6 +78,7 @@ Optional flags:
 | `--dep-version libz=1.3.1` | Explicit dep version when `pkg-config` is unavailable (typical cross-compile) |
 | `--license-override LicenseRef-wolfSSL-Commercial` | If you are a commercial licensee, not GPL |
 | `--license-text /path/to/commercial-license.txt` | Required when `--license-override` is a `LicenseRef-*` |
+| `--document-namespace https://example.com/sbom/wolfssl-5.9.1.spdx.json` | Override the SPDX `documentNamespace`.  Default is a deterministic `urn:uuid:` derived from `--name`/`--version` (SPDX 2.3 §6.5 requires only uniqueness, not resolvability).  Set this when **your** distribution re-hosts the SBOM under a stable URL. |
 
 ### 1.3 Dependencies
 
@@ -458,6 +459,23 @@ make sbom \
     SBOM_LICENSE_TEXT=/path/to/wolfssl-commercial-license.txt
 ```
 
+#### Overriding the SPDX `documentNamespace`
+
+By default the SPDX document's `documentNamespace` is a deterministic
+`urn:uuid:<uuid5-derived>` value.  SPDX 2.3 §6.5 only requires that this
+field be a unique URI; it does **not** have to resolve to anything.  The
+default avoids asserting a hosted URL the wolfSSL project does not serve.
+
+If your distribution re-publishes the SBOM under a stable URL you control,
+set `SBOM_DOCUMENT_NAMESPACE` (or `--document-namespace` in the standalone
+entry point) so downstream consumers can `externalDocumentRef` your
+hosted copy:
+
+```sh
+make sbom \
+    SBOM_DOCUMENT_NAMESPACE=https://example.com/sbom/wolfssl-5.9.1.spdx.json
+```
+
 #### External dependency version detection
 
 The optional external dependencies wolfSSL can link against (`libz` and

scripts/gen-sbom

@@ -13,8 +13,17 @@ import uuid
 from datetime import datetime, timezone
 
 
-# Stable namespace for deterministic uuid5 derivation.  Anchored under
-# wolfssl.com so collisions with other projects' SBOM UUIDs are not a concern.
+# Stable namespace for deterministic uuid5 derivation.  The seed string is
+# an opaque input to uuid5 -- it only needs to be (a) constant across
+# releases so the derived UUIDs reproduce byte-for-byte (any consumer
+# pinning a wolfSSL SBOM hash would otherwise see a content rotation
+# from a seed change alone), and (b) unlikely to collide with another
+# project's uuid5 namespace.  It is NOT a URL the SBOM resolves to and
+# is NOT what we serialize as the SPDX documentNamespace -- that field
+# is now `urn:uuid:<derived>` (see generate_spdx).  The historical
+# string is preserved verbatim to keep derived UUIDs (bom-refs,
+# serialNumbers, the documentNamespace UUID component) stable across
+# the documentNamespace shape change.
 SBOM_UUID_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_URL, 'https://wolfssl.com/sbom/')
 
 
@@ -707,7 +716,7 @@ def generate_cdx(name, version, supplier, license_id, license_text, lib_hash,
 def generate_spdx(name, version, supplier, license_id, license_text, lib_hash,
                   timestamp, year, doc_ns_uuid, enabled_deps, build_props,
                   dep_version_overrides=None, hash_kind='library-binary',
-                  srcs_basenames=None):
+                  srcs_basenames=None, document_namespace=None):
     build_defines = ', '.join(k for k, _ in build_props)
     # Only annotate the comment when running the source-merkle entry
     # point.  The autotools / library-binary path keeps its existing
@@ -762,14 +771,20 @@ def generate_spdx(name, version, supplier, license_id, license_text, lib_hash,
             'relationshipType': 'DEPENDS_ON',
         })
 
+    # SPDX 2.3 §6.5: documentNamespace must be a unique URI; it is NOT
+    # required to resolve to anything.  Default to `urn:uuid:<derived>`
+    # rather than a `https://wolfssl.com/sbom/...` URL the project does
+    # not actually host -- emitting an unresolvable URL misleads any
+    # downstream tool that follows it.  Downstream packagers who DO host
+    # a per-version mirror can override via `--document-namespace`
+    # (Makefile.am: SBOM_DOCUMENT_NAMESPACE).
+    doc_namespace = document_namespace or f'urn:uuid:{doc_ns_uuid}'
     doc = {
         'spdxVersion': 'SPDX-2.3',
         'dataLicense': 'CC0-1.0',
         'SPDXID': 'SPDXRef-DOCUMENT',
         'name': f'{name}-{version}',
-        'documentNamespace': (
-            f'https://wolfssl.com/sbom/{name}-{version}-{doc_ns_uuid}'
-        ),
+        'documentNamespace': doc_namespace,
         'creationInfo': {
             'creators': [
                 f'Organization: {supplier}',
@@ -884,6 +899,16 @@ def main():
                              + ', '.join(sorted(DEP_META)) + '. Required '
                              'on hosts without pkg-config (typical embedded '
                              'cross-compile setups).')
+    parser.add_argument('--document-namespace', default='',
+                        metavar='URI',
+                        help='Override SPDX documentNamespace.  Default '
+                             'is a deterministic urn:uuid derived from '
+                             '--name and --version.  Set to a URI you '
+                             'actually host (e.g. '
+                             'https://example.com/sbom/wolfssl-X.Y.Z.spdx.json) '
+                             'when re-publishing the SBOM under your own '
+                             'distribution.  SPDX 2.3 §6.5 requires only '
+                             'uniqueness, not resolvability.')
     parser.add_argument('--cdx-out', required=True,
                         help='Output path for CycloneDX JSON')
     parser.add_argument('--spdx-out', required=True,
@@ -908,6 +933,24 @@ def main():
             "       --srcs: hash the wolfSSL source files compiled into "
             "your firmware (OmniBOR gitoid Merkle hash).")
 
+    # SPDX 2.3 §6.5 requires documentNamespace to be a unique absolute URI
+    # per RFC 3986.  `make sbom` runs pyspdxtools afterwards and would
+    # catch a malformed value, but the standalone entry point has no
+    # validation gate -- a typo in SBOM_DOCUMENT_NAMESPACE / a packager
+    # passing a relative path would otherwise land malformed SPDX in
+    # downstream artefacts.  An absolute URI per RFC 3986 §3 has a
+    # non-empty scheme; urlparse extracts that.
+    if args.document_namespace:
+        from urllib.parse import urlparse
+        scheme = urlparse(args.document_namespace).scheme
+        if not scheme:
+            sys.exit(
+                f"ERROR: --document-namespace {args.document_namespace!r} "
+                "is not an absolute URI (SPDX 2.3 §6.5 requires RFC 3986 "
+                "absolute URI form).  Expected e.g. "
+                "https://example.com/sbom/wolfssl-X.Y.Z.spdx.json or "
+                "urn:uuid:00000000-0000-0000-0000-000000000000.")
+
     enabled_deps = [
         key for key, flag in [
             ('libz',   args.dep_libz),
@@ -1004,6 +1047,7 @@ def main():
         enabled_deps, build_props,
         dep_version_overrides=dep_version_overrides,
         hash_kind=hash_kind, srcs_basenames=srcs_basenames,
+        document_namespace=(args.document_namespace or None),
     )
 
     try:

scripts/test_gen_sbom.py

@@ -1720,12 +1720,45 @@ def test_top_level_shape(self):
         self.assertEqual(doc['dataLicense'], 'CC0-1.0')
         self.assertEqual(doc['SPDXID'], 'SPDXRef-DOCUMENT')
         self.assertEqual(doc['name'], 'wolfssl-5.9.1')
-        self.assertTrue(
-            doc['documentNamespace'].startswith('https://wolfssl.com/sbom/'))
-        # documentNamespace must include the doc_ns_uuid so two
-        # different versions produce different namespaces (SPDX 2.3
-        # §6.5).
-        self.assertIn(self.BASE_KW['doc_ns_uuid'], doc['documentNamespace'])
+        # SPDX 2.3 §6.5: documentNamespace must be a unique URI; no
+        # requirement that it resolve.  Default to `urn:uuid:<derived>`
+        # rather than a `https://wolfssl.com/sbom/...` URL the project
+        # does not host -- emitting an unresolvable URL would mislead
+        # any downstream tool that follows it.  The doc_ns_uuid keeps
+        # the namespace per-version unique without making a hosting
+        # claim.
+        self.assertEqual(
+            doc['documentNamespace'],
+            f'urn:uuid:{self.BASE_KW["doc_ns_uuid"]}')
+
+    def test_document_namespace_override_is_honoured(self):
+        # Downstream packagers who legitimately re-host the SBOM under
+        # their own URL pass --document-namespace; the override must
+        # win over the urn:uuid default.  Without this knob a packager
+        # would have to fork the script to satisfy SPDX 2.3 §6.5
+        # uniqueness against a self-hosted mirror.
+        custom = 'https://example.com/sbom/wolfssl-5.9.1.spdx.json'
+        doc = gs.generate_spdx(**{
+            **self.BASE_KW,
+            'document_namespace': custom,
+        })
+        self.assertEqual(doc['documentNamespace'], custom)
+
+    def test_document_namespace_default_is_urn_uuid(self):
+        # Negative companion to test_document_namespace_override: when
+        # no override is supplied (None or empty), the urn:uuid form is
+        # used and the previously-emitted https://wolfssl.com/sbom/
+        # URL is NOT reintroduced (regression guard for the M1
+        # correction).
+        for explicit in (None, ''):
+            doc = gs.generate_spdx(**{
+                **self.BASE_KW,
+                'document_namespace': explicit,
+            })
+            self.assertTrue(
+                doc['documentNamespace'].startswith('urn:uuid:'),
+                f'{explicit!r} -> {doc["documentNamespace"]!r}')
+            self.assertNotIn('wolfssl.com/sbom', doc['documentNamespace'])
 
     def test_main_package_fields(self):
         doc = gs.generate_spdx(**self.BASE_KW)