Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
aa39a5c
feat(security): enable Secure Boot from Settings
odudex Nov 11, 2026
9052d59
docs(security): drop flash encryption, describe the Settings lockdown…
odudex Nov 11, 2026
ea018eb
fix(security): keep the idle watchdog subscribed during secure boot c…
odudex Nov 13, 2026
36aa066
fix(ui): label the button "Restart" after lockdown and firmware update
odudex Nov 13, 2026
e8e95b4
feat(build): add build-secure recipe for a lockable release image
odudex Nov 13, 2026
0d2e3db
feat(security): turn on anti-rollback in the secure overlay
odudex Nov 13, 2026
fd80901
feat(security): show the eFuse security version on the Secure Boot page
odudex Nov 15, 2026
fffe0cb
docs(security): check a locked device without espefuse
odudex Nov 15, 2026
9e050da
feat(build): stage, sign and import frozen bootloaders
odudex Nov 15, 2026
0ca5fda
feat(build): write and GPG-sign SHA256SUMS in the bootloader freeze
odudex Nov 15, 2026
65eff93
docs(secure-boot): describe frozen bootloader 1 in the key README
odudex Nov 15, 2026
8525243
feat(build): ship the frozen bootloaders in releases
odudex Nov 15, 2026
8f28dbe
chore: bump version to 0.0.22
odudex Nov 16, 2026
b940f9f
chore(secure-boot): publish frozen bootloader 1
odudex Nov 16, 2026
5f4a8e5
docs(security): give the flash size when flashing a locked device
odudex Nov 16, 2026
7cc9b2c
feat(flasher): flash devices that have secure boot enabled
odudex Nov 17, 2026
f4237d1
fix(security): refuse secure boot on chip revision v3.1 and later
odudex Nov 17, 2026
5f8e136
docs(security): describe flashing a locked device and the v3.1 limit
odudex Nov 17, 2026
db83fbe
ci: check the frozen bootloaders against the keys and their freeze co…
odudex Nov 17, 2026
ea0a4c3
fix(security): format secure boot key digests without snprintf
odudex Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/test-all-builds.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,28 @@ jobs:
if-no-files-found: error
retention-days: 30

# The frozen bootloaders (kern_secure_boot/bootloaders/) against the public
# keys, against a rebuild from their freeze commit, and against this commit.
bootloaders:
runs-on: ubuntu-latest
container: espressif/idf:v6.1.1
name: frozen bootloaders
steps:
- name: Checkout repo
uses: actions/checkout@v4
with:
submodules: 'recursive'
# --reproduce checks the freeze commits out of this history
fetch-depth: 0
- name: Rebuild the frozen bootloaders from their freeze commits
run: |
git config --global --add safe.directory '*'
. $IDF_PATH/export.sh
./scripts/check_bootloaders.sh --reproduce
- name: Report bootloader drift at this commit
run: |
. $IDF_PATH/export.sh
./scripts/check_bootloaders.sh --drift

deploy-site:
needs: [build]
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ build_wave_35/
build_pbkdf2_*/
build_scanprof_*/
build_release_*/
build_sbtest_*/
build_secure_*/
build_wave_4b/
build_wave_43/
build_wave_5/
Expand Down
57 changes: 56 additions & 1 deletion .justfile
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ flash board="wave_4b": (_check_board board)
idf.py -B build_{{board}} -D SDKCONFIG=build_{{board}}/sdkconfig -D "SDKCONFIG_DEFAULTS=$(just _defaults {{board}})" flash

# The sdkconfig is regenerated every time so overlay edits always land.
# Release image (sdkconfig.release overlay) in build_release_<board>/, as scripts/release.sh builds it
# Release log and panic settings (sdkconfig.release overlay) with a plain bootloader, in build_release_<board>/.
# scripts/release.sh builds with build-secure.
build-release board="wave_4b": (_check_board board)
#!/usr/bin/env sh
set -e
Expand All @@ -46,6 +47,58 @@ flash-release board="wave_4b": (build-release board)
command -v idf.py >/dev/null || . $IDF_PATH/export.sh
idf.py -B build_release_{{board}} -D SDKCONFIG=build_release_{{board}}/sdkconfig flash

# Lockable release image (sdkconfig.release + sdkconfig.secure, published key digests) in build_secure_<board>/.
# The build signs with dev_signing_key.pem; the files to sign with the release keys are
# kern-unsigned.bin (key 0) and bootloader/bootloader-unsigned.bin (keys 0, 1 and 2).
build-secure board="wave_4b" target="build": (_check_board board)
#!/usr/bin/env sh
set -e
command -v idf.py >/dev/null || . $IDF_PATH/export.sh
rm -f build_secure_{{board}}/sdkconfig
idf.py -B build_secure_{{board}} -D SDKCONFIG=build_secure_{{board}}/sdkconfig -D "SDKCONFIG_DEFAULTS=$(just _defaults {{board}});sdkconfig.release;sdkconfig.secure" {{target}}

# Build every board's secure bootloader and stage one unsigned image per variant in release/bootloader-<N>/
# for scripts/freeze_bootloader.sh, which signs them with the three release keys on the air-gapped PC.
bootloader-stage:
./scripts/bootloader_stage.sh

# Verify a signed release/bootloader-<N>/ folder and copy it into kern_secure_boot/bootloaders/
bootloader-import dir:
./scripts/bootloader_import.sh {{dir}}

# Secure boot dry run: a sdkconfig.secure build with virtual eFuses (sdkconfig.sbtest), so the
# Settings lockdown burns a RAM copy that is gone after the restart. Signed with test keys:
# dev_signing_key.pem signs the app, it and two throwaway keys sign the bootloader, and their
# digests replace the release ones. Run on a board that already has a PIN.
sbtest-build board="wave_4b": (_check_board board)
#!/usr/bin/env sh
set -e
command -v idf.py >/dev/null || . $IDF_PATH/export.sh
dir=build_sbtest_{{board}}
mkdir -p $dir/keys $dir/digests
[ -f dev_signing_key.pem ] || python -m espsecure generate-signing-key --version 2 --scheme rsa3072 dev_signing_key.pem
cp dev_signing_key.pem $dir/keys/key0.pem
for n in 1 2; do
[ -f $dir/keys/key$n.pem ] || python -m espsecure generate-signing-key --version 2 --scheme rsa3072 $dir/keys/key$n.pem
done
for n in 0 1 2; do
python -m espsecure digest-sbv2-public-key --keyfile $dir/keys/key$n.pem -o $dir/digests/kern-sb-digest$n.bin
done
rm -f $dir/sdkconfig
idf.py -B $dir -D SDKCONFIG=$dir/sdkconfig -D "SDKCONFIG_DEFAULTS=$(just _defaults {{board}});sdkconfig.secure;sdkconfig.sbtest" -D KERN_SB_DIGEST_DIR=$PWD/$dir/digests build
python -m espsecure sign-data --version 2 --keyfile $dir/keys/key1.pem --append-signatures -o $dir/bootloader-2sig.bin $dir/bootloader/bootloader.bin
python -m espsecure sign-data --version 2 --keyfile $dir/keys/key2.pem --append-signatures -o $dir/bootloader-sbtest.bin $dir/bootloader-2sig.bin

# idf.py leaves the bootloader out when secure boot is configured, so esptool writes it.
# `just flash <board>` puts the normal firmware back.
sbtest-flash board="wave_4b": (sbtest-build board)
#!/usr/bin/env sh
set -e
command -v idf.py >/dev/null || . $IDF_PATH/export.sh
dir=build_sbtest_{{board}}
idf.py -B $dir -D SDKCONFIG=$dir/sdkconfig flash
python -m esptool --chip esp32p4 write-flash 0x2000 $dir/bootloader-sbtest.bin

monitor board="wave_4b": (_check_board board)
#!/usr/bin/env sh
command -v idf.py >/dev/null || . $IDF_PATH/export.sh
Expand Down Expand Up @@ -87,6 +140,8 @@ clean:
rm -fRd build_pbkdf2_*
rm -fRd build_scanprof_*
rm -fRd build_release_*
rm -fRd build_sbtest_*
rm -fRd build_secure_*
rm -f sdkconfig
rm -fRd compile_commands.json
rm -fRd .cache/
Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,22 @@
# Changelog

## [0.0.22] - 2026-11-17

### Added
- Secure Boot can be enabled from Settings > Security > Secure Boot. It locks the device to firmware signed by the three release keys: unsigned firmware no longer starts from SD card or USB, JTAG is turned off and the ROM goes to secure download mode. The page shows the three key digests to compare with the published ones and offers the step only when a PIN is set, the running firmware is signed by a release key and the bootloader by all three. It is permanent. Not offered on chip revision v3.1 and later yet: once locked, those could not be flashed over USB again
- Releases ship a frozen bootloader, signed once by all three keys and published in `kern_secure_boot/bootloaders/` (freeze 1, tag `bootloader-1`). A device needs one USB install of this release to get it; devices updated over SD keep their old bootloader and the Secure Boot page says so
- Anti-rollback: the bootloader refuses firmware whose security version is below the device's eFuse counter. This release is security version 0, which burns nothing; the Secure Boot page shows the counter once secure boot is on

### Changed
- Release images log at WARN level and reboot silently on a panic instead of printing registers and stack memory
- The dialog after a firmware update has a Restart button instead of announcing the restart above an OK button
- The web flasher writes a release to a device with secure boot enabled, and no longer rewrites image headers on any device
- Built on ESP-IDF 6.1.1
- Updated libwally (1.6.1), cUR, k_quirc and bip138

### Fixed
- Simulator builds on macOS: SDL2 is found through its CMake package and libwally's secret wipe uses memset_s

## [0.0.21] - 2026-11-05

### Added
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ just clean # Wipe all build_<board> dirs + sdkconfig

ESP32-P4 chip revision v3.x needs its own image: ESP-IDF builds for either v0.x/v1.x or v3.x silicon, never both. Append `_v3` to any board (`just build wave_43_v3`, `just flash wave_43_v3`) to build with the `sdkconfig.rev3` overlay into `build_<board>_v3/`. The web flasher reads the chip revision on connect and picks the matching build.

Published releases are built with `just build-release <board>` (what `scripts/release.sh` runs for every board), which adds the `sdkconfig.release` overlay into `build_release_<board>/`: WARN-level logs, a silent reboot on panic instead of a register and stack dump, and silent assertions. Use it to reproduce a release image; `just build` is the development configuration.
Published releases are built by `scripts/release.sh`, which runs `just build-secure <board>` for every board, into `build_secure_<board>/`. That adds two overlays: `sdkconfig.release` (WARN-level logs, a silent reboot on panic instead of a register and stack dump, silent assertions) and `sdkconfig.secure` (a bootloader that verifies the app, the Secure Boot menu, anti-rollback). The release zip carries the frozen bootloader from `kern_secure_boot/bootloaders/`, not the one that build produces. `just build-release <board>` applies only the release overlay and keeps a plain bootloader, to reproduce release logging and panic behaviour on a development board; `just build` is the development configuration.

Or using `idf.py` directly:

Expand Down
17 changes: 17 additions & 0 deletions bootloader_components/secure_boot_opt_in/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# A stock CONFIG_SECURE_BOOT bootloader burns secure boot on its first boot,
# from the digests of its own signature blocks. Kern burns it from the app
# instead, once the user opts in (main/core/secure_boot.c), so this component
# keeps the bootloader from touching eFuses until SECURE_BOOT_EN is set.
set(srcs "")
if(CONFIG_SECURE_BOOT_V2_ENABLED)
list(APPEND srcs "secure_boot_opt_in.c")
endif()

idf_component_register(SRCS ${srcs}
PRIV_REQUIRES bootloader_support efuse log)

if(CONFIG_SECURE_BOOT_V2_ENABLED)
target_link_libraries(${COMPONENT_LIB} INTERFACE
"-Wl,--wrap=esp_secure_boot_v2_permanently_enable"
"-u __wrap_esp_secure_boot_v2_permanently_enable")
endif()
17 changes: 17 additions & 0 deletions bootloader_components/secure_boot_opt_in/secure_boot_opt_in.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
#include "esp_log.h"
#include "esp_secure_boot.h"

esp_err_t __real_esp_secure_boot_v2_permanently_enable(
const esp_image_metadata_t *image_data);

/* Called on every boot before the app loads. The app has already been
* verified against its own keys (or the burned digests once they exist); only
* the first-boot burn is skipped. */
esp_err_t __wrap_esp_secure_boot_v2_permanently_enable(
const esp_image_metadata_t *image_data) {
if (!esp_secure_boot_enabled()) {
ESP_LOGI("secure_boot", "Off until enabled in Settings");
return ESP_OK;
}
return __real_esp_secure_boot_v2_permanently_enable(image_data);
}
Loading
Loading