simplify OpenPGP signature verification instructions

Trac:
Child Ticket(s): #31254 (moved)

added component::webpages/support owner::ggus priority::medium severity::normal status::reopened type::defect labels

Trac:
Description: The OpenPGP signature verification instructions at https://support.torproject.org/tbb/how-to-verify-signature/ are more complicated than they need to be, and more repetitive. They also are confusing!

I'll attach a revised version of the contents.lr file, but you can also see the changes with more clarity as a series of individual git commits on the pgp-verification branch of tor's support repo at https://0xacab.org/dkg/tor-support.

the main changes are:

group GnuPG installation instructions in one place
export the tor developer OpenPGP certificate as a "keyring"
use gpgv for verification, not raw gpg
remove accidentally misleading statements about "assigning a trust index" and "exchanging fingerprints"
use fingerprints and not keyids
bake fingerprint verification into the workflow, rather than asking humans to compare them manually.

If you disagree with any of these changes

to

The OpenPGP signature verification instructions at https://support.torproject.org/tbb/how-to-verify-signature/ are more complicated than they need to be, and more repetitive. They also are confusing!

I'll attach a revised version of the contents.lr file, but you can also see the changes with more clarity as a series of individual git commits on the pgp-verification branch of tor's support repo at https://0xacab.org/dkg/tor-support.

the main changes are:

group GnuPG installation instructions in one place
export the tor developer OpenPGP certificate as a "keyring"
use gpgv for verification, not raw gpg
remove accidentally misleading statements about "assigning a trust index" and "exchanging fingerprints"
use fingerprints and not keyids
bake fingerprint verification into the workflow, rather than asking humans to compare them manually.

If you disagree with any of these changes, please let me know, and why. i'd be happy to reconsider them with good reason.

Trac:
Component: - Select a component to Webpages/Support
Owner: N/A to hiro

Thanks for that!

We have our websites meeting today (Wednesday @ 16:00 UTC in #tor-meeting ) and we can discuss these changes with the team then.

Trac:
Cc: N/A to pili

I just realized that while i've tested the GNU/Linux and Windows processes, i don't know for certain that gpgtools on macOS provides a gpgv binary. The proposed text assumes that it does. I hope that someone with macOS and gpgtools installed can verify before adoption of the full set of changes.

One additional change that i don't know how to make is to encourage the person reading these instructions to identify the correct version number that they are installing. The instructions before my changes had as an example the version number 8.0.8. In my edits, i updated that to 8.5.4 (more current).

I see three options to make this less tricky/confusing to a new user:

update this page upon every release of TBB, so that the version number in the instructions matches the version number they download at the time. This is the simplest for the novice user who can just copy the commands directly without having to learn exactly what they mean.
use some sort of explicit placeholder in the text of the page, asking the reader explicitly to interpolate (for example) VERSION for the version that they downloaded. This ensures that the user actually understands what they are doing, while making the verification break for users who are confused.
use some explicit shell variable in the command-line instructions (e.g. instructing the user to set TOR_VERSION=8.5.4 as the first step), and then do shell variable expansion in the later stages (e.g.gpgv --keyring ./tor.keyring tor-install-${TOR_VERSION}{.asc,}). This makes the command line invocations look even more "magic" for users who don't know shell, but gives them one explicit step to take to assert the version number as part of the verification process.

Trac:
contents.lr

updated version of contents.lr

A few more usability improvements that would be good (but i don't know enough of the publishing platform to do confidently myself):

set off "install gpg" section in a distinct box -- this is a "one-time" operation, while we expect the other two top-level steps to be repeated on each verification.
add "platform" icons to the platform-specific steps. that is, a little embedded windows logo next to "for Windows users", etc.
little graphics for getting to a terminal window on the proprietary platforms -- it could be as simple as the icon for cmd.exe for Windows and the icon for Terminal.app on macOS. Or if you want to get complicated/fancy, a miniature screenshot or animations of getting to the terminal by mouse on those platforms.

Gus is working on this

Trac:
Owner: hiro to ggus
Status: new to assigned

Merged, thanks!

Trac:
Resolution: N/A to fixed
Status: assigned to closed

Platform: Tor Browser 8.5.5 on macOS Mojave version 10.14.6

Instructions in the current Support documentation for macOS users https://support.torproject.org/tbb/how-to-verify-signature/ causes attempts to verify the signature to fail.

The examples below assume that the macOS user has downloaded the files to the "Downloads" folder.

Terminal command

gpg --verify ~/Downloads/TorBrowser-8.5.5-osx64_en-US.dmg.asc /Downloads/TorBrowser-8.5.5-osx64_en-US.dmg

successfully verifies the signature by returning Terminal message

gpg: Signature made Tue Sep 3 06:07:30 2019 PDT
gpg: using RSA key EB774491D9FF06E2
gpg: Good signature from "Tor Browser Developers (signing key) <torbrowser@torproject.org>" [ultimate]

In the preceding Terminal command, notice that the TorBrowser-8.5.5-osx64_en-US.dmg.asc file entry precedes the TorBrowser-8.5.5-osx64_en-US.dmg file entry.

The current Support documentation instructs macOS users to enter Terminal command

gpgv --keyring ./tor.keyring ~/Downloads/TorBrowser-8.5.4-osx64_en-US.dmg{.asc,}

The preceding Terminal command returns Terminal message

gpgv: keyblock resource './tor.keyring': No such file or directory
gpgv: no valid OpenPGP data found.
gpgv: the signature could not be verified.
Please remember that the signature file (.sig or .asc)
should be the first file given on the command line.

Apparently, macOS users must use Terminal command gpg --verify, and the {.asc,} file must appear before the {.dmg,} file in the Terminal command line before an attempt to verify the signature can be successful.

Trac:
Username: monmire
Resolution: fixed to N/A
Status: closed to reopened

When fetching the torbrowser key with wkd using the command from https://support.torproject.org/tbb/how-to-verify-signature/, I get the following two subkeys:

pub   rsa4096/4E2C6E8793298290 2014-12-15 [C] [expires: 2020-08-24]
      EF6E286DDA85EA2A4BA7DE684E2C6E8793298290
uid                 [ unknown] Tor Browser Developers (signing key) <torbrowser@torproject.org>
sub   rsa4096/2D000988589839A3 2014-12-15 [S] [revoked: 2015-08-26]
sub   rsa4096/EB774491D9FF06E2 2018-05-26 [S] [expires: 2020-09-12]

One of them is a revoked subkey.

According to the gpgv manpage: "gpgv assumes that all keys in the keyring are trustworthy. That does also mean that it does not check for expired or revoked keys".

Does this mean that if a new Tor Browser release is signed with the revoked subkey EB774491D9FF06E2, then gpgv will not complain? If so then we probably need to add instructions explaining how to remove revoked subkeys from the keyring.

As we regularly rotate the subkey we use for signing the releases, I think we should also include on this page how to refresh the key (and how to remove expired and revoked subkeys from the keyring, if gpgv would use them without complaining).

Trac:
Cc: pili to pili, boklm

mentioned in issue #31254 (moved)

moved to tpo/web/support-trac#31296 (moved)

simplify OpenPGP signature verification instructions

Child items ...

Activity