add mike's triangle boy analysis
[torspec/rransom.git] / dir-spec-v2.txt
blobd1be27f3dbf78644e9e499b6df013719b40eba9e
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
31    about 6.
33 1. Outline
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
44    descriptors.
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
52    to clients.
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
94   armor. (cf. RFC 2440)
96   More formally:
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.
104     WS = (SP | TAB)+
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
114   described.
116   The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
117   extensions.  All implementations MUST ignore any item of the form "opt
118   keyword ....." when they would not recognize "keyword ....."; and MUST
119   treat "opt keyword ....."  as synonymous with "keyword ......" when keyword
120   is recognized.
122   Implementations before 0.1.2.5-alpha rejected any document with a
123   KeywordLine that started with a keyword that they didn't recognize.
124   Implementations MUST prefix items not recognized by older versions of Tor
125   with an "opt" until those versions of Tor are obsolete.
127   Other implementations that want to extend Tor's directory format MAY
128   introduce their own items.  The keywords for extension items SHOULD start
129   with the characters "x-" or "X-", to guarantee that they will not conflict
130   with keywords used by future versions of Tor.
132 2. Router operation
134    ORs SHOULD generate a new router descriptor whenever any of the
135    following events have occurred:
137       - A period of time (18 hrs by default) has passed since the last
138         time a descriptor was generated.
140       - A descriptor field other than bandwidth or uptime has changed.
142       - Bandwidth has changed by at least a factor of 2 from the last time a
143         descriptor was generated, and at least a given interval of time
144         (20 mins by default) has passed since then.
146       - Its uptime has been reset (by restarting).
148    After generating a descriptor, ORs upload it to every directory
149    authority they know, by posting it to the URL
151       http://<hostname:port>/tor/
153 2.1. Router descriptor format
155    Every router descriptor MUST start with a "router" Item; MUST end with a
156    "router-signature" Item and an extra NL; and MUST contain exactly one
157    instance of each of the following Items: "published" "onion-key"
158    "signing-key" "bandwidth". 
160    A router descriptor MAY have zero or one of each of the following Items,
161    but MUST NOT have more than one: "contact", "uptime", "fingerprint",
162    "hibernating", "read-history", "write-history", "eventdns", "platform",
163    "family".
165    Additionally, a router descriptor MAY contain any number of "accept",
166    "reject", and "opt" Items.  Other than "router" and "router-signature",
167    the items may appear in any order.
169    The items' formats are as follows:
170     "router" nickname address ORPort SocksPort DirPort
172        Indicates the beginning of a router descriptor.  "address" must be an
173        IPv4 address in dotted-quad format. The last three numbers indicate
174        the TCP ports at which this OR exposes functionality. ORPort is a port
175        at which this OR accepts TLS connections for the main OR protocol;
176        SocksPort is deprecated and should always be 0; and DirPort is the
177        port at which this OR accepts directory-related HTTP connections.  If
178        any port is not supported, the value 0 is given instead of a port
179        number.
181     "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed
183        Estimated bandwidth for this router, in bytes per second.  The
184        "average" bandwidth is the volume per second that the OR is willing to
185        sustain over long periods; the "burst" bandwidth is the volume that
186        the OR is willing to sustain in very short intervals.  The "observed"
187        value is an estimate of the capacity this server can handle.  The
188        server remembers the max bandwidth sustained output over any ten
189        second period in the past day, and another sustained input.  The
190        "observed" value is the lesser of these two numbers.
192     "platform" string
194        A human-readable string describing the system on which this OR is
195        running.  This MAY include the operating system, and SHOULD include
196        the name and version of the software implementing the Tor protocol.
198     "published" YYYY-MM-DD HH:MM:SS
200        The time, in GMT, when this descriptor was generated.
202     "fingerprint"
204        A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
205        hex, with a single space after every 4 characters) for this router's
206        identity key. A descriptor is considered invalid (and MUST be
207        rejected) if the fingerprint line does not match the public key.
209        [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
210         be marked with "opt" until earlier versions of Tor are obsolete.]
212     "hibernating" 0|1
214        If the value is 1, then the Tor server was hibernating when the
215        descriptor was published, and shouldn't be used to build circuits.
217        [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
218         marked with "opt" until earlier versions of Tor are obsolete.]
220     "uptime"
222        The number of seconds that this OR process has been running.
224     "onion-key" NL a public key in PEM format
226        This key is used to encrypt EXTEND cells for this OR.  The key MUST be
227        accepted for at least 1 week after any new key is published in a
228        subsequent descriptor.
230     "signing-key" NL a public key in PEM format
232        The OR's long-term identity key.
234     "accept" exitpattern
235     "reject" exitpattern
237        These lines describe the rules that an OR follows when
238        deciding whether to allow a new stream to a given address.  The
239        'exitpattern' syntax is described below.  The rules are considered in
240        order; if no rule matches, the address will be accepted.  For clarity,
241        the last such entry SHOULD be accept *:* or reject *:*.
243     "router-signature" NL Signature NL
245        The "SIGNATURE" object contains a signature of the PKCS1-padded
246        hash of the entire router descriptor, taken from the beginning of the
247        "router" line, through the newline after the "router-signature" line.
248        The router descriptor is invalid unless the signature is performed
249        with the router's identity key.
251     "contact" info NL
253         Describes a way to contact the server's administrator, preferably
254         including an email address and a PGP key fingerprint.
256     "family" names NL
258         'Names' is a space-separated list of server nicknames or
259         hexdigests. If two ORs list one another in their "family" entries,
260         then OPs should treat them as a single OR for the purpose of path
261         selection.
263         For example, if node A's descriptor contains "family B", and node B's
264         descriptor contains "family A", then node A and node B should never
265         be used on the same circuit.
267     "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
268     "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
270         Declare how much bandwidth the OR has used recently. Usage is divided
271         into intervals of NSEC seconds.  The YYYY-MM-DD HH:MM:SS field
272         defines the end of the most recent interval.  The numbers are the
273         number of bytes used in the most recent intervals, ordered from
274         oldest to newest.
276         [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
277          be marked with "opt" until earlier versions of Tor are obsolete.]
279     "eventdns" bool NL
281         Declare whether this version of Tor is using the newer enhanced
282         dns logic.  Versions of Tor without eventdns SHOULD NOT be used for
283         reverse hostname lookups.
285         [All versions of Tor before 0.1.2.2-alpha should be assumed to have
286          this option set to 0 if it is not present.  All Tor versions at
287          0.1.2.2-alpha or later should be assumed to have this option set to
288          1 if it is not present.  Until 0.1.2.1-alpha-dev, this option was
289          not generated, even when eventdns was in use.  Versions of Tor
290          before 0.1.2.1-alpha-dev did not parse this option, so it should be
291          marked "opt".  With 0.2.0.1-alpha, the old 'dnsworker' logic has
292          been removed, rendering this option of historical interest only.]
294 2.2. Nonterminals in router descriptors
296    nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
297    hexdigest ::= a '$', followed by 20 hexadecimal characters.
298       [Represents a server by the digest of its identity key.]
300    exitpattern ::= addrspec ":" portspec
301    portspec ::= "*" | port | port "-" port
302    port ::= an integer between 1 and 65535, inclusive.
303       [Some implementations incorrectly generate ports with value 0.
304        Implementations SHOULD accept this, and SHOULD NOT generate it.]
306    addrspec ::= "*" | ip4spec | ip6spec
307    ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
308    ip4 ::= an IPv4 address in dotted-quad format
309    ip4mask ::= an IPv4 mask in dotted-quad format
310    num_ip4_bits ::= an integer between 0 and 32
311    ip6spec ::= ip6 | ip6 "/" num_ip6_bits
312    ip6 ::= an IPv6 address, surrounded by square brackets.
313    num_ip6_bits ::= an integer between 0 and 128
315    bool ::= "0" | "1"
317    Ports are required; if they are not included in the router
318    line, they must appear in the "ports" lines.
320 3. Network status format
322    Directory authorities generate, sign, and compress network-status
323    documents.  Directory servers SHOULD generate a fresh network-status
324    document when the contents of such a document would be different from the
325    last one generated, and some time (at least one second, possibly longer)
326    has passed since the last one was generated.
328    The network status document contains a preamble, a set of router status
329    entries, and a signature, in that order.
331    We use the same meta-format as used for directories and router descriptors
332    in "tor-spec.txt".  Implementations MAY insert blank lines
333    for clarity between sections; these blank lines are ignored.
334    Implementations MUST NOT depend on blank lines in any particular location.
336    As used here, "whitespace" is a sequence of 1 or more tab or space
337    characters.
339    The preamble contains:
341       "network-status-version" -- A document format version.  For this
342          specification, the version is "2".
343       "dir-source" -- The authority's hostname, current IP address, and
344          directory port, all separated by whitespace.
345       "fingerprint" -- A base16-encoded hash of the signing key's
346          fingerprint, with no additional spaces added.
347       "contact" -- An arbitrary string describing how to contact the
348          directory server's administrator.  Administrators should include at
349          least an email address and a PGP fingerprint.
350       "dir-signing-key" -- The directory server's public signing key.
351       "client-versions" -- A comma-separated list of recommended client
352         versions.
353       "server-versions" -- A comma-separated list of recommended server
354         versions.
355       "published" -- The publication time for this network-status object.
356       "dir-options" -- A set of flags, in any order, separated by whitespace:
357           "Names" if this directory authority performs name bindings.
358           "Versions" if this directory authority recommends software versions.
359           "BadExits" if the directory authority flags nodes that it believes
360               are performing incorrectly as exit nodes.
361           "BadDirectories" if the directory authority flags nodes that it
362               believes are performing incorrectly as directory caches.
364    The dir-options entry is optional.  The "-versions" entries are required if
365    the "Versions" flag is present.  The other entries are required and must
366    appear exactly once. The "network-status-version" entry must appear first;
367    the others may appear in any order.  Implementations MUST ignore
368    additional arguments to the items above, and MUST ignore unrecognized
369    flags.
371    For each router, the router entry contains:  (This format is designed for
372    conciseness.)
374       "r" -- followed by the following elements, in order, separated by
375           whitespace:
376           - The OR's nickname,
377           - A hash of its identity key, encoded in base64, with trailing =
378             signs removed.
379           - A hash of its most recent descriptor, encoded in base64, with
380             trailing = signs removed.  (The hash is calculated as for
381             computing the signature of a descriptor.)
382           - The publication time of its most recent descriptor, in the form
383             YYYY-MM-DD HH:MM:SS, in GMT.
384           - An IP address
385           - An OR port
386           - A directory port (or "0" for none")
387       "s" -- A series of whitespace-separated status flags, in any order:
388           "Authority" if the router is a directory authority.
389           "BadExit" if the router is believed to be useless as an exit node
390              (because its ISP censors it, because it is behind a restrictive
391              proxy, or for some similar reason).
392           "BadDirectory" if the router is believed to be useless as a
393              directory cache (because its directory port isn't working,
394              its bandwidth is always throttled, or for some similar
395              reason).
396           "Exit" if the router is useful for building general-purpose exit
397              circuits.
398           "Fast" if the router is suitable for high-bandwidth circuits.
399           "Guard" if the router is suitable for use as an entry guard.
400           "Named" if the router's identity-nickname mapping is canonical,
401              and this authority binds names.
402           "Stable" if the router is suitable for long-lived circuits.
403           "Running" if the router is currently usable.
404           "Valid" if the router has been 'validated'.
405           "V2Dir" if the router implements this protocol.
406       "v" -- The version of the Tor protocol that this server is running.  If
407           the value begins with "Tor" SP, the rest of the string is a Tor
408           version number, and the protocol is "The Tor protocol as supported
409           by the given version of Tor."  Otherwise, if the value begins with
410           some other string, Tor has upgraded to a more sophisticated
411           protocol versioning system, and the protocol is "a version of the
412           Tor protocol more recent than any we recognize."
414       The "r" entry for each router must appear first and is required. The
415       "s" entry is optional (see Section 3.1 below for how the flags are
416       decided). Unrecognized flags on the "s" line and extra elements
417       on the "r" line must be ignored.  The "v" line is optional; it was not
418       supported until 0.1.2.5-alpha, and it must be preceded with an "opt"
419       until all earlier versions of Tor are obsolete.
421    The signature section contains:
423       "directory-signature" nickname-of-dirserver NL Signature
425       Signature is a signature of this network-status document
426       (the document up until the signature, including the line
427       "directory-signature <nick>\n"), using the directory authority's
428       signing key.
430    We compress the network status list with zlib before transmitting it.
432 3.1. Establishing server status
434    (This section describes how directory authorities choose which status
435    flags to apply to routers, as of Tor 0.1.1.18-rc. Later directory
436    authorities MAY do things differently, so long as clients keep working
437    well.  Clients MUST NOT depend on the exact behaviors in this section.)
439    In the below definitions, a router is considered "active" if it is
440    running, valid, and not hibernating.
442    "Valid" -- a router is 'Valid' if it is running a version of Tor not
443    known to be broken, and the directory authority has not blacklisted
444    it as suspicious.
446    "Named" -- Directory authority administrators may decide to support name
447    binding.  If they do, then they must maintain a file of
448    nickname-to-identity-key mappings, and try to keep this file consistent
449    with other directory authorities.  If they don't, they act as clients, and
450    report bindings made by other directory authorities (name X is bound to
451    identity Y if at least one binding directory lists it, and no directory
452    binds X to some other Y'.)  A router is called 'Named' if the router
453    believes the given name should be bound to the given key.
455    "Running" -- A router is 'Running' if the authority managed to connect to
456    it successfully within the last 30 minutes.
458    "Stable" -- A router is 'Stable' if it is active, and either its
459    uptime is at least the median uptime for known active routers, or
460    its uptime is at least 30 days. Routers are never called stable if
461    they are running a version of Tor known to drop circuits stupidly.
462    (0.1.1.10-alpha through 0.1.1.16-rc are stupid this way.)
464    "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
465    in the top 7/8ths for known active routers.
467    "Guard" -- A router is a possible 'Guard' if it is 'Stable' and its
468    bandwidth is above median for known active routers. If the total
469    bandwidth of active non-BadExit Exit servers is less than one third
470    of the total bandwidth of all active servers, no Exit is listed as
471    a Guard.
473    "Authority" -- A router is called an 'Authority' if the authority
474    generating the network-status document believes it is an authority.
476    "V2Dir" -- A router supports the v2 directory protocol if it has an open
477    directory port, and it is running a version of the directory protocol that
478    supports the functionality clients need.  (Currently, this is
479    0.1.1.9-alpha or later.)
481    Directory server administrators may label some servers or IPs as
482    blacklisted, and elect not to include them in their network-status lists.
484    Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
485    When there are more than 3 to choose from, authorities should first prefer
486    authorities to non-authorities, then prefer Running to non-Running, and
487    then prefer high-bandwidth to low-bandwidth.  To 'disable' a server, the
488    authority *should* advertise it without the Running or Valid flag.
490    Thus, the network-status list includes all non-blacklisted,
491    non-expired, non-superseded descriptors.
493 4. Directory server operation
495    All directory authorities and directory mirrors ("directory servers")
496    implement this section, except as noted.
498 4.1. Accepting uploads (authorities only)
500    When a router posts a signed descriptor to a directory authority, the
501    authority first checks whether it is well-formed and correctly
502    self-signed.  If it is, the authority next verifies that the nickname
503    in question is not already assigned to a router with a different
504    public key.
505    Finally, the authority MAY check that the router is not blacklisted
506    because of its key, IP, or another reason.
508    If the descriptor passes these tests, and the authority does not already
509    have a descriptor for a router with this public key, it accepts the
510    descriptor and remembers it.
512    If the authority _does_ have a descriptor with the same public key, the
513    newly uploaded descriptor is remembered if its publication time is more
514    recent than the most recent old descriptor for that router, and either:
515       - There are non-cosmetic differences between the old descriptor and the
516         new one.
517       - Enough time has passed between the descriptors' publication times.
518         (Currently, 12 hours.)
520    Differences between router descriptors are "non-cosmetic" if they would be
521    sufficient to force an upload as described in section 2 above.
523    Note that the "cosmetic difference" test only applies to uploaded
524    descriptors, not to descriptors that the authority downloads from other
525    authorities.
527 4.2. Downloading network-status documents (authorities and caches)
529    All directory servers (authorities and mirrors) try to keep a fresh
530    set of network-status documents from every authority.  To do so,
531    every 5 minutes, each authority asks every other authority for its
532    most recent network-status document.  Every 15 minutes, each mirror
533    picks a random authority and asks it for the most recent network-status
534    documents for all the authorities the authority knows about (including
535    the chosen authority itself).
537    Directory servers and mirrors remember and serve the most recent
538    network-status document they have from each authority.  Other
539    network-status documents don't need to be stored.  If the most recent
540    network-status document is over 10 days old, it is discarded anyway.
541    Mirrors SHOULD store and serve network-status documents from authorities
542    they don't recognize, but SHOULD NOT use such documents for any other
543    purpose.  Mirrors SHOULD discard network-status documents older than 48
544    hours.
546 4.3. Downloading and storing router descriptors (authorities and caches)
548    Periodically (currently, every 10 seconds), directory servers check
549    whether there are any specific descriptors (as identified by descriptor
550    hash in a network-status document) that they do not have and that they
551    are not currently trying to download.
553    If so, the directory server launches requests to the authorities for these
554    descriptors, such that each authority is only asked for descriptors listed
555    in its most recent network-status.  When more than one authority lists the
556    descriptor, we choose which to ask at random.
558    If one of these downloads fails, we do not try to download that descriptor
559    from the authority that failed to serve it again unless we receive a newer
560    network-status from that authority that lists the same descriptor.
562    Directory servers must potentially cache multiple descriptors for each
563    router. Servers must not discard any descriptor listed by any current
564    network-status document from any authority.  If there is enough space to
565    store additional descriptors, servers SHOULD try to hold those which
566    clients are likely to download the most.  (Currently, this is judged
567    based on the interval for which each descriptor seemed newest.)
569    Authorities SHOULD NOT download descriptors for routers that they would
570    immediately reject for reasons listed in 3.1.
572 4.4. HTTP URLs
574    "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
576    The authoritative network-status published by a host should be available at:
577       http://<hostname>/tor/status/authority.z
579    The network-status published by a host with fingerprint
580    <F> should be available at:
581       http://<hostname>/tor/status/fp/<F>.z
583    The network-status documents published by hosts with fingerprints
584    <F1>,<F2>,<F3> should be available at:
585       http://<hostname>/tor/status/fp/<F1>+<F2>+<F3>.z
587    The most recent network-status documents from all known authorities,
588    concatenated, should be available at:
589       http://<hostname>/tor/status/all.z
591    The most recent descriptor for a server whose identity key has a
592    fingerprint of <F> should be available at:
593       http://<hostname>/tor/server/fp/<F>.z
595    The most recent descriptors for servers with identity fingerprints
596    <F1>,<F2>,<F3> should be available at:
597       http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
599    (NOTE: Implementations SHOULD NOT download descriptors by identity key
600    fingerprint. This allows a corrupted server (in collusion with a cache) to
601    provide a unique descriptor to a client, and thereby partition that client
602    from the rest of the network.)
604    The server descriptor with (descriptor) digest <D> (in hex) should be
605    available at:
606       http://<hostname>/tor/server/d/<D>.z
608    The most recent descriptors with digests <D1>,<D2>,<D3> should be
609    available at:
610       http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
612    The most recent descriptor for this server should be at:
613       http://<hostname>/tor/server/authority.z
614     [Nothing in the Tor protocol uses this resource yet, but it is useful
615      for debugging purposes. Also, the official Tor implementations
616      (starting at 0.1.1.x) use this resource to test whether a server's
617      own DirPort is reachable.]
619    A concatenated set of the most recent descriptors for all known servers
620    should be available at:
621       http://<hostname>/tor/server/all.z
623    For debugging, directories SHOULD expose non-compressed objects at URLs like
624    the above, but without the final ".z".
625    Clients MUST handle compressed concatenated information in two forms:
626      - A concatenated list of zlib-compressed objects.
627      - A zlib-compressed concatenated list of objects.
628    Directory servers MAY generate either format: the former requires less
629    CPU, but the latter requires less bandwidth.
631    Clients SHOULD use upper case letters (A-F) when base16-encoding
632    fingerprints.  Servers MUST accept both upper and lower case fingerprints
633    in requests.
635 5. Client operation: downloading information
637    Every Tor that is not a directory server (that is, those that do
638    not have a DirPort set) implements this section.
640 5.1. Downloading network-status documents
642    Each client maintains an ordered list of directory authorities.
643    Insofar as possible, clients SHOULD all use the same ordered list.
645    For each network-status document a client has, it keeps track of its
646    publication time *and* the time when the client retrieved it.  Clients
647    consider a network-status document "live" if it was published within the
648    last 24 hours.
650    Clients try to have a live network-status document hours from *every*
651    authority, and try to periodically get new network-status documents from
652    each authority in rotation as follows:
654    If a client is missing a live network-status document for any
655    authority, it tries to fetch it from a directory cache.  On failure,
656    the client waits briefly, then tries that network-status document
657    again from another cache.  The client does not build circuits until it
658    has live network-status documents from more than half the authorities
659    it trusts, and it has descriptors for more than 1/4 of the routers
660    that it believes are running.
662    If the most recently _retrieved_ network-status document is over 30
663    minutes old, the client attempts to download a network-status document.
664    When choosing which documents to download, clients treat their list of
665    directory authorities as a circular ring, and begin with the authority
666    appearing immediately after the authority for their most recently
667    retrieved network-status document.  If this attempt fails (either it
668    fails to download at all, or the one it gets is not as good as the
669    one it has), the client retries at other caches several times, before
670    moving on to the next network-status document in sequence.
672    Clients discard all network-status documents over 24 hours old.
674    If enough mirrors (currently 4) claim not to have a given network status,
675    we stop trying to download that authority's network-status, until we
676    download a new network-status that makes us believe that the authority in
677    question is running.  Clients should wait a little longer after each
678    failure.
680    Clients SHOULD try to batch as many network-status requests as possible
681    into each HTTP GET.
683    (Note: clients can and should pick caches based on the network-status
684    information they have: once they have first fetched network-status info
685    from an authority, they should not need to go to the authority directly
686    again.)
688 5.2. Downloading and storing router descriptors
690    Clients try to have the best descriptor for each router.  A descriptor is
691    "best" if:
692       * It is the most recently published descriptor listed for that router
693         by at least two network-status documents.
694         OR,
695       * No descriptor for that router is listed by two or more
696         network-status documents, and it is the most recently published
697         descriptor listed by any network-status document.
699    Periodically (currently every 10 seconds) clients check whether there are
700    any "downloadable" descriptors.  A descriptor is downloadable if:
701       - It is the "best" descriptor for some router.
702       - The descriptor was published at least 10 minutes in the past.
703         (This prevents clients from trying to fetch descriptors that the
704         mirrors have probably not yet retrieved and cached.)
705       - The client does not currently have it.
706       - The client is not currently trying to download it.
707       - The client would not discard it immediately upon receiving it.
708       - The client thinks it is running and valid (see 6.1 below).
710    If at least 16 known routers have downloadable descriptors, or if
711    enough time (currently 10 minutes) has passed since the last time the
712    client tried to download descriptors, it launches requests for all
713    downloadable descriptors, as described in 5.3 below.
715    When a descriptor download fails, the client notes it, and does not
716    consider the descriptor downloadable again until a certain amount of time
717    has passed. (Currently 0 seconds for the first failure, 60 seconds for the
718    second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
719    thereafter.)  Periodically (currently once an hour) clients reset the
720    failure count.
722    No descriptors are downloaded until the client has downloaded more than
723    half of the network-status documents.
725    Clients retain the most recent descriptor they have downloaded for each
726    router so long as it is not too old (currently, 48 hours), OR so long as
727    it is recommended by at least one networkstatus AND no "better"
728    descriptor has been downloaded.  [Versions of Tor before 0.1.2.3-alpha
729    would discard descriptors simply for being published too far in the past.]
730    [The code seems to discard descriptors in all cases after they're 5
731    days old. True? -RD]
733 5.3. Managing downloads
735    When a client has no live network-status documents, it downloads
736    network-status documents from a randomly chosen authority.  In all other
737    cases, the client downloads from mirrors randomly chosen from among those
738    believed to be V2 directory servers.  (This information comes from the
739    network-status documents; see 6 below.)
741    When downloading multiple router descriptors, the client chooses multiple
742    mirrors so that:
743      - At least 3 different mirrors are used, except when this would result
744        in more than one request for under 4 descriptors.
745      - No more than 128 descriptors are requested from a single mirror.
746      - Otherwise, as few mirrors as possible are used.
747    After choosing mirrors, the client divides the descriptors among them
748    randomly.
750    After receiving any response client MUST discard any network-status
751    documents and descriptors that it did not request.
753 6. Using directory information
755    Everyone besides directory authorities uses the approaches in this section
756    to decide which servers to use and what their keys are likely to be.
757    (Directory authorities just believe their own opinions, as in 3.1 above.)
759 6.1. Choosing routers for circuits.
761    Tor implementations only pay attention to "live" network-status documents.
762    A network status is "live" if it is the most recently downloaded network
763    status document for a given directory server, and the server is a
764    directory server trusted by the client, and the network-status document is
765    no more than 1 day old.
767    For time-sensitive information, Tor implementations focus on "recent"
768    network-status documents.  A network status is "recent" if it is live, and
769    if it was published in the last 60 minutes.  If there are fewer
770    than 3 such documents, the most recently published 3 are "recent."  If
771    there are fewer than 3 in all, all are "recent.")
773    Circuits SHOULD NOT be built until the client has enough directory
774    information: network-statuses (or failed attempts to download
775    network-statuses) for all authorities, network-statuses for at more than
776    half of the authorities, and descriptors for at least 1/4 of the servers
777    believed to be running.
779    A server is "listed" if it is included by more than half of the live
780    network status documents.  Clients SHOULD NOT use unlisted servers.
782    Clients believe the flags "Valid", "Exit", "Fast", "Guard", "Stable", and
783    "V2Dir" about a given router when they are asserted by more than half of
784    the live network-status documents.  Clients believe the flag "Running" if
785    it is listed by more than half of the recent network-status documents.
787    These flags are used as follows:
789      - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
790        requested to do so.
792      - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
793        very-low-bandwidth circuits (such as introduction circuits).
795      - Clients SHOULD NOT use non-'Stable' routers for circuits that are
796        likely to need to be open for a very long time (such as those used for
797        IRC or SSH connections).
799      - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
800        nodes.
802      - Clients SHOULD NOT download directory information from non-'V2Dir'
803        caches.
805 6.2. Managing naming
807    In order to provide human-memorable names for individual server
808    identities, some directory servers bind names to IDs.  Clients handle
809    names in two ways:
811    When a client encounters a name it has not mapped before:
813       If all the live "Naming" network-status documents the client has
814       claim that the name binds to some identity ID, and the client has at
815       least three live network-status documents, the client maps the name to
816       ID.
818    When a user tries to refer to a router with a name that does not have a
819    mapping under the above rules, the implementation SHOULD warn the user.
820    After giving the warning, the implementation MAY use a router that at
821    least one Naming authority maps the name to, so long as no other naming
822    authority maps that name to a different router.  If no Naming authority
823    maps the name to a router, the implementation MAY use any router that
824    advertises the name.
826    Not every router needs a nickname.  When a router doesn't configure a
827    nickname, it publishes with the default nickname "Unnamed".  Authorities
828    SHOULD NOT ever mark a router with this nickname as Named; client software
829    SHOULD NOT ever use a router in response to a user request for a router
830    called "Unnamed".
832 6.3. Software versions
834    An implementation of Tor SHOULD warn when it has fetched (or has
835    attempted to fetch and failed four consecutive times) a network-status
836    for each authority, and it is running a software version
837    not listed on more than half of the live "Versioning" network-status
838    documents.
840 6.4. Warning about a router's status.
842    If a router tries to publish its descriptor to a Naming authority
843    that has its nickname mapped to another key, the router SHOULD
844    warn the operator that it is either using the wrong key or is using
845    an already claimed nickname.
847    If a router has fetched (or attempted to fetch and failed four
848    consecutive times) a network-status for every authority, and at
849    least one of the authorities is "Naming", and no live "Naming"
850    authorities publish a binding for the router's nickname, the
851    router MAY remind the operator that the chosen nickname is not
852    bound to this key at the authorities, and suggest contacting the
853    authority operators.
855    ...
857 6.5. Router protocol versions
859    A client should believe that a router supports a given feature if that
860    feature is supported by the router or protocol versions in more than half
861    of the live networkstatus's "v" entries for that router.  In other words,
862    if the "v" entries for some router are:
863        v Tor 0.0.8pre1                (from authority 1)
864        v Tor 0.1.2.11                 (from authority 2)
865        v FutureProtocolDescription 99 (from authority 3)
866    then the client should believe that the router supports any feature
867    supported by 0.1.2.11.
869    This is currently equivalent to believing the median declared version for
870    a router in all live networkstatuses.
872 7. Standards compliance
874    All clients and servers MUST support HTTP 1.0.
876 7.1. HTTP headers
878   Servers MAY set the Content-Length: header.  Servers SHOULD set
879   Content-Encoding to "deflate" or "identity".
881   Servers MAY include an X-Your-Address-Is: header, whose value is the
882   apparent IP address of the client connecting to them (as a dotted quad).
883   For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
884   report the IP from which the circuit carrying the BEGIN_DIR stream reached
885   them.  [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
886   BEGIN_DIR-tunneled connections.]
888   Servers SHOULD disable caching of multiple network statuses or multiple
889   router descriptors.  Servers MAY enable caching of single descriptors,
890   single network statuses, the list of all router descriptors, a v1
891   directory, or a v1 running routers document.  XXX mention times.
893 7.2. HTTP status codes
895   XXX We should write down what return codes dirservers send in what situations.