arno/trezor-firmware
1
0
Fork 0
mirror of https://github.com/trezor/trezor-firmware.git synced 2024-11-15 12:08:59 +00:00
Code Issues Releases Wiki Activity

docs: update reproducibility instructions

Browse Source 
fixes #3418
This commit is contained in:
matejcik 2024-10-11 12:53:44 +02:00 committed by matejcik
parent 74655931ce
commit ca1ed7cecc
1 changed files with 74 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/common/reproducible-build.md
View File

@ -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-<model>/firmware/firmware.bin` and `build/core-<model>-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=<your offset here>
# 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
```
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.
```
wget https://data.trezor.io/firmware/1/trezor-1.10.3.bin
# strip legacy header
tail -c +257 trezor-1.10.3.bin > trezor-1.10.3-nolegacyhdr.bin
```