bootloader: version stage1 and firmware sighashes
What changed, and why it matters
This commit changes how the BitBox02 bootloader and firmware compute the cryptographic hash used to verify signed updates. It adds a version byte (0x01) to the data that gets hashed before signatures are checked, starting with bootloader v1.2.3 and firmware version 57. The goal is to make old and new verification schemes distinguishable, so an older, less secure bootloader cannot be tricked into accepting a newer firmware image using the old hash format, and vice versa. The change is defensive: it does not fix a known remote exploit, but it hardens the upgrade chain against potential downgrade or cross-version signature-confusion attacks. Existing signing keys and the overall image format stay the same.
Treat this as a hardening change rather than an emergency fix. Verify that bundled stage1 binaries are rebuilt and re-signed with the new monotonic version and prefixed prehash before shipping, as the commit message notes this is still required. Confirm that release tooling and client libraries are deployed together so users can verify displayed firmware hashes correctly for v1.2.3+ bootloaders and v57+ firmware. Review the upgrade path to ensure old stage0 bootloaders can still install the intermediate bootloader that understands the new scheme.
Security signals we found
Adds a domain-separation/version prefix to cryptographic prehashes for firmware and stage1 bootloader signatures.
Bumps stage1 monotonic version from 1 to 2 and ties the new prehash to that version.
Ties the new firmware prehash to monotonic firmware version 57 while keeping versions <= 56 on the prior scheme.
Updates both device C code and host-side Python tooling to remain consistent with the new scheme.
Adds unit tests that explicitly reject legacy (unprefixed) stage1 digests and test SHA failure propagation.
CHANGELOG frames the change as 'Verify firmware/stage1 with a versioned signature prehash'.
Evidence from the diff
The patch introduces a versioned signature prehash scheme. For stage1 (the intermediate bootloader) the monotonic version is bumped to 2 and the signed digest becomes sha256(0x01 || signed_header || body). For firmware, starting at monotonic version 57, the digest becomes sha256(0x01 || product_id_le16 || firmware_version_le32 || padded_firmware). The device bootloader (src/bootloader/bootloader.c), stage0 stage1 verifier (src/bootloader/stage0/stage1_sigcheck.c), release tooling (releases/describe_signed_firmware.py, scripts/signed_firmware.py, scripts/bootloader_update.py), and the Python client library (py/bitbox02/bitbox02/bitbox02/bootloader.py) are updated to compute and expect the new scheme. Backward compatibility is preserved: build-time verification still accepts the legacy stage1 prehash for version < 2, and old firmware hashes are retained in tooling. Tests are updated to cover the new prefix and to assert that legacy digests are rejected.
Changed components
src/bootloader/bootloader.csrc/bootloader/stage0/stage1_sigcheck.csrc/bootloader/image_header.json.inpy/bitbox02/bitbox02/bitbox02/bootloader.pyreleases/describe_signed_firmware.pyscripts/signed_firmware.pyscripts/bootloader_update.pytest/scripts/test_load_firmware.pytest/unit-test/test_stage0_sigcheck.cInspect captured patch +151 / −30
### CHANGELOG.md
@@ -231,6 +231,9 @@ recorded separately.
## Bootloader
### Unreleased
+
+### v1.2.3
+- Verify firmware with a versioned signature prehash.
- Speed up the empty firmware check when entering bootloader mode.
- Speed up firmware upgrades over USB.
- Hold the screen reset pin low until bootloader is ready to initalize it.
@@ -272,6 +275,8 @@ recorded separately.
### v3
- Move the factory randomness backup out of the firmware area to preserve firmware integrity
during stage1 updates.
+- Verify stage1 with a versioned signature prehash, allowing stage0 to be upgraded before the bundled
+ stage1 is installed.
### v2
- Hold the screen reset pin low until bootloader is ready to initalize it.
### py/bitbox02/bitbox02/bitbox02/bootloader.py
@@ -28,6 +28,7 @@
NUM_ROOT_KEYS = 3
NUM_SIGNING_KEYS = 3
BOOTLOADER_NEW_SIGHASH_VERSION = semver.VersionInfo(1, 2, 0)
+BOOTLOADER_VERSIONED_SIGHASH_VERSION = semver.VersionInfo(1, 2, 3)
MAX_FIRMWARE_SIZE = 884736 # 928kB - 64kB
CHUNK_SIZE = 4096
@@ -274,6 +275,10 @@ def erase(self) -> None:
def _empty_firmware_hash(self, firmware_v: int) -> bytes:
empty_firmware = struct.pack("<I", firmware_v) + b"\xff" * MAX_FIRMWARE_SIZE
+ if self.version >= BOOTLOADER_VERSIONED_SIGHASH_VERSION:
+ return hashlib.sha256(
+ b"\x01" + struct.pack("<H", self.product_id) + empty_firmware
+ ).digest()
if self.version >= BOOTLOADER_NEW_SIGHASH_VERSION:
return hashlib.sha256(struct.pack("<H", self.product_id) + empty_firmware).digest()
return hashlib.sha256(hashlib.sha256(empty_firmware).digest()).digest()
### releases/README.md
@@ -63,8 +63,15 @@ contains the unsigned binary with the following script (please install the [BitB
## Verify the hash as shown by the BitBox02 at startup
When installing new firmware on the BitBox02, an option can be turned on to display the firmware
-hash on the device screen when the BitBox02 is plugged in. The hash shown is a hash of the firmware
-and the firmware version: `sha256d(<version><padded firmware>)`.
+hash on the device screen when the BitBox02 is plugged in. The displayed hash depends on the
+monotonic firmware version. All versions below are encoded as four little-endian bytes, product
+IDs as two little-endian bytes, and firmware is padded with `0xff` to 884736 bytes:
+
+- Through version 50: `sha256d(version || padded_firmware)`.
+- Versions 51 through 56: `sha256(product_id || version || padded_firmware)`.
+- From version 57: `sha256(0x01 || product_id || version || padded_firmware)`.
+
+The `0x01` prefix is one byte. The signature verifier hashes the displayed hash once more.
It can be verified with the same tool as above. For example:
### releases/describe_signed_firmware.py
@@ -29,7 +29,8 @@
SIGNING_PUBKEYS_DATA_LEN = VERSION_LEN + NUM_SIGNING_KEYS * 64 + NUM_ROOT_KEYS * 64
FIRMWARE_DATA_LEN = VERSION_LEN + NUM_SIGNING_KEYS * 64
SIGDATA_LEN = SIGNING_PUBKEYS_DATA_LEN + FIRMWARE_DATA_LEN
-NEW_SIGHASH_VERSION_CUTOFF = 50
+NEW_SIGHASH_VERSION_CUTOFF = 51
+VERSIONED_SIGHASH_VERSION_CUTOFF = 57
def main() -> int:
@@ -81,7 +82,13 @@ def main() -> int:
monotonic_version = struct.unpack("<I", version)[0]
print("The monotonic firmware version is:", monotonic_version)
print("The firmware sighash as verified/shown by the bootloader is:")
- if monotonic_version >= NEW_SIGHASH_VERSION_CUTOFF:
+ if monotonic_version >= VERSIONED_SIGHASH_VERSION_CUTOFF:
+ print(
+ hashlib.sha256(
+ b"\x01" + struct.pack("<H", product_id) + version + firmware_padded
+ ).hexdigest()
+ )
+ elif monotonic_version >= NEW_SIGHASH_VERSION_CUTOFF:
print(hashlib.sha256(struct.pack("<H", product_id) + version + firmware_padded).hexdigest())
else:
print(hashlib.sha256(hashlib.sha256(version + firmware_padded).digest()).hexdigest())
### scripts/bootloader_update.py
@@ -9,7 +9,6 @@
import ecdsa
-
STAGE1_HEADER_MAGIC = 0x31534242
STAGE0_DESCRIPTOR_MAGIC = 0x30534242
STAGE1_HEADER_FORMAT_VERSION = 1
@@ -144,6 +143,8 @@ def _stage1_signed_digest(image: bytes) -> bytes:
raise RuntimeError("stage1 image does not contain a vector table")
signed_header_len = header["header_len"] - STAGE1_HEADER_SIGNATURES_LEN
hasher = hashlib.sha256()
+ if header["monotonic_version"] >= 2:
+ hasher.update(b"\x01")
hasher.update(image[:signed_header_len])
hasher.update(image[header["header_len"] :])
return hasher.digest()
### scripts/signed_firmware.py
@@ -9,7 +9,6 @@
import struct
from dataclasses import dataclass
-
# A signed firmware file consists of MAGIC_LEN bytes of a product marker, followed by SIGDATA_LEN
# bytes of signature data, and ending with the firmware bytes from the reproducible build.
MAGIC_LEN = 4
@@ -88,14 +87,25 @@ def unsigned_sha256(signed_firmware: SignedFirmware) -> bytes:
def sighash(signed_firmware: SignedFirmware) -> bytes:
- """Return the current firmware hash verified and shown by the bootloader."""
+ """Return the firmware hash verified and shown by its target bootloader."""
firmware_padded = signed_firmware.firmware + b"\xff" * (
MAX_FIRMWARE_SIZE - len(signed_firmware.firmware)
)
- preimage = (
- struct.pack("<H", signed_firmware.product.product_id)
- + signed_firmware.version
- + firmware_padded
- )
+ version = int.from_bytes(signed_firmware.version, "little")
+ if version >= 57:
+ preimage = (
+ b"\x01"
+ + struct.pack("<H", signed_firmware.product.product_id)
+ + signed_firmware.version
+ + firmware_padded
+ )
+ elif version >= 51:
+ preimage = (
+ struct.pack("<H", signed_firmware.product.product_id)
+ + signed_firmware.version
+ + firmware_padded
+ )
+ else:
+ preimage = hashlib.sha256(signed_firmware.version + firmware_padded).digest()
return hashlib.sha256(preimage).digest()
### src/bootloader/bootloader.c
@@ -547,12 +547,14 @@ static secbool_u32 _pubkeys_verified(const boot_data_t* data)
return secfalse_u32;
}
-// Computes sha256(product_id_le16 | firmware_version | firmware).
+// Computes sha256(0x01 | product_id_le16 | firmware_version | firmware).
// pukcc_ecdsa_verify() hashes this prehash once more, so signatures cover:
-// sha256(sha256(product_id_le16 | firmware_version | firmware)).
+// sha256(sha256(0x01 | product_id_le16 | firmware_version | firmware)).
static void _firmware_hash(const boot_data_t* data, uint8_t* hash_out)
{
+ const uint8_t sighash_version = 0x01;
sha_sync_sha256_start(&HASH_ALGORITHM_0, &_pukcc_sha256_context, false);
+ sha_sync_sha256_update(&HASH_ALGORITHM_0, &sighash_version, sizeof(sighash_version));
_hash_product_id();
sha_sync_sha256_update(
&HASH_ALGORITHM_0,
@@ -646,7 +648,7 @@ static uint8_t _write_chunk(uint32_t address, const uint8_t* data)
/*
* input: firmware version | i signatures of the double hash of
- * [product id | version | firmware app]
+ * [0x01 | product id | version | firmware app]
*/
static uint8_t _set_firmware_data(boot_data_t* data, const uint8_t* input)
{
### src/bootloader/image_header.json.in
@@ -2,6 +2,6 @@
"magic": "BBS1",
"flags": @header_flags@,
"product_id": @product_id@,
- "monotonic_version": 1,
+ "monotonic_version": 2,
"marketing_version": "@BOOTLOADER_VERSION_FULL@"
}
### src/bootloader/stage0/stage1_sigcheck.c
@@ -78,6 +78,7 @@ static int32_t _canonical_signed_digest(
{
memset(digest, STAGE1_SIGCHECK_INVALID_DIGEST_BYTE, BB02_STAGE1_SIGNED_DIGEST_LEN);
+ const uint8_t sighash_version = 0x01;
const uint32_t expected_magic = BB02_STAGE1_HEADER_MAGIC;
const uint32_t flags = header->flags;
const uint16_t header_version = header->header_version;
@@ -90,6 +91,7 @@ static int32_t _canonical_signed_digest(
const uint8_t* image_body = ((const uint8_t*)header) + header_len;
int32_t status = sha_sync_sha256_start(&HASH_ALGORITHM_0, &_sha_context, false);
+ status |= sha_sync_sha256_update(&HASH_ALGORITHM_0, &sighash_version, sizeof(sighash_version));
status |= sha_sync_sha256_update(
&HASH_ALGORITHM_0, (const uint8_t*)&expected_magic, sizeof(expected_magic));
status |= sha_sync_sha256_update(&HASH_ALGORITHM_0, (const uint8_t*)&flags, sizeof(flags));
### test/scripts/test_load_firmware.py
@@ -3,15 +3,16 @@
"""Tests for py/load_firmware.py and its bootloader helpers."""
import contextlib
+import hashlib
import importlib.util
import io
+import struct
import sys
import tempfile
import unittest
from pathlib import Path
from unittest import mock
-
REPOSITORY_ROOT = Path(__file__).resolve().parents[2]
PYTHON_PACKAGE_ROOT = REPOSITORY_ROOT / "py" / "bitbox02"
sys.path.insert(0, str(PYTHON_PACKAGE_ROOT))
@@ -27,7 +28,6 @@
import bitbox02 as bitbox02_package # noqa: E402
from bitbox02.bitbox02 import bootloader as bootloader_module # noqa: E402
-
MAGIC = bootloader_module.SIGDATA_MAGIC_BITBOX02_MULTI
OTHER_MAGIC = bootloader_module.SIGDATA_MAGIC_BITBOX02_BTCONLY
SIGDATA = bytes(bootloader_module.SIGDATA_LEN)
@@ -127,6 +127,46 @@ def test_flash_sigdata(self) -> None:
bootloader.flash_sigdata(SIGDATA)
self.assertEqual(transport.queries, [b"s" + SIGDATA])
+ def test_empty_firmware_hash(self) -> None:
+ for product_id, product_string in enumerate(
+ (
+ bootloader_module.BB02MULTI_BOOTLOADER,
+ bootloader_module.BB02BTC_BOOTLOADER,
+ bootloader_module.BITBOX02PLUS_MULTI_BOOTLOADER,
+ bootloader_module.BITBOX02PLUS_BTC_BOOTLOADER,
+ ),
+ 1,
+ ):
+ for version, scheme in (
+ ("v1.1.0", "legacy"),
+ ("v1.2.0", "product"),
+ ("v1.2.2", "product"),
+ ("v1.2.3", "versioned"),
+ ("v1.2.3-rc1", "versioned"),
+ ("v1.2.3+git.123", "versioned"),
+ ):
+ for firmware_version in (56, 57):
+ with self.subTest(
+ product=product_id, version=version, firmware=firmware_version
+ ):
+ info = device_info(version)
+ info["product_string"] = product_string
+ bootloader = bootloader_module.Bootloader(DummyTransport(), info)
+ preimage = (
+ struct.pack("<I", firmware_version)
+ + b"\xff" * bootloader_module.MAX_FIRMWARE_SIZE
+ )
+ if scheme == "legacy":
+ expected = hashlib.sha256(hashlib.sha256(preimage).digest()).digest()
+ else:
+ preimage = struct.pack("<H", product_id) + preimage
+ if scheme == "versioned":
+ preimage = b"\x01" + preimage
+ expected = hashlib.sha256(preimage).digest()
+ self.assertEqual(
+ bootloader._empty_firmware_hash(firmware_version), expected
+ )
+
def test_flash_sigdata_rejects_wrong_length(self) -> None:
bootloader = bootloader_module.Bootloader(DummyTransport(), device_info())
with self.assertRaises(ValueError):
### test/unit-test/test_stage0_sigcheck.c
@@ -18,7 +18,7 @@
#define EXTRA_HEADER_LEN (BB02_STAGE1_HEADER_ALIGNMENT)
#define IMAGE_BUF_LEN (BB02_STAGE1_HEADER_LEN + EXTRA_HEADER_LEN + BODY_LEN)
#define INVALID_DIGEST_BYTE (0xa5u)
-#define SHA_UPDATE_COUNT (6u)
+#define SHA_UPDATE_COUNT (7u)
#define SIGNED_HEADER_TAIL_OFFSET ((uint32_t)offsetof(bb02_stage1_header_t, header_len))
struct sha_sync_descriptor HASH_ALGORITHM_0;
@@ -58,7 +58,7 @@ MONOTONIC_VERSION = 7
MARKETING_VERSION = b"dev"
MARKETING_VERSION_FIELD_LEN = 37
-def compute_digest(header_len):
+def compute_digest(header_len, prefix=b"\x01"):
image_len = header_len + BODY_LEN
marketing_version_size = len(MARKETING_VERSION)
marketing_version_field = MARKETING_VERSION + bytes(
@@ -89,20 +89,26 @@ def compute_digest(header_len):
body = bytes((0x40 + i) & 0xff for i in range(BODY_LEN))
signed_payload += body
assert len(signed_payload) + len(signatures) == image_len
- return hashlib.sha256(signed_payload).hexdigest()
+ return hashlib.sha256(prefix + signed_payload).hexdigest()
print(compute_digest(header_len=1024))
print(compute_digest(header_len=2048))
+print(compute_digest(header_len=1024, prefix=b""))
PY
*/
static const uint8_t _digest_fixture_default[BB02_STAGE1_SIGNED_DIGEST_LEN] = {
- 0xd4, 0xde, 0xc4, 0x9d, 0xab, 0x5f, 0x53, 0x7a, 0x3b, 0xfd, 0x3b, 0x29, 0xff, 0x34, 0xf3, 0x37,
- 0xdf, 0x27, 0x68, 0xc3, 0x0e, 0x65, 0x15, 0x5d, 0x6d, 0xca, 0x6b, 0xb8, 0x41, 0xc6, 0xf9, 0x4f,
+ 0xfc, 0xd3, 0x70, 0xeb, 0x53, 0xe1, 0x29, 0x71, 0xba, 0xa3, 0x3e, 0xd6, 0xd7, 0xea, 0x38, 0x3b,
+ 0xc9, 0x3e, 0x1d, 0x7f, 0x41, 0x56, 0xd9, 0x0f, 0x99, 0x6b, 0x0f, 0x54, 0x20, 0x72, 0x61, 0x82,
};
static const uint8_t _digest_fixture_extended_reserved[BB02_STAGE1_SIGNED_DIGEST_LEN] = {
- 0x39, 0xf9, 0xc2, 0x93, 0x12, 0x55, 0xb5, 0x0a, 0x1f, 0x86, 0xc0, 0xd7, 0x5c, 0xd7, 0x7e, 0x6a,
- 0xde, 0xda, 0x6b, 0x3f, 0x4b, 0x22, 0x05, 0xdb, 0x01, 0xda, 0x3c, 0x91, 0x53, 0x8e, 0xf4, 0x55,
+ 0x11, 0x50, 0xa5, 0x86, 0xb7, 0xa6, 0xe9, 0x21, 0xf0, 0x7e, 0x96, 0xcc, 0x63, 0x4c, 0xc0, 0x0f,
+ 0x3b, 0xde, 0x52, 0xd8, 0x1b, 0x61, 0x89, 0x6d, 0x82, 0xaf, 0xb7, 0xd9, 0x37, 0x2e, 0x24, 0x18,
+};
+
+static const uint8_t _digest_fixture_legacy[BB02_STAGE1_SIGNED_DIGEST_LEN] = {
+ 0xd4, 0xde, 0xc4, 0x9d, 0xab, 0x5f, 0x53, 0x7a, 0x3b, 0xfd, 0x3b, 0x29, 0xff, 0x34, 0xf3, 0x37,
+ 0xdf, 0x27, 0x68, 0xc3, 0x0e, 0x65, 0x15, 0x5d, 0x6d, 0xca, 0x6b, 0xb8, 0x41, 0xc6, 0xf9, 0x4f,
};
static bb02_stage1_header_t* _header_ptr(void)
@@ -152,10 +158,12 @@ static void _compute_digest(
{
void* ctx = rust_sha256_new();
assert_non_null(ctx);
+ const uint8_t sighash_version = 0x01;
const uint32_t expected_magic = BB02_STAGE1_HEADER_MAGIC;
const uint32_t flags = header->flags;
const uint16_t header_version = header->header_version;
const uint16_t expected_product_id = BB02_STAGE1_PRODUCT_ID;
+ rust_sha256_update(ctx, &sighash_version, sizeof(sighash_version));
rust_sha256_update(ctx, (const uint8_t*)&expected_magic, sizeof(expected_magic));
rust_sha256_update(ctx, (const uint8_t*)&flags, sizeof(flags));
rust_sha256_update(ctx, (const uint8_t*)&header_version, sizeof(header_version));
@@ -238,33 +246,38 @@ int32_t __wrap_sha_sync_sha256_update(
switch (_sha_update_count) {
case 0: {
- const uint32_t expected = BB02_STAGE1_HEADER_MAGIC;
+ const uint8_t expected = 0x01;
assert_int_equal(length, sizeof(expected));
assert_memory_equal(input, &expected, sizeof(expected));
} break;
case 1: {
- const uint32_t expected = _header.flags;
+ const uint32_t expected = BB02_STAGE1_HEADER_MAGIC;
assert_int_equal(length, sizeof(expected));
assert_memory_equal(input, &expected, sizeof(expected));
} break;
case 2: {
- const uint16_t expected = _header.header_version;
+ const uint32_t expected = _header.flags;
assert_int_equal(length, sizeof(expected));
assert_memory_equal(input, &expected, sizeof(expected));
} break;
case 3: {
+ const uint16_t expected = _header.header_version;
+ assert_int_equal(length, sizeof(expected));
+ assert_memory_equal(input, &expected, sizeof(expected));
+ } break;
+ case 4: {
const uint16_t expected = BB02_STAGE1_PRODUCT_ID;
assert_int_equal(length, sizeof(expected));
assert_memory_equal(input, &expected, sizeof(expected));
} break;
- case 4:
+ case 5:
assert_ptr_equal(input, ((const uint8_t*)&_header) + SIGNED_HEADER_TAIL_OFFSET);
assert_int_equal(
length,
_header.header_len - BB02_STAGE1_HEADER_SIGNATURES_LEN - SIGNED_HEADER_TAIL_OFFSET);
break;
default:
- assert_int_equal(_sha_update_count, 5u);
+ assert_int_equal(_sha_update_count, 6u);
assert_ptr_equal(input, _body());
assert_int_equal(length, BODY_LEN);
break;
@@ -402,6 +415,33 @@ static void test_stage1_sigcheck_image_ok_matches_extended_reserved_digest_fixtu
_assert_call_order();
}
+static void test_stage1_sigcheck_image_ok_rejects_legacy_digest(void** state)
+{
+ (void)state;
+ _reset_image();
+ _fill_reserved_fixture();
+ _fill_signature_fixture();
+ _reset_script(0x07, 0x07);
+ _use_digest_fixture(_digest_fixture_default);
+ memcpy(_accepted_digest, _digest_fixture_legacy, sizeof(_accepted_digest));
+
+ assert_int_equal(stage1_sigcheck_image_ok(&_header, _pubkeys), secfalse_u32);
+ _assert_sha_calls();
+ _assert_call_order();
+}
+
+static void test_stage1_sigcheck_image_ok_rejects_prefix_hash_failure(void** state)
+{
+ (void)state;
+ _reset_image();
+ _reset_script(0x07, 0x07);
+ _sha_update_status[0] = -1;
+
+ assert_int_equal(stage1_sigcheck_image_ok(&_header, _pubkeys), secfalse_u32);
+ _assert_sha_calls();
+ _assert_call_order();
+}
+
static void test_stage1_sigcheck_image_ok_rejects_invalid_image_len(void** state)
{
(void)state;
@@ -627,6 +667,8 @@ int main(void)
const struct CMUnitTest tests[] = {
cmocka_unit_test(test_stage1_sigcheck_image_ok_matches_default_digest_fixture),
cmocka_unit_test(test_stage1_sigcheck_image_ok_matches_extended_reserved_digest_fixture),
+ cmocka_unit_test(test_stage1_sigcheck_image_ok_rejects_legacy_digest),
+ cmocka_unit_test(test_stage1_sigcheck_image_ok_rejects_prefix_hash_failure),
cmocka_unit_test(test_stage1_sigcheck_image_ok_rejects_invalid_image_len),
cmocka_unit_test(test_stage1_sigcheck_image_ok_rejects_invalid_header_len),
cmocka_unit_test(test_stage1_sigcheck_image_ok_rejects_invalid_fixed_header_fields),Why this scored 47/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.