contrib: verifybinaries: allow multisig verification

This commit adds the functionality necessary to transition from
doing binary verification on the basis of a single signature to
requiring a minimum threshold of trusted signatures.

A signature can appear as "good" from GPG output, but it may not come
from an identity the user trusts. We call these "good, untrusted"
signatures.

We report bad signatures but do not necessarily fail in their presence,
since a bad signature might coexist with enough good, trusted signatures
to fulfill our criteria.

If "--import-keys" is enabled, we will prompt the user to
optionally try to retrieve unknown keys. Marking them as trusted locally
is a WIP, but keys which are retrieved successfully and appear on the
builder-keys list will immediately count as being useful towards
fulfilling the threshold.

Logging is improved and an option to output JSON that summarizes the
whole sum signature and binary verification processes has been added.

Co-authored-by: Russ Yanofsky <[email protected]>
Co-authored-by: willcl-ark <[email protected]>

Author: 3 people

contrib/verifybinaries/README.md

@@ -1,30 +1,77 @@
 ### Verify Binaries
 
-#### Usage:
+#### Preparation
 
-This script attempts to download the signature file `SHA256SUMS.asc` from https://bitcoin.org.
+As of Bitcoin Core v22.0, releases are signed by a number of public keys on the basis
+of the [guix.sigs repository](https://github.com/bitcoin-core/guix.sigs/). When
+verifying binary downloads, you (the end user) decide which of these public keys you
+trust and then use that trust model to evaluate the signature on a file that contains
+hashes of the release binaries. The downloaded binaries are then hashed and compared to
+the signed checksum file.
 
-It first checks if the signature passes, and then downloads the files specified in the file, and checks if the hashes of these files match those that are specified in the signature file.
+First, you have to figure out which public keys to recognize. Browse the [list of frequent
+builder-keys](https://github.com/bitcoin-core/guix.sigs/tree/main/builder-keys) and
+decide which of these keys you would like to trust. For each key you want to trust, you
+must obtain that key for your local GPG installation.
 
-The script returns 0 if everything passes the checks. It returns 1 if either the signature check or the hash check doesn't pass. If an error occurs the return value is 2.
+You can obtain these keys by
+  - through a browser using a key server (e.g. keyserver.ubuntu.com),
+  - manually using the `gpg --keyserver <url> --recv-keys <key>` command, or
+  - you can run the packaged `verifybinaries.py ... --import-keys` script to
+    have it automatically retrieve unrecognized keys.
 
+#### Usage
 
+This script attempts to download the checksum file (`SHA256SUMS`) and corresponding
+signature file `SHA256SUMS.asc` from https://bitcoincore.org and https://bitcoin.org.
+
+It first checks if the checksum file is valid based upon a plurality of signatures, and
+then downloads the release files specified in the checksum file, and checks if the
+hashes of the release files are as expected.
+
+If we encounter pubkeys in the signature file that we do not recognize, the script
+can prompt the user as to whether they'd like to download the pubkeys. To enable
+this behavior, use the `--import-keys` flag.
+
+The script returns 0 if everything passes the checks. It returns 1 if either the
+signature check or the hash check doesn't pass. An exit code of >2 indicates an error.
+
+See the `Config` object for various options.
+
+#### Examples
+
+Validate releases with default settings:
+```sh
+./contrib/verifybinaries/verify.py 22.0
+./contrib/verifybinaries/verify.py 22.0-rc2
+./contrib/verifybinaries/verify.py bitcoin-core-23.0
+./contrib/verifybinaries/verify.py bitcoin-core-23.0-rc1
+```
+
+Get JSON output and don't prompt for user input (no auto key import):
+
+```sh
+./contrib/verifybinaries/verify.py 22.0-x86 --json
+```
+
+Don't trust builder-keys by default, and rely only on local GPG state and manually
+specified keys, while requiring a threshold of at least 10 trusted signatures:
 ```sh
-./verify.py bitcoin-core-0.11.2
-./verify.py bitcoin-core-0.12.0
-./verify.py bitcoin-core-0.13.0-rc3
+./contrib/verifybinaries/verify.py 22.0-x86 \
+    --no-trust-builder-keys \
+    --trusted-keys 74E2DEF5D77260B98BC19438099BAD163C70FBFA,9D3CC86A72F8494342EA5FD10A41BDC3F4FAFF1C \
+    --min-trusted-sigs 10
 ```
 
 If you only want to download the binaries of certain platform, add the corresponding suffix, e.g.:
 
 ```sh
-./verify.py bitcoin-core-0.11.2-osx
-./verify.py 0.12.0-linux
-./verify.py bitcoin-core-0.13.0-rc3-win64
+./contrib/verifybinaries/verify.py bitcoin-core-22.0-osx
+./contrib/verifybinaries/verify.py bitcoin-core-22.0-rc2-win64
 ```
 
 If you do not want to keep the downloaded binaries, specify anything as the second parameter.
 
 ```sh
-./verify.py bitcoin-core-0.13.0 delete
+./contrib/verifybinaries/verify.py bitcoin-core-22.0 delete
 ```

contrib/verifybinaries/test.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+
+import json
+import sys
+import subprocess
+from pathlib import Path
+
+
+def main():
+    """Tests ordered roughly from faster to slower."""
+    expect_code(run_verify('0.32'), 4, "Nonexistent version should fail")
+    expect_code(run_verify('0.32.awefa.12f9h'), 11, "Malformed version should fail")
+    expect_code(run_verify('22.0 --min-good-sigs 20'), 9, "--min-good-sigs 20 should fail")
+
+    print("- testing multisig verification (22.0)", flush=True)
+    _220 = run_verify('22.0 --json')
+    try:
+        result = json.loads(_220.stdout.decode())
+    except Exception:
+        print("failed on 22.0 --json:")
+        print_process_failure(_220)
+        raise
+
+    expect_code(_220, 0, "22.0 should succeed")
+    v = result['verified_binaries']
+    assert result['good_trusted_sigs']
+    assert v['bitcoin-22.0-aarch64-linux-gnu.tar.gz'] == 'ac718fed08570a81b3587587872ad85a25173afa5f9fbbd0c03ba4d1714cfa3e'
+    assert v['bitcoin-22.0-osx64.tar.gz'] == '2744d199c3343b2d94faffdfb2c94d75a630ba27301a70e47b0ad30a7e0155e9'
+    assert v['bitcoin-22.0-x86_64-linux-gnu.tar.gz'] == '59ebd25dd82a51638b7a6bb914586201e67db67b919b2a1ff08925a7936d1b16'
+
+
+def run_verify(extra: str) -> subprocess.CompletedProcess:
+    maybe_here = Path.cwd() / 'verify.py'
+    path = maybe_here if maybe_here.exists() else Path.cwd() / 'contrib' / 'verifybinaries' / 'verify.py'
+
+    return subprocess.run(
+        f"{path} --cleanup {extra}",
+        stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=True)
+
+
+def expect_code(completed: subprocess.CompletedProcess, expected_code: int, msg: str):
+    if completed.returncode != expected_code:
+        print(f"{msg!r} failed: got code {completed.returncode}, expected {expected_code}")
+        print_process_failure(completed)
+        sys.exit(1)
+    else:
+        print(f"✓ {msg!r} passed")
+
+
+def print_process_failure(completed: subprocess.CompletedProcess):
+    print(f"stdout:\n{completed.stdout.decode()}")
+    print(f"stderr:\n{completed.stderr.decode()}")
+
+
+if __name__ == '__main__':
+    main()