path-spec.txt 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657
  1. Tor Path Specification
  2. Roger Dingledine
  3. Nick Mathewson
  4. Note: This is an attempt to specify Tor as currently implemented. Future
  5. versions of Tor will implement improved algorithms.
  6. This document tries to cover how Tor chooses to build circuits and assign
  7. streams to circuits. Other implementations MAY take other approaches, but
  8. implementors should be aware of the anonymity and load-balancing implications
  9. of their choices.
  10. THIS SPEC ISN'T DONE YET.
  11. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  12. NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
  13. "OPTIONAL" in this document are to be interpreted as described in
  14. RFC 2119.
  15. 1. General operation
  16. Tor begins building circuits as soon as it has enough directory
  17. information to do so (see section 5 of dir-spec.txt). Some circuits are
  18. built preemptively because we expect to need them later (for user
  19. traffic), and some are built because of immediate need (for user traffic
  20. that no current circuit can handle, for testing the network or our
  21. reachability, and so on).
  22. When a client application creates a new stream (by opening a SOCKS
  23. connection or launching a resolve request), we attach it to an appropriate
  24. open circuit if one exists, or wait if an appropriate circuit is
  25. in-progress. We launch a new circuit only
  26. if no current circuit can handle the request. We rotate circuits over
  27. time to avoid some profiling attacks.
  28. To build a circuit, we choose all the nodes we want to use, and then
  29. construct the circuit. Sometimes, when we want a circuit that ends at a
  30. given hop, and we have an appropriate unused circuit, we "cannibalize" the
  31. existing circuit and extend it to the new terminus.
  32. These processes are described in more detail below.
  33. This document describes Tor's automatic path selection logic only; path
  34. selection can be overridden by a controller (with the EXTENDCIRCUIT and
  35. ATTACHSTREAM commands). Paths constructed through these means may
  36. violate some constraints given below.
  37. 1.1. Terminology
  38. A "path" is an ordered sequence of nodes, not yet built as a circuit.
  39. A "clean" circuit is one that has not yet been used for any traffic.
  40. A "fast" or "stable" or "valid" node is one that has the 'Fast' or
  41. 'Stable' or 'Valid' flag
  42. set respectively, based on our current directory information. A "fast"
  43. or "stable" circuit is one consisting only of "fast" or "stable" nodes.
  44. In an "exit" circuit, the final node is chosen based on waiting stream
  45. requests if any, and in any case it avoids nodes with exit policy of
  46. "reject *:*". An "internal" circuit, on the other hand, is one where
  47. the final node is chosen just like a middle node (ignoring its exit
  48. policy).
  49. A "request" is a client-side stream or DNS resolve that needs to be
  50. served by a circuit.
  51. A "pending" circuit is one that we have started to build, but which has
  52. not yet completed.
  53. A circuit or path "supports" a request if it is okay to use the
  54. circuit/path to fulfill the request, according to the rules given below.
  55. A circuit or path "might support" a request if some aspect of the request
  56. is unknown (usually its target IP), but we believe the path probably
  57. supports the request according to the rules given below.
  58. 1.1. A server's bandwidth
  59. Old versions of Tor did not report bandwidths in network status
  60. documents, so clients had to learn them from the routers' advertised
  61. server descriptors.
  62. For versions of Tor prior to 0.2.1.17-rc, everywhere below where we
  63. refer to a server's "bandwidth", we mean its clipped advertised
  64. bandwidth, computed by taking the smaller of the 'rate' and
  65. 'observed' arguments to the "bandwidth" element in the server's
  66. descriptor. If a router's advertised bandwidth is greater than
  67. MAX_BELIEVABLE_BANDWIDTH (currently 10 MB/s), we clipped to that
  68. value.
  69. For more recent versions of Tor, we take the bandwidth value declared
  70. in the consensus, and fall back to the clipped advertised bandwidth
  71. only if the consensus does not have bandwidths listed.
  72. 2. Building circuits
  73. 2.1. When we build
  74. 2.1.1. Clients build circuits preemptively
  75. When running as a client, Tor tries to maintain at least a certain
  76. number of clean circuits, so that new streams can be handled
  77. quickly. To increase the likelihood of success, Tor tries to
  78. predict what circuits will be useful by choosing from among nodes
  79. that support the ports we have used in the recent past (by default
  80. one hour). Specifically, on startup Tor tries to maintain one clean
  81. fast exit circuit that allows connections to port 80, and at least
  82. two fast clean stable internal circuits in case we get a resolve
  83. request or hidden service request (at least three if we _run_ a
  84. hidden service).
  85. After that, Tor will adapt the circuits that it preemptively builds
  86. based on the requests it sees from the user: it tries to have two fast
  87. clean exit circuits available for every port seen within the past hour
  88. (each circuit can be adequate for many predicted ports -- it doesn't
  89. need two separate circuits for each port), and it tries to have the
  90. above internal circuits available if we've seen resolves or hidden
  91. service activity within the past hour. If there are 12 or more clean
  92. circuits open, it doesn't open more even if it has more predictions.
  93. Only stable circuits can "cover" a port that is listed in the
  94. LongLivedPorts config option. Similarly, hidden service requests
  95. to ports listed in LongLivedPorts make us create stable internal
  96. circuits.
  97. Note that if there are no requests from the user for an hour, Tor
  98. will predict no use and build no preemptive circuits.
  99. The Tor client SHOULD NOT store its list of predicted requests to a
  100. persistent medium.
  101. 2.1.2. Clients build circuits on demand
  102. Additionally, when a client request exists that no circuit (built or
  103. pending) might support, we create a new circuit to support the request.
  104. For exit connections, we pick an exit node that will handle the
  105. most pending requests (choosing arbitrarily among ties), launch a
  106. circuit to end there, and repeat until every unattached request
  107. might be supported by a pending or built circuit. For internal
  108. circuits, we pick an arbitrary acceptable path, repeating as needed.
  109. In some cases we can reuse an already established circuit if it's
  110. clean; see Section 2.3 (cannibalizing circuits) for details.
  111. 2.1.3. Servers build circuits for testing reachability and bandwidth
  112. Tor servers test reachability of their ORPort once they have
  113. successfully built a circuit (on start and whenever their IP address
  114. changes). They build an ordinary fast internal circuit with themselves
  115. as the last hop. As soon as any testing circuit succeeds, the Tor
  116. server decides it's reachable and is willing to publish a descriptor.
  117. We launch multiple testing circuits (one at a time), until we
  118. have NUM_PARALLEL_TESTING_CIRC (4) such circuits open. Then we
  119. do a "bandwidth test" by sending a certain number of relay drop
  120. cells down each circuit: BandwidthRate * 10 / CELL_NETWORK_SIZE
  121. total cells divided across the four circuits, but never more than
  122. CIRCWINDOW_START (1000) cells total. This exercises both outgoing and
  123. incoming bandwidth, and helps to jumpstart the observed bandwidth
  124. (see dir-spec.txt).
  125. Tor servers also test reachability of their DirPort once they have
  126. established a circuit, but they use an ordinary exit circuit for
  127. this purpose.
  128. 2.1.4. Hidden-service circuits
  129. See section 4 below.
  130. 2.1.5. Rate limiting of failed circuits
  131. If we fail to build a circuit N times in a X second period (see Section
  132. 2.3 for how this works), we stop building circuits until the X seconds
  133. have elapsed.
  134. XXXX
  135. 2.1.6. When to tear down circuits
  136. XXXX
  137. 2.2. Path selection and constraints
  138. We choose the path for each new circuit before we build it. We choose the
  139. exit node first, followed by the other nodes in the circuit. All paths
  140. we generate obey the following constraints:
  141. - We do not choose the same router twice for the same path.
  142. - We do not choose any router in the same family as another in the same
  143. path.
  144. - We do not choose more than one router in a given /16 subnet
  145. (unless EnforceDistinctSubnets is 0).
  146. - We don't choose any non-running or non-valid router unless we have
  147. been configured to do so. By default, we are configured to allow
  148. non-valid routers in "middle" and "rendezvous" positions.
  149. - If we're using Guard nodes, the first node must be a Guard (see 5
  150. below)
  151. - XXXX Choosing the length
  152. For "fast" circuits, we only choose nodes with the Fast flag. For
  153. non-"fast" circuits, all nodes are eligible.
  154. For all circuits, we weight node selection according to router bandwidth.
  155. We also weight the bandwidth of Exit and Guard flagged nodes depending on
  156. the fraction of total bandwidth that they make up and depending upon the
  157. position they are being selected for.
  158. These weights are published in the consensus, and are computed as described
  159. in Section 3.4.3 of dir-spec.txt. They are:
  160. Wgg - Weight for Guard-flagged nodes in the guard position
  161. Wgm - Weight for non-flagged nodes in the guard Position
  162. Wgd - Weight for Guard+Exit-flagged nodes in the guard Position
  163. Wmg - Weight for Guard-flagged nodes in the middle Position
  164. Wmm - Weight for non-flagged nodes in the middle Position
  165. Wme - Weight for Exit-flagged nodes in the middle Position
  166. Wmd - Weight for Guard+Exit flagged nodes in the middle Position
  167. Weg - Weight for Guard flagged nodes in the exit Position
  168. Wem - Weight for non-flagged nodes in the exit Position
  169. Wee - Weight for Exit-flagged nodes in the exit Position
  170. Wed - Weight for Guard+Exit-flagged nodes in the exit Position
  171. Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
  172. Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
  173. Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
  174. Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes
  175. Wbg - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
  176. Wbm - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
  177. Wbe - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
  178. Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
  179. Additionally, we may be building circuits with one or more requests in
  180. mind. Each kind of request puts certain constraints on paths:
  181. - All service-side introduction circuits and all rendezvous paths
  182. should be Stable.
  183. - All connection requests for connections that we think will need to
  184. stay open a long time require Stable circuits. Currently, Tor decides
  185. this by examining the request's target port, and comparing it to a
  186. list of "long-lived" ports. (Default: 21, 22, 706, 1863, 5050,
  187. 5190, 5222, 5223, 6667, 6697, 8300.)
  188. - DNS resolves require an exit node whose exit policy is not equivalent
  189. to "reject *:*".
  190. - Reverse DNS resolves require a version of Tor with advertised eventdns
  191. support (available in Tor 0.1.2.1-alpha-dev and later).
  192. - All connection requests require an exit node whose exit policy
  193. supports their target address and port (if known), or which "might
  194. support it" (if the address isn't known). See 2.2.1.
  195. - Rules for Fast? XXXXX
  196. 2.2.1. Choosing an exit
  197. If we know what IP address we want to connect to or resolve, we can
  198. trivially tell whether a given router will support it by simulating
  199. its declared exit policy.
  200. Because we often connect to addresses of the form hostname:port, we do not
  201. always know the target IP address when we select an exit node. In these
  202. cases, we need to pick an exit node that "might support" connections to a
  203. given address port with an unknown address. An exit node "might support"
  204. such a connection if any clause that accepts any connections to that port
  205. precedes all clauses (if any) that reject all connections to that port.
  206. Unless requested to do so by the user, we never choose an exit server
  207. flagged as "BadExit" by more than half of the authorities who advertise
  208. themselves as listing bad exits.
  209. 2.2.2. User configuration
  210. Users can alter the default behavior for path selection with configuration
  211. options.
  212. - If "ExitNodes" is provided, then every request requires an exit node on
  213. the ExitNodes list. (If a request is supported by no nodes on that list,
  214. and StrictExitNodes is false, then Tor treats that request as if
  215. ExitNodes were not provided.)
  216. - "EntryNodes" and "StrictEntryNodes" behave analogously.
  217. - If a user tries to connect to or resolve a hostname of the form
  218. <target>.<servername>.exit, the request is rewritten to a request for
  219. <target>, and the request is only supported by the exit whose nickname
  220. or fingerprint is <servername>.
  221. 2.3. Cannibalizing circuits
  222. If we need a circuit and have a clean one already established, in
  223. some cases we can adapt the clean circuit for our new
  224. purpose. Specifically,
  225. For hidden service interactions, we can "cannibalize" a clean internal
  226. circuit if one is available, so we don't need to build those circuits
  227. from scratch on demand.
  228. We can also cannibalize clean circuits when the client asks to exit
  229. at a given node -- either via the ".exit" notation or because the
  230. destination is running at the same location as an exit node.
  231. 2.4. Learning when to give up ("timeout") on circuit construction
  232. Since version 0.2.2.8-alpha, Tor attempts to learn when to give up on
  233. circuits based on network conditions.
  234. 2.4.1 Distribution choice and parameter estimation
  235. Based on studies of build times, we found that the distribution of
  236. circuit build times appears to be a Frechet distribution. However,
  237. estimators and quantile functions of the Frechet distribution are
  238. difficult to work with and slow to converge. So instead, since we
  239. are only interested in the accuracy of the tail, we approximate
  240. the tail of the distribution with a Pareto curve.
  241. We calculate the parameters for a Pareto distribution fitting the data
  242. using the estimators in equation 4 from:
  243. http://portal.acm.org/citation.cfm?id=1647962.1648139
  244. This is:
  245. alpha_m = s/(ln(U(X)/Xm^n))
  246. where s is the total number of completed circuits we have seen, and
  247. U(X) = x_max^u * Prod_s{x_i}
  248. with x_i as our i-th completed circuit time, x_max as the longest
  249. completed circuit build time we have yet observed, u as the
  250. number of unobserved timeouts that have no exact value recorded,
  251. and n as u+s, the total number of circuits that either timeout or
  252. complete.
  253. Using log laws, we compute this as the sum of logs to avoid
  254. overflow and ln(1.0+epsilon) precision issues:
  255. alpha_m = s/(u*ln(x_max) + Sum_s{ln(x_i)} - n*ln(Xm))
  256. This estimator is closely related to the parameters present in:
  257. http://en.wikipedia.org/wiki/Pareto_distribution#Parameter_estimation
  258. except they are adjusted to handle the fact that our samples are
  259. right-censored at the timeout cutoff.
  260. Additionally, because this is not a true Pareto distribution, we alter
  261. how Xm is computed. The Xm parameter is computed as the midpoint of the most
  262. frequently occurring 50ms histogram bin, until the point where 1000
  263. circuits are recorded. After this point, the weighted average of the top
  264. 'cbtnummodes' (default: 3) midpoint modes is used as Xm. All times below
  265. this value are counted as having the midpoint value of this weighted average bin.
  266. The timeout itself is calculated by using the Pareto Quantile function (the
  267. inverted CDF) to give us the value on the CDF such that 80% of the mass
  268. of the distribution is below the timeout value.
  269. Thus, we expect that the Tor client will accept the fastest 80% of
  270. the total number of paths on the network.
  271. 2.4.2. How much data to record
  272. From our observations, the minimum number of circuit build times for a
  273. reasonable fit appears to be on the order of 100. However, to keep a
  274. good fit over the long term, we store 1000 most recent circuit build times
  275. in a circular array.
  276. The Tor client should build test circuits at a rate of one per
  277. minute up until 100 circuits are built. This allows a fresh Tor to have
  278. a CircuitBuildTimeout estimated within 1.5 hours after install,
  279. upgrade, or network change (see below).
  280. Timeouts are stored on disk in a histogram of 50ms bin width, the same
  281. width used to calculate the Xm value above. This histogram must be shuffled
  282. after being read from disk, to preserve a proper expiration of old values
  283. after restart.
  284. 2.4.3. How to record timeouts
  285. Circuits that pass the timeout threshold should be allowed to continue
  286. building until a time corresponding to the point 'cbtclosequantile'
  287. (default 95) on the Pareto curve, or 60 seconds, whichever is greater.
  288. The actual completion times for these circuits should be recorded.
  289. Implementations should completely abandon a circuit and record a value
  290. as an 'unknown' timeout if the total build time exceeds this threshold.
  291. The reason for this is that right-censored pareto estimators begin to lose
  292. their accuracy if more than approximately 5% of the values are censored.
  293. Since we wish to set the cutoff at 20%, we must allow circuits to continue
  294. building past this cutoff point up to the 95th percentile.
  295. 2.4.4. Detecting Changing Network Conditions
  296. We attempt to detect both network connectivity loss and drastic
  297. changes in the timeout characteristics.
  298. We assume that we've had network connectivity loss if 3 circuits
  299. timeout and we've received no cells or TLS handshakes since those
  300. circuits began. We then temporarily set the timeout to 60 seconds
  301. and stop counting timeouts.
  302. If 3 more circuits timeout and the network still has not been
  303. live within this new 60 second timeout window, we then discard
  304. the previous timeouts during this period from our history.
  305. To detect changing network conditions, we keep a history of
  306. the timeout or non-timeout status of the past 20 circuits that
  307. successfully completed at least one hop. If more than 90% of
  308. these circuits timeout, we discard all buildtimes history, reset
  309. the timeout to 60, and then begin recomputing the timeout.
  310. If the timeout was already 60 or higher, we double the timeout.
  311. 2.4.5. Consensus parameters governing behavior
  312. Clients that implement circuit build timeout learning should obey the
  313. following consensus parameters that govern behavior, in order to allow
  314. us to handle bugs or other emergent behaviors due to client circuit
  315. construction. If these parameters are not present in the consensus,
  316. the listed default values should be used instead.
  317. cbtdisabled
  318. Default: 0
  319. Min: 0
  320. Max: 1
  321. Effect: If 1, all CircuitBuildTime learning code should be
  322. disabled and history should be discarded. For use in
  323. emergency situations only.
  324. cbtnummodes
  325. Default: 3
  326. Min: 1
  327. Max: 20
  328. Effect: This value governs how many modes to use in the weighted
  329. average calculation of Pareto parameter Xm. A value of 3 introduces
  330. some bias (2-5% of CDF) under ideal conditions, but allows for better
  331. performance in the event that a client chooses guard nodes of radically
  332. different performance characteristics.
  333. cbtrecentcount
  334. Default: 20
  335. Min: 3
  336. Max: 1000
  337. Effect: This is the number of circuit build times to keep track of
  338. for the following option.
  339. cbtmaxtimeouts
  340. Default: 18
  341. Min: 3
  342. Max: 10000
  343. Effect: When this many timeouts happen in the last 'cbtrecentcount'
  344. circuit attempts, the client should discard all of its
  345. history and begin learning a fresh timeout value.
  346. cbtmincircs
  347. Default: 100
  348. Min: 1
  349. Max: 10000
  350. Effect: This is the minimum number of circuits to build before
  351. computing a timeout.
  352. cbtquantile
  353. Default: 80
  354. Min: 10
  355. Max: 99
  356. Effect: This is the position on the quantile curve to use to set the
  357. timeout value. It is a percent (10-99).
  358. cbtclosequantile
  359. Default: 95
  360. Min: Value of cbtquantile parameter
  361. Max: 99
  362. Effect: This is the position on the quantile curve to use to set the
  363. timeout value to use to actually close circuits. It is a percent
  364. (0-99).
  365. cbttestfreq
  366. Default: 60
  367. Min: 1
  368. Max: 2147483647 (INT32_MAX)
  369. Effect: Describes how often in seconds to build a test circuit to
  370. gather timeout values. Only applies if less than 'cbtmincircs'
  371. have been recorded.
  372. cbtmintimeout
  373. Default: 2000
  374. Min: 500
  375. Max: 2147483647 (INT32_MAX)
  376. Effect: This is the minimum allowed timeout value in milliseconds.
  377. The minimum is to prevent rounding to 0 (we only check once
  378. per second).
  379. cbtinitialtimeout
  380. Default: 60000
  381. Min: Value of cbtmintimeout
  382. Max: 2147483647 (INT32_MAX)
  383. Effect: This is the timeout value to use before computing a timeout,
  384. in milliseconds.
  385. 2.5. Handling failure
  386. If an attempt to extend a circuit fails (either because the first create
  387. failed or a subsequent extend failed) then the circuit is torn down and is
  388. no longer pending. (XXXX really?) Requests that might have been
  389. supported by the pending circuit thus become unsupported, and a new
  390. circuit needs to be constructed.
  391. If a stream "begin" attempt fails with an EXITPOLICY error, we
  392. decide that the exit node's exit policy is not correctly advertised,
  393. so we treat the exit node as if it were a non-exit until we retrieve
  394. a fresh descriptor for it.
  395. XXXX
  396. 3. Attaching streams to circuits
  397. When a circuit that might support a request is built, Tor tries to attach
  398. the request's stream to the circuit and sends a BEGIN, BEGIN_DIR,
  399. or RESOLVE relay
  400. cell as appropriate. If the request completes unsuccessfully, Tor
  401. considers the reason given in the CLOSE relay cell. [XXX yes, and?]
  402. After a request has remained unattached for SocksTimeout (2 minutes
  403. by default), Tor abandons the attempt and signals an error to the
  404. client as appropriate (e.g., by closing the SOCKS connection).
  405. XXX Timeouts and when Tor auto-retries.
  406. * What stream-end-reasons are appropriate for retrying.
  407. If no reply to BEGIN/RESOLVE, then the stream will timeout and fail.
  408. 4. Hidden-service related circuits
  409. XXX Tracking expected hidden service use (client-side and hidserv-side)
  410. 5. Guard nodes
  411. We use Guard nodes (also called "helper nodes" in the literature) to
  412. prevent certain profiling attacks. Here's the risk: if we choose entry and
  413. exit nodes at random, and an attacker controls C out of N servers
  414. (ignoring bandwidth), then the
  415. attacker will control the entry and exit node of any given circuit with
  416. probability (C/N)^2. But as we make many different circuits over time,
  417. then the probability that the attacker will see a sample of about (C/N)^2
  418. of our traffic goes to 1. Since statistical sampling works, the attacker
  419. can be sure of learning a profile of our behavior.
  420. If, on the other hand, we picked an entry node and held it fixed, we would
  421. have probability C/N of choosing a bad entry and being profiled, and
  422. probability (N-C)/N of choosing a good entry and not being profiled.
  423. When guard nodes are enabled, Tor maintains an ordered list of entry nodes
  424. as our chosen guards, and stores this list persistently to disk. If a Guard
  425. node becomes unusable, rather than replacing it, Tor adds new guards to the
  426. end of the list. When choosing the first hop of a circuit, Tor
  427. chooses at
  428. random from among the first NumEntryGuards (default 3) usable guards on the
  429. list. If there are not at least 2 usable guards on the list, Tor adds
  430. routers until there are, or until there are no more usable routers to add.
  431. A guard is unusable if any of the following hold:
  432. - it is not marked as a Guard by the networkstatuses,
  433. - it is not marked Valid (and the user hasn't set AllowInvalid entry)
  434. - it is not marked Running
  435. - Tor couldn't reach it the last time it tried to connect
  436. A guard is unusable for a particular circuit if any of the rules for path
  437. selection in 2.2 are not met. In particular, if the circuit is "fast"
  438. and the guard is not Fast, or if the circuit is "stable" and the guard is
  439. not Stable, or if the guard has already been chosen as the exit node in
  440. that circuit, Tor can't use it as a guard node for that circuit.
  441. If the guard is excluded because of its status in the networkstatuses for
  442. over 30 days, Tor removes it from the list entirely, preserving order.
  443. If Tor fails to connect to an otherwise usable guard, it retries
  444. periodically: every hour for six hours, every 4 hours for 3 days, every
  445. 18 hours for a week, and every 36 hours thereafter. Additionally, Tor
  446. retries unreachable guards the first time it adds a new guard to the list,
  447. since it is possible that the old guards were only marked as unreachable
  448. because the network was unreachable or down.
  449. Tor does not add a guard persistently to the list until the first time we
  450. have connected to it successfully.
  451. 6. Router descriptor purposes
  452. There are currently three "purposes" supported for router descriptors:
  453. general, controller, and bridge. Most descriptors are of type general
  454. -- these are the ones listed in the consensus, and the ones fetched
  455. and used in normal cases.
  456. Controller-purpose descriptors are those delivered by the controller
  457. and labelled as such: they will be kept around (and expire like
  458. normal descriptors), and they can be used by the controller in its
  459. CIRCUITEXTEND commands. Otherwise they are ignored by Tor when it
  460. chooses paths.
  461. Bridge-purpose descriptors are for routers that are used as bridges. See
  462. doc/design-paper/blocking.pdf for more design explanation, or proposal
  463. 125 for specific details. Currently bridge descriptors are used in place
  464. of normal entry guards, for Tor clients that have UseBridges enabled.
  465. X. Old notes
  466. X.1. Do we actually do this?
  467. How to deal with network down.
  468. - While all helpers are down/unreachable and there are no established
  469. or on-the-way testing circuits, launch a testing circuit. (Do this
  470. periodically in the same way we try to establish normal circuits
  471. when things are working normally.)
  472. (Testing circuits are a special type of circuit, that streams won't
  473. attach to by accident.)
  474. - When a testing circuit succeeds, mark all helpers up and hold
  475. the testing circuit open.
  476. - If a connection to a helper succeeds, close all testing circuits.
  477. Else mark that helper down and try another.
  478. - If the last helper is marked down and we already have a testing
  479. circuit established, then add the first hop of that testing circuit
  480. to the end of our helper node list, close that testing circuit,
  481. and go back to square one. (Actually, rather than closing the
  482. testing circuit, can we get away with converting it to a normal
  483. circuit and beginning to use it immediately?)
  484. [Do we actually do any of the above? If so, let's spec it. If not, let's
  485. remove it. -NM]
  486. X.2. A thing we could do to deal with reachability.
  487. And as a bonus, it leads to an answer to Nick's attack ("If I pick
  488. my helper nodes all on 18.0.0.0:*, then I move, you'll know where I
  489. bootstrapped") -- the answer is to pick your original three helper nodes
  490. without regard for reachability. Then the above algorithm will add some
  491. more that are reachable for you, and if you move somewhere, it's more
  492. likely (though not certain) that some of the originals will become useful.
  493. Is that smart or just complex?
  494. X.3. Some stuff that worries me about entry guards. 2006 Jun, Nickm.
  495. It is unlikely for two users to have the same set of entry guards.
  496. Observing a user is sufficient to learn its entry guards. So, as we move
  497. around, entry guards make us linkable. If we want to change guards when
  498. our location (IP? subnet?) changes, we have two bad options. We could
  499. - Drop the old guards. But if we go back to our old location,
  500. we'll not use our old guards. For a laptop that sometimes gets used
  501. from work and sometimes from home, this is pretty fatal.
  502. - Remember the old guards as associated with the old location, and use
  503. them again if we ever go back to the old location. This would be
  504. nasty, since it would force us to record where we've been.
  505. [Do we do any of this now? If not, this should move into 099-misc or
  506. 098-todo. -NM]