Opened 5 months ago
Last modified 7 weeks ago
#31296 reopened defect
simplify OpenPGP signature verification instructions
Reported by: | dkg | Owned by: | ggus |
---|---|---|---|
Priority: | Medium | Milestone: | |
Component: | Webpages/Support | Version: | |
Severity: | Normal | Keywords: | |
Cc: | pili, boklm | Actual Points: | |
Parent ID: | Points: | ||
Reviewer: | Sponsor: |
Description (last modified by )
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 rawgpg
- 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.
Child Tickets
Ticket | Status | Owner | Summary | Component |
---|---|---|---|---|
#31254 | closed | ggus | Tor Support Portal "How can I verify Tor Browser's signature" has inaccurate instructions that can prevent signature verification of Tor Browser | Webpages/Support |
Attachments (1)
Change History (13)
comment:1 Changed 5 months ago by
Description: | modified (diff) |
---|
comment:2 Changed 5 months ago by
Component: | - Select a component → Webpages/Support |
---|---|
Owner: | set to hiro |
comment:3 Changed 5 months ago by
comment:4 Changed 5 months ago by
Cc: | pili added |
---|
comment:5 Changed 5 months ago by
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.
comment:6 Changed 5 months ago by
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.
comment:7 Changed 5 months ago by
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.
comment:8 Changed 4 months ago by
Owner: | changed from hiro to ggus |
---|---|
Status: | new → assigned |
Gus is working on this
comment:10 Changed 3 months ago by
Resolution: | fixed |
---|---|
Status: | closed → reopened |
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.
comment:11 Changed 7 weeks ago by
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).
comment:12 Changed 7 weeks ago by
Cc: | boklm added |
---|
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.