simplify OpenPGP signature verification instructions

[dkg]

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.

[pili]

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.

[dkg]

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.

[dkg]

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.

[dkg]

updated version of contents.lr

[dkg]

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.

[pili]

Gus is working on this

[ggus]

Merged, thanks!

[monmire]

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.