Skip to content

Commit c57de5d

Browse files
hughsiehughsie
committed
Move the specification from fwupd.org to here
1 parent 7107367 commit c57de5d

15 files changed

+1028
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Github Action CI
2+
3+
on:
4+
push:
5+
branches:
6+
- '**'
7+
tags:
8+
- 'v*'
9+
pull_request:
10+
branches:
11+
master
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: install
23+
run: |
24+
sudo apt-get update
25+
sudo apt-get install latexmk libalgorithm-diff-perl texlive texlive-latex-extra texlive-humanities graphviz
26+
pip3 install --user mako
27+
pip3 install --user typing
28+
pip3 install --user Sphinx
29+
pip3 install --user codespell
30+
31+
- name: build pdf
32+
run: |
33+
make latexpdf
34+
git fetch --tags --force # Needed to make git-describe work
35+
mv build/latex/sbom-specification.pdf build/latex/sbom-specification-$(git describe).pdf
36+
- name: build html
37+
run: make html
38+
- name: build singlehtml
39+
run: make singlehtml
40+
41+
- name: upload
42+
uses: actions/upload-artifact@v4
43+
with:
44+
name: artifacts
45+
path: |
46+
build/latex/sbom-specification-*.pdf
47+
48+
- name: deploy
49+
uses: peaceiris/actions-gh-pages@v4
50+
with:
51+
github_token: ${{ secrets.GITHUB_TOKEN }}
52+
publish_dir: ./build/singlehtml
53+
54+
- name: release
55+
uses: softprops/action-gh-release@v2
56+
if: startsWith(github.ref, 'refs/tags/')
57+
with:
58+
files: build/latex/sbom-specification-*.pdf
59+
env:
60+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
build

‎Makefile‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# SPDX-License-Identifier: CC-BY-4.0
2+
#
3+
# Minimal makefile for Sphinx documentation
4+
#
5+
6+
# You can set these variables from the command line.
7+
SPHINXOPTS =
8+
SPHINXBUILD = sphinx-build
9+
SOURCEDIR = source
10+
BUILDDIR = build
11+
LATEXDIFF = latexdiff
12+
13+
all: latexpdf html
14+
15+
help:
16+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
17+
@echo " latexdiff to make LaTeX files including changebars against previous release"
18+
19+
.PHONY: all help latexdiff Makefile
20+
21+
latexdiff: latex
22+
@echo "Generating LaTeX changebars..."
23+
$(LATEXDIFF) --type=UNDERLINE --config VERBATIMENV=sphinxVerbatim \
24+
$(BUILDDIR)/latex-previous/sbom-specification.tex \
25+
$(BUILDDIR)/latex/sbom-specification.tex \
26+
> $(BUILDDIR)/latex/sbom-specification-changebars.tex
27+
@echo "Running LaTeX files through pdflatex..."
28+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
29+
@echo
30+
@echo "latexdiff finished; the PDF files are in $(BUILDDIR)/latex."
31+
32+
# Catch-all target: route all unknown targets to Sphinx using the new
33+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
34+
%: Makefile
35+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,21 @@
11
# Firmware Embedded SBOM Specification
2+
3+
This [repository](https://github.com/open-source-firmware/sbom) holds the source for the generation
4+
of the Firmware Embedded SBOM Specification using Sphinx.
5+
6+
Build commands:
7+
8+
>```
9+
>$ make html # For generating a hierarchy of html pages
10+
>$ make singlehtml # For generating a single html page
11+
>```
12+
13+
Output goes in ./build subdirectory.
14+
15+
## License
16+
This project is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) license.
17+
18+
## Contributions
19+
Patches should be submitted via [a pull request](https://github.com/open-source-firmware/sbom/pull).
20+
21+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->

‎source/acknowledgements.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. SPDX-License-Identifier: CC-BY-4.0
2+
3+
Acknowledgements
4+
================
5+
6+
The Firmware Embedded SBOM Specification was developed in 2024 by Richard Hughes (Red Hat),
7+
Martin Fernandez (Eclypsium) and Adam Williamson (Red Hat).
8+
9+
Many thanks should also go to the UEFI SBOM Sub Team for all thier support in the creation of this document.

‎source/appendix.rst‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
.. SPDX-License-Identifier: CC-BY-4.0
2+
3+
.. _chapter-appendix:
4+
5+
Appendix
6+
========
7+
8+
External SBOM Metadata
9+
----------------------
10+
11+
This document strongly encourages vendors to embed the SBOM metadata into the respective binaries, but there are two situations where externally referenced SBOM metadata would be allowed:
12+
13+
- Where the binary is loaded onto critically space-constrained devices, for example microcode that is loaded into the processor itself.
14+
- Where only later newer versions of the component have embedded SBOM metadata, and backwards compatibility is required with older revisions.
15+
16+
In these cases, the *component vendor* **MUST** provide “detached metadata” from the same source (or in the same archive file) as is used to distribute the immutable blob.
17+
18+
As the SBOM metadata is detached, vendors **MUST** ensure that the files do not get “out of sync” and are updated at the same time in the firmware source tree.
19+
Detached metadata **MUST** `always contain the SHA256 hash value of the binary <https://github.com/hughsie/python-uswid/#use-cases>`_ as evidence to allow validation and **MAY** be signed using a detached signature if the archive is not already signed.
20+
The public key **SHOULD** be distributed on a keyserver or company website for verification.
21+
22+
23+
Wasted Space Concerns
24+
---------------------
25+
26+
Some vendors have expressed concerns about “wasted” space from including the SBOM data in the binary image.
27+
For source components such as CPU microcode, a single *component* and vendor *entity* would use an additional ~350 bytes (zlib compressed coSWID), compared to 48kB for the average EFI binary and 25kb for a typical vendor BGRT “splash” logo.
28+
29+
The ``uswid`` command can automatically `generate <https://github.com/hughsie/python-uswid#generating-test-data>`_ a complete “worst case” platform SBOM with 1,000 plausible components.
30+
This SBOM requires an additional 140kB of SPI flash space (uncompressed coSWID), or 60kB when compressed with LZMA.
31+
For reference, the average free space in an Intel Flash ROM BIOS partition is 5.26Mb, where “free space” is defined as a greater than 100KiB stream of consecutive 0xFF’s after the first detected EFI file volume.
32+
Adding the SBOM as embedded metadata would use 1.1% of the available free space.
33+
Other firmware ecosystems such as Coreboot also `now include SBOM generation <https://doc.coreboot.org/sbom/sbom.html>`_ as part of the monolithic image.
34+
35+
36+
Getting the Runtime SBOM
37+
------------------------
38+
39+
The ACPI ``SBOM`` ACPI table may be used in the future to return the coSWID formatted binary SBOM data from any device exporting an ACPI callable interface.
40+
Further details will be provided when the SBOM table has been implemented.
41+
42+
If the platform allows direct access to the system SPI device, then the entire firmware image can be dumped to a local file and analyzed by tools such as ``uswid``.
43+
44+
Converting the SBOM
45+
-------------------
46+
47+
The embedded SBOM **SHOULD** be converted it into one or more SBOM export formats before publication.
48+
49+
This can be achieved easily using tools such as ``uswid``.
50+
For example, this can be used to produce two JSON files in CycloneDX and SPDX formats from the platform image:
51+
52+
::
53+
54+
$ uswid --load rom.bin --save cyclonedx-bom.json
55+
$ uswid --load rom.bin --save spdx.json
56+
57+
Signing the SBOM
58+
----------------
59+
60+
The embedded SBOM **MAY** be signed, and **MAY** also be included in the firmware checksum.
61+
If the firmware component is signed then the SBOM **SHOULD** be included in to the signature.
62+
The signing step is optional because a malicious silicon provider can typically do much worse things (e.g. adding or replacing a DXE binary) than modify the SBOM metadata.
63+
64+
Using the LVFS
65+
--------------
66+
67+
When firmware is uploaded to the LVFS it automatically extracts all available SBOM metadata and generates `a HTML page <https://fwupd.org/lvfs/devices/component/64327/swid>`_ with SPDX, SWID and CycloneDX download links that can be used for compliance purposes.
68+
The LVFS **MAY** allow vendors to upload firmware or platform SBOMs without uploading the firmware binary.
69+
Other services like Windows Update may offer this service in the future.
70+
71+
The VEX "trusted neutral entity" **MAY** also be the LVFS, even for firmware updates not distributed by the LVFS.
72+
Uploading VEX data requires vendors to register `for a LVFS vendor account <https://lvfs.readthedocs.io/en/latest/apply.html>`_ which is available at no cost.

0 commit comments

Comments
 (0)