A minimal, security-hardened U-Boot build and test environment targeting QEMU x86_64 with full TPM 2.0 (via swtpm), Measured Boot, FIT Image Signing (RSA-4096), and UEFI Secure Boot support. Designed as a firmware security reference for automotive and embedded Linux platforms.

• Architecture
• Security Features
• Prerequisites
• Quick Start
• Scripts Reference
• Secure Boot Workflow
• Configuration Guide
• TPM PCR Layout
• Testing Workflows Locally
• Contributing
• License

┌─────────────────────────────────────────────────────────┐
│  Host Machine                                            │
│                                                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │  QEMU x86_64                                       │  │
│  │                                                    │  │
│  │   ┌──────────────────┐    ┌─────────────────────┐ │  │
│  │   │  U-Boot ROM      │◄──►│  swtpm              │ │  │
│  │   │  (2 MB)          │    │  TPM 2.0 emulator   │ │  │
│  │   │                  │    │  Unix socket        │ │  │
│  │   │  • Measured Boot │    └─────────────────────┘ │  │
│  │   │  • FIT Signing   │                             │  │
│  │   │  • EFI SecureBoot│                             │  │
│  │   └──────────────────┘                             │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Open the repository in VS Code and click Reopen in Container.
All tools are pre-installed. See .devcontainer/ for the full environment definition.

One-liner install:

sudo apt-get install -y gcc make flex bison bc \
    python3 python3-dev python3-pip python3-setuptools swig \
    openssl libssl-dev libgnutls28-dev u-boot-tools \
    qemu-system-x86 swtpm swtpm-tools \
    device-tree-compiler python3-pyelftools shellcheck

# 1. Clone U-Boot source (shallow, tag v2026.01)
./setup.sh

# 2. Build U-Boot ROM with security config applied
./build.sh

# 3. Run in QEMU with software TPM 2.0
./qemu.sh

# 4. Clean all build artefacts
./clean.sh

FIT image signing allows U-Boot to cryptographically verify a payload before executing it. The signing certificate is embedded in the U-Boot ROM at build time — U-Boot will refuse to boot any image not signed with the embedded key.

# 1. Generate RSA-4096 key pair
./scripts/gen-keys.sh dev

# 2. Build U-Boot ROM (generates u-boot.dtb needed for cert embedding)
./build.sh

# 3. Assemble a demo FIT image + raw boot disk
./scripts/make-demo-fit.sh

# 4. Sign FIT, embed cert into DTB, re-link ROM
./scripts/embed-key.sh dev

# 5. Boot — U-Boot verifies the FIT image before loading
./qemu.sh --boot-img build/boot.img

Expected output in U-Boot serial console:

## Loading kernel from FIT Image at 01000000 ...
   Using 'conf-1' configuration
   Verifying Hash Integrity ... sha256,rsa4096:dev+ OK
   Loading Kernel Image ...

sha256,rsa4096:dev+ OK confirms the signature verified against the certificate baked into the ROM.

Note: Steps 2 and 4 both run make. Step 2 is a full build (distclean). Step 4 is an incremental re-link only — it takes ~2 seconds because only the DTB-linked objects are rebuilt.

Replace make-demo-fit.sh with your own boot.its pointing at a real Image/uImage, then run embed-key.sh and qemu.sh --boot-img as above. The FIT source template is in the scripts reference.

Custom options live in config/qemu-x86_64 and are merged on top of the upstream qemu-x86_64_defconfig at build time.

The autoboot countdown cannot be interrupted by pressing any random key. A SHA-256-hashed passphrase is required. The demo passphrase is stop.

When you see this prompt in the QEMU serial console:

Passphrase required to abort autoboot (5 s) — type silently

Type stop (characters are not echoed) to drop into the U-Boot shell.

To set a custom passphrase, regenerate the hash and update the config:

printf '%s' 'your-passphrase' | sha256sum
# Paste the result into CONFIG_AUTOBOOT_STOP_STR_SHA256 in config/qemu-x86_64
# Then rebuild: ./build.sh

Standard TCG PC Client Platform PCR assignments used by U-Boot's measured boot:

Read PCR values at runtime:

• U-Boot shell: tpm pcr_read 0
• Host (after boot): tpm2_pcrread (tpm2-tools)

Use act to run GitHub Actions workflows locally via Docker before pushing.

Install once:

gh extension install https://github.com/nektos/gh-act

Run each workflow:

# Lint all shell scripts
gh act push -W .github/workflows/shellcheck.yml -P ubuntu-24.04=ghcr.io/catthehacker/ubuntu:act-24.04

# Build U-Boot ROM
gh act push -W .github/workflows/build.yml -P ubuntu-24.04=ghcr.io/catthehacker/ubuntu:act-24.04

# Boot smoke test in QEMU (TCG mode, 30 s timeout)
gh act push -W .github/workflows/qemu-smoke-test.yml -P ubuntu-24.04=ghcr.io/catthehacker/ubuntu:act-24.04

Artifact upload steps are automatically skipped when running under act (the ACT env var is set by the runner).

See CONTRIBUTING.md for the Gitflow workflow, signed-commit requirements, and branch naming conventions.

MIT — see LICENSE.