Merge pull request #736 from Foundation-Devices/sft-8554-bootloader-setup-checks
What changed, and why it matters
This commit hardens how Passport's bootloader handles a sensitive factory key during initial device setup. Previously, the code trusted that erasing the key from SPI flash succeeded without checking, and it left a temporary copy of the key sitting in memory after use. The patch now verifies the key is actually gone from flash, retries the erase if needed, and wipes the temporary memory copy immediately. It also adds automated tests that simulate failures to make sure the key is never left behind.
Treat this as a security hardening fix and include it in the next bootloader/firmware release. Run the new host tests regularly in CI. Consider whether older devices that already went through factory setup could have left the SCV key in SPI flash due to the unverified erase, and evaluate whether any additional remediation (e.g., a one-time secure-wipe or attestation check) is warranted for already-shipped units.
Security signals we found
Sensitive key material (supply-chain validation key) is now explicitly zeroed from stack memory after use
SPI flash erase of the SCV key is now verified by read-back instead of assumed successful
Bootloader setup now aborts if the SCV key cannot be confirmed erased from SPI flash
Retry loop added for SPI erase/read failures to tolerate transient hardware errors
New host-side C unit tests exercise failure paths including failed reads, failed erases, and unconfirmed clears
Evidence from the diff
The change modifies the Passport bootloader’s secure-element setup flow. spi_clear_scv_key() now performs up to three erase/read-back attempts and confirms the SCV key sector is blank (all 0xFF) before returning success. se_setup_config() now uses memzero() to clear the stack copy of supply_chain_key on both success and failure paths, and it aborts setup with a new error code if the SPI flash clear cannot be confirmed. A host-side pytest harness compiles the relevant C snippets with stubs to verify retry logic, failure handling, and memory wiping behavior.
Changed components
ports/stm32/boards/Passport/bootloader/se-atecc608a.cports/stm32/boards/Passport/common/spiflash.cports/stm32/boards/Passport/bootloader/Makefileports/stm32/boards/Passport/common/se.cports/stm32/boards/Passport/modules/tests/test_bootloader_host.pyInspect captured patch +245 / −5
### ports/stm32/boards/Passport/bootloader/Makefile
@@ -42,6 +42,10 @@ VPATH += $(PASSPORT_PATH)/common
VPATH += $(PASSPORT_PATH)/common/micro-ecc
VPATH += $(CURDIR)/images/$(shell echo $(SCREEN_MODE) | tr A-Z a-z)
+# memzero() from the firmware's crypto library, for wiping secrets.
+TREZOR_CRYPTO_PATH = $(MPY_TOP)/extmod/trezor-firmware/crypto
+vpath memzero.c $(TREZOR_CRYPTO_PATH)
+
# Basename of all targets
TARGET_NAME = bootloader-$(SCREEN_MODE)-$(COLORWAY)
TARGETDIR = arm
@@ -113,6 +117,7 @@ SOURCES += sha256.c
SOURCES += spiflash.c
SOURCES += uECC.c
SOURCES += utils.c
+SOURCES += memzero.c
SOURCES += system_stm32h7xx.c
@@ -216,7 +221,8 @@ CC_SYMBOLS = -mcpu=cortex-m7
INC_PATHS = $(LIB_PATH)/stm32lib/CMSIS/STM32H7xx/Include \
$(LIB_PATH)/stm32lib/STM32H7xx_HAL_Driver/Inc \
$(LIB_PATH)/cmsis/inc \
- $(TOP)/boards/Passport
+ $(TOP)/boards/Passport \
+ $(TREZOR_CRYPTO_PATH)
CFLAGS += $(foreach INC,$(INC_PATHS),-I$(INC))
### ports/stm32/boards/Passport/bootloader/se-atecc608a.c
@@ -14,6 +14,7 @@
#include "spiflash.h"
#include "flash.h"
#include "hash.h"
+#include "memzero.h"
#include "pprng.h"
#include "se-atecc608a.h"
#include "se-config.h"
@@ -204,6 +205,7 @@ int se_setup_config(rom_secrets_t* secrets) {
// It was written there by the factory test bootloader
uint8_t supply_chain_key[32] = {0xff,};
if (!spi_get_scv_key(&supply_chain_key[0])) {
+ memzero(supply_chain_key, sizeof(supply_chain_key));
return -11;
}
@@ -220,11 +222,14 @@ int se_setup_config(rom_secrets_t* secrets) {
}
int rc = se_write_data_slot(kn, supply_chain_key, 32, false);
+ memzero(supply_chain_key, sizeof(supply_chain_key));
- // Always erase the supply chain key, even if the write failed
- spi_clear_scv_key();
+ // Always erase the supply chain key, even if the write failed,
+ // and don't finish setup until it is confirmed gone from SPI flash.
+ bool is_cleared = spi_clear_scv_key();
if (rc) return -7;
+ if (!is_cleared) return -12;
} break;
case KEYNUM_seed:
### ports/stm32/boards/Passport/common/se.c
@@ -15,6 +15,7 @@
#include "stm32h7xx_hal_uart_ex.h"
#include "delay.h"
+#include "memzero.h"
#include "pprng.h"
#include "se-config.h"
#include "se.h"
### ports/stm32/boards/Passport/common/spiflash.c
@@ -307,9 +307,30 @@ bool spi_set_scv_key(uint8_t* buf) {
return false;
}
+#define SPI_SCV_KEY_CLEAR_ATTEMPTS (3)
+
+// Erases the sector holding the SCV key and reads the key back to confirm it
+// is blank. Returns false if it still isn't after a few attempts.
bool spi_clear_scv_key() {
- if (spi_sector_erase(SPI_ADDR_SCV_KEY) == HAL_OK) {
- return true;
+ for (int attempt = 0; attempt < SPI_SCV_KEY_CLEAR_ATTEMPTS; attempt++) {
+ uint8_t check[SPI_SCV_KEY_SIZE];
+
+ if (spi_sector_erase(SPI_ADDR_SCV_KEY) != HAL_OK) {
+ continue;
+ }
+ if (spi_read(SPI_ADDR_SCV_KEY, sizeof(check), check) != HAL_OK) {
+ continue;
+ }
+
+ bool is_blank = true;
+ for (size_t i = 0; i < sizeof(check); i++) {
+ if (check[i] != 0xFF) {
+ is_blank = false;
+ }
+ }
+ if (is_blank) {
+ return true;
+ }
}
return false;
### ports/stm32/boards/Passport/modules/tests/test_bootloader_host.py
@@ -0,0 +1,207 @@
+# SPDX-FileCopyrightText: 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Host tests: pytest ports/stm32/boards/Passport/modules/tests/test_bootloader_host.py."""
+
+import os
+from pathlib import Path
+import shlex
+import subprocess
+
+BOARD = Path(__file__).resolve().parents[2]
+
+HAL_STUB = '''
+#include <assert.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+typedef enum { HAL_OK = 0, HAL_ERROR = 1 } HAL_StatusTypeDef;
+'''
+
+
+def build_and_run(tmp_path, name, source):
+ harness = tmp_path / (name + '.c')
+ harness.write_text(source)
+ binary = tmp_path / name
+ subprocess.run(shlex.split(os.environ.get('CC', 'cc')) +
+ ['-std=gnu99', '-Wall', '-Werror', str(harness), '-o', str(binary)], check=True)
+ subprocess.run([str(binary)], check=True)
+
+
+def test_scv_key_clear_is_confirmed_c(tmp_path):
+ source = (BOARD / 'common/spiflash.c').read_text()
+ key_helpers = source[source.index('#define SPI_ADDR_SCV_KEY'):]
+ build_and_run(tmp_path, 'scv_clear', HAL_STUB + '''
+static uint8_t flash[4096];
+static int erase_errors, erases_ignored, read_errors, erase_calls;
+
+HAL_StatusTypeDef spi_sector_erase(uint32_t addr) {
+ assert(addr == 0);
+ erase_calls++;
+ if (erase_errors > 0) {
+ erase_errors--;
+ return HAL_ERROR;
+ }
+ if (erases_ignored > 0) {
+ erases_ignored--;
+ return HAL_OK;
+ }
+ memset(flash, 0xFF, sizeof(flash));
+ return HAL_OK;
+}
+
+HAL_StatusTypeDef spi_read(uint32_t addr, int len, uint8_t* buf) {
+ if (read_errors > 0) {
+ read_errors--;
+ return HAL_ERROR;
+ }
+ memcpy(buf, flash + addr, len);
+ return HAL_OK;
+}
+
+HAL_StatusTypeDef spi_write(uint32_t addr, int len, const uint8_t* buf) {
+ memcpy(flash + addr, buf, len);
+ return HAL_OK;
+}
+''' + key_helpers + '''
+static void stage_key(void) {
+ uint8_t key[32];
+ memset(flash, 0xFF, sizeof(flash));
+ memset(key, 0xA5, sizeof(key));
+ assert(spi_set_scv_key(key));
+ erase_errors = erases_ignored = read_errors = erase_calls = 0;
+}
+
+int main(void) {
+ stage_key();
+ assert(spi_clear_scv_key());
+ assert(erase_calls == 1);
+
+ // An erase or read-back that fails is retried.
+ stage_key();
+ erase_errors = 2;
+ assert(spi_clear_scv_key());
+ assert(erase_calls == 3);
+
+ stage_key();
+ read_errors = 1;
+ assert(spi_clear_scv_key());
+
+ stage_key();
+ erases_ignored = 2;
+ assert(spi_clear_scv_key());
+
+ // A key that can't be confirmed gone is reported, not assumed.
+ stage_key();
+ erases_ignored = 3;
+ assert(!spi_clear_scv_key());
+
+ stage_key();
+ erase_errors = 3;
+ assert(!spi_clear_scv_key());
+
+ stage_key();
+ read_errors = 3;
+ assert(!spi_clear_scv_key());
+ return 0;
+}
+''')
+
+
+def test_scv_key_provisioning_c(tmp_path):
+ source = (BOARD / 'bootloader/se-atecc608a.c').read_text()
+ start = source.index('case KEYNUM_supply_chain: {')
+ case = source[start:source.index('} break;', start) + len('} break;')]
+ build_and_run(tmp_path, 'scv_provision', HAL_STUB + '''
+#define KEYNUM_supply_chain 7
+
+static uint8_t staged[32];
+static bool read_ok, write_ok, clear_ok;
+static int writes, clears, wipes;
+static uint8_t written[32];
+static void* write_buf;
+static void* wiped_buf;
+static size_t wiped_len;
+static bool wiped_after_write;
+
+HAL_StatusTypeDef spi_setup(void) {
+ return HAL_OK;
+}
+
+bool spi_get_scv_key(uint8_t* buf) {
+ memcpy(buf, staged, sizeof(staged));
+ return read_ok;
+}
+
+bool spi_clear_scv_key(void) {
+ clears++;
+ return clear_ok;
+}
+
+int se_write_data_slot(int slot_num, uint8_t* data, int len, bool lock_it) {
+ assert(slot_num == KEYNUM_supply_chain && len == 32 && !lock_it);
+ writes++;
+ write_buf = data;
+ memcpy(written, data, sizeof(written));
+ return write_ok ? 0 : 1;
+}
+
+void memzero(void* const pnt, const size_t len) {
+ memset(pnt, 0, len);
+ wipes++;
+ wiped_buf = pnt;
+ wiped_len = len;
+ wiped_after_write = writes > 0;
+}
+
+static int provision(int kn) {
+ switch (kn) {
+''' + case + '''
+ }
+ return 0;
+}
+
+static void reset(uint8_t fill) {
+ memset(staged, fill, sizeof(staged));
+ read_ok = write_ok = clear_ok = true;
+ writes = clears = wipes = 0;
+ wiped_buf = write_buf = NULL;
+ wiped_len = 0;
+ wiped_after_write = false;
+}
+
+int main(void) {
+ // The key goes to the SE, its stack copy is wiped, and SPI is cleared.
+ reset(0x5A);
+ assert(provision(KEYNUM_supply_chain) == 0);
+ assert(writes == 1 && memcmp(written, staged, sizeof(staged)) == 0);
+ assert(wipes == 1 && wiped_buf == write_buf && wiped_len == 32 && wiped_after_write);
+ assert(clears == 1);
+
+ // Setup does not finish while the key may still be in SPI flash.
+ reset(0x5A);
+ clear_ok = false;
+ assert(provision(KEYNUM_supply_chain) != 0);
+ assert(writes == 1 && wipes == 1 && clears == 1);
+
+ // A failed SE write still wipes and clears the key.
+ reset(0x5A);
+ write_ok = false;
+ assert(provision(KEYNUM_supply_chain) != 0);
+ assert(wipes == 1 && clears == 1);
+
+ // A failed read wipes whatever was read, and nothing is written.
+ reset(0x5A);
+ read_ok = false;
+ assert(provision(KEYNUM_supply_chain) != 0);
+ assert(writes == 0 && wipes == 1 && wiped_len == 32);
+
+ // No key staged: nothing to write or clear.
+ reset(0xFF);
+ assert(provision(KEYNUM_supply_chain) != 0);
+ assert(writes == 0 && clears == 0);
+ return 0;
+}
+''')Why this scored 60/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.