stage0: name backup block as shared scratch space
What changed, and why it matters
This commit is a code cleanup and documentation change in the BitBox02 bootloader. It renames a flash memory region from 'factory randomness backup' to 'shared scratch space' because the same area can be used for temporary data by other bootloader stages. The actual memory layout and runtime behavior are explicitly stated to be unchanged. A new compile-time check is added to ensure the stage1 update area stays within the firmware region.
No security action required. This is a non-functional refactor. Continue normal review and testing.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch refactors naming and adds static assertions in stage0 bootloader code. It replaces BB02_STAGE1_FACTORY_RANDOM_BACKUP_ macros with FLASH_SCRATCH_ and STAGE0_FACTORY_RANDOM_BACKUP_ADDR, updates a flash layout diagram comment, and adds a _Static_assert ensuring BB02_BOOTLOADER_UPGRADE_STAGE1_UPDATE_ADDR + BB02_STAGE1_MAX_LEN <= FLASH_APPDATA_START. The commit message and diff both state that flash layout and runtime behavior are unchanged. No security vulnerability is introduced or fixed by this change.
Changed components
src/bootloader/stage0/stage0.csrc/bootloader/stage0/stage0_flash.hsrc/bootloader_upgrade/bootloader_upgrade.hsrc/flags.htest/unit-test/test_stage0_flash.cInspect captured patch +33 / −38
### src/bootloader/stage0/stage0.c
@@ -350,24 +350,24 @@ static secbool_u32 _factory_random_backup_valid(
uint8_t factory_random_out[BB02_STAGE1_FACTORY_RANDOM_LEN])
{
return stage0_factory_random_backup_valid(
- (const stage0_factory_random_backup_t*)BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR,
+ (const stage0_factory_random_backup_t*)STAGE0_FACTORY_RANDOM_BACKUP_ADDR,
factory_random_out);
}
static void _factory_random_backup_create(
const uint8_t factory_random[BB02_STAGE1_FACTORY_RANDOM_LEN],
const volatile secbool_u32* install_auth)
{
- if (_flash_block_erased(BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR) != sectrue_u32) {
- _flash_erase_block(BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR, install_auth);
+ if (_flash_block_erased(FLASH_SCRATCH_START) != sectrue_u32) {
+ _flash_erase_block(FLASH_SCRATCH_START, install_auth);
}
uint32_t page[STAGE0_FLASH_PAGE_WORDS];
stage0_factory_random_backup_make_data_page(page, factory_random);
- _flash_write_page(BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR, page, install_auth);
+ _flash_write_page(STAGE0_FACTORY_RANDOM_BACKUP_ADDR, page, install_auth);
stage0_factory_random_backup_make_commit_page(page);
- _flash_write_page(BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR, page, install_auth);
+ _flash_write_page(STAGE0_FACTORY_RANDOM_BACKUP_ADDR, page, install_auth);
uint8_t verify[BB02_STAGE1_FACTORY_RANDOM_LEN];
if (_factory_random_backup_valid(verify) != sectrue_u32 ||
@@ -491,7 +491,7 @@ static void _install_stage1(
uint32_t page[STAGE0_FLASH_PAGE_WORDS];
_nvm_disable_bootprot(install_auth);
- _flash_unlock_region(BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR, install_auth);
+ _flash_unlock_region(FLASH_SCRATCH_START, install_auth);
_factory_random_load_or_create_backup(factory_random, installed_header_ok, install_auth);
_flash_unlock_region(0x00000000U, install_auth);
_flash_unlock_region(0x00008000U, install_auth);
### src/bootloader/stage0/stage0_flash.h
@@ -22,6 +22,7 @@
#define STAGE0_STAGE1_FACTORY_RANDOM_BLOCK_ADDR \
(BB02_STAGE1_FACTORY_RANDOM_ADDR & ~(STAGE0_FLASH_BLOCK_SIZE_BYTES - 1U))
+#define STAGE0_FACTORY_RANDOM_BACKUP_ADDR FLASH_SCRATCH_START
#define STAGE0_FACTORY_RANDOM_BACKUP_MAGIC (0x30524642U) // "BFR0" in little-endian flash order.
#define STAGE0_FACTORY_RANDOM_BACKUP_FORMAT_VERSION (1U)
#define STAGE0_FACTORY_RANDOM_BACKUP_COMMIT_ERASED UINT32_MAX
@@ -49,21 +50,23 @@ _Static_assert(
STAGE0_STAGE1_BLOCK_ADDR % STAGE0_FLASH_BLOCK_SIZE_BYTES == 0,
"stage1 block is unaligned");
_Static_assert(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR % STAGE0_FLASH_PAGE_SIZE_BYTES == 0,
+ STAGE0_FACTORY_RANDOM_BACKUP_ADDR % STAGE0_FLASH_PAGE_SIZE_BYTES == 0,
"factory randomness backup page is unaligned");
_Static_assert(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR % STAGE0_FLASH_BLOCK_SIZE_BYTES == 0,
- "factory randomness backup block is unaligned");
+ FLASH_SCRATCH_START % STAGE0_FLASH_BLOCK_SIZE_BYTES == 0,
+ "scratch space is unaligned");
_Static_assert(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_LEN == STAGE0_FLASH_BLOCK_SIZE_BYTES,
- "factory randomness backup must occupy one erase block");
+ FLASH_SCRATCH_LEN == STAGE0_FLASH_BLOCK_SIZE_BYTES,
+ "scratch space must occupy one erase block");
_Static_assert(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR >= FLASH_BOOTDATA_START + FLASH_BOOTDATA_LEN,
- "factory randomness backup overlaps bootdata");
+ FLASH_SCRATCH_START >= FLASH_BOOTDATA_START + FLASH_BOOTDATA_LEN,
+ "scratch space overlaps bootdata");
_Static_assert(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR + BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_LEN <=
- FLASH_SMARTEEPROM_START,
- "factory randomness backup overlaps SmartEEPROM");
+ FLASH_SCRATCH_START + FLASH_SCRATCH_LEN <= FLASH_SMARTEEPROM_START,
+ "scratch space overlaps SmartEEPROM");
+_Static_assert(
+ BB02_BOOTLOADER_UPGRADE_STAGE1_UPDATE_ADDR + BB02_STAGE1_MAX_LEN <= FLASH_APPDATA_START,
+ "stage1 update slot overlaps appdata");
_Static_assert(
sizeof(stage0_factory_random_backup_t) <= STAGE0_FLASH_PAGE_SIZE_BYTES,
"factory randomness backup record does not fit in one page");
@@ -87,7 +90,7 @@ static secbool_u32 __attribute__((noinline, noclone)) stage0_flash_page_addr_ok(
if (addr >= STAGE0_STAGE1_PAGE_ADDR && addr <= STAGE0_STAGE1_FACTORY_RANDOM_PAGE_ADDR) {
return sectrue_u32;
}
- if (addr == BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR) {
+ if (addr == STAGE0_FACTORY_RANDOM_BACKUP_ADDR) {
return sectrue_u32;
}
return secfalse_u32;
@@ -104,7 +107,7 @@ static secbool_u32 __attribute__((noinline, noclone)) stage0_flash_block_addr_ok
if (addr >= STAGE0_STAGE1_BLOCK_ADDR && addr <= STAGE0_STAGE1_FACTORY_RANDOM_BLOCK_ADDR) {
return sectrue_u32;
}
- if (addr == BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR) {
+ if (addr == FLASH_SCRATCH_START) {
return sectrue_u32;
}
return secfalse_u32;
### src/bootloader_upgrade/bootloader_upgrade.h
@@ -19,10 +19,6 @@
#define BB02_STAGE1_FACTORY_RANDOM_ADDR (0x0000DFE0U)
#define BB02_STAGE1_FACTORY_RANDOM_LEN (32U)
-#define BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR (0x000FA000U)
-#define BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_LEN (0x00002000U)
-#define BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR
-
#define BB02_BOOTLOADER_UPGRADE_STAGE1_UPDATE_ADDR (0x000DB000U)
#define BB02_STAGE1_HEADER_MAGIC (0x31534242U) // "BBS1" in little-endian flash order.
@@ -64,10 +60,6 @@ typedef struct __attribute__((__packed__)) {
#define BB02_STAGE1_HEADER_SIGNED_LEN ((uint32_t)offsetof(bb02_stage1_header_t, signatures))
_Static_assert(sizeof(bb02_stage1_header_t) == 1024, "header ABI changed");
-_Static_assert(
- BB02_BOOTLOADER_UPGRADE_STAGE1_UPDATE_ADDR + BB02_STAGE1_MAX_LEN <=
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR,
- "factory randomness backup overlaps stage1 update slot");
_Static_assert(
BB02_STAGE1_HEADER_SIGNED_LEN + BB02_STAGE1_HEADER_SIGNATURES_LEN == BB02_STAGE1_HEADER_LEN,
"header ABI changed");
### src/flags.h
@@ -21,9 +21,8 @@
// | (0x04000) |
// | |
// +-------------+ 0xFC000
-// | Factory |
-// | randomness |
-// | backup |
+// | Scratch |
+// | space |
// | (0x02000) |
// +-------------+ 0xFA000
// | Boot data |
@@ -60,7 +59,7 @@
#define FLASH_END (2048 * FLASH_PAGE_SIZE)
// The firmware and its data areas end at page 2000. The remaining flash is reserved
-// for the factory randomness backup and SmartEEPROM.
+// for scratch space and SmartEEPROM.
#define FLASH_USER_END (2000 * FLASH_PAGE_SIZE)
// Erase granularity is 1 block (8kB; 16 pages)
@@ -103,6 +102,11 @@
#define CHUNK_SIZE (FLASH_ERASE_MIN_LEN) // 8kB; minimum erase granularity
+// Shared temporary storage for stage1 and firmware. Contents may not survive a reboot:
+// stage0 currently overwrites this space with a factory randomness backup when updating stage1.
+#define FLASH_SCRATCH_START (0x000FA000U)
+#define FLASH_SCRATCH_LEN (0x00002000U)
+
// SmartEEPROM reserved memory start
#define FLASH_SMARTEEPROM_START (FLASH_END - SMARTEEPROM_RESERVED_FLASH_PAGES * FLASH_PAGE_SIZE)
### test/unit-test/test_stage0_flash.c
@@ -19,8 +19,7 @@ static void test_stage0_flash_page_addr_ok(void** state)
sectrue_u32);
assert_int_equal(
stage0_flash_page_addr_ok(STAGE0_STAGE1_FACTORY_RANDOM_PAGE_ADDR), sectrue_u32);
- assert_int_equal(
- stage0_flash_page_addr_ok(BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR), sectrue_u32);
+ assert_int_equal(stage0_flash_page_addr_ok(STAGE0_FACTORY_RANDOM_BACKUP_ADDR), sectrue_u32);
assert_int_equal(stage0_flash_page_addr_ok(STAGE0_STAGE1_PAGE_ADDR - 1u), secfalse_u32);
assert_int_equal(
@@ -32,8 +31,7 @@ static void test_stage0_flash_page_addr_ok(void** state)
STAGE0_STAGE1_FACTORY_RANDOM_PAGE_ADDR + STAGE0_FLASH_PAGE_SIZE_BYTES),
secfalse_u32);
assert_int_equal(
- stage0_flash_page_addr_ok(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_ADDR + STAGE0_FLASH_PAGE_SIZE_BYTES),
+ stage0_flash_page_addr_ok(STAGE0_FACTORY_RANDOM_BACKUP_ADDR + STAGE0_FLASH_PAGE_SIZE_BYTES),
secfalse_u32);
for (uint32_t addr = FLASH_APP_START; addr < FLASH_APP_START + FLASH_APP_LEN;
addr += STAGE0_FLASH_PAGE_SIZE_BYTES) {
@@ -57,8 +55,7 @@ static void test_stage0_flash_block_addr_ok(void** state)
sectrue_u32);
assert_int_equal(
stage0_flash_block_addr_ok(STAGE0_STAGE1_FACTORY_RANDOM_BLOCK_ADDR), sectrue_u32);
- assert_int_equal(
- stage0_flash_block_addr_ok(BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR), sectrue_u32);
+ assert_int_equal(stage0_flash_block_addr_ok(FLASH_SCRATCH_START), sectrue_u32);
assert_int_equal(stage0_flash_block_addr_ok(STAGE0_STAGE1_BLOCK_ADDR - 1u), secfalse_u32);
assert_int_equal(
@@ -70,8 +67,7 @@ static void test_stage0_flash_block_addr_ok(void** state)
STAGE0_STAGE1_FACTORY_RANDOM_BLOCK_ADDR + STAGE0_FLASH_BLOCK_SIZE_BYTES),
secfalse_u32);
assert_int_equal(
- stage0_flash_block_addr_ok(
- BB02_STAGE1_FACTORY_RANDOM_BACKUP_BLOCK_ADDR + STAGE0_FLASH_BLOCK_SIZE_BYTES),
+ stage0_flash_block_addr_ok(FLASH_SCRATCH_START + STAGE0_FLASH_BLOCK_SIZE_BYTES),
secfalse_u32);
for (uint32_t addr = FLASH_APP_START; addr < FLASH_APP_START + FLASH_APP_LEN;
addr += STAGE0_FLASH_BLOCK_SIZE_BYTES) {Why this scored 15/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.