[tor-dev] Mostly Automatic Censorship Circumvention in Tor Browser
richard at torproject.org
Thu Jul 8 16:22:13 UTC 2021
As part of our Sponsor 30 work, we are looking to improve the new
about:torconnect experience by adding automatic tor settings
configuration for censorship circumvention.
This document outlines and discusses the *technical* challenges
associated with this work, and does not go into any great detail on the
right UX would be (in terms of easy of use, user trust, etc).
Anyway, if you see any pitfalls or problems with anything here, do let
# Mostly Automatic Bridge Configuration to Bypass Internet Censorship
Our goal for this work is to enable Tor Browser users to access tor
without having to navigate to about:preferences#tor to configure
bridges. Technically speaking, this is a trivial problem assuming you know:
- which bridge settings work at the user's location
- the location of the user
## Circumvention Settings Map
For now, it seems sufficient to maintain a map of countries to some
data-structure containing information about which censorship
circumvention techniques work and which ones do not. A proposed example
format can be found here:
This map would at be distributed and updated through tor-browser releases.
#### Censorship Changes Invalidate the Map
The obvious problem with distributing the censorship-circumvention
settings map with Tor Browser is that if the techniques used in a
location change such that old settings no longer work, you will be left
with a non-functional Tor Browser with no way to update it apart from
acquiring a fresh install with the updated settings or by manually
configuring Tor Browser's bridge settings (so what users have to do now)
A fix for this would be to provide a rules update mechanism whereby
updated rules could be fetched outside of tor (via the clearnet, or over
moat). Special care would need to be taken to ensure the rule updates
from this automatic mechanism actually came from the Tor Project (via
some sort of signature verification scheme, for example).
Another wrinkle here is that rules would also need to be distributed
somewhere that is difficult to censor. It seems likely that we may need
different locations and mechanisms for acquiring the rule-set based on
the user's location.
Whatever the mechanism, updates should happen at least before the user
attempts to auto-configure. Otherwise, perhaps we should periodically
auto-update the the settings at a reasonable cadence.
#### Time Investment to Update Map
Another problem with solely distributing the rules through Tor Browser,
is that censorship events would now require a Tor Browser release just
to push new rules out to people. Publishing new Tor Browser releases is
not a simple task, and enabling adversaries to force Tor Browser
releases by tweaking their censorship systems seems like a cute way to
DDOS the Applications team.
An alternate update channel is definitely necessary outside of periodic
Tor Browser releases.
#### Are Per-Country Entries Granular Enough?
One could imagine highly localized censorship events occurring which
require special settings that are not needed in the rest of the country.
For instance, if there is a clearnet blackout in Minneapolis, would we
want to pipe *all* of our US users through the same bridges? Seems like
a potential scalability problem for countries with large populations.
## Determining User Location
A user's location can be determined by accessing location services
through the clearnet. Mozilla offers a such a service (
https://location.services.mozilla.com/ ) with a very simple HTTP
interface. Prior to bootstrapping, Tor Browser can access the location
service by temporarily enabling network DNS:
and making an exception for the location service URL to bypass the proxy by:
The location service would send back a country code in a JSON object
which we can use to look up appropriate bridge settings in our map
So the functionality of this approach is pretty easy to implement: tweak
some prefs, make an XMLHttpRequest, change the prefs back.
One possible problem we may face is if censors start blocking Mozilla's
location services. Maybe we should have a pool of location service
providers to make this more difficult (though we would need to do the
research and figure out how feasible this is from a cost perspective).
It is also possible to add location service functionality to moat,
though this would also be a bit of an engineering endeavor.
If we move forward with Mozilla's location services, we will need to
acquire an API key, but I would not expect this to be an issue. We will
also need to make arrangements with them to surpass the current limit of
100,000 daily API requests ( see:
The big challenge here is engineering the right UX which maintains our
users trust. I think we need to be very explicit with this convenience
feature, and definitely not just have it silently happen in the
background. Users should also be able to opt-out, and manually select
their country for the purposes of getting the right settings out of the
above mentioned map.
It should be very difficult to accidentally enable this automatic
lookup. This will likely require a fair bit of iteration on the
about:torconnect page design and flow.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 840 bytes
Desc: OpenPGP digital signature
More information about the tor-dev