-
-
Notifications
You must be signed in to change notification settings - Fork 654
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: update reproducibility instructions #4255
Open
matejcik
wants to merge
1
commit into
main
Choose a base branch
from
matejcik/ts5-repro-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+73
−26
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -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 | ||||||
|
||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. add T3W1? |
||||||
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 | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
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 | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. …. for example T3T1 … ? |
||||||
|
||||||
# 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 | ||||||
``` | ||||||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can we change it to T2T1 and T2B1 for TT and TS3 rev.A?