bridges-spec.txt 11 KB

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