1 Filename: 125-bridges.txt
2 Title: Behavior for bridge users, bridge relays, and bridge authorities
5 Author: Roger Dingledine
8 Implemented-In: 0.2.0.x
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.
17 For more details on what all of these mean, look at blocking.tex in
22 Bridge relays are just like normal Tor relays except they don't publish
23 their server descriptors to the main directory authorities.
25 1.1. PublishServerDescriptor
27 To configure your relay to be a bridge relay, just add
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.
33 Alternatively, you can say
35 PublishServerDescriptor 0
36 which will cause your relay to not publish anywhere. This could be
37 useful for private bridges.
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.
46 1.3. RelayBandwidthRate / RelayBandwidthBurst
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.
52 1.4. Helping the user with port forwarding, NAT, etc.
54 Just as for operating normal relays, our documentation and hints for
55 how to make your ORPort reachable are inadequate for normal users.
57 We need to work harder on this step, perhaps in 0.2.2.x.
59 1.5. Vidalia integration
61 Vidalia has turned its "Relay" settings page into a tri-state
62 "Don't relay" / "Relay for the Tor network" / "Help censored users".
64 If you click the third choice, it forces your exit policy to reject *:*.
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
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.
76 1.6. What if the default ORPort is already used?
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.
87 2. Bridge authorities.
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.
97 To become a bridge authority, add these lines to your torrc:
98 AuthoritativeDirectory 1
99 BridgeAuthoritativeDir 1
101 Right now there's one bridge authority, running on the Tonga relay.
103 2.1. Exporting bridge-purpose descriptors
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
110 Currently we export the bridge descriptors from Tonga to the
111 BridgeDB server, so it can give them out according to the policies
114 2.2. Reachability/uptime testing
116 Right now the bridge authorities do active reachability testing of
117 bridges, so we know which ones to recommend for users.
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?
125 Answering this issue is scheduled for 0.2.1.x.
127 2.3. Migrating to multiple bridge authorities
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).
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.
138 In 0.2.2.x and later we should think about better ways to have multiple
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).
148 To become a bridge user, add the following line to your torrc:
152 and then add at least one "Bridge" line to your torrc based on the
155 3.1. Format of the bridge identifier.
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
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.
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).
174 3.2. Bridges as entry guards
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.
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).
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.
203 We could disable writing out the bridge lines to the state file, if
204 we think this is a problem.
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.
212 3.3. Bridges as directory guards
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
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.
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.
231 3.4. How bridge users get their bridge descriptor
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).
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.
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.
255 3.5. Bridge descriptor retry schedule
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
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.
266 In 0.2.2.x we should come up with some smarter retry schedules.
268 3.6. Vidalia integration
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:
274 UpdateBridgesFromAuthority 1
275 and should specify at least one Bridge identifier.
277 3.7. Do we need a second layer of entry guards?
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).
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.
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?
292 We should figure this out in the 0.2.1.x timeframe.