wiki/src/blueprint/bridge_support.mdwn

   1 [[!toc levels=2]]
   2
   3 **Note**: this was not updated accordingly to the way this feature is
   4 being implemented yet. Updating the design documentation is tracked by
   5 [[!tails_ticket 6843]].
   6
   7 Given the increasing practice of blocking Tor usage in more
   8 authoritarian countries, censorship resistance is getting more
   9 important. To merely try to use Tor might even be dangerous in these
  10 countries as the government can log it and take action against the
  11 user. Hence we should provide an easy to use facility for our users to achieve:
  12
  13 * Reliability: make sure that they always can reach the Tor network, and
  14 * Obfuscation: prevent others from knowing that our user may be using the Tor network.
  15
  16 In Tor there is the concept of
  17 [bridges](http://www.torproject.org/bridges). By relaying the user's
  18 Tor traffic through a so called *bridge node* which is not listed in
  19 Tor's directory the user may be able to achieve a reliable connection
  20 and hide the fact that the user is connecting to a Tor server.
  21 Tor's bridging makes no attempt to mask the (Tor) nature of the
  22 traffic between the Tails user's client and the bridge node.
  23 Therefore the users access to the Tor network can still be determined
  24 by simple traffic analysis.
  25 See [[obfsproxy|todo/obfsproxy]] for a much better
  26 solution to the obfuscation problem.
  27
  28 Bridges in Tails
  29 ================
  30
  31 While Vidalia makes it straight-forward to use bridges there are some
  32 special considerations that needs to be accounted for in the context
  33 of Tails. Since all Tor is started at boot, it is immediately
  34 disclosed that Tor is used. We need to make it possible for our users
  35 to prevent this, for instance by toggling some option in the boot
  36 menu. However, since all internet traffic is routed through Tor, if a
  37 user doesn't know of any bridges we have a Catch-22 situation since the
  38 user's best possibility to get a bridge is by getting it over the
  39 Internet, for instance from [the Tor project's
  40 website](https://bridges.torproject.org/), IRC or IM buddies and
  41 similar.
  42
  43 Specification
  44 =============
  45
  46 The use of bridges should be optional, and if desired it must be
  47 chosen before Tor starts. The best place for such an option is
  48 probably in tails-greeter. When activated the following things should
  49 happen:
  50
  51 * Tor doesn't try to connect directly to the Tor network.
  52 * The user is somehow helped to setup a bridge, and possibly
  53   instructed how to get one.
  54 * Once a bridge has been chosen, Tor should immediately start to use
  55   it.
  56
  57 Current work
  58 ============
  59
  60 We are going to use Vidalia's bridges configuration UI.
  61
  62 When bridges are enabled (by adding `bridge` to the kernel
  63 command-line):
  64
  65 * [[!tails_gitweb
  66   config/chroot_local-includes/lib/live/config/204-bridge]] adds a
  67   buggy bridge (127.0.0.1:7777) to `/etc/tor/torrc` and enables
  68   `UseBridges` so that Tor does not even try to connect directly to
  69   the network, even when restarted.
  70 * Vidalia is started with the `-bridgeconf` option brought by our
  71   custom patch (XXX):
  72   - network settings are displayed on startup
  73   - `UseBridges` is enabled
  74   - a Tails-specifig pop-up is shown.
  75 * As a workaround to [[!tor_bug 2355]], [[!tails_gitweb
  76   config/chroot_local-includes/etc/NetworkManager/dispatcher.d/60-tor-sighup.sh]]
  77   cleans up the Tor data directory when a network interface goes up.
  78   A real fix for this bug is being worked on, see the bug page for
  79   details and status updates.
  80 * When a network interface goes up, Tor and Vidalia are restarted. Tor
  81   cannot reach its network until the real (working) bridges
  82   configuration is applied by Vidalia, either saved from previous
  83   input or newly entered by the user.
  84
  85 Left to do
  86 ==========
  87
  88 General
  89 -------
  90
  91 Fix all child tickets of [[todo/bridge_support:_complete_phase_one]].
  92
  93 Find bridges button
  94 -------------------
  95
  96 Vidalia has a "Find bridges now" button which won't work for us
  97 since it can't reach bridges.torproject.org. To get it to work we
  98 would need some kind of exception in the firewall rules.
  99
 100 Anyway, bridges.tpo now asks for a CAPTCHA, so an automated,
 101 out-of-the-browser solution seems not doable this way.
 102
 103 It should be noted that just connecting to bridges.torproject.org
 104 can be dangerous if the regime is hostile towards Tor, and/or it
 105 could simply be censored. This must be explained to the user, and
 106 manual input of bridges must be available as an alternative.
 107
 108 One can also get Obfsproxy [bridges by email](https://www.torproject.org/docs/bridges.html.en#FindingMore) (currently sent from Yahoo
 109 and Gmail email accounts only).
 110
 111 Until a solution is found for this issue, we should probably [[hide this
 112 button|todo/hide_Find_bridges_button]].