Inside Bitcoin

1### Verify Binaries
2
3#### Preparation
4
5As of Bitcoin Core v22.0, releases are signed by a number of public keys on the basis
6of the [guix.sigs repository](https://github.com/bitcoin-core/guix.sigs/). When
7verifying binary downloads, you (the end user) decide which of these public keys you
8trust and then use that trust model to evaluate the signature on a file that contains
9hashes of the release binaries. The downloaded binaries are then hashed and compared to
10the signed checksum file.
11
12First, you have to figure out which public keys to recognize. Browse the [list of frequent
13builder-keys](https://github.com/bitcoin-core/guix.sigs/tree/main/builder-keys) and
14decide which of these keys you would like to trust. For each key you want to trust, you
15must obtain that key for your local GPG installation.
16
17You can obtain these keys by
18  - through a browser using a key server (e.g. keyserver.ubuntu.com),
19  - manually using the `gpg --keyserver <url> --recv-keys <key>` command, or
20  - you can run the packaged `verify.py --import-keys ...` script to
21    have it automatically retrieve unrecognized keys.
22
23#### Usage
24
25This script attempts to download the checksum file (`SHA256SUMS`) and corresponding
26signature file `SHA256SUMS.asc` from https://bitcoincore.org and https://bitcoin.org.
27
28It first checks if the checksum file is valid based upon a plurality of signatures, and
29then downloads the release files specified in the checksum file, and checks if the
30hashes of the release files are as expected.
31
32If we encounter pubkeys in the signature file that we do not recognize, the script
33can prompt the user as to whether they'd like to download the pubkeys. To enable
34this behavior, use the `--import-keys` flag.
35
36The script returns 0 if everything passes the checks. It returns 1 if either the
37signature check or the hash check doesn't pass. An exit code of >2 indicates an error.
38
39See the `Config` object for various options.
40
41#### Examples
42
43Validate releases with default settings:
44```sh
45./contrib/verify-binaries/verify.py pub 22.0
46./contrib/verify-binaries/verify.py pub 22.0-rc3
47```
48
49Get JSON output and don't prompt for user input (no auto key import):
50
51```sh
52./contrib/verify-binaries/verify.py --json pub 22.0-x86
53./contrib/verify-binaries/verify.py --json pub 23.0-rc5-linux-gnu
54```
55
56Rely only on local GPG state and manually specified keys, while requiring a
57threshold of at least 10 trusted signatures:
58```sh
59./contrib/verify-binaries/verify.py \
60    --trusted-keys 74E2DEF5D77260B98BC19438099BAD163C70FBFA,9D3CC86A72F8494342EA5FD10A41BDC3F4FAFF1C \
61    --min-good-sigs 10 pub 22.0-linux
62```
63
64If you only want to download the binaries for a certain architecture and/or platform, add the corresponding suffix, e.g.:
65
66```sh
67./contrib/verify-binaries/verify.py pub 25.2-x86_64-linux
68./contrib/verify-binaries/verify.py pub 24.1-rc1-darwin
69./contrib/verify-binaries/verify.py pub 27.0-win64-setup.exe
70```
71
72If you do not want to keep the downloaded binaries, specify the cleanup option.
73
74```sh
75./contrib/verify-binaries/verify.py pub --cleanup 22.0
76```
77
78Use the bin subcommand to verify all files listed in a local checksum file
79
80```sh
81./contrib/verify-binaries/verify.py bin SHA256SUMS
82```
83
84Verify only a subset of the files listed in a local checksum file
85
86```sh
87./contrib/verify-binaries/verify.py bin ~/Downloads/SHA256SUMS \
88    ~/Downloads/bitcoin-24.0.1-x86_64-linux-gnu.tar.gz \
89    ~/Downloads/bitcoin-24.0.1-arm-linux-gnueabihf.tar.gz
90```
91