## 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.