Opened 19 months ago

Last modified 3 weeks ago

#28526 assigned project

Document how NGOs can run private obfs4 bridges, and get some doing it

Reported by: arma Owned by: ggus
Priority: Medium Milestone:
Component: Community/Tor Support Version:
Severity: Normal Keywords: education, documentation, s30-o24a1, anti-censorship-roadmap-2020
Cc: sysrqb, ggus, phoul Actual Points:
Parent ID: #31281 Points:
Reviewer: Sponsor: Sponsor30-must

Description

One of our eventual goals is to get bridgedb back on its feet, and using bridge distribution strategies that China can't defeat, but in the mean time we should document one approach that should still work: setting up your Tor Browser with a private (not publicized) tor bridge.

In particular, we know many NGOs that would be happy to run unpublished obfs4 bridges for their people, and give them private bridge addresses when they visit China.

There are several steps to following through with this idea.

Round one (minimum viable approach):

(1) Document for NGOs how to easily run a few private obfs4 bridges. I've seen some guides floating around but nothing both simple and obviously official.

(2) Document for NGOs how they should get these bridge addresses to their users, and how the users should add them to Tor Browser. On Android it seems that Orbot hooks the "bridge://" url, so sending bridge addresses via signal, email, etc should work: the user clicks on the bridge address, which launches Orbot which adds that bridge to its configuration. Having docs for actual users, with screenshots and stuff, would be the clear next step. On desktop the interface choices are messier: see #28015.

(3) Walk a few NGOs through the process from beginning to end, so we can confirm for ourselves that it works as intended, and so we can have a more direct connection to actual users to get feedback on all angles of the user experience.

Round two (once we like round one):

(4) Document for NGOs how to run a series of obfs4 bridges. This could start with one bridge address per computer, but the longer term answer is to have a single Tor client binding to many bridge addresses, maybe with help from the ISP to point these many bridge addresses to that Tor.

(5) Understand if private bridges actually work in China. Apparently Lantern uses obfs4 and they don't get blocked by DPI, so that's a good start, but I've also heard stories of DPI-based throttling. In step 3 above we'll get some anecdotal answers, but here we should design and deploy some recurring experiments from computers inside China that assess (a) connectivity, (b) whether it can bootstrap, and (c) throughput, through a private bridge.

(6) We should invent and document some best practices for where NGOs ought to run their bridges, and how many bridges they need per user. At the extreme bad end of the spectrum, they would run one bridge and give it to all of the people attending a given training -- and in that case, apart from the obvious "what if one of the users is bad and gets the address blocked" worry, discovering some of the users could lead to discovering other related users. At the other end of the spectrum is one bridge (on its own separate ISP) per user. What are some acceptable solutions in between?

Child Tickets

Change History (27)

comment:1 Changed 19 months ago by arma

Status: assignednew

comment:2 Changed 19 months ago by arma

(I put this ticket in webpages -> support because I couldn't think of a better component. It is clearly a cross-component project, so please feel free to bring in the other right people.)

comment:3 Changed 18 months ago by emmapeel

Component: Webpages/SupportCommunity/Tor Support
Owner: set to ggus
Status: newassigned

ey gus, maybe this is one for the community portal?

comment:4 Changed 18 months ago by pili

Once we have a nice guide, maybe this is something we could try to do during some of our country trainings when we're meeting with people.

comment:5 in reply to:  description Changed 18 months ago by arma

Replying to arma:

(1) Document for NGOs how to easily run a few private obfs4 bridges. I've seen some guides floating around but nothing both simple and obviously official.

I just watched somebody on irc use
https://trac.torproject.org/projects/tor/wiki/doc/PluggableTransports/obfs4proxy
to get their obfs4 bridge up and working on debian.

So this might be a good guide to start from.

comment:6 Changed 18 months ago by phoul

Cc: phoul added

comment:7 Changed 18 months ago by gaba

Keywords: education documentation added

comment:8 Changed 12 months ago by gaba

Keywords: ex-sponsor-19 added

Adding the keyword to mark everything that didn't fit into the time for sponsor 19.

comment:9 Changed 12 months ago by phw

Sponsor: Sponsor19Sponsor30-must

Moving from Sponsor 19 to Sponsor 30.

comment:10 Changed 10 months ago by gaba

Parent ID: #31281

comment:11 Changed 10 months ago by pili

Keywords: ux-team removed

comment:12 Changed 9 months ago by phw

Brief update:

comment:13 Changed 8 months ago by phw

Keywords: s30-o24a1 added

comment:14 Changed 8 months ago by phw

I created a wiki page on how to walk an NGO through this process, based on the very limited experience we already have.

comment:15 Changed 8 months ago by ggus

Hey, could we have a full torrc example?

I'm confused if we need to add this:

# This is a private bridge
PublishServerDescriptor 0

Or just this would be enough:

# Tell BridgeDB to not distribute the bridge.
BridgeDistribution none
# Don't self-test, to minimise exposure.
AssumeReachable 1

comment:16 in reply to:  15 Changed 7 months ago by phw

Replying to ggus:

Hey, could we have a full torrc example?


Good idea, I'll do that.

I'm confused if we need to add this:

# This is a private bridge
PublishServerDescriptor 0


This makes your bridge private but you won't be able to see its usage statistics on metrics.tp.o (these are reported in your bridge's descriptors). If you're fine with that, then there's nothing wrong with using PublishServerDescriptor.

comment:17 Changed 5 months ago by sigvids

Here is a sample full torrc:

Log notice file /var/log/tor/log
ORPort 9001
AssumeReachable 1
ExtORPort auto
BridgeRelay 1
PublishServerDescriptor 0
ExitPolicy reject *:*
ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
ServerTransportListenAddr obfs4 0.0.0.0:443
ContactInfo yourname@example.com
Nickname YourBridgeNick

comment:18 Changed 5 months ago by sigvids

I created a draft document at https://sigvids.gitlab.io/create-tor-private-obfs4-bridges.html

As noted in the draft, there is a decision to be made as to whether you install and configure software before or after you enter a censored country. There is a trade-off between convenience and security. It is more convenient to install software and configurations in a free country. The risk is that electronic devices may be inspected when entering a censored country. On the other hand, installing software and configurations after arrival may necessitate additional circumvention measures to reach blocked resources. In the worst case, a user may be completely unable to download the required software and/or bridge lines.

comment:19 Changed 5 months ago by sigvids

Problem #32856 prevents documenting procedure for Android clients.

comment:20 in reply to:  17 Changed 5 months ago by arma

Replying to sigvids:

Here is a sample full torrc:

Log notice file /var/log/tor/log
ORPort 9001
AssumeReachable 1
ExtORPort auto
BridgeRelay 1
PublishServerDescriptor 0
ExitPolicy reject *:*
ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
ServerTransportListenAddr obfs4 0.0.0.0:443
ContactInfo yourname@example.com
Nickname YourBridgeNick

Better to say BridgeDistribution none and leave PublishServerDescriptor at its default. That way your bridge will publish its statistics in the metrics dataset, but bridgedb won't give it out. (See comments above.)

Also, setting ExitPolicy reject *:* is redundant with setting BridgeRelay 1, but I guess it can't hurt to still have it there explicitly.

Thanks!

comment:21 Changed 5 months ago by sigvids

Has BridgeDistribution none been implemented yet? According to the manual at https://2019.www.torproject.org/docs/tor-manual.html.en "the BridgeDB part of this option is not yet implemented."

comment:22 Changed 5 months ago by arma

It has been implemented:
https://gitweb.torproject.org/bridgedb.git/tree/CHANGELOG?h=bridgedb-0.9.1#n264
(in late 2017)

The online manual that you're looking at is a snapshot in time, from the past, originally put up for the benefit of the Windows users who can't run "man tor" themselves. I've just opened #32863 to remind the Tor devs to get a new web version of the manual up somewhere.

comment:23 Changed 5 months ago by sigvids

I have draft some guides and taken some screenshots showing how the users could add them to Tor Browser.

comment:24 Changed 5 months ago by sigvids

I have prepared two additional drafts with screenshots to assist whoever prepares the official versions in connection with #28526.

macOS https://sigvids.gitlab.io/use-tor-private-obfs4-bridges-macos.html
Linux https://sigvids.gitlab.io/use-tor-private-obfs4-bridges-linux.html

comment:25 Changed 4 months ago by gaba

Cc: flexlibris removed
Keywords: anti-censorship-roadmap-2020Q1 added; ex-sponsor-19 removed

comment:26 Changed 4 months ago by phw

Below is a brief summary of where we are.

(1) Document for NGOs how to easily run a few private obfs4 bridges. I've seen some guides floating around but nothing both simple and obviously official.


Over at #31872, we developed a process for distributing private bridges. Section 2.1 of the resulting wiki page discusses how to set up a private bridge. I just filed #33153 to make it easier to set up a private obfs4 Docker container. Once this is done, we should mention it on the wiki page. Also, we now have official obfs4 bridge setup guides.

So far, we talked to three organisations and neither one of them had the expertise or ability to set up their own bridges. One organisation mentioned that it may be a possibility at some point down the road. We ended up working with a volunteer who is now running several private, reliable, and fast obfs4 bridges for us, which we sent to these organisations. Regardless, we should still make progress towards making it easier for these organisations to run their own bridges.

(2) Document for NGOs how they should get these bridge addresses to their users, and how the users should add them to Tor Browser. On Android it seems that Orbot hooks the "bridge://" url, so sending bridge addresses via signal, email, etc should work: the user clicks on the bridge address, which launches Orbot which adds that bridge to its configuration. Having docs for actual users, with screenshots and stuff, would be the clear next step. On desktop the interface choices are messier: see #28015.


Before handing out bridges, NGOs need to equip their users with copies of Tor Browser. We sent our partnering NGOs GetTor download links. Users in China can download Tor Browser over GitLab.

As for instructions on how to add bridges to Tor Browser: we sent our partnering NGOs written instructions in English. It's probably better to take our user manual, turn it into a PDF in whatever language is needed, and send it to the NGO. In the long run, the user manual will hopefully be part of Tor Browser one day (see #11698).

We have yet to work on instructions for Android (see #30317).

(3) Walk a few NGOs through the process from beginning to end, so we can confirm for ourselves that it works as intended, and so we can have a more direct connection to actual users to get feedback on all angles of the user experience.


I recently filed #33145 for this. It has been difficult to find NGOs that can do this on a large-ish scale. Two organisations distributed private obfs4 bridges to their users and we only got feedback from two users. For one, the bridge worked perfectly. The other user seemingly failed at adding it to their Tor Browser.

(5) Understand if private bridges actually work in China. Apparently Lantern uses obfs4 and they don't get blocked by DPI, so that's a good start, but I've also heard stories of DPI-based throttling. In step 3 above we'll get some anecdotal answers, but here we should design and deploy some recurring experiments from computers inside China that assess (a) connectivity, (b) whether it can bootstrap, and (c) throughput, through a private bridge.


Private obfs4 bridges work in China. We know this from our measurements in #29279, and from our preliminary experience with distributing private obfs4 bridges in China.

comment:27 Changed 3 weeks ago by gaba

Keywords: anti-censorship-roadmap-2020 added; anti-censorship-roadmap-2020Q1 removed

No more Q1 for 2020.

Note: See TracTickets for help on using tickets.