test(core): synthesize dev-key signed firmware images for the bootloader tests [no changelog]
What changed, and why it matters
This commit adds test-only code that creates fake Trezor firmware images signed with the project's public development keys. The images are used only in automated bootloader tests and never contain real firmware code. It does not change any production bootloader, firmware, or signing process, and it does not introduce a vulnerability in shipped devices.
No security action required. As a routine hygiene measure, confirm that development keys and synthesized images are not referenced or bundled in release builds, and that CI does not publish test fixtures as artifacts.
Security signals we found
Use of development signing keys in test fixtures
Synthetic firmware images accepted only by bootloader emulators built with BOOTLOADER_DEVEL=1
No runtime execution of synthesized code; emulator only verifies images
No change to production bootloader, firmware, or release signing infrastructure
Evidence from the diff
The change introduces tests/bootloader_tests/images.py, which synthesizes dev-key signed firmware and (on secmon models) TSEC images for bootloader emulator tests. It reuses checked-in vendor headers signed with development keys, constructs firmware headers via trezorlib firmware header constructs, hashes filler code, and signs with development private keys. The conftest.py change exposes model properties and a make_firmware helper to tests. Documentation is updated to note that the bootloader under test must be built with BOOTLOADER_DEVEL=1. There is no production code change.
Changed components
tests/bootloader_tests/images.pytests/bootloader_tests/conftest.pydocs/tests/bootloader-tests.mdInspect captured patch +215 / −2
### docs/tests/bootloader-tests.md
@@ -49,6 +49,13 @@ Finish with `bootloader.wait_exit()` for a run that ends by itself, or
device. Both return an `ExitRecord` with `kind`, `bootargs` and
`storage_erased`.
+Firmware images come from `bootloader_tests/images.py`: `make_firmware(model,
+vendor=..., version=...)` builds a dev-key signed image with filler code for
+any model, vendor trust level and version. The emulator never runs firmware,
+it only verifies it, so that is enough for the install, upgrade and boot
+flows. The suite therefore needs a bootloader built with the development
+keys (`BOOTLOADER_DEVEL=1`).
+
The bootloader emulator prints its flash layout with `-p` and takes a boot
command from a file with `-B`; `BootArgs.wipe(...)`, `BootArgs.show_rsod(...)`
and friends build such files.
### tests/bootloader_tests/conftest.py
@@ -47,6 +47,7 @@
from .. import ui_tests
from ..emulators import _get_port, delete_profile, get_logfile
from ..ui_tests.common import TestCase
+from .images import make_firmware
LOG = logging.getLogger(__name__)
@@ -87,17 +88,44 @@ def __init__(
self._runs = 0
self._testcase: TestCase | None = None
self._record_dir: Path | None = None
+ self._properties: dict[str, t.Any] | None = None
@property
def recording(self) -> bool:
return bool(self.request.config.getoption("ui"))
+ @property
+ def properties(self) -> dict[str, t.Any]:
+ """What the emulator binary reports with -p: model, flash layout."""
+ if self._properties is None:
+ # a wrapper that is never started: only its properties are read
+ probe = BootloaderEmulator(
+ self.executable, self.profile_dir, port=self.port, logfile=self.logfile
+ )
+ self._properties = probe.properties()
+ return self._properties
+
+ @property
+ def model(self) -> str:
+ """Internal model name of the emulator binary, e.g. "T3T1"."""
+ return self.properties["model"]
+
+ def make_firmware(self, **kwargs: t.Any) -> bytes:
+ """A dev-key signed firmware image the emulator's bootloader accepts."""
+ return make_firmware(
+ self.model,
+ secmon=self.properties["secmon_verification"],
+ code_alignment=self.properties["code_alignment"],
+ **kwargs,
+ )
+
def _prepare_recording(self, emu: BootloaderEmulator) -> Path:
# TestCase needs the model and language, which only a running
# emulator reports; take them from a throwaway properties query.
- model = emu.properties()["model"]
name, group = ui_tests.common._get_test_name_and_group(self.request.node.nodeid)
- self._testcase = TestCase(model=model, group=group, name=name, language="en")
+ self._testcase = TestCase(
+ model=emu.properties()["model"], group=group, name=name, language="en"
+ )
self._testcase.dir.mkdir(exist_ok=True, parents=True)
shutil.rmtree(self._testcase.actual_dir, ignore_errors=True)
self._testcase.actual_dir.mkdir()
### tests/bootloader_tests/images.py
@@ -0,0 +1,178 @@
+# This file is part of the Trezor project.
+#
+# Copyright (C) 2012-2026 SatoshiLabs and contributors
+#
+# This library is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License version 3
+# as published by the Free Software Foundation.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the License along with this library.
+# If not, see <https://www.gnu.org/licenses/lgpl-3.0.html>.
+
+"""Firmware images for bootloader tests.
+
+A bootloader built with the development keys accepts an image signed with
+them. The images built here carry no code that runs: the emulator never
+executes firmware, it only verifies it. That is enough for the install,
+upgrade and boot flows, and lets a test choose the version, vendor and
+model of each image.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from trezorlib import cosi
+from trezorlib._internal import firmware_headers
+from trezorlib.firmware.core import FirmwareHeader, HeaderType
+from trezorlib.firmware.models import Model
+from trezorlib.firmware.secmon import SecmonHeader
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+VENDOR_HEADERS = ROOT / "core" / "embed" / "models"
+
+# IMAGE_HEADER_SIZE and SECMON_HEADER_SIZE in core/embed/sec/image/inc/sec/image.h
+IMAGE_HEADER_SIZE = 1024
+SECMON_HEADER_SIZE = 0x200
+
+# Checked-in vendor headers signed with the development bootloader keys.
+VENDORS = {
+ # full trust: no warning, no click, installs without a confirmation
+ "dev": "vendorheader_dev_DO_NOT_SIGN_signed_dev.bin",
+ # untrusted: red warning screen with a click, confirmation before install
+ "unsafe": "vendorheader_unsafe_signed_dev.bin",
+}
+
+
+def vendor_header(model: str, vendor: str = "dev") -> bytes:
+ return (VENDOR_HEADERS / model / "vendorheader" / VENDORS[vendor]).read_bytes()
+
+
+def _filler(size: int, seed: bytes) -> bytes:
+ """Deterministic bytes that look like code."""
+ data = b""
+ counter = 0
+ while len(data) < size:
+ data += hashlib.sha256(seed + counter.to_bytes(4, "little")).digest()
+ counter += 1
+ return data[:size]
+
+
+def _align(value: int, alignment: int) -> int:
+ return (value + alignment - 1) & ~(alignment - 1)
+
+
+def make_secmon(
+ model: str,
+ *,
+ version: tuple[int, int, int, int] = (1, 0, 0, 0),
+ monotonic: int = 0,
+ code_size: int = 4096 - SECMON_HEADER_SIZE,
+ seed: bytes = b"bootloader-tests-secmon",
+) -> bytes:
+ """Build a dev-key signed secure-monitor image (`TSEC`) for `model`."""
+ if (SECMON_HEADER_SIZE + code_size) % 512 or SECMON_HEADER_SIZE + code_size < 4096:
+ raise ValueError("code_size must make the image a multiple of 512 B, >= 4 KiB")
+
+ code = _filler(code_size, seed)
+ header = SecmonHeader.SUBCON.build(
+ dict(
+ header_len=SECMON_HEADER_SIZE,
+ code_length=code_size,
+ version=version,
+ hw_model=Model[model],
+ hw_revision=0,
+ monotonic=monotonic,
+ reserved_0=b"\0" * 2,
+ hash=b"\0" * 32,
+ reserved_1=b"\0" * 391,
+ sigmask=0,
+ signature=b"\0" * 64,
+ )
+ )
+ assert len(header) == SECMON_HEADER_SIZE
+
+ image = firmware_headers.SecmonImage.parse(header + code)
+ image.header.hash = image.code_hash()
+ privkeys = image.DEV_KEYS
+ signature = cosi.sign_with_privkeys(image.digest(), privkeys, deterministic=True)
+ image.insert_signature(signature, (1 << len(privkeys)) - 1)
+ data = image.build()
+ firmware_headers.SecmonImage.parse(data).verify(dev_keys=True)
+ return data
+
+
+def make_firmware(
+ model: str,
+ *,
+ vendor: str = "dev",
+ version: tuple[int, int, int, int] = (2, 9, 0, 0),
+ fix_version: tuple[int, int, int, int] = (2, 0, 0, 0),
+ monotonic: int = 0,
+ code_size: int = 15 * 1024,
+ seed: bytes = b"bootloader-tests",
+ secmon: bool = False,
+ code_alignment: int = 0x200,
+) -> bytes:
+ """Build a dev-key signed firmware image for `model`.
+
+ `code_size` plus the header must be at least 4 KiB and a multiple of
+ 512 bytes, as the bootloader requires. The code is deterministic for
+ a given `seed`, so two images with the same parameters are identical.
+
+ On models that verify a secure monitor (`secmon=True`) the code starts,
+ at the model's `code_alignment` past the headers, with a signed secmon
+ image, which is what the bootloader looks for there.
+ """
+ if (IMAGE_HEADER_SIZE + code_size) % 512 or IMAGE_HEADER_SIZE + code_size < 4096:
+ raise ValueError("code_size must make the image a multiple of 512 B, >= 4 KiB")
+
+ vendor_data = vendor_header(model, vendor)
+ code = _filler(code_size, seed)
+ if secmon:
+ headers_len = len(vendor_data) + IMAGE_HEADER_SIZE
+ offset = _align(headers_len, code_alignment) - headers_len
+ secmon_data = make_secmon(model, monotonic=monotonic)
+ if offset + len(secmon_data) > code_size:
+ raise ValueError("code_size too small for the secmon image")
+ code = code[:offset] + secmon_data + code[offset + len(secmon_data) :]
+
+ header = FirmwareHeader.SUBCON.build(
+ dict(
+ magic=HeaderType.FIRMWARE,
+ header_len=IMAGE_HEADER_SIZE,
+ # bit 0 set: an image for the current generation of bootloaders
+ expiry=1,
+ code_length=code_size,
+ version=version,
+ fix_version=fix_version,
+ hw_model=Model[model],
+ hw_revision=0,
+ monotonic=monotonic,
+ reserved_0=b"\0" * 2,
+ hashes=[b"\0" * 32] * 16,
+ v1_signatures=[b"\0" * 64] * 3,
+ v1_key_indexes=[0] * 3,
+ reserved_1=b"\0" * 220,
+ sigmask=0,
+ signature=b"\0" * 64,
+ )
+ )
+ assert len(header) == IMAGE_HEADER_SIZE
+
+ image = firmware_headers.VendorFirmware.parse(vendor_data + header + code)
+ image.firmware.header.hashes = image.firmware.code_hashes()
+ privkeys = image.DEV_KEYS
+ signature = cosi.sign_with_privkeys(image.digest(), privkeys, deterministic=True)
+ image.insert_signature(signature, (1 << len(privkeys)) - 1)
+ data = image.build()
+
+ # the bootloader built with the development keys must accept it
+ firmware_headers.VendorFirmware.parse(data).verify(dev_keys=True)
+ return dataWhy this scored 19/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.