finish writing my overview of bridge design and deployment

svn:r12481

1 files changed, 218 insertions, 36 deletions

diff --git a/doc/spec/proposals/xxx-bridges.txt b/doc/spec/proposals/xxx-bridges.txt
index d0191b9662..0658519fc1 100644
--- a/doc/spec/proposals/xxx-bridges.txt
+++ b/doc/spec/proposals/xxx-bridges.txt
@@ -3,18 +3,20 @@ Title: Behavior for bridge users, bridge relays, and bridge authorities
 Version: $Revision: 12051 $
 Last-Modified: $Date: 2007-10-19 14:56:24 -0400 (Fri, 19 Oct 2007) $
 Author: Roger Dingledine
-Created: xx-Oct-2007
+Created: 11-Nov-2007
 Status: Open
 
-0. Preface:
+0. Preface
 
   This document describes the design decisions around support for bridge
-  users, bridge relays, and bridge authorities.
+  users, bridge relays, and bridge authorities. It acts as an overview
+  of the bridge design and deployment for developers, and it also tries
+  to point out limitations in the current design and implementation.
 
   For more details on what all of these mean, look at blocking.tex in
   /doc/design-paper/
 
-1. Bridge relays.
+1. Bridge relays
 
   Bridge relays are just like normal Tor relays except they don't publish
   their server descriptors to the main directory authorities.
@@ -24,7 +26,7 @@ Status: Open
   To configure your relay to be a bridge relay, just add
     PublishServerDescriptor bridge
   to your torrc. This will cause your relay to publish its descriptor
-  to all the bridge authorities rather than the default authorities.
+  to the bridge authorities rather than to the default authorities.
 
   Alternatively, you can say
     PublishServerDescriptor 0
@@ -34,24 +36,32 @@ Status: Open
 1.2. Defining DirPort
 
   Bridges need to answer BEGIN_DIR requests, both so they can answer
-  /server/authority questions ("what's your descriptor?") and so they
+  "/server/authority" questions ("what's your descriptor?") and so they
   can supply their bridge users with cached copies of all the various
   Tor network information.
 
-  Right now (0.2.0.9-alpha) we require that bridges turn their DirPort on
+  Right now (0.2.0.11-alpha) we require that bridges turn their DirPort on
   -- which means both that we answer BEGIN_DIR requests and that we fetch
   and cache directory information in an aggressive way like other servers.
 
   But:
   a) we don't enforce that DirPort is on, since it's not clear how to
-  detect if the user meant to be a bridge. So it's easy to launch a bridge
+  detect if the user meant to be a bridge. So it's easy to set up a bridge
   relay that silently refuses BEGIN_DIR requests and is thus useless.
   b) We don't actually care if they have an open or reachable DirPort. So
   at some point we should separate having an open DirPort from answering
   directory questions. Which leads to:
   c) We need to investigate if there are any anonymity worries with
   answering BEGIN_DIR requests when our DirPort is off. If there aren't,
-  we can drop the DirPort requirement.
+  we should drop the DirPort requirement.
+
+  I claim that we don't open any new attacks by answering BEGIN_DIR
+  questions when DirPort is off: it's still a fine question to ask what
+  partitioning attacks there are when you can query a Tor client about
+  its current directory opinions, but these attacks already exist when
+  DirPort is on.
+
+  We need to answer this issue in 0.2.0.x.
 
 1.3. Exit policy
 
@@ -71,15 +81,15 @@ Status: Open
   Just as for operating normal relays, our documentation and hints for
   how to make your ORPort reachable are inadequate for normal users.
 
-  We need to work harder on this step.
+  We need to work harder on this step, perhaps in 0.2.1.x.
 
 1.6. Vidalia integration
 
-  Vidalia has turned into "Relay" settings page into a tri-state
-  "Don't relay" "Relay for the Tor network" "Help censored users".
+  Vidalia 0.0.15 has turned its "Relay" settings page into a tri-state
+  "Don't relay" / "Relay for the Tor network" / "Help censored users".
 
-  If the click the third choice, it forces your exit policy to reject *:*,
-  and it forces your DirPort to 9030 (see Sec 1.2 above about DirPort).
+  If you click the third choice, it forces your exit policy to reject *:*,
+  and it forces your DirPort to 9030 (but see Sec 1.2 above about DirPort).
 
   If all the bridges end up on port 9001, that's not so good. On the
   other hand, putting the bridges on a low-numbered port in the Unix
@@ -87,22 +97,39 @@ Status: Open
   that Vidalia makes the ORPort default to 443 on Windows, and 9001 on
   other platforms.
 
+  At the bottom of the relay config settings window, Vidalia displays
+  the bridge identifier to the operator (see Section 3.1) so he can pass
+  it on to bridge users.
+
+1.7. What if the default ORPort is already used?
+
+  If the user already has a webserver or some other application
+  bound to port 443, then Tor will fail to bind it and complain to the
+  user, probably in a cryptic way. Rather than just working on a better
+  error message (though we should do this), we should consider an
+  "ORPort auto" option that tells Tor to try to find something that's
+  bindable and reachable. This would also help us tolerate ISPs that
+  filter incoming connections on port 80 and port 443. But this should
+  be a different proposal, and can wait until 0.2.1.x.
+
 2. Bridge authorities.
 
   Bridge authorities are like normal directory authorities, except they
-  don't create their own network-status documents. So if you ask an
-  authority for a network-status document, they behave like a directory
-  mirror: they give you one from one of the main authorities. But if
-  you ask the bridge authority for a particular identity fingerprint,
-  it will happily give you the latest descriptor for that fingerprint.
+  don't create their own network-status documents or votes. So if you
+  ask an authority for a network-status document or consensus, they
+  behave like a directory mirror: they give you one from one of the main
+  authorities. But if you ask the bridge authority for the descriptor
+  corresponding to a particular identity fingerprint, it will happily
+  give you the latest descriptor for that fingerprint.
 
   Right now there's one bridge authority, running on the Tonga relay.
 
 2.1. Exporting bridge-purpose descriptors
 
-  We've added a new purpose for server descriptors, the "bridge"
-  purpose. With the new router-descriptors file that includes annotations,
-  it's easy to look through it and find the bridge-purpose descriptors.
+  We've added a new purpose for server descriptors: the "bridge"
+  purpose. With the new router-descriptors file format that includes
+  annotations, it's easy to look through it and find the bridge-purpose
+  descriptors.
 
   We should work with Tonga to export its router-descriptors file to
   some place where we can distribute the bridge addresses according to
@@ -113,33 +140,188 @@ Status: Open
 
 2.2. Reachability/uptime testing
 
-  should bridge relays publish anonymously to the bridge authority?
+  Right now the bridge authorities just passively collect bridge
+  descriptors, and give them out on request. At some point we are going
+  to want to recommend new bridges to users, and we'll want to have
+  some way of deciding which ones are up right now, which ones have
+  been around for a while, etc. We should have the bridge authorities
+  do active measurements of bridges just as the normal authorities do
+  active measurements of normal relays. Then we can export the results
+  just like in Section 2.1. above.
+
+  In the design document, we suggested that bridges should publish
+  anonymously (i.e. via Tor) to the bridge authority, so somebody watching
+  the bridge authority can't just enumerate all the bridges. But if we're
+  doing active measurement, the game is up. Perhaps we should back off on
+  this goal, or perhaps we should do our active measurement anonymously?
 
-  migrating to multiple bridge authorities
+  Answering this issue is scheduled for 0.2.1.x.
+
+2.3. Migrating to multiple bridge authorities
+
+  Having only one bridge authority is both a trust bottleneck (if you
+  break into one place you learn about every single bridge we've got)
+  and a robustness bottleneck (when it's down, bridge users become sad).
+
+  Right now if we put up a second bridge authority, all the bridges would
+  publish to it, and (assuming the code works) bridge users would query
+  a random bridge authority. This resolves the robustness bottleneck,
+  but makes the trust bottleneck even worse.
+
+  In 0.2.1.x and later we should think about better ways to have multiple
+  bridge authorities.
 
 3. Bridge users.
 
+  Bridge users are like ordinary Tor users except they use encrypted
+  directory connections by default, and they use bridge relays as both
+  entry guards (their first hop) and directory guards (the source of
+  all their directory information).
+
+  To become a bridge user, add the following two lines to your torrc:
+
     UseBridges 1
     TunnelDirConns 1
 
-  Format of the bridge identifier.
+  and then add at least one "Bridge" line to your torrc based on the
+  format below.
+
+3.1. Format of the bridge identifier.
+
+  The canonical format for a bridge identifier contains an IP address,
+  an ORPort, and an identity fingerprint:
+    bridge 128.31.0.34:9009 4C17 FB53 2E20 B2A8 AC19 9441 ECD2 B017 7B39 E4B1
+
+  However, the identity fingerprint can be left out, in which case the
+  bridge user will connect to that relay and use it as a bridge regardless
+  of what identity key it presents:
+    bridge 128.31.0.34:9009
+  This might be useful for cases where only short bridge identifiers
+  can be communicated to bridge users.
+
+  In a future version we may also support bridge identifiers that are
+  only a key fingerprint:
+    bridge 4C17 FB53 2E20 B2A8 AC19 9441 ECD2 B017 7B39 E4B1
+  and the bridge user can fetch the latest descriptor from the bridge
+  authority (see Section 3.4).
+
+3.2. Bridges as entry guards
+
+  For now, bridge users add their bridge relays to their list of "entry
+  guards" (see path-spec.txt for background on entry guards). They are
+  managed by the entry guard algorithms exactly as if they were a normal
+  entry guard -- their keys and timing get cached in the "state" file,
+  etc. This means that when the Tor user starts up with "UseBridges"
+  disabled, he will skip past the bridge entries since they won't be
+  listed as up and usable in his networkstatus consensus. But to be clear,
+  the "entry_guards" list doesn't currently distinguish guards by purpose.
+
+  Internally, each bridge user keeps a smartlist of "bridge_info_t"
+  that reflects the "bridge" lines from his torrc along with a download
+  schedule (see Section 3.5 below). When he starts Tor, he attempts
+  to fetch a descriptor for each configured bridge (see Section 3.4
+  below). When he succeeds at getting a descriptor for one of the bridges
+  in his list, he adds it directly to the entry guard list using the
+  normal add_an_entry_guard() interface. Once a bridge descriptor has
+  been added, should_delay_dir_fetches() will stop delaying further
+  directory fetches, and the user begins to bootstrap his directory
+  information from that bridge (see Section 3.3).
+
+  Currently bridge users cache their bridge descriptors to the
+  "cached-descriptors" file (annotated with purpose "bridge"), but
+  they don't make any attempt to reuse descriptors they find in this
+  file. The theory is that either the bridge is available now, in which
+  case you can get a fresh descriptor, or it's not, in which case an
+  old descriptor won't do you much good.
+
+  We could disable writing out the bridge lines to the state file, if
+  we think this is a problem.
+
+  As an exception, if we get an application request when we have one
+  or more bridge descriptors but we believe none of them are running,
+  we mark them all as running again. This is similar to the exception
+  already in place to help long-idle Tor clients realize they should
+  fetch fresh directory information rather than just refuse requests.
+
+3.3. Bridges as directory guards
+
+  In addition to using bridges as the first hop in their circuits, bridge
+  users also use them to fetch directory updates. Other than initial
+  bootstrapping to find a working bridge descriptor (see Section 3.4
+  below), all further non-anonymized directory fetches will be redirected
+  to the bridge.
+
+  This means that bridge relays need to have cached answers for all
+  questions the bridge user might ask. This makes the upgrade path
+  tricky --- for example, if we migrate to a v4 directory design, the
+  bridge user would need to keep using v3 so long as his bridge relays
+  only knew how to answer v3 queries.
+
+  In a future design, for cases where the user has enough information
+  to build circuits yet the chosen bridge doesn't know how to answer a
+  given query, we might teach bridge users to make an anonymized request
+  to a more suitable directory server.
+
+3.4. How bridge users get their bridge descriptor
+
+  Bridge users can fetch bridge descriptors in two ways: by going directly
+  to the bridge and asking for "/tor/server/authority", or by going to
+  the bridge authority and asking for "/tor/server/fp/ID". By default,
+  they will only try the direct queries. If the user sets
+    UpdateBridgesFromAuthority 1
+  in his config file, then he will try querying the bridge authority
+  first for bridges where he knows a digest (if he only knows an IP
+  address and ORPort, then his only option is a direct query).
 
-  bridges as entry guards
+  If the user has at least one working bridge, then he will do further
+  queries to the bridge authority through a full three-hop Tor circuit.
+  But when bootstrapping, he will make a direct begin_dir-style connection
+  to the bridge authority.
 
-  bridges as directory guards
+  As of Tor 0.2.0.10-alpha, if the user attempts to fetch a descriptor
+  from the bridge authority and it returns a 404 not found, the user
+  will automatically fall back to trying a direct query. Therefore it is
+  recommended that bridge users always set UpdateBridgesFromAuthority,
+  since at worst it will delay their fetches a little bit and notify
+  the bridge authority of the identity fingerprint (but not location)
+  of their intended bridges.
 
-    UpdateBridgesFromAuthority 1
+3.5. Bridge descriptor retry schedule
+
+  Bridge users try to fetch a descriptor for each bridge (using the
+  steps in Section 3.4 above) on startup. Whenever they receive a
+  bridge descriptor, they reschedule a new descriptor download for 1
+  hour from then.
+
+  If on the other hand it fails, they try again after 15 minutes for the
+  first attempt, after 15 minutes for the second attempt, and after 60
+  minutes for subsequent attempts.
 
-  when to use a one-hop circuit, when to use a three-hop, to reach
-  the directory authority
+  In 0.2.1.x we should come up with some smarter retry schedules.
 
-  bridge descriptor retry schedule
+3.6. Vidalia integration
+
+  Vidalia 0.0.15 has a new checkbox in its Network config window called
+  "My ISP blocks connections to the Tor network." Users who click that
+  box change their configuration to:
+    TunnelDirConns 1
+    PreferTunneledDirConns 1
+
+  Once the box is checked, there is also a section for adding bridge
+  identifiers. When at least one bridge identifier is present, Vidalia
+  also changes their config to:
+    UseBridges 1
+    UpdateBridgesFromAuthority 1
+  and updates their Bridge config option accordingly.
 
-  when to make TunnelDirConns default.
+3.7. When should we make TunnelDirConns default
 
-  Vidalia integration:
+  Right now Tor's directory requests can be filtered on the network,
+  and some tools used by Middle Eastern governments even do this. A user
+  who wants to circumvent these filters should click the above box in
+  Vidalia 0.0.15. But at what point should we make tunneled directory
+  requests the default?
 
-    vidalia looks up the geoip data for tor servers it knows about. which
-    is fine, except when they're bridges. now geoip.vidalia-project.net
-    is a place to go to learn bridge IP addresses.
+  Once proposal 124 (modified TLS handshake) is in place, we should
+  consider doing the switch. This might even be in the 0.2.0.x timeframe.