gitian-verify.md

Manifest

• gitian-verify/
  • README.md
  • step_1/
    • verify-keys.sh
    • fingerprints.txt
    • signatures/
      • ...
  • step_2/
    • download-and-verify.sh

verify-keys.sh: create and edit a trusted gitian keyring

Summary: a very simple and clear shell script that's easily audited even by relatively inexperienced programmers that bootstraps a gitian-specific keyring for the user and uses that to verify the remainder of the verification code (and, ultimately, the binaries).

1. Includes a hardcoded list of pubkeys belonging to Gitian signers sourced from the bitcoin/bitcoin repository. (The list is not trusted, but is part of the program to keep the code simple and auditable.)

2. Checks to see if any of those keys are already in a gitian-specific keyring. If so, tells the user that they trust n gitian signers so far and lists the names of them (and provides an option to remove individuals from that list).

3. Presents the list of Gitian signers who have not been trusted yet, and asks the user if they want to trust any of those keys. Provides some guideance (perhaps via URLs to multiple different sites) about how to authenticate keys and what can go wrong if the user chooses the wrong keys to trust. If the user choose a key for trust, adds it to the gitian-specific keyring.

4. Repeat steps two and three until the user is satisfied with their key selection.

5. Uses gpg/gpgv to verify the full contents of the gitian-verify/ directiory, except for the signatures/ subdirectory, using the gitian-specific keyring the user populated and the contents of the signatures/ subdirectory.

download-and-verify.sh: install/upgrade verification

Summary: a shell script that can be a bit less clear (because it's been verified) that presents the user with a list of download options, retieves the binary and its gitian sigs, and verifies them.

1. Checks out the gitian sigs repository (or grabs a pre-packaged tarball, whatever).

2. Finds and verifies all attestations signed by keys on the gitian-specific keyring.

3. Using only those authenticated attestations, builds a list of known releases and presents that to the user in order, with highest-version-number first.

4. The user selects a release to download. The program tells the user what each key on the gitian-specific keyring did. E.g.,

   a. Signed a file with the same hash as n other signers on the gitian-specific key ring b. Signed a file with a different hash from any other signers c. Did not sign anything for this release

5. After the user has reviewed the above information, gives them the option to download a release tarball/zipfile. Prompts them for their platform. Downloads the archive, verifies its hash, and indicates success to the user.

6. If the downloaded archive includes a more recent version of the gitian-verify/ directory, encourages the user to use that archive's download-and-verify.sh for future upgrades.

Notes

• All programs can take environment variables or CLI parameters to retrieve remote content at a different URL than whatever is set as the default.