Opened 3 years ago

Closed 7 months ago

#23226 closed defect (fixed)

GetTor help message could be more helpful

Reported by: catalyst Owned by: cohosh
Priority: Medium Milestone:
Component: Applications/GetTor Version:
Severity: Normal Keywords: anti-censorship-roadmap-2020Q1, ux-team
Cc: cohosh, phw, hiro, antonela Actual Points: 1.5
Parent ID: #9036 Points: 1
Reviewer: phw Sponsor:

Description (last modified by cohosh)

The GetTor email help message says

This is how you can request a tor browser bundle link.

Send an email to: gettor@torproject.org

In the body of the email only write: <operating system> <language>.

We only support windows, osx and linux as operating systems.

Some things we can add:

  • instructions on how to verify the signature
  • instructions on how to get bridges?

Child Tickets

Change History (28)

comment:1 Changed 2 years ago by traumschule

Parent ID: #9036

Let #9036 adopt some children.

comment:2 Changed 13 months ago by cohosh

Cc: cohosh added

cc'ing cohosh on open GetTor tickets.

comment:3 Changed 13 months ago by gaba

Owner: ilv deleted
Status: newassigned

Removing ilv as onwer of many of the tickets. He can take back the ticket he will work on if he comes back into gettor.

comment:4 Changed 13 months ago by gaba

Status: assignednew

comment:5 Changed 9 months ago by cohosh

Points: 1

comment:6 Changed 9 months ago by gaba

Keywords: anti-censorship-roadmap-2020Q1 added

comment:7 Changed 9 months ago by cohosh

Description: modified (diff)

comment:8 Changed 8 months ago by cohosh

Since this project is in many ways similar to bridgedb, here's the bridgedb help message for reference:

Hey, cohosh! Welcome to BridgeDB!



COMMANDs: (combine COMMANDs to specify multiple options simultaneously)
  get help               Displays this message.
  get bridges            Request vanilla bridges.
  get ipv6               Request IPv6 bridges.
  get transport [TYPE]   Request a Pluggable Transport by TYPE.
  get key                Get a copy of BridgeDB's public GnuPG key.

Currently supported transport TYPEs:
  obfs4


BridgeDB can provide bridges with several types of Pluggable Transports[0],
which can help obfuscate your connections to the Tor Network, making it more
difficult for anyone watching your internet traffic to determine that you are
using Tor.

Some bridges with IPv6 addresses are also available, though some Pluggable
Transports aren't IPv6 compatible.

Additionally, BridgeDB has plenty of plain-ol'-vanilla bridges - without any
Pluggable Transports - which maybe doesn't sound as cool, but they can still
help to circumvent internet censorship in many cases.

[0]: https://www.torproject.org/docs/pluggable-transports.html

 --
 <3 BridgeDB

comment:9 Changed 8 months ago by cohosh

There's also some ongoing changes to the bridgedb email in #30941. Specifically, the suggestion to include links in the help email is interesting.

comment:10 Changed 8 months ago by cohosh

There was also some work on this a while ago in https://trac.torproject.org/projects/tor/ticket/9036#comment:18

comment:11 Changed 8 months ago by cohosh

I'd suggest keeping the help message simple, and then including instructions for verifying signatures in the actual links email. That way users don't get overwhelmed or confused about what a signature is before they see that it is an additional file they download. I think we should use the same approach for bridge instructions.

Here's what I'd suggest for a help message email:

Hi! Welcome to GetTor!

GetTor provides links and download instructions for Tor Browser. 

Please reply to this message with one of the options below:

    windows
    linux 
    osx

We will then send you the download instructions. 

You can also specify a locale for your Tor Browser download. We currently support
the following locales:
en-US, es-ES, pt-BR, ar, ca, cs, da, de, el, es-AR, fa, fr, ga-IE, he, hu, id, is,
it, ja, ka, ko, nb-NO, nl, pl, ru, sv-SE, tr, vi, zh-CN, zh-TW

--
GetTor

And the links email:

Hi! Welcome to GetTor!

You requested Tor Browser for linux.

Step 1: Download Tor Browser

You will need only one of the links below. If a link does not work for you,
try the next one.

GitLab: https://gitlab.com/thetorproject/torbrowser-linux/raw/master/tor-browser-linux64-9.0.4_en-US.tar.xz
Signature file: https://gitlab.com/thetorproject/torbrowser-linux/raw/master/tor-browser-linux64-9.0.4_en-US.tar.xz.asc

Github: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/tor-browser-linux64-9.0.4_en-US.tar.xz
Signature file: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/tor-browser-linux64-9.0.4_en-US.tar.xz.asc

If you have issues with any of the links above you can access the following
archives and download the file: tor-browser-linux64-9.0.4_en-US.tar.xz

- Internet Archive: https://archive.org/details/@gettor

- Google Drive folder: https://drive.google.com/open?id=13CADQTsCwrGsIID09YQbNz2DfRMUoxUU


Step 2: Verify the signature (Optional)

Verifying the signature ensures that a certain package was generated by its
developers and has not been tampered with. In GetTor emails we provide a link
to a file with the same name as the package and the extension ".asc". These
.asc files are OpenPGP signatures.

< Include os-specific instructions here >


Step 3: Get Bridges

Bridge relays are Tor relays that are not listed in the public Tor directory.
That means that ISPs or governments trying to block access to the Tor network
can't simply block all bridges. Tor Browser comes with several built-in bridges.
If Tor is censored in your country, you may need to request additional bridges
from BridgeDB.

If the built-in bridges do not work for you, send an email to bridges@torproject.org.
Please note that you must send the email using an address from one of the following
email providers: Riseup or Gmail.

--
GetTor

comment:12 Changed 8 months ago by cohosh

Cc: phw hiro antonela added
Status: newneeds_review

I'll ask for feedback on this before moving forward with the changes.

comment:13 Changed 8 months ago by cohosh

Notes:

  • Asking users to reply to the help email will work after we merge #23225.
  • Adding the OS-specific signature verification instructions will take care of #17425.
  • There is a ticket for giving out bridges with GetTor links (#3862). I think this is a reasonable change but we should add this in a future iteration of the text.

comment:14 Changed 8 months ago by cohosh

Owner: set to cohosh
Status: needs_reviewassigned

comment:15 Changed 8 months ago by cohosh

Reviewer: phw
Status: assignedneeds_review

comment:16 Changed 8 months ago by phw

I would rephrase the help message as follows. Please don't feel obliged to use any of my writing; just cherry-pick whatever you consider reasonable.

This is an automated email response from GetTor.

GetTor can send you download links for Tor Browser.
Simply reply to this email and write one of the following three
operating systems in your response:

    windows
    linux 
    osx

GetTor will then respond with download instructions. 

If you want Tor Browser in a language other than English, mention one of the
following language codes in your response:

    en-US
    es-ES
    pt-BR
    ar
    ca
    cs
    da
    de
    el
    es-AR
    fa
    fr
    ga-IE
    he
    hu
    id
    is
    it
    ja
    ka
    ko
    nb-NO
    nl
    pl
    ru
    sv-SE
    tr
    vi
    zh-CN
    zh-TW

In particular, here's what I changed:

  • Removed the signature because there's no point in having one.
  • Replaced Hi! Welcome to GetTor! with This is an automated email response from GetTor. because the service should make it clear that it's a bot responding.
  • Replaced "locale" (which is jargon) with "language".
  • Tried to make sentences shorter and simpler.
  • Make the language list be one per line, to be consistent with the operating system list.

I'll add comments for the links email in a second.

comment:17 Changed 8 months ago by phw

Status: needs_reviewneeds_revision

Again, here's how I would change the email:

This is an automated email response from GetTor.

You requested Tor Browser for linux.

Step 1: Download Tor Browser

  First, try downloading Tor Browser from either GitLab or GitHub:

  GitLab: https://gitlab.com/thetorproject/torbrowser-linux/raw/master/tor-browser-linux64-9.0.4_en-US.tar.xz
  Signature file: https://gitlab.com/thetorproject/torbrowser-linux/raw/master/tor-browser-linux64-9.0.4_en-US.tar.xz.asc

  GitHub: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/tor-browser-linux64-9.0.4_en-US.tar.xz
  Signature file: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/tor-browser-linux64-9.0.4_en-US.tar.xz.asc

  If you cannot download Tor Browser from GitLab or GitHub,
  try downloading the file tor-browser-linux64-9.0.4_en-US.tar.xz
  from the following archives:

  Internet Archive: https://archive.org/details/@gettor

  Google Drive folder: https://drive.google.com/open?id=13CADQTsCwrGsIID09YQbNz2DfRMUoxUU

Step 2: Verify the signature (Optional)

  Verifying the signature ensures that a certain package was generated by its
  developers, and has not been tampered with.  This email provides links to signature
  files that have the same name as the Tor Browser file, but end with ".asc" instead.

  < Include os-specific instructions here >

Step 3: Get Bridges (Optional)

  If you believe that Tor is blocked where you are, you can use bridges to connect
  to Tor.  Bridges are hidden Tor relays that can circumvent censorship.

  Tor Browser includes a list of built-in bridges, which you should  try first.
  You can activate built-in bridges inside of Tor Browser's settings, under the
  "Tor" menu.  If built-in bridges don't work, try requesting different bridges,
  which you can also do in the "Tor" menu inside Tor Browser's settings.

I changed the following:

  • Mentioned that it's an automated email response.
  • Indented text, to create a clearer visual distinction between our steps.
  • Made step three optional (it is, isn't it?).
  • Removed the email signature.
  • Tried to make sentences shorter and more clear.
  • Encourage users to try moat instead of email.
  • Rephrased step 3.

comment:18 Changed 8 months ago by cohosh

Nice! I like these changes. One thing I'm wondering is whether we should include an example query in the help message email. Something like:

This is an automated email response from GetTor.

GetTor can send you download links for Tor Browser.
Simply reply to this email and write one of the following three
operating systems in your response:

    windows
    linux 
    osx

GetTor will then respond with download instructions. 

If you want Tor Browser in a language other than English, mention one of the
following language codes in your response:

    en-US
    es-ES
    pt-BR
    ar
    [...]

Example:
    windows es-ES

Let's get antonela's feedback on this.

comment:19 Changed 8 months ago by antonela

Thanks for working on improving this message!

Some comments:

  1. Yes! let's include an example of how the message should look. I know we have been receiving emails with bad formatting. Let's be explicit about it.
  2. Do we know which are the most requested locale versions? If yes, let's use them in the list. If we don't know, then we should list in alphabetical order for fast scanning.

Changes:

  • Removed three, seems redundant.
  • Made explicit that the OS is the one that they want to install TB. Seems clear but was not.
  • Tried to explain the example.
This is an automated email response from GetTor.

GetTor can send you download links for Tor Browser.
Simply reply to this email and write the operating system you want to install Tor Browser on in your response:

    windows
    linux 
    osx

GetTor will then respond with download instructions. 

If you want Tor Browser in a language other than English, mention one of the
following language codes in your response:

    en-US
    es-ES
    pt-BR
    ar
    [...]

For example, if you want Tor Browser in Spanish your email content will look like:

    windows es-ES

We will run user testing on this flow, and we can iterate and adjust what is necessary after it.


comment:20 Changed 8 months ago by antonela

Keywords: ux-team added

comment:21 in reply to:  19 ; Changed 8 months ago by cohosh

Replying to antonela:

Thanks for working on improving this message!

Thanks for taking a look!

Some comments:

  1. Yes! let's include an example of how the message should look. I know we have been receiving emails with bad formatting. Let's be explicit about it.
  2. Do we know which are the most requested locale versions? If yes, let's use them in the list. If we don't know, then we should list in alphabetical order for fast scanning.

We don't have this data, we can go with alphabetical order.

Changes:

  • Removed three, seems redundant.
  • Made explicit that the OS is the one that they want to install TB. Seems clear but was not.
  • Tried to explain the example.

These changes look good to me :)

We will run user testing on this flow, and we can iterate and adjust what is necessary after it.

Okay great, so the next step is to implement it then? If so, I'll move forward with a patch!

comment:22 in reply to:  21 Changed 8 months ago by antonela

Replying to cohosh:

Okay great, so the next step is to implement it then? If so, I'll move forward with a patch!

I think so, thanks!

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

comment:23 Changed 8 months ago by cohosh

Okay, here's a commit that updates the help message: https://gitlab.torproject.org/cohosh/gettor/commit/7f1fd7e2c8ad5235af99ff3af9c5e5c94d16e5f8

It will produce an email that looks like this (note there are some very minor adjustments):

This is an automated email response from GetTor.

GetTor can send you download links for Tor Browser.
Simply reply to this email and write the operating system you want to install Tor Browser on in your response. We support the following operating systems:

	windows
	linux
	osx

GetTor will then respond with download instructions.

If you want Tor Browser in a language other than English, mention one of the following language codes in your response:

	en-US
	es-ES
	pt-BR
	ar
	ca
	cs
	da
	de
	el
	es-AR
	fa
	fr
	ga-IE
	he
	hu
	id
	is
	it
	ja
	ka
	ko
	nb-NO
	nl
	pl
	ru
	sv-SE
	tr
	vi
	zh-CN
	zh-TW

For example, if you want Tor Browser for Windows in Arabic your email content will look like:

	windows ar
Last edited 8 months ago by cohosh (previous) (diff)

comment:24 Changed 8 months ago by antonela

Looks good for me!

When you have it live, I'll update https://support.torproject.org/gettor/gettor-2/

comment:25 Changed 8 months ago by cohosh

Okay here's a merge request that includes also updates to the body message (with the specialized signature verification instructions built-in): https://gitlab.torproject.org/torproject/anti-censorship/gettor-project/gettor/merge_requests/3

The result for osx is:

This is an automated email response from GetTor.

You requested Tor Browser for osx.

Step 1: Download Tor Browser

	First, try downloading Tor Browser from either GitLab or GitHub:


	gitlab: https://gitlab.com/thetorproject/torbrowser-9.0.6-osx/raw/master/TorBrowser-9.0.6-osx64_en-US.dmg
	Signature file: https://gitlab.com/thetorproject/torbrowser-9.0.6-osx/raw/master/TorBrowser-9.0.6-osx64_en-US.dmg.asc

	github: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/TorBrowser-9.0.6-osx64_en-US.dmg
	Signature file: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/TorBrowser-9.0.6-osx64_en-US.dmg.asc


	If you cannot download Tor Browser from GitLab or GitHub,
	try downloading the file TorBrowser-9.0.6-osx64_en-US.dmg
	from the following archives:

	Internet Archive: https://archive.org/details/@gettor

	Google Drive folder: https://drive.google.com/open?id=13CADQTsCwrGsIID09YQbNz2DfRMUoxUU

Step 2: Verify the signature (Optional)

	Verifying the signature ensures that a certain package was generated by its
	developers, and has not been tampered with.  This email provides links to signature
	files that have the same name as the Tor Browser file, but end with ".asc" instead.

	If you are using macOS, you can install GPGTools. In order to verify the signature
	you will need to type a few commands in the Terminal (under "Applications").

	The Tor Browser team signs Tor Browser releases. Import the Tor Browser Developers
	signing key (0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290):

		gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org

	This should show you something like:

		gpg: key 4E2C6E8793298290: public key "Tor Browser Developers (signing key) <torbrowser@torproject.org>" imported
		gpg: Total number processed: 1
		gpg:               imported: 1
		pub   rsa4096 2014-12-15 [C] [expires: 2020-08-24]
		      EF6E286DDA85EA2A4BA7DE684E2C6E8793298290
		uid           [ unknown] Tor Browser Developers (signing key) <torbrowser@torproject.org>
		sub   rsa4096 2018-05-26 [S] [expires: 2020-09-12]

	After importing the key, you can save it to a file (identifying it by fingerprint here):

		gpg --output ./tor.keyring --export 0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290

	Next, you will need to download the corresponding ".asc" signature file and verify it
	with the command:

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

	The result of the command should produce something like this:

		gpgv: Signature made 07/08/19 04:03:49 Pacific Daylight Time
		gpgv:                using RSA key EB774491D9FF06E2
		gpgv: Good signature from "Tor Browser Developers (signing key) <torbrowser@torproject.org>"

Step 3: Get Bridges (Optional)

	If you believe that Tor is blocked where you are, you can use bridges to connect
	to Tor.  Bridges are hidden Tor relays that can circumvent censorship.
	Tor Browser includes a list of built-in bridges, which you should  try first.
	You can activate built-in bridges inside of Tor Browser's settings, under the
	"Tor" menu.  If built-in bridges don't work, try requesting different bridges,
	which you can also do in the "Tor" menu inside Tor Browser's settings.

For windows:

This is an automated email response from GetTor.

You requested Tor Browser for windows.

Step 1: Download Tor Browser

	First, try downloading Tor Browser from either GitLab or GitHub:


	gitlab: https://gitlab.com/thetorproject/torbrowser-9.0.6-windows/raw/master/torbrowser-install-9.0.6_en-US.exe
	Signature file: https://gitlab.com/thetorproject/torbrowser-9.0.6-windows/raw/master/torbrowser-install-9.0.6_en-US.exe.asc

	github: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/torbrowser-install-9.0.6_en-US.exe
	Signature file: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/torbrowser-install-9.0.6_en-US.exe.asc


	If you cannot download Tor Browser from GitLab or GitHub,
	try downloading the file torbrowser-install-9.0.6_en-US.exe
	from the following archives:

	Internet Archive: https://archive.org/details/@gettor

	Google Drive folder: https://drive.google.com/open?id=13CADQTsCwrGsIID09YQbNz2DfRMUoxUU

Step 2: Verify the signature (Optional)

	Verifying the signature ensures that a certain package was generated by its
	developers, and has not been tampered with.  This email provides links to signature
	files that have the same name as the Tor Browser file, but end with ".asc" instead.

	If you run Windows, download Gpg4win and run its installer. In order to verify the
	signature you will need to type a few commands in windows command-line, cmd.exe.

	The Tor Browser team signs Tor Browser releases. Import the Tor Browser Developers
	signing key (0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290):

		gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org

	This should show you something like:

		gpg: key 4E2C6E8793298290: public key "Tor Browser Developers (signing key) <torbrowser@torproject.org>" imported
		gpg: Total number processed: 1
		gpg:               imported: 1
		pub   rsa4096 2014-12-15 [C] [expires: 2020-08-24]
		      EF6E286DDA85EA2A4BA7DE684E2C6E8793298290
		uid           [ unknown] Tor Browser Developers (signing key) <torbrowser@torproject.org>
		sub   rsa4096 2018-05-26 [S] [expires: 2020-09-12]

	After importing the key, you can save it to a file (identifying it by fingerprint here):

		gpg --output ./tor.keyring --export 0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290

	Next, you will need to download the corresponding ".asc" signature file and verify it
	with the command:

		gpgv --keyring .\tor.keyring Downloads\torbrowser-install-9.0.6_en-US.exe.asc Downloads\torbrowser-install-9.0.6_en-US.exe

	The result of the command should produce something like this:

		gpgv: Signature made 07/08/19 04:03:49 Pacific Daylight Time
		gpgv:                using RSA key EB774491D9FF06E2
		gpgv: Good signature from "Tor Browser Developers (signing key) <torbrowser@torproject.org>"

For linux:

Step 3: Get Bridges (Optional)

	If you believe that Tor is blocked where you are, you can use bridges to connect
	to Tor.  Bridges are hidden Tor relays that can circumvent censorship.
	Tor Browser includes a list of built-in bridges, which you should  try first.
	You can activate built-in bridges inside of Tor Browser's settings, under the
	"Tor" menu.  If built-in bridges don't work, try requesting different bridges,
	which you can also do in the "Tor" menu inside Tor Browser's settings.


This is an automated email response from GetTor.

You requested Tor Browser for linux.

Step 1: Download Tor Browser

	First, try downloading Tor Browser from either GitLab or GitHub:


	gitlab: https://gitlab.com/thetorproject/torbrowser-9.0.6-linux/raw/master/tor-browser-linux64-9.0.6_en-US.tar.xz
	Signature file: https://gitlab.com/thetorproject/torbrowser-9.0.6-linux/raw/master/tor-browser-linux64-9.0.6_en-US.tar.xz.asc

	github: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/tor-browser-linux64-9.0.6_en-US.tar.xz
	Signature file: https://github.com/torproject/torbrowser-releases/releases/download/torbrowser-release/tor-browser-linux64-9.0.6_en-US.tar.xz.asc


	If you cannot download Tor Browser from GitLab or GitHub,
	try downloading the file tor-browser-linux64-9.0.6_en-US.tar.xz
	from the following archives:

	Internet Archive: https://archive.org/details/@gettor

	Google Drive folder: https://drive.google.com/open?id=13CADQTsCwrGsIID09YQbNz2DfRMUoxUU

Step 2: Verify the signature (Optional)

	Verifying the signature ensures that a certain package was generated by its
	developers, and has not been tampered with.  This email provides links to signature
	files that have the same name as the Tor Browser file, but end with ".asc" instead.

	If you are using GNU/Linux, then you probably already have GnuPG in your system,
	as most GNU/Linux distributions come with it preinstalled. In order to verify the
	signature you will need to type a few commands in a terminal window.

	The Tor Browser team signs Tor Browser releases. Import the Tor Browser Developers
	signing key (0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290):

		gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org

	This should show you something like:

		gpg: key 4E2C6E8793298290: public key "Tor Browser Developers (signing key) <torbrowser@torproject.org>" imported
		gpg: Total number processed: 1
		gpg:               imported: 1
		pub   rsa4096 2014-12-15 [C] [expires: 2020-08-24]
		      EF6E286DDA85EA2A4BA7DE684E2C6E8793298290
		uid           [ unknown] Tor Browser Developers (signing key) <torbrowser@torproject.org>
		sub   rsa4096 2018-05-26 [S] [expires: 2020-09-12]

	After importing the key, you can save it to a file (identifying it by fingerprint here):

		gpg --output ./tor.keyring --export 0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290

	Next, you will need to download the corresponding ".asc" signature file and verify it
	with the command:

		gpgv --keyring ./tor.keyring ~/Downloads/tor-browser-linux64-9.0.6_en-US.tar.xz{.asc,}

	The result of the command should produce something like this:

		gpgv: Signature made 07/08/19 04:03:49 Pacific Daylight Time
		gpgv:                using RSA key EB774491D9FF06E2
		gpgv: Good signature from "Tor Browser Developers (signing key) <torbrowser@torproject.org>"

Step 3: Get Bridges (Optional)

	If you believe that Tor is blocked where you are, you can use bridges to connect
	to Tor.  Bridges are hidden Tor relays that can circumvent censorship.
	Tor Browser includes a list of built-in bridges, which you should  try first.
	You can activate built-in bridges inside of Tor Browser's settings, under the
	"Tor" menu.  If built-in bridges don't work, try requesting different bridges,
	which you can also do in the "Tor" menu inside Tor Browser's settings.

comment:26 Changed 8 months ago by cohosh

Status: needs_revisionneeds_review

comment:27 Changed 7 months ago by phw

Status: needs_reviewmerge_ready

The Linux email starts with step 3. I suppose that's a formatting error, and belongs to the Windows guide?

Other than that, this looks good to me.

comment:28 Changed 7 months ago by cohosh

Actual Points: 1.5
Resolution: fixed
Status: merge_readyclosed

Merged to master here, and deployed to gettor-01 at 2020-03-30T18:00:27.

Note: See TracTickets for help on using tickets.