2 Tor directory protocol, version 2
4 0. Scope and preliminaries
6 This directory protocol is used by Tor version 0.1.1.x and 0.1.2.x. See
7 dir-spec-v1.txt for information on earlier versions, and dir-spec.txt
8 for information on later versions.
10 0.1. Goals and motivation
12 There were several problems with the way Tor handles directory information
13 in version 0.1.0.x and earlier. Here are the problems we try to fix with
14 this new design, already implemented in 0.1.1.x:
15 1. Directories were very large and use up a lot of bandwidth: clients
16 downloaded descriptors for all router several times an hour.
17 2. Every directory authority was a trust bottleneck: if a single
18 directory authority lied, it could make clients believe for a time an
19 arbitrarily distorted view of the Tor network.
20 3. Our current "verified server" system is kind of nonsensical.
22 4. Getting more directory authorities would add more points of failure
23 and worsen possible partitioning attacks.
25 There are two problems that remain unaddressed by this design.
26 5. Requiring every client to know about every router won't scale.
27 6. Requiring every directory cache to know every router won't scale.
29 We attempt to fix 1-4 here, and to build a solution that will work when we
30 figure out an answer for 5. We haven't thought at all about what to do
35 There is a small set (say, around 10) of semi-trusted directory
36 authorities. A default list of authorities is shipped with the Tor
37 software. Users can change this list, but are encouraged not to do so, in
38 order to avoid partitioning attacks.
40 Routers periodically upload signed "descriptors" to the directory
41 authorities describing their keys, capabilities, and other information.
42 Routers may act as directory mirrors (also called "caches"), to reduce
43 load on the directory authorities. They announce this in their
46 Each directory authority periodically generates and signs a compact
47 "network status" document that lists that authority's view of the current
48 descriptors and status for known routers, but which does not include the
49 descriptors themselves.
51 Directory mirrors download, cache, and re-serve network-status documents
54 Clients, directory mirrors, and directory authorities all use
55 network-status documents to find out when their list of routers is
56 out-of-date. If it is, they download any missing router descriptors.
57 Clients download missing descriptors from mirrors; mirrors and authorities
58 download from authorities. Descriptors are downloaded by the hash of the
59 descriptor, not by the server's identity key: this prevents servers from
60 attacking clients by giving them descriptors nobody else uses.
62 All directory information is uploaded and downloaded with HTTP.
64 Coordination among directory authorities is done client-side: clients
65 compute a vote-like algorithm among the network-status documents they
66 have, and base their decisions on the result.
68 1.1. What's different from 0.1.0.x?
70 Clients used to download a signed concatenated set of router descriptors
71 (called a "directory") from directory mirrors, regardless of which
72 descriptors had changed.
74 Between downloading directories, clients would download "network-status"
75 documents that would list which servers were supposed to running.
77 Clients would always believe the most recently published network-status
78 document they were served.
80 Routers used to upload fresh descriptors all the time, whether their keys
81 and other information had changed or not.
83 1.2. Document meta-format
85 Router descriptors, directories, and running-routers documents all obey the
86 following lightweight extensible information format.
88 The highest level object is a Document, which consists of one or more
89 Items. Every Item begins with a KeywordLine, followed by one or more
90 Objects. A KeywordLine begins with a Keyword, optionally followed by
91 whitespace and more non-newline characters, and ends with a newline. A
92 Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
93 An Object is a block of encoded data in pseudo-Open-PGP-style
98 Document ::= (Item | NL)+
99 Item ::= KeywordLine Object*
100 KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
101 Keyword = KeywordChar+
102 KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
103 ArgumentChar ::= any printing ASCII character except NL.
105 Object ::= BeginLine Base-64-encoded-data EndLine
106 BeginLine ::= "-----BEGIN " Keyword "-----" NL
107 EndLine ::= "-----END " Keyword "-----" NL
109 The BeginLine and EndLine of an Object must use the same keyword.
111 When interpreting a Document, software MUST ignore any KeywordLine that
112 starts with a keyword it doesn't recognize; future implementations MUST NOT
113 require current clients to understand any KeywordLine not currently
116 Other implementations that want to extend Tor's directory format MAY
117 introduce their own items. The keywords for extension items SHOULD start
118 with the characters "x-" or "X-", to guarantee that they will not conflict
119 with keywords used by future versions of Tor.
123 ORs SHOULD generate a new router descriptor whenever any of the
124 following events have occurred:
126 - A period of time (18 hrs by default) has passed since the last
127 time a descriptor was generated.
129 - A descriptor field other than bandwidth or uptime has changed.
131 - Bandwidth has changed by at least a factor of 2 from the last time a
132 descriptor was generated, and at least a given interval of time
133 (20 mins by default) has passed since then.
135 - Its uptime has been reset (by restarting).
137 After generating a descriptor, ORs upload it to every directory
138 authority they know, by posting it to the URL
140 http://<hostname:port>/tor/
142 2.1. Router descriptor format
144 Every router descriptor MUST start with a "router" Item; MUST end with a
145 "router-signature" Item and an extra NL; and MUST contain exactly one
146 instance of each of the following Items: "published" "onion-key"
147 "signing-key" "bandwidth".
149 A router descriptor MAY have zero or one of each of the following Items,
150 but MUST NOT have more than one: "contact", "uptime", "fingerprint",
151 "hibernating", "read-history", "write-history", "eventdns", "platform",
154 For historical reasons some options are prefixed with "opt ", for instance
155 "opt fingerprint". This "opt " prefix should be ignored with the second word
156 used as the keyword instead.
158 Additionally, a router descriptor MAY contain any number of "accept",
159 "reject", and "opt" Items. Other than "router" and "router-signature",
160 the items may appear in any order.
162 The items' formats are as follows:
163 "router" nickname address ORPort SocksPort DirPort
165 Indicates the beginning of a router descriptor. "address" must be an
166 IPv4 address in dotted-quad format. The last three numbers indicate
167 the TCP ports at which this OR exposes functionality. ORPort is a port
168 at which this OR accepts TLS connections for the main OR protocol;
169 SocksPort is deprecated and should always be 0; and DirPort is the
170 port at which this OR accepts directory-related HTTP connections. If
171 any port is not supported, the value 0 is given instead of a port
174 "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed
176 Estimated bandwidth for this router, in bytes per second. The
177 "average" bandwidth is the volume per second that the OR is willing to
178 sustain over long periods; the "burst" bandwidth is the volume that
179 the OR is willing to sustain in very short intervals. The "observed"
180 value is an estimate of the capacity this server can handle. The
181 server remembers the max bandwidth sustained output over any ten
182 second period in the past day, and another sustained input. The
183 "observed" value is the lesser of these two numbers.
187 A human-readable string describing the system on which this OR is
188 running. This MAY include the operating system, and SHOULD include
189 the name and version of the software implementing the Tor protocol.
191 "published" YYYY-MM-DD HH:MM:SS
193 The time, in GMT, when this descriptor was generated.
197 A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
198 hex, with a single space after every 4 characters) for this router's
199 identity key. A descriptor is considered invalid (and MUST be
200 rejected) if the fingerprint line does not match the public key.
204 If the value is 1, then the Tor server was hibernating when the
205 descriptor was published, and shouldn't be used to build circuits.
209 The number of seconds that this OR process has been running.
211 "onion-key" NL a public key in PEM format
213 This key is used to encrypt EXTEND cells for this OR. The key MUST be
214 accepted for at least 1 week after any new key is published in a
215 subsequent descriptor.
217 "signing-key" NL a public key in PEM format
219 The OR's long-term identity key.
224 These lines describe the rules that an OR follows when
225 deciding whether to allow a new stream to a given address. The
226 'exitpattern' syntax is described below. The rules are considered in
227 order; if no rule matches, the address will be accepted. For clarity,
228 the last such entry SHOULD be accept *:* or reject *:*.
230 "router-signature" NL Signature NL
232 The "SIGNATURE" object contains a signature of the PKCS1-padded
233 hash of the entire router descriptor, taken from the beginning of the
234 "router" line, through the newline after the "router-signature" line.
235 The router descriptor is invalid unless the signature is performed
236 with the router's identity key.
240 Describes a way to contact the server's administrator, preferably
241 including an email address and a PGP key fingerprint.
245 'Names' is a space-separated list of server nicknames or
246 hexdigests. If two ORs list one another in their "family" entries,
247 then OPs should treat them as a single OR for the purpose of path
250 For example, if node A's descriptor contains "family B", and node B's
251 descriptor contains "family A", then node A and node B should never
252 be used on the same circuit.
254 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
255 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
257 Declare how much bandwidth the OR has used recently. Usage is divided
258 into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
259 defines the end of the most recent interval. The numbers are the
260 number of bytes used in the most recent intervals, ordered from
265 Declare whether this version of Tor is using the newer enhanced
266 dns logic. Versions of Tor without eventdns SHOULD NOT be used for
267 reverse hostname lookups.
269 [All versions of Tor before 0.1.2.2-alpha should be assumed to have
270 this option set to 0 if it is not present. All Tor versions at
271 0.1.2.2-alpha or later should be assumed to have this option set to
272 1 if it is not present. Until 0.1.2.1-alpha-dev, this option was
273 not generated, even when eventdns was in use. With 0.2.0.1-alpha, the
274 old 'dnsworker' logic has been removed, rendering this option of
275 historical interest only.]
277 2.2. Nonterminals in router descriptors
279 nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
280 hexdigest ::= a '$', followed by 20 hexadecimal characters.
281 [Represents a server by the digest of its identity key.]
283 exitpattern ::= addrspec ":" portspec
284 portspec ::= "*" | port | port "-" port
285 port ::= an integer between 1 and 65535, inclusive.
286 [Some implementations incorrectly generate ports with value 0.
287 Implementations SHOULD accept this, and SHOULD NOT generate it.]
289 addrspec ::= "*" | ip4spec | ip6spec
290 ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
291 ip4 ::= an IPv4 address in dotted-quad format
292 ip4mask ::= an IPv4 mask in dotted-quad format
293 num_ip4_bits ::= an integer between 0 and 32
294 ip6spec ::= ip6 | ip6 "/" num_ip6_bits
295 ip6 ::= an IPv6 address, surrounded by square brackets.
296 num_ip6_bits ::= an integer between 0 and 128
300 Ports are required; if they are not included in the router
301 line, they must appear in the "ports" lines.
303 3. Network status format
305 Directory authorities generate, sign, and compress network-status
306 documents. Directory servers SHOULD generate a fresh network-status
307 document when the contents of such a document would be different from the
308 last one generated, and some time (at least one second, possibly longer)
309 has passed since the last one was generated.
311 The network status document contains a preamble, a set of router status
312 entries, and a signature, in that order.
314 We use the same meta-format as used for directories and router descriptors
315 in "tor-spec.txt". Implementations MAY insert blank lines
316 for clarity between sections; these blank lines are ignored.
317 Implementations MUST NOT depend on blank lines in any particular location.
319 As used here, "whitespace" is a sequence of 1 or more tab or space
322 The preamble contains:
324 "network-status-version" -- A document format version. For this
325 specification, the version is "2".
326 "dir-source" -- The authority's hostname, current IP address, and
327 directory port, all separated by whitespace.
328 "fingerprint" -- A base16-encoded hash of the signing key's
329 fingerprint, with no additional spaces added.
330 "contact" -- An arbitrary string describing how to contact the
331 directory server's administrator. Administrators should include at
332 least an email address and a PGP fingerprint.
333 "dir-signing-key" -- The directory server's public signing key.
334 "client-versions" -- A comma-separated list of recommended client
336 "server-versions" -- A comma-separated list of recommended server
338 "published" -- The publication time for this network-status object.
339 "dir-options" -- A set of flags, in any order, separated by whitespace:
340 "Names" if this directory authority performs name bindings.
341 "Versions" if this directory authority recommends software versions.
342 "BadExits" if the directory authority flags nodes that it believes
343 are performing incorrectly as exit nodes.
344 "BadDirectories" if the directory authority flags nodes that it
345 believes are performing incorrectly as directory caches.
347 The dir-options entry is optional. The "-versions" entries are required if
348 the "Versions" flag is present. The other entries are required and must
349 appear exactly once. The "network-status-version" entry must appear first;
350 the others may appear in any order. Implementations MUST ignore
351 additional arguments to the items above, and MUST ignore unrecognized
354 For each router, the router entry contains: (This format is designed for
357 "r" -- followed by the following elements, in order, separated by
360 - A hash of its identity key, encoded in base64, with trailing =
362 - A hash of its most recent descriptor, encoded in base64, with
363 trailing = signs removed. (The hash is calculated as for
364 computing the signature of a descriptor.)
365 - The publication time of its most recent descriptor, in the form
366 YYYY-MM-DD HH:MM:SS, in GMT.
369 - A directory port (or "0" for none")
370 "s" -- A series of whitespace-separated status flags, in any order:
371 "Authority" if the router is a directory authority.
372 "BadExit" if the router is believed to be useless as an exit node
373 (because its ISP censors it, because it is behind a restrictive
374 proxy, or for some similar reason).
375 "BadDirectory" if the router is believed to be useless as a
376 directory cache (because its directory port isn't working,
377 its bandwidth is always throttled, or for some similar
379 "Exit" if the router is useful for building general-purpose exit
381 "Fast" if the router is suitable for high-bandwidth circuits.
382 "Guard" if the router is suitable for use as an entry guard.
383 "Named" if the router's identity-nickname mapping is canonical,
384 and this authority binds names.
385 "Stable" if the router is suitable for long-lived circuits.
386 "Running" if the router is currently usable.
387 "Valid" if the router has been 'validated'.
388 "V2Dir" if the router implements this protocol.
389 "v" -- The version of the Tor protocol that this server is running. If
390 the value begins with "Tor" SP, the rest of the string is a Tor
391 version number, and the protocol is "The Tor protocol as supported
392 by the given version of Tor." Otherwise, if the value begins with
393 some other string, Tor has upgraded to a more sophisticated
394 protocol versioning system, and the protocol is "a version of the
395 Tor protocol more recent than any we recognize."
397 The "r" entry for each router must appear first and is required. The
398 "s" entry is optional (see Section 3.1 below for how the flags are
399 decided). Unrecognized flags on the "s" line and extra elements
400 on the "r" line must be ignored. The "v" line is optional.
402 The signature section contains:
404 "directory-signature" nickname-of-dirserver NL Signature
406 Signature is a signature of this network-status document
407 (the document up until the signature, including the line
408 "directory-signature <nick>\n"), using the directory authority's
411 We compress the network status list with zlib before transmitting it.
413 3.1. Establishing server status
415 (This section describes how directory authorities choose which status
416 flags to apply to routers, as of Tor 0.1.1.18-rc. Later directory
417 authorities MAY do things differently, so long as clients keep working
418 well. Clients MUST NOT depend on the exact behaviors in this section.)
420 In the below definitions, a router is considered "active" if it is
421 running, valid, and not hibernating.
423 "Valid" -- a router is 'Valid' if it is running a version of Tor not
424 known to be broken, and the directory authority has not blacklisted
427 "Named" -- Directory authority administrators may decide to support name
428 binding. If they do, then they must maintain a file of
429 nickname-to-identity-key mappings, and try to keep this file consistent
430 with other directory authorities. If they don't, they act as clients, and
431 report bindings made by other directory authorities (name X is bound to
432 identity Y if at least one binding directory lists it, and no directory
433 binds X to some other Y'.) A router is called 'Named' if the router
434 believes the given name should be bound to the given key.
436 "Running" -- A router is 'Running' if the authority managed to connect to
437 it successfully within the last 30 minutes.
439 "Stable" -- A router is 'Stable' if it is active, and either its
440 uptime is at least the median uptime for known active routers, or
441 its uptime is at least 30 days. Routers are never called stable if
442 they are running a version of Tor known to drop circuits stupidly.
443 (0.1.1.10-alpha through 0.1.1.16-rc are stupid this way.)
445 "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
446 in the top 7/8ths for known active routers.
448 "Guard" -- A router is a possible 'Guard' if it is 'Stable' and its
449 bandwidth is above median for known active routers. If the total
450 bandwidth of active non-BadExit Exit servers is less than one third
451 of the total bandwidth of all active servers, no Exit is listed as
454 "Authority" -- A router is called an 'Authority' if the authority
455 generating the network-status document believes it is an authority.
457 "V2Dir" -- A router supports the v2 directory protocol if it has an open
458 directory port, and it is running a version of the directory protocol that
459 supports the functionality clients need. (Currently, this is
460 0.1.1.9-alpha or later.)
462 Directory server administrators may label some servers or IPs as
463 blacklisted, and elect not to include them in their network-status lists.
465 Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
466 When there are more than 3 to choose from, authorities should first prefer
467 authorities to non-authorities, then prefer Running to non-Running, and
468 then prefer high-bandwidth to low-bandwidth. To 'disable' a server, the
469 authority *should* advertise it without the Running or Valid flag.
471 Thus, the network-status list includes all non-blacklisted,
472 non-expired, non-superseded descriptors.
474 4. Directory server operation
476 All directory authorities and directory mirrors ("directory servers")
477 implement this section, except as noted.
479 4.1. Accepting uploads (authorities only)
481 When a router posts a signed descriptor to a directory authority, the
482 authority first checks whether it is well-formed and correctly
483 self-signed. If it is, the authority next verifies that the nickname
484 in question is not already assigned to a router with a different
486 Finally, the authority MAY check that the router is not blacklisted
487 because of its key, IP, or another reason.
489 If the descriptor passes these tests, and the authority does not already
490 have a descriptor for a router with this public key, it accepts the
491 descriptor and remembers it.
493 If the authority _does_ have a descriptor with the same public key, the
494 newly uploaded descriptor is remembered if its publication time is more
495 recent than the most recent old descriptor for that router, and either:
496 - There are non-cosmetic differences between the old descriptor and the
498 - Enough time has passed between the descriptors' publication times.
499 (Currently, 12 hours.)
501 Differences between router descriptors are "non-cosmetic" if they would be
502 sufficient to force an upload as described in section 2 above.
504 Note that the "cosmetic difference" test only applies to uploaded
505 descriptors, not to descriptors that the authority downloads from other
508 4.2. Downloading network-status documents (authorities and caches)
510 All directory servers (authorities and mirrors) try to keep a fresh
511 set of network-status documents from every authority. To do so,
512 every 5 minutes, each authority asks every other authority for its
513 most recent network-status document. Every 15 minutes, each mirror
514 picks a random authority and asks it for the most recent network-status
515 documents for all the authorities the authority knows about (including
516 the chosen authority itself).
518 Directory servers and mirrors remember and serve the most recent
519 network-status document they have from each authority. Other
520 network-status documents don't need to be stored. If the most recent
521 network-status document is over 10 days old, it is discarded anyway.
522 Mirrors SHOULD store and serve network-status documents from authorities
523 they don't recognize, but SHOULD NOT use such documents for any other
524 purpose. Mirrors SHOULD discard network-status documents older than 48
527 4.3. Downloading and storing router descriptors (authorities and caches)
529 Periodically (currently, every 10 seconds), directory servers check
530 whether there are any specific descriptors (as identified by descriptor
531 hash in a network-status document) that they do not have and that they
532 are not currently trying to download.
534 If so, the directory server launches requests to the authorities for these
535 descriptors, such that each authority is only asked for descriptors listed
536 in its most recent network-status. When more than one authority lists the
537 descriptor, we choose which to ask at random.
539 If one of these downloads fails, we do not try to download that descriptor
540 from the authority that failed to serve it again unless we receive a newer
541 network-status from that authority that lists the same descriptor.
543 Directory servers must potentially cache multiple descriptors for each
544 router. Servers must not discard any descriptor listed by any current
545 network-status document from any authority. If there is enough space to
546 store additional descriptors, servers SHOULD try to hold those which
547 clients are likely to download the most. (Currently, this is judged
548 based on the interval for which each descriptor seemed newest.)
550 Authorities SHOULD NOT download descriptors for routers that they would
551 immediately reject for reasons listed in 3.1.
555 "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
557 The authoritative network-status published by a host should be available at:
558 http://<hostname>/tor/status/authority.z
560 The network-status published by a host with fingerprint
561 <F> should be available at:
562 http://<hostname>/tor/status/fp/<F>.z
564 The network-status documents published by hosts with fingerprints
565 <F1>,<F2>,<F3> should be available at:
566 http://<hostname>/tor/status/fp/<F1>+<F2>+<F3>.z
568 The most recent network-status documents from all known authorities,
569 concatenated, should be available at:
570 http://<hostname>/tor/status/all.z
572 The most recent descriptor for a server whose identity key has a
573 fingerprint of <F> should be available at:
574 http://<hostname>/tor/server/fp/<F>.z
576 The most recent descriptors for servers with identity fingerprints
577 <F1>,<F2>,<F3> should be available at:
578 http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
580 (NOTE: Implementations SHOULD NOT download descriptors by identity key
581 fingerprint. This allows a corrupted server (in collusion with a cache) to
582 provide a unique descriptor to a client, and thereby partition that client
583 from the rest of the network.)
585 The server descriptor with (descriptor) digest <D> (in hex) should be
587 http://<hostname>/tor/server/d/<D>.z
589 The most recent descriptors with digests <D1>,<D2>,<D3> should be
591 http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
593 The most recent descriptor for this server should be at:
594 http://<hostname>/tor/server/authority.z
595 [Nothing in the Tor protocol uses this resource yet, but it is useful
596 for debugging purposes. Also, the official Tor implementations
597 (starting at 0.1.1.x) use this resource to test whether a server's
598 own DirPort is reachable.]
600 A concatenated set of the most recent descriptors for all known servers
601 should be available at:
602 http://<hostname>/tor/server/all.z
604 For debugging, directories SHOULD expose non-compressed objects at URLs like
605 the above, but without the final ".z".
606 Clients MUST handle compressed concatenated information in two forms:
607 - A concatenated list of zlib-compressed objects.
608 - A zlib-compressed concatenated list of objects.
609 Directory servers MAY generate either format: the former requires less
610 CPU, but the latter requires less bandwidth.
612 Clients SHOULD use upper case letters (A-F) when base16-encoding
613 fingerprints. Servers MUST accept both upper and lower case fingerprints
616 5. Client operation: downloading information
618 Every Tor that is not a directory server (that is, those that do
619 not have a DirPort set) implements this section.
621 5.1. Downloading network-status documents
623 Each client maintains an ordered list of directory authorities.
624 Insofar as possible, clients SHOULD all use the same ordered list.
626 For each network-status document a client has, it keeps track of its
627 publication time *and* the time when the client retrieved it. Clients
628 consider a network-status document "live" if it was published within the
631 Clients try to have a live network-status document hours from *every*
632 authority, and try to periodically get new network-status documents from
633 each authority in rotation as follows:
635 If a client is missing a live network-status document for any
636 authority, it tries to fetch it from a directory cache. On failure,
637 the client waits briefly, then tries that network-status document
638 again from another cache. The client does not build circuits until it
639 has live network-status documents from more than half the authorities
640 it trusts, and it has descriptors for more than 1/4 of the routers
641 that it believes are running.
643 If the most recently _retrieved_ network-status document is over 30
644 minutes old, the client attempts to download a network-status document.
645 When choosing which documents to download, clients treat their list of
646 directory authorities as a circular ring, and begin with the authority
647 appearing immediately after the authority for their most recently
648 retrieved network-status document. If this attempt fails (either it
649 fails to download at all, or the one it gets is not as good as the
650 one it has), the client retries at other caches several times, before
651 moving on to the next network-status document in sequence.
653 Clients discard all network-status documents over 24 hours old.
655 If enough mirrors (currently 4) claim not to have a given network status,
656 we stop trying to download that authority's network-status, until we
657 download a new network-status that makes us believe that the authority in
658 question is running. Clients should wait a little longer after each
661 Clients SHOULD try to batch as many network-status requests as possible
664 (Note: clients can and should pick caches based on the network-status
665 information they have: once they have first fetched network-status info
666 from an authority, they should not need to go to the authority directly
669 5.2. Downloading and storing router descriptors
671 Clients try to have the best descriptor for each router. A descriptor is
673 * It is the most recently published descriptor listed for that router
674 by at least two network-status documents.
676 * No descriptor for that router is listed by two or more
677 network-status documents, and it is the most recently published
678 descriptor listed by any network-status document.
680 Periodically (currently every 10 seconds) clients check whether there are
681 any "downloadable" descriptors. A descriptor is downloadable if:
682 - It is the "best" descriptor for some router.
683 - The descriptor was published at least 10 minutes in the past.
684 (This prevents clients from trying to fetch descriptors that the
685 mirrors have probably not yet retrieved and cached.)
686 - The client does not currently have it.
687 - The client is not currently trying to download it.
688 - The client would not discard it immediately upon receiving it.
689 - The client thinks it is running and valid (see 6.1 below).
691 If at least 16 known routers have downloadable descriptors, or if
692 enough time (currently 10 minutes) has passed since the last time the
693 client tried to download descriptors, it launches requests for all
694 downloadable descriptors, as described in 5.3 below.
696 When a descriptor download fails, the client notes it, and does not
697 consider the descriptor downloadable again until a certain amount of time
698 has passed. (Currently 0 seconds for the first failure, 60 seconds for the
699 second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
700 thereafter.) Periodically (currently once an hour) clients reset the
703 No descriptors are downloaded until the client has downloaded more than
704 half of the network-status documents.
706 Clients retain the most recent descriptor they have downloaded for each
707 router so long as it is not too old (currently, 48 hours), OR so long as
708 it is recommended by at least one networkstatus AND no "better"
709 descriptor has been downloaded. [Versions of Tor before 0.1.2.3-alpha
710 would discard descriptors simply for being published too far in the past.]
711 [The code seems to discard descriptors in all cases after they're 5
714 5.3. Managing downloads
716 When a client has no live network-status documents, it downloads
717 network-status documents from a randomly chosen authority. In all other
718 cases, the client downloads from mirrors randomly chosen from among those
719 believed to be V2 directory servers. (This information comes from the
720 network-status documents; see 6 below.)
722 When downloading multiple router descriptors, the client chooses multiple
724 - At least 3 different mirrors are used, except when this would result
725 in more than one request for under 4 descriptors.
726 - No more than 128 descriptors are requested from a single mirror.
727 - Otherwise, as few mirrors as possible are used.
728 After choosing mirrors, the client divides the descriptors among them
731 After receiving any response client MUST discard any network-status
732 documents and descriptors that it did not request.
734 6. Using directory information
736 Everyone besides directory authorities uses the approaches in this section
737 to decide which servers to use and what their keys are likely to be.
738 (Directory authorities just believe their own opinions, as in 3.1 above.)
740 6.1. Choosing routers for circuits.
742 Tor implementations only pay attention to "live" network-status documents.
743 A network status is "live" if it is the most recently downloaded network
744 status document for a given directory server, and the server is a
745 directory server trusted by the client, and the network-status document is
746 no more than 1 day old.
748 For time-sensitive information, Tor implementations focus on "recent"
749 network-status documents. A network status is "recent" if it is live, and
750 if it was published in the last 60 minutes. If there are fewer
751 than 3 such documents, the most recently published 3 are "recent." If
752 there are fewer than 3 in all, all are "recent.")
754 Circuits SHOULD NOT be built until the client has enough directory
755 information: network-statuses (or failed attempts to download
756 network-statuses) for all authorities, network-statuses for at more than
757 half of the authorities, and descriptors for at least 1/4 of the servers
758 believed to be running.
760 A server is "listed" if it is included by more than half of the live
761 network status documents. Clients SHOULD NOT use unlisted servers.
763 Clients believe the flags "Valid", "Exit", "Fast", "Guard", "Stable", and
764 "V2Dir" about a given router when they are asserted by more than half of
765 the live network-status documents. Clients believe the flag "Running" if
766 it is listed by more than half of the recent network-status documents.
768 These flags are used as follows:
770 - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
773 - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
774 very-low-bandwidth circuits (such as introduction circuits).
776 - Clients SHOULD NOT use non-'Stable' routers for circuits that are
777 likely to need to be open for a very long time (such as those used for
778 IRC or SSH connections).
780 - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
783 - Clients SHOULD NOT download directory information from non-'V2Dir'
788 In order to provide human-memorable names for individual server
789 identities, some directory servers bind names to IDs. Clients handle
792 When a client encounters a name it has not mapped before:
794 If all the live "Naming" network-status documents the client has
795 claim that the name binds to some identity ID, and the client has at
796 least three live network-status documents, the client maps the name to
799 When a user tries to refer to a router with a name that does not have a
800 mapping under the above rules, the implementation SHOULD warn the user.
801 After giving the warning, the implementation MAY use a router that at
802 least one Naming authority maps the name to, so long as no other naming
803 authority maps that name to a different router. If no Naming authority
804 maps the name to a router, the implementation MAY use any router that
807 Not every router needs a nickname. When a router doesn't configure a
808 nickname, it publishes with the default nickname "Unnamed". Authorities
809 SHOULD NOT ever mark a router with this nickname as Named; client software
810 SHOULD NOT ever use a router in response to a user request for a router
813 6.3. Software versions
815 An implementation of Tor SHOULD warn when it has fetched (or has
816 attempted to fetch and failed four consecutive times) a network-status
817 for each authority, and it is running a software version
818 not listed on more than half of the live "Versioning" network-status
821 6.4. Warning about a router's status.
823 If a router tries to publish its descriptor to a Naming authority
824 that has its nickname mapped to another key, the router SHOULD
825 warn the operator that it is either using the wrong key or is using
826 an already claimed nickname.
828 If a router has fetched (or attempted to fetch and failed four
829 consecutive times) a network-status for every authority, and at
830 least one of the authorities is "Naming", and no live "Naming"
831 authorities publish a binding for the router's nickname, the
832 router MAY remind the operator that the chosen nickname is not
833 bound to this key at the authorities, and suggest contacting the
838 6.5. Router protocol versions
840 A client should believe that a router supports a given feature if that
841 feature is supported by the router or protocol versions in more than half
842 of the live networkstatus's "v" entries for that router. In other words,
843 if the "v" entries for some router are:
844 v Tor 0.0.8pre1 (from authority 1)
845 v Tor 0.1.2.11 (from authority 2)
846 v FutureProtocolDescription 99 (from authority 3)
847 then the client should believe that the router supports any feature
848 supported by 0.1.2.11.
850 This is currently equivalent to believing the median declared version for
851 a router in all live networkstatuses.
853 7. Standards compliance
855 All clients and servers MUST support HTTP 1.0.
859 Servers MAY set the Content-Length: header. Servers SHOULD set
860 Content-Encoding to "deflate" or "identity".
862 Servers MAY include an X-Your-Address-Is: header, whose value is the
863 apparent IP address of the client connecting to them (as a dotted quad).
864 For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
865 report the IP from which the circuit carrying the BEGIN_DIR stream reached
868 Servers SHOULD disable caching of multiple network statuses or multiple
869 router descriptors. Servers MAY enable caching of single descriptors,
870 single network statuses, the list of all router descriptors, a v1
871 directory, or a v1 running routers document. XXX mention times.
873 7.2. HTTP status codes
875 XXX We should write down what return codes dirservers send in what