Skip to content

Feat/secure boot lockdown - #224

Merged
odudex merged 20 commits into
masterfrom
feat/secure-boot-lockdown
Nov 17, 2026
Merged

odudex merged 20 commits into
masterfrom
feat/secure-boot-lockdown

Conversation

@odudex

@odudex odudex commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Adds on-device Secure Boot v2 lockdown and everything a release needs to support it.

What changes

  • Secure Boot from Settings. Settings > Security > Secure Boot locks a device to the three release keys after checking the PIN keys, the key slots, and the signatures of the running app and the bootloader. A --wrap bootloader component keeps the bootloader from enabling secure boot by itself.
  • Anti-rollback is on in sdkconfig.secure at security version 0, which burns nothing. The Secure Boot page shows the eFuse counter once locked.
  • Frozen bootloaders. Freeze 1 is published in kern_secure_boot/bootloaders/ for the four variants (v1/v3 x QIO/DIO), signed by all three keys, with a manifest and a GPG-signed SHA256SUMS. New tooling: just bootloader-stage, scripts/freeze_bootloader.sh, just bootloader-import.
  • Releases are built with sdkconfig.release + sdkconfig.secure and ship the frozen bootloader. sign_release.sh refuses a bootloader that is not signed by all three keys.
  • Web flasher can write a release to a locked device (secure download mode) and no longer rewrites image headers on any device.
  • Chip revision v3.1 and later cannot be locked yet. Once locked they could not be flashed over USB again, so the page refuses them.
  • CI verifies the frozen bootloaders against the public keys and rebuilds them from their freeze commit.
  • Version 0.0.22, with docs in docs/secure-boot.md and docs/security-plan.md.

A sdkconfig.secure bootloader no longer burns secure boot on its first boot (bootloader_components/secure_boot_opt_in). Settings → Security → Secure Boot does it, after checking that the running app is signed by one of the three embedded key digests and the flashed bootloader by all of them. `just sbtest-flash` runs the whole flow on virtual eFuses with test keys.
Secure download mode refuses espefuse, so the post-lock checks use esptool get-security-info and the Secure Boot page, and the manual lockdown burns ENABLE_SECURITY_DOWNLOAD last.
In secure download mode esptool cannot detect the flash size, and with --flash-size keep the ROM refuses writes past 2 MB, which the app reaches.
In secure download mode the ROM takes flash data uncompressed, in 1 KiB blocks, and needs the flash size set; register reads and the stub are unavailable. Image headers are no longer rewritten on any device, so a signed bootloader lands as built.
Their flash is unpowered in download mode and powering it takes register writes, which secure download mode refuses: once locked they could not be flashed over USB again.
@odudex
odudex merged commit ea0a4c3 into master Nov 17, 2026
45 checks passed

This branch was successfully deployed

1 active deployment
github-pages — ea0a4c3f Deployed Nov 17, 2026 by odudex via deploy-site #451
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants