doc/spec/bridges-spec.txt

   1 $Id$
   2
   3                           Tor bridges specification
   4
   5 0. Preface
   6
   7   This document describes the design decisions around support for bridge
   8   users, bridge relays, and bridge authorities. It acts as an overview
   9   of the bridge design and deployment for developers, and it also tries
  10   to point out limitations in the current design and implementation.
  11
  12   For more details on what all of these mean, look at blocking.tex in
  13   /doc/design-paper/
  14
  15 1. Bridge relays
  16
  17   Bridge relays are just like normal Tor relays except they don't publish
  18   their server descriptors to the main directory authorities.
  19
  20 1.1. PublishServerDescriptor
  21
  22   To configure your relay to be a bridge relay, just add
  23     BridgeRelay 1
  24     PublishServerDescriptor bridge
  25   to your torrc. This will cause your relay to publish its descriptor
  26   to the bridge authorities rather than to the default authorities.
  27
  28   Alternatively, you can say
  29     BridgeRelay 1
  30     PublishServerDescriptor 0
  31   which will cause your relay to not publish anywhere. This could be
  32   useful for private bridges.
  33
  34 1.2. Recommendations.
  35
  36   Bridge relays should use an exit policy of "reject *:*". This is
  37   because they only need to relay traffic between the bridge users
  38   and the rest of the Tor network, so there's no need to let people
  39   exit directly from them.
  40
  41   We invented the RelayBandwidth* options for this situation: Tor clients
  42   who want to allow relaying too. See proposal 111 for details. Relay
  43   operators should feel free to rate-limit their relayed traffic.
  44
  45 1.3. Implementation note.
  46
  47   Vidalia 0.0.15 has turned its "Relay" settings page into a tri-state
  48   "Don't relay" / "Relay for the Tor network" / "Help censored users".
  49
  50   If you click the third choice, it forces your exit policy to reject *:*.
  51
  52   If all the bridges end up on port 9001, that's not so good. On the
  53   other hand, putting the bridges on a low-numbered port in the Unix
  54   world requires jumping through extra hoops. The current compromise is
  55   that Vidalia makes the ORPort default to 443 on Windows, and 9001 on
  56   other platforms.
  57
  58   At the bottom of the relay config settings window, Vidalia displays
  59   the bridge identifier to the operator (see Section 3.1) so he can pass
  60   it on to bridge users.
  61
  62 2. Bridge authorities.
  63
  64   Bridge authorities are like normal v3 directory authorities, except
  65   they don't create their own network-status documents or votes. So if
  66   you ask a bridge authority for a network-status document or consensus,
  67   they behave like a directory mirror: they give you one from one of
  68   the main authorities. But if you ask the bridge authority for the
  69   descriptor corresponding to a particular identity fingerprint, it will
  70   happily give you the latest descriptor for that fingerprint.
  71
  72   To become a bridge authority, add these lines to your torrc:
  73     AuthoritativeDirectory 1
  74     BridgeAuthoritativeDir 1
  75
  76   Right now there's one bridge authority, running on the Tonga relay.
  77
  78 2.1. Exporting bridge-purpose descriptors
  79
  80   We've added a new purpose for server descriptors: the "bridge"
  81   purpose. With the new router-descriptors file format that includes
  82   annotations, it's easy to look through it and find the bridge-purpose
  83   descriptors.
  84
  85   Currently we export the bridge descriptors from Tonga to the
  86   BridgeDB server, so it can give them out according to the policies
  87   in blocking.pdf.
  88
  89 2.2. Reachability/uptime testing
  90
  91   Right now the bridge authorities do active reachability testing of
  92   bridges, so we know which ones to recommend for users.
  93
  94   But in the design document, we suggested that bridges should publish
  95   anonymously (i.e. via Tor) to the bridge authority, so somebody watching
  96   the bridge authority can't just enumerate all the bridges. But if we're
  97   doing active measurement, the game is up. Perhaps we should back off on
  98   this goal, or perhaps we should do our active measurement anonymously?
  99
 100   Answering this issue is scheduled for 0.2.1.x.
 101
 102 2.3. Future work: migrating to multiple bridge authorities
 103
 104   Having only one bridge authority is both a trust bottleneck (if you
 105   break into one place you learn about every single bridge we've got)
 106   and a robustness bottleneck (when it's down, bridge users become sad).
 107
 108   Right now if we put up a second bridge authority, all the bridges would
 109   publish to it, and (assuming the code works) bridge users would query
 110   a random bridge authority. This resolves the robustness bottleneck,
 111   but makes the trust bottleneck even worse.
 112
 113   In 0.2.2.x and later we should think about better ways to have multiple
 114   bridge authorities.
 115
 116 3. Bridge users.
 117
 118   Bridge users are like ordinary Tor users except they use encrypted
 119   directory connections by default, and they use bridge relays as both
 120   entry guards (their first hop) and directory guards (the source of
 121   all their directory information).
 122
 123   To become a bridge user, add the following line to your torrc:
 124     UseBridges 1
 125
 126   and then add at least one "Bridge" line to your torrc based on the
 127   format below.
 128
 129 3.1. Format of the bridge identifier.
 130
 131   The canonical format for a bridge identifier contains an IP address,
 132   an ORPort, and an identity fingerprint:
 133     bridge 128.31.0.34:9009 4C17 FB53 2E20 B2A8 AC19 9441 ECD2 B017 7B39 E4B1
 134
 135   However, the identity fingerprint can be left out, in which case the
 136   bridge user will connect to that relay and use it as a bridge regardless
 137   of what identity key it presents:
 138     bridge 128.31.0.34:9009
 139   This might be useful for cases where only short bridge identifiers
 140   can be communicated to bridge users.
 141
 142   In a future version we may also support bridge identifiers that are
 143   only a key fingerprint:
 144     bridge 4C17 FB53 2E20 B2A8 AC19 9441 ECD2 B017 7B39 E4B1
 145   and the bridge user can fetch the latest descriptor from the bridge
 146   authority (see Section 3.4).
 147
 148 3.2. Bridges as entry guards
 149
 150   For now, bridge users add their bridge relays to their list of "entry
 151   guards" (see path-spec.txt for background on entry guards). They are
 152   managed by the entry guard algorithms exactly as if they were a normal
 153   entry guard -- their keys and timing get cached in the "state" file,
 154   etc. This means that when the Tor user starts up with "UseBridges"
 155   disabled, he will skip past the bridge entries since they won't be
 156   listed as up and usable in his networkstatus consensus. But to be clear,
 157   the "entry_guards" list doesn't currently distinguish guards by purpose.
 158
 159   Internally, each bridge user keeps a smartlist of "bridge_info_t"
 160   that reflects the "bridge" lines from his torrc along with a download
 161   schedule (see Section 3.5 below). When he starts Tor, he attempts
 162   to fetch a descriptor for each configured bridge (see Section 3.4
 163   below). When he succeeds at getting a descriptor for one of the bridges
 164   in his list, he adds it directly to the entry guard list using the
 165   normal add_an_entry_guard() interface. Once a bridge descriptor has
 166   been added, should_delay_dir_fetches() will stop delaying further
 167   directory fetches, and the user begins to bootstrap his directory
 168   information from that bridge (see Section 3.3).
 169
 170   Currently bridge users cache their bridge descriptors to the
 171   "cached-descriptors" file (annotated with purpose "bridge"), but
 172   they don't make any attempt to reuse descriptors they find in this
 173   file. The theory is that either the bridge is available now, in which
 174   case you can get a fresh descriptor, or it's not, in which case an
 175   old descriptor won't do you much good.
 176
 177   We could disable writing out the bridge lines to the state file, if
 178   we think this is a problem.
 179
 180   As an exception, if we get an application request when we have one
 181   or more bridge descriptors but we believe none of them are running,
 182   we mark them all as running again. This is similar to the exception
 183   already in place to help long-idle Tor clients realize they should
 184   fetch fresh directory information rather than just refuse requests.
 185
 186 3.3. Bridges as directory guards
 187
 188   In addition to using bridges as the first hop in their circuits, bridge
 189   users also use them to fetch directory updates. Other than initial
 190   bootstrapping to find a working bridge descriptor (see Section 3.4
 191   below), all further non-anonymized directory fetches will be redirected
 192   to the bridge.
 193
 194   This means that bridge relays need to have cached answers for all
 195   questions the bridge user might ask. This makes the upgrade path
 196   tricky --- for example, if we migrate to a v4 directory design, the
 197   bridge user would need to keep using v3 so long as his bridge relays
 198   only knew how to answer v3 queries.
 199
 200   In a future design, for cases where the user has enough information
 201   to build circuits yet the chosen bridge doesn't know how to answer a
 202   given query, we might teach bridge users to make an anonymized request
 203   to a more suitable directory server.
 204
 205 3.4. How bridge users get their bridge descriptor
 206
 207   Bridge users can fetch bridge descriptors in two ways: by going directly
 208   to the bridge and asking for "/tor/server/authority", or by going to
 209   the bridge authority and asking for "/tor/server/fp/ID". By default,
 210   they will only try the direct queries. If the user sets
 211     UpdateBridgesFromAuthority 1
 212   in his config file, then he will try querying the bridge authority
 213   first for bridges where he knows a digest (if he only knows an IP
 214   address and ORPort, then his only option is a direct query).
 215
 216   If the user has at least one working bridge, then he will do further
 217   queries to the bridge authority through a full three-hop Tor circuit.
 218   But when bootstrapping, he will make a direct begin_dir-style connection
 219   to the bridge authority.
 220
 221   As of Tor 0.2.0.10-alpha, if the user attempts to fetch a descriptor
 222   from the bridge authority and it returns a 404 not found, the user
 223   will automatically fall back to trying a direct query. Therefore it is
 224   recommended that bridge users always set UpdateBridgesFromAuthority,
 225   since at worst it will delay their fetches a little bit and notify
 226   the bridge authority of the identity fingerprint (but not location)
 227   of their intended bridges.
 228
 229 3.5. Bridge descriptor retry schedule
 230
 231   Bridge users try to fetch a descriptor for each bridge (using the
 232   steps in Section 3.4 above) on startup. Whenever they receive a
 233   bridge descriptor, they reschedule a new descriptor download for 1
 234   hour from then.
 235
 236   If on the other hand it fails, they try again after 15 minutes for the
 237   first attempt, after 15 minutes for the second attempt, and after 60
 238   minutes for subsequent attempts.
 239
 240   In 0.2.2.x we should come up with some smarter retry schedules.
 241
 242 3.6. Implementation note.
 243
 244   Vidalia 0.1.0 has a new checkbox in its Network config window called
 245   "My ISP blocks connections to the Tor network." Users who click that
 246   box change their configuration to:
 247     UseBridges 1
 248     UpdateBridgesFromAuthority 1
 249   and should add at least one bridge identifier.
 250