Opened 6 years ago

Closed 3 months ago

#9843 closed task (fixed)

Document how to verify Tor Browser archives after download

Reported by: Sherief Owned by: traumschule
Priority: Medium Milestone:
Component: Community/Tor Browser Manual Version:
Severity: Normal Keywords: SponsorO, sebastian-0115-triaged
Cc: admin@…, harmony Actual Points:
Parent ID: #3893 Points:
Reviewer: Sponsor:

Description

I made a small guide (with pictures) to verify TBB. Please review and commit it to the short user manual.

Child Tickets

Attachments (3)

short-user-manual-verify-div.7z (193.5 KB) - added by Sherief 6 years ago.
short-user-manual-verify-div.zip (193.8 KB) - added by Sherief 6 years ago.
short-user-manual-verify(windows-only).zip (169.6 KB) - added by Sherief 6 years ago.

Download all attachments as: .zip

Change History (26)

Changed 6 years ago by Sherief

comment:1 Changed 6 years ago by Sherief

Summary: Short User Manual verification secionShort User Manual verification section

Changed 6 years ago by Sherief

comment:2 Changed 6 years ago by Sherief

Parent ID: #8779

comment:3 Changed 6 years ago by runa

I think this needs a lot more work. Ideally, the manual should:

  • Give the user an idea of why she should care about digital signatures in the first place.
  • Explain what digital signatures are and where to get the software required.
  • How to use said software on Windows (at the very least, bonus for OS X and Linux).
  • Explain the commands used in the terminal, how to know which key to download and use.
  • How to interpret the result you get once you verify the bundle.

The Tor Project website contains useful information on this topic, but we need to find a way to simplify it, make it a bit more user friendly, and put it together in one manual.

comment:4 Changed 6 years ago by phoul

Cc: admin@… added

Changed 6 years ago by Sherief

comment:5 Changed 6 years ago by mrphs

Cc: mrphs added

comment:6 Changed 6 years ago by runa

General comments:

The manual needs to be even more user friendly. The language is very technical and assumes a lot of things about the reader. Ideally, the manual should give the reader all the information that she needs to fully understand the what, the why, and the how. The manual should also make it clear that all of our software packages are signed, it's not just the stable Tor Browser Bundle for Windows (which you include a screenshot of).

Why:

This section should be written for a more general, non-technical audience. Not everyone will understand what an adversary is, nor feel they have anything to worry about. What are the risks involved with not verifying a package you download? How does the process of verifying a digital signature improve things?

What:

Again, this section needs to be written for a more general, non-technical audience. What does verifying a signature actually mean? What is a GPG key? Be careful with referencing specific versions of the Tor Browser Bundle as it may confuse some readers. If you want to use a filename as an example (in a sentence or in a command line argument), make that clear.

How:

The previous section talks a lot about the stable Tor Browser Bundle for Windows, but this section only mentions "the appropriate bundle". Be consistent and give the user all the information necessary to successfully follow this manual.

The process of verifying a digital signature can be confusing, especially if you have never done it before. Try to include as much explanatory information as possible.

This section should explain why you need to have both .exe and .asc in the same place, it should link to the verifying-signatures-page and the signing-keys-page we have on torproject.org, it should explain what the user should do if keys.gnupg.net goes down, and why it is important to verify the fingerprint of the key.

The output you illustrate in step III does not match the output you get in the screenshot below (Figure X). It also looks like you skipped the step of verifying the fingerprint of Erinn's key. The last sentence in step III should probably be a part of step IV? It might be a good idea to clarify that users who get a bad signature should not run the Tor Browser Bundle they just downloaded.

The screenshot at the bottom (Figure X) contains a warning. What does this mean?

comment:7 Changed 5 years ago by lunar

Keywords: SponsorO added
Parent ID: #8779
Summary: Short User Manual verification sectionDocument how to verify Tor Browser archives after download

The verification section should stay out of the upcoming Tor Browser User Manual (#10974) and be integrated into the website, close to the download section.

comment:8 Changed 4 years ago by Sebastian

Keywords: sebastian-0115-triaged added
Owner: changed from runa to Sherief
Status: newassigned

What's the status on this?

comment:9 in reply to:  8 ; Changed 4 years ago by Sherief

Cc: harmony added

Replying to Sebastian:

What's the status on this?

I think this will be part of the user manual harmony and I are working on (previously lunar and Matt) so when it's ready I will submit a patch to the website.

Currently we halted any progress regarding verification until the tbb team switches the signing key from Erinn to somebody else.

comment:10 in reply to:  9 Changed 4 years ago by harmony

Replying to Sherief:

Replying to Sebastian:

What's the status on this?

I think this will be part of the user manual harmony and I are working on (previously lunar and Matt) so when it's ready I will submit a patch to the website.

According to #10974:
"The Tor Browser User Manual will not explain how to download and verify the Tor Browser (if you are reading it, it means that you are either able to reach the Tor website or that you already have the Tor Browser)."

We can change this and include the information in the manual, of course. But the main location for the verification guide should be somewhere very near the download button.

If you just meant 'we will document this information during the user manual writing process' then I agree.

comment:11 Changed 4 years ago by lunar

Actually, Sherief convinced me at some point that this should be part of the Tor Browser manual for practical reasons. It's likely to be translated by the same people, and so get a more coherent vocabulary. Also it benefits from the internationalization and support for conditionals section depending on the platform. (That's if you kept the previous technical approach.)

It's then just a matter of linking to the right versions deployed online.

comment:12 Changed 3 years ago by Sebastian

Severity: Normal

What's the status on this? I don't think it belongs in website component at all?

comment:13 Changed 2 years ago by hiro

Keywords: ux-team added

comment:14 Changed 16 months ago by hiro

Component: Webpages/WebsiteApplications/Tor Browser

comment:15 Changed 16 months ago by gk

Component: Applications/Tor BrowserCommunity/Tor Browser Manual

comment:16 Changed 11 months ago by traumschule

Owner: changed from Sherief to traumschule
Parent ID: #3893

Just want to let you know, that i started working on this:
https://github.com/traumschule/tor-tb-manual/tree/verify

Next is to go through all comments and make it better.

comment:17 Changed 10 months ago by traumschule

Status: assignedneeds_review

i added a paragraph why to verify signatures with a link to the updates website guide. If we want to bring all relevant info to the short manual page it might not be sort anymore. It's worth a try however. What do you think, is it better to only use this as an intro are should all OS specific info go in there?

comment:18 Changed 8 months ago by emmapeel

traumschule: I could review a patch for the tb-manual if you want....

comment:19 Changed 8 months ago by traumschule

Status: needs_reviewneeds_revision

Shall this replace https://github.com/torproject/webwml/pull/31 (#3893) or will this go to support.tpo instead? What about the CSS accordion?

Last edited 8 months ago by traumschule (previous) (diff)

comment:20 Changed 4 months ago by antonela

Keywords: ux-team removed

ux-team label removed because is community team related work.

comment:21 Changed 4 months ago by emmapeel

Priority: LowMedium

it would go into support.tpo

i raise the priority of this ticket because this page should be linked from the new tpo site

comment:22 Changed 3 months ago by mrphs

Cc: mrphs removed

comment:23 Changed 3 months ago by emmapeel

Resolution: fixed
Status: needs_revisionclosed

ok, we already have some instructions and it does not seem we are working on this patch for the previous website, so I will close this ticket.

we can reopen another ticket if we have changes for https://support.torproject.org/tbb/how-to-verify-signature/

Note: See TracTickets for help on using tickets.