[[!toc levels=2]]

**Note**: this was not updated accordingly to the way this feature is
being implemented yet.

Given the increasing practice of blocking Tor usage in more
authoritarian countries, censorship resistance is getting more
important. To merely try to use Tor might even be dangerous in these
countries as the government can log it and take action against the
user. Hence we should provide an easy to use facility for our users to achieve:

* Reliability: make sure that they always can reach the Tor network, and
* Obfuscation: prevent others from knowing that our user may be using the Tor network.

In Tor there is the concept of
[bridges](http://www.torproject.org/bridges). By relaying the user's
Tor traffic through a so called *bridge node* which is not listed in
Tor's directory the user may be able to achieve a reliable connection
and hide the fact that the user is connecting to a Tor server.
Tor's bridging makes no attempt to mask the (Tor) nature of the
traffic between the Tails user's client and the bridge node.
Therefore the users access to the Tor network can still be determined
by simple traffic analysis.
See [[obfsproxy|todo/obfsproxy]] for a much better
solution to the obfuscation problem.

Bridges in Tails
================

While Vidalia makes it straight-forward to use bridges there are some
special considerations that needs to be accounted for in the context
of Tails. Since all Tor is started at boot, it is immediately
disclosed that Tor is used. We need to make it possible for our users
to prevent this, for instance by toggling some option in the boot
menu. However, since all internet traffic is routed through Tor, if a
user doesn't know of any bridges we have a Catch-22 situation since the
user's best possibility to get a bridge is by getting it over the
Internet, for instance from [the Tor project's
website](https://bridges.torproject.org/), IRC or IM buddies and
similar.

Specification
=============

The use of bridges should be optional, and if desired it must be
chosen before Tor starts. The best place for such an option is
probably in tails-greeter. When activated the following things should
happen:

* Tor doesn't try to connect directly to the Tor network.
* The user is somehow helped to setup a bridge, and possibly
  instructed how to get one.
* Once a bridge has been chosen, Tor should immediately start to use
  it.

Current work
============

We are going to use Vidalia's bridges configuration UI.

When bridges are enabled (by adding `bridge` to the kernel
command-line):

* [[!tails_gitweb
  config/chroot_local-includes/lib/live/config/204-bridge]] adds a
  buggy bridge (127.0.0.1:7777) to `/etc/tor/torrc` and enables
  `UseBridges` so that Tor does not even try to connect directly to
  the network, even when restarted.
* Vidalia is started with the `-bridgeconf` option brought by our
  custom patch (XXX):
  - network settings are displayed on startup
  - `UseBridges` is enabled
  - a Tails-specifig pop-up is shown.
* As a workaround to [[!tor_bug 2355]], [[!tails_gitweb
  config/chroot_local-includes/etc/NetworkManager/dispatcher.d/60-tor-sighup.sh]]
  cleans up the Tor data directory when a network interface goes up.
  A real fix for this bug is being worked on, see the bug page for
  details and status updates.
* When a network interface goes up, Tor and Vidalia are restarted. Tor
  cannot reach its network until the real (working) bridges
  configuration is applied by Vidalia, either saved from previous
  input or newly entered by the user.

Left to do
==========

General
-------

Fix all child tickets of [[todo/bridge_support:_complete_phase_one]].

Find bridges button
-------------------

Vidalia has a "Find bridges now" button which won't work for us
since it can't reach bridges.torproject.org. To get it to work we
would need some kind of exception in the firewall rules.

Anyway, bridges.tpo now asks for a CAPTCHA, so an automated,
out-of-the-browser solution seems not doable this way.

It should be noted that just connecting to bridges.torproject.org
can be dangerous if the regime is hostile towards Tor, and/or it
could simply be censored. This must be explained to the user, and
manual input of bridges must be available as an alternative.

One can also get Obfsproxy [bridges by email](https://www.torproject.org/docs/bridges.html.en#FindingMore) (currently sent from Yahoo
and Gmail email accounts only).

Until a solution is found for this issue, we should probably [[hide this
button|todo/hide_Find_bridges_button]].
