From d5f2ea48feebeb4c8f7abc98392f64f23b8d9dba Mon Sep 17 00:00:00 2001 From: matejcik Date: Fri, 11 Oct 2024 12:53:44 +0200 Subject: [PATCH] docs: update reproducibility instructions fixes #3418 --- docs/common/reproducible-build.md | 99 +++++++++++++++++++++++-------- 1 file changed, 73 insertions(+), 26 deletions(-) diff --git a/docs/common/reproducible-build.md b/docs/common/reproducible-build.md index 9b489f4441f..8db6b09d5d4 100644 --- a/docs/common/reproducible-build.md +++ b/docs/common/reproducible-build.md @@ -1,64 +1,111 @@ # Reproducible build -We want to invite the wider community to participate in the verification of -the firmware built by SatoshiLabs. With reasonable effort you should be able to -build the firmware and verify that it's identical to the official firmware. +We want to invite the wider community to participate in the verification of the firmware +built by Trezor Company. With reasonable effort you should be able to build the firmware +and verify that it's identical to the official firmware. -Trezor Firmware uses [Nix](https://nixos.org/), [Poetry](https://python-poetry.org/) -and [Cargo](https://doc.rust-lang.org/cargo/) to make the build environment -deterministic. We also provide a Docker-based script so that the build can be -performed with a single command on usual x86 Linux system. +Trezor Firmware uses [Nix](https://nixos.org/), [Poetry](https://python-poetry.org/) and +[Cargo](https://doc.rust-lang.org/cargo/) to make the build environment deterministic. +We also provide a Docker-based script so that the build can be performed with a single +command on usual x86 Linux system. ## Building First you need to determine which *version tag* you want to build: * for Trezor One it is `legacy/vX.Y.Z`, e.g. `legacy/v1.10.3`, -* for Trezor Model T it is `core/vX.Y.Z`, e.g. `core/v2.4.2`. +* for newer models, it is `core/vX.Y.Z`, e.g. `core/v2.4.2`. -Assuming you want to build `core/v2.4.2`: +Assuming you want to build `core/v2.8.3`: 1. install [Docker](https://www.docker.com/) 2. clone the firmware repository: `git clone https://github.com/trezor/trezor-firmware.git` 3. go into the firmware directory: `cd trezor-firmware` -4. checkout the version tag: `git checkout core/v2.4.2` -5. run: `bash build-docker.sh core/v2.4.2` +4. checkout the version tag: `git checkout core/v2.8.3` +5. run: `bash build-docker.sh core/v2.8.3` After the build finishes the firmware images are located in: * `build/legacy/firmware/firmware.bin` and `build/legacy-bitcoinonly/firmware/firmware.bin` for Trezor One, -* `build/core/firmware/firmware.bin` and `build/core-bitcoinonly/firmware/firmware.bin` for Trezor Model T. +* `build/core-/firmware/firmware.bin` and `build/core--bitcoinonly/firmware/firmware.bin` for later models. + +### Model identifiers + +You can speed up the build process by adding options to the script: + +* `--skip-core` if you are only building for Trezor One, +* `--skip-legacy --models=A,B,C` to only build for specific model(s) which are not Trezor One. + +The following models are supported: + +* **`T`** - Trezor Model T +* **`R`** - Trezor Safe 3 rev.A +* **`T3B1`** - Trezor Safe 3 rev.B +* **`T3T1`** - Trezor Safe 5 + +Examples: + +```sh +bash build-docker.sh --skip-core legacy/v1.10.3 # build only for Trezor One +bash build-docker.sh --skip-legacy --models=T3T1 core/v2.8.3 # build only for Trezor Safe 5 +``` ## Verifying The result won't be bit-by-bit identical with the official images because the -official images are signed while local builds aren't. Official release of -Trezor One firmware also has additional 256-byte legacy header that needs to be -removed first. +official images are signed while local builds aren't. -### Trezor T +### Trezor T and the Safe family -The [firmware header](../hardware/model-t/boot.md#firmware-header) contains 65 -bytes of signature data at offset 0x15bf. After overwriting it by zeros in -official release the binaries should become identical. +You can use `trezorctl` to download the official firmware image for your device: +```sh +trezorctl firmware download --model t3t1 --version 2.8.3 ``` -wget https://data.trezor.io/firmware/2/trezor-2.4.2.bin +Or locate the firmware image in the [Trezor Data repository](https://github.com/trezor/data/tree/master/firmware). + +The firmware binary starts with a [vendor header](../hardware/model-t/boot.md#vendor-header) +whose size is: + +* Model T: 4608 bytes +* Safe 3: 512 bytes +* Safe 5: 1024 bytes + +The vendor header is followed by a [firmware header](../hardware/model-t/boot.md#firmware-header) +that contains a 65-byte signature at offset `0x3bf` (959 in decimal). + +You will need to calculate the right offset for the signature based on the model: + +* Model T: 4608 + 959 = 5567 +* Safe 3: 512 + 959 = 1471 +* Safe 5: 1024 + 959 = 1983 + +Zero out the signature data to obtain an image identical to the one built locally: + +```sh +OFFSET= # the following line removes 65 bytes of signature data from the official firmware -dd if=/dev/zero of=trezor-2.4.2.bin bs=1 seek=5567 count=65 conv=notrunc +dd if=/dev/zero of=trezor-t3t1-2.8.3.bin bs=1 seek=$OFFSET count=65 conv=notrunc # the following two lines print out the hashes of the firmwares -sha256sum trezor-2.4.2.bin -sha256sum build/core/firmware/firmware.bin +sha256sum trezor-t3t1-2.8.3.bin +sha256sum build/core-T3T1/firmware/firmware.bin ``` ### Trezor One -Official T1 firmware starts with [256-byte legacy header](../hardware/model-one/firmware-format.md) -used for compatibility with old bootloaders. Locally built firmware doesn't have this header. +You can use `trezorctl` to download the official firmware image for your device: +```sh +trezorctl firmware download --model 1 --version 1.10.3 ``` -wget https://data.trezor.io/firmware/1/trezor-1.10.3.bin +Or locate the firmware image in the [Trezor Data repository](https://github.com/trezor/data/tree/master/firmware). + +Official Trezor One firmware older than 1.12 starts with [256-byte legacy +header](../hardware/model-one/firmware-format.md) used for compatibility with old +bootloaders. Locally built firmware doesn't have this header. + +``` # strip legacy header tail -c +257 trezor-1.10.3.bin > trezor-1.10.3-nolegacyhdr.bin ```