doc/spec/proposals/125-bridges.txt

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