3 Tor directory protocol, version 3
5 0. Scope and preliminaries
7 This directory protocol is used by Tor version 0.2.0.x-alpha and later.
8 See dir-spec-v1.txt for information on the protocol used up to the
9 0.1.0.x series, and dir-spec-v2.txt for information on the protocol
10 used by the 0.1.1.x and 0.1.2.x series.
12 Caches and authorities must still support older versions of the
13 directory protocols, until the versions of Tor that require them are
14 finally out of commission. See Section XXXX on backward compatibility.
16 This document merges and supersedes the following proposals:
18 101 Voting on the Tor Directory System
19 103 Splitting identity key from regularly used signing key
20 104 Long and Short Router Descriptors
22 AS OF 14 JUNE 2007, THIS SPECIFICATION HAS NOT YET BEEN COMPLETELY
23 IMPLEMENTED, OR COMPLETELY COMPLETED.
25 XXX when to download certificates.
31 The earliest versions of Onion Routing shipped with a list of known
32 routers and their keys. When the set of routers changed, users needed to
35 The Version 1 Directory protocol
36 --------------------------------
38 Early versions of Tor (0.0.2) introduced "Directory authorities": servers
39 that served signed "directory" documents containing a list of signed
40 "router descriptors", along with short summary of the status of each
41 router. Thus, clients could get up-to-date information on the state of
42 the network automatically, and be certain that the list they were getting
43 was attested by a trusted directory authority.
45 Later versions (0.0.8) added directory caches, which download
46 directories from the authorities and serve them to clients. Non-caches
47 fetch from the caches in preference to fetching from the authorities, thus
48 distributing bandwidth requirements.
50 Also added during the version 1 directory protocol were "router status"
51 documents: short documents that listed only the up/down status of the
52 routers on the network, rather than a complete list of all the
53 descriptors. Clients and caches would fetch these documents far more
54 frequently than they would fetch full directories.
56 The Version 2 Directory Protocol
57 --------------------------------
59 During the Tor 0.1.1.x series, Tor revised its handling of directory
60 documents in order to address two major problems:
62 * Directories had grown quite large (over 1MB), and most directory
63 downloads consisted mainly of router descriptors that clients
66 * Every directory authority was a trust bottleneck: if a single
67 directory authority lied, it could make clients believe for a time
68 an arbitrarily distorted view of the Tor network. (Clients
69 trusted the most recent signed document they downloaded.) Thus,
70 adding more authorities would make the system less secure, not
73 To address these, we extended the directory protocol so that
74 authorities now published signed "network status" documents. Each
75 network status listed, for every router in the network: a hash of its
76 identity key, a hash of its most recent descriptor, and a summary of
77 what the authority believed about its status. Clients would download
78 the authorities' network status documents in turn, and believe
79 statements about routers iff they were attested to by more than half of
82 Instead of downloading all router descriptors at once, clients
83 downloaded only the descriptors that they did not have. Descriptors
84 were indexed by their digests, in order to prevent malicious caches
85 from giving different versions of a router descriptor to different
88 Routers began working harder to upload new descriptors only when their
89 contents were substantially changed.
92 0.2. Goals of the version 3 protocol
94 Version 3 of the Tor directory protocol tries to solve the following
97 * A great deal of bandwidth used to transmit router descriptors was
98 used by two fields that are not actually used by Tor routers
99 (namely read-history and write-history). We save about 60% by
100 moving them into a separate document that most clients do not
103 * It was possible under certain perverse circumstances for clients
104 to download an unusual set of network status documents, thus
105 partitioning themselves from clients who have a more recent and/or
106 typical set of documents. Even under the best of circumstances,
107 clients were sensitive to the ages of the network status documents
108 they downloaded. Therefore, instead of having the clients
109 correlate multiple network status documents, we have the
110 authorities collectively vote on a single consensus network status
113 * The most sensitive data in the entire network (the identity keys
114 of the directory authorities) needed to be stored unencrypted so
115 that the authorities can sign network-status documents on the fly.
116 Now, the authorities' identity keys are stored offline, and used
117 to certify medium-term signing keys that can be rotated.
119 0.3. Some Remaining questions
121 Things we could solve on a v3 timeframe:
123 The SHA-1 hash is showing its age. We should do something about our
124 dependency on it. We could probably future-proof ourselves here in
125 this revision, at least so far as documents from the authorities are
128 Too many things about the authorities are hardcoded by IP.
130 Perhaps we should start accepting longer identity keys for routers
133 Things to solve eventually:
135 Requiring every client to know about every router won't scale forever.
137 Requiring every directory cache to know every router won't scale
143 There is a small set (say, around 5-10) of semi-trusted directory
144 authorities. A default list of authorities is shipped with the Tor
145 software. Users can change this list, but are encouraged not to do so,
146 in order to avoid partitioning attacks.
148 Every authority has a very-secret, long-term "Authority Identity Key".
149 This is stored encrypted and/or offline, and is used to sign "key
150 certificate" documents. Every key certificate contains a medium-term
151 (3-12 months) "authority signing key", that is used by the authority to
152 sign other directory information. (Note that the authority identity
153 key is distinct from the router identity key that the authority uses
154 in its role as an ordinary router.)
156 Routers periodically upload signed "routers descriptors" to the
157 directory authorities describing their keys, capabilities, and other
158 information. Routers may also upload signed "extra info documents"
159 containing information that is not required for the Tor protocol.
160 Directory authorities serve router descriptors indexed by router
161 identity, or by hash of the descriptor.
163 Routers may act as directory caches to reduce load on the directory
164 authorities. They announce this in their descriptors.
166 Periodically, each directory authority generates a view of
167 the current descriptors and status for known routers. They send a
168 signed summary of this view (a "status vote") to the other
169 authorities. The authorities compute the result of this vote, and sign
170 a "consensus status" document containing the result of the vote.
172 Directory caches download, cache, and re-serve consensus documents.
174 Clients, directory caches, and directory authorities all use consensus
175 documents to find out when their list of routers is out-of-date.
176 (Directory authorities also use vote statuses.) If it is, they download
177 any missing router descriptors. Clients download missing descriptors
178 from caches; caches and authorities download from authorities.
179 Descriptors are downloaded by the hash of the descriptor, not by the
180 server's identity key: this prevents servers from attacking clients by
181 giving them descriptors nobody else uses.
183 All directory information is uploaded and downloaded with HTTP.
185 [Authorities also generate and caches also cache documents produced and
186 used by earlier versions of this protocol; see section XXX for notes.]
188 1.1. What's different from version 2?
190 Clients used to download multiple network status documents,
191 corresponding roughly to "status votes" above. They would compute the
192 result of the vote on the client side.
194 Authorities used to sign documents using the same private keys they used
195 for their roles as routers. This forced them to keep these extremely
196 sensitive keys in memory unencrypted.
198 All of the information in extra-info documents used to be kept in the
201 1.2. Document meta-format
203 Router descriptors, directories, and running-routers documents all obey the
204 following lightweight extensible information format.
206 The highest level object is a Document, which consists of one or more
207 Items. Every Item begins with a KeywordLine, followed by zero or more
208 Objects. A KeywordLine begins with a Keyword, optionally followed by
209 whitespace and more non-newline characters, and ends with a newline. A
210 Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
211 An Object is a block of encoded data in pseudo-Open-PGP-style
212 armor. (cf. RFC 2440)
216 NL = The ascii LF character (hex value 0x0a).
217 Document ::= (Item | NL)+
218 Item ::= KeywordLine Object*
219 KeywordLine ::= Keyword NL | Keyword WS ArgumentChar+ NL
220 Keyword = KeywordChar+
221 KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
222 ArgumentChar ::= any printing ASCII character except NL.
224 Object ::= BeginLine Base-64-encoded-data EndLine
225 BeginLine ::= "-----BEGIN " Keyword "-----" NL
226 EndLine ::= "-----END " Keyword "-----" NL
228 The BeginLine and EndLine of an Object must use the same keyword.
230 When interpreting a Document, software MUST ignore any KeywordLine that
231 starts with a keyword it doesn't recognize; future implementations MUST NOT
232 require current clients to understand any KeywordLine not currently
235 The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
236 extensions. All implementations MUST ignore any item of the form "opt
237 keyword ....." when they would not recognize "keyword ....."; and MUST
238 treat "opt keyword ....." as synonymous with "keyword ......" when keyword
241 Implementations before 0.1.2.5-alpha rejected any document with a
242 KeywordLine that started with a keyword that they didn't recognize.
243 When generating documents that need to be read by older versions of Tor,
244 implementations MUST prefix items not recognized by older versions of
245 Tor with an "opt" until those versions of Tor are obsolete. [Note that
246 key certificates, status vote documents, extra info documents, and
247 status consensus documents will never be read by older versions of Tor.]
249 Other implementations that want to extend Tor's directory format MAY
250 introduce their own items. The keywords for extension items SHOULD start
251 with the characters "x-" or "X-", to guarantee that they will not conflict
252 with keywords used by future versions of Tor.
254 In our document descriptions below, we tag Items with a multiplicity in
255 brackets. Possible tags are:
257 "At start, exactly once": These items MUST occur in every instance of
258 the document type, and MUST appear exactly once, and MUST be the
259 first item in their documents.
261 "Exactly once": These items MUST occur exactly one time in every
262 instance of the document type.
264 "At end, exactly once": These items MUST occur in every instance of
265 the document type, and MUST appear exactly once, and MUST be the
266 last item in their documents.
268 "At most once": These items MAY occur zero or one times in any
269 instance of the document type, but MUST NOT occur more than once.
271 "Any number": These items MAY occur zero, one, or more times in any
272 instance of the document type.
274 "Once or more": These items MUST occur at least once in any instance
275 of the document type, and MAY occur more.
277 1.3. Signing documents
279 Every signable document below is signed in a similar manner, using a
280 given "Initial Item", a final "Signature Item", a digest algorithm, and
283 The Initial Item must be the first item in the document.
285 The Signature Item has the following format:
287 <signature item keyword> [arguments] NL SIGNATURE NL
289 The "SIGNATURE" Object contains a signature (using the signing key) of
290 the PKCS1-padded digest of the entire document, taken from the
291 beginning of the Initial item, through the newline after the Signature
292 Item's keyword and its arguments.
294 Unless otherwise, the digest algorithm is SHA-1.
296 All documents are invalid unless signed with the correct signing key.
298 The "Digest" of a document, unless stated otherwise, is its digest *as
299 signed by this signature scheme*.
303 Every consensus document has a "valid-after" (VA) time, a "fresh-until"
304 (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
305 in turn precede VU. Times are chosen so that every consensus will be
306 "fresh" until the next consensus becomes valid, and "valid" for a while
307 after. At least 3 consensuses should be valid at any given time.
309 The timeline for a given consensus is as follows:
311 VA-DistSeconds-VoteSeconds: The authorities exchange votes.
313 VA-DistSeconds-VoteSeconds/2: The authorities try to download any
314 votes they don't have.
316 VA-DistSeconds: The authorities calculate the consensus and exchange
319 VA-DistSeconds/2: The authorities try to download any signatures
322 VA: All authorities have a multiply signed consensus.
324 VA ... FU: Caches download the consensus. (Note that since caches have
325 no way of telling what VA and FU are until they have downloaded
326 the consensus, they assume that the present consensus's VA is
327 equal to the previous one's FU, and that its FU is one interval after
330 FU: The consensus is no longer the freshest consensus.
332 FU ... (the current consensus's VU): Clients download the consensus.
333 (See note above: clients guess that the next consensus's FU will be
334 two intervals after the current VA.)
336 VU: The consensus is no longer valid.
338 VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
339 VU-FU MUST each be at least 5 minutes.
341 2. Router operation and formats
343 ORs SHOULD generate a new router descriptor and a new extra-info
344 document whenever any of the following events have occurred:
346 - A period of time (18 hrs by default) has passed since the last
347 time a descriptor was generated.
349 - A descriptor field other than bandwidth or uptime has changed.
351 - Bandwidth has changed by a factor of 2 from the last time a
352 descriptor was generated, and at least a given interval of time
353 (20 mins by default) has passed since then.
355 - Its uptime has been reset (by restarting).
357 [XXX this list is incomplete; see router_differences_are_cosmetic()
358 in routerlist.c for others]
360 ORs SHOULD NOT publish a new router descriptor or extra-info document
361 if none of the above events have occurred and not much time has passed
362 (12 hours by default).
364 After generating a descriptor, ORs upload them to every directory
365 authority they know, by posting them (in order) to the URL
367 http://<hostname:port>/tor/
369 2.1. Router descriptor format
371 Router descriptors consist of the following items. For backward
372 compatibility, there should be an extra NL at the end of each router
375 In lines that take multiple arguments, extra arguments SHOULD be
376 accepted and ignored. Many of the nonterminals below are defined in
379 "router" nickname address ORPort SOCKSPort DirPort NL
381 [At start, exactly once.]
383 Indicates the beginning of a router descriptor. "nickname" must be a
384 valid router nickname as specified in 2.3. "address" must be an IPv4
385 address in dotted-quad format. The last three numbers indicate the
386 TCP ports at which this OR exposes functionality. ORPort is a port at
387 which this OR accepts TLS connections for the main OR protocol;
388 SOCKSPort is deprecated and should always be 0; and DirPort is the
389 port at which this OR accepts directory-related HTTP connections. If
390 any port is not supported, the value 0 is given instead of a port
391 number. (At least one of DirPort and ORPort SHOULD be set;
392 authorities MAY reject any descriptor with both DirPort and ORPort of
395 "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
399 Estimated bandwidth for this router, in bytes per second. The
400 "average" bandwidth is the volume per second that the OR is willing to
401 sustain over long periods; the "burst" bandwidth is the volume that
402 the OR is willing to sustain in very short intervals. The "observed"
403 value is an estimate of the capacity this server can handle. The
404 server remembers the max bandwidth sustained output over any ten
405 second period in the past day, and another sustained input. The
406 "observed" value is the lesser of these two numbers.
412 A human-readable string describing the system on which this OR is
413 running. This MAY include the operating system, and SHOULD include
414 the name and version of the software implementing the Tor protocol.
416 "published" YYYY-MM-DD HH:MM:SS NL
420 The time, in GMT, when this descriptor (and its corresponding
421 extra-info document if any) was generated.
423 "fingerprint" fingerprint NL
427 A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
428 hex, with a single space after every 4 characters) for this router's
429 identity key. A descriptor is considered invalid (and MUST be
430 rejected) if the fingerprint line does not match the public key.
432 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
433 be marked with "opt" until earlier versions of Tor are obsolete.]
435 "hibernating" bool NL
439 If the value is 1, then the Tor server was hibernating when the
440 descriptor was published, and shouldn't be used to build circuits.
442 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
443 marked with "opt" until earlier versions of Tor are obsolete.]
449 The number of seconds that this OR process has been running.
451 "onion-key" NL a public key in PEM format
455 This key is used to encrypt EXTEND cells for this OR. The key MUST be
456 accepted for at least 1 week after any new key is published in a
457 subsequent descriptor. It MUST be 1024 bits.
459 "signing-key" NL a public key in PEM format
463 The OR's long-term identity key. It MUST be 1024 bits.
465 "accept" exitpattern NL
466 "reject" exitpattern NL
470 These lines describe an "exit policy": the rules that an OR follows
471 when deciding whether to allow a new stream to a given address. The
472 'exitpattern' syntax is described below. There MUST be at least one
473 such entry. The rules are considered in order; if no rule matches,
474 the address will be accepted. For clarity, the last such entry SHOULD
475 be accept *:* or reject *:*.
477 "router-signature" NL Signature NL
479 [At end, exactly once]
481 The "SIGNATURE" object contains a signature of the PKCS1-padded
482 hash of the entire router descriptor, taken from the beginning of the
483 "router" line, through the newline after the "router-signature" line.
484 The router descriptor is invalid unless the signature is performed
485 with the router's identity key.
491 Describes a way to contact the server's administrator, preferably
492 including an email address and a PGP key fingerprint.
498 'Names' is a space-separated list of server nicknames or
499 hexdigests. If two ORs list one another in their "family" entries,
500 then OPs should treat them as a single OR for the purpose of path
503 For example, if node A's descriptor contains "family B", and node B's
504 descriptor contains "family A", then node A and node B should never
505 be used on the same circuit.
507 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
509 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
512 Declare how much bandwidth the OR has used recently. Usage is divided
513 into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
514 defines the end of the most recent interval. The numbers are the
515 number of bytes used in the most recent intervals, ordered from
518 [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
519 be marked with "opt" until earlier versions of Tor are obsolete.]
521 [See also migration notes in section 2.2.1.]
527 Declare whether this version of Tor is using the newer enhanced
528 dns logic. Versions of Tor with this field set to false SHOULD NOT
529 be used for reverse hostname lookups.
531 [All versions of Tor before 0.1.2.2-alpha should be assumed to have
532 this option set to 0 if it is not present. All Tor versions at
533 0.1.2.2-alpha or later should be assumed to have this option set to
534 1 if it is not present. Until 0.1.2.1-alpha-dev, this option was
535 not generated, even when the new DNS code was in use. Versions of Tor
536 before 0.1.2.1-alpha-dev did not parse this option, so it should be
537 marked "opt". The dnsworker logic has been removed, so this option
538 should not be used by new server code. However, it can still be
539 used, and should still be recognized by new code until Tor 0.1.2.x
542 "caches-extra-info" NL
546 Present only if this router is a directory cache that provides
547 extra-info documents.
549 [Versions before 0.2.0.1-alpha don't recognize this, and versions
550 before 0.1.2.5-alpha will reject descriptors containing it unless
551 it is prefixed with "opt"; it should be so prefixed until these
552 versions are obsolete.]
554 "extra-info-digest" digest NL
558 "Digest" is a hex-encoded digest (using upper-case characters) of the
559 router's extra-info document, as signed in the router's extra-info
560 (that is, not including the signature). (If this field is absent, the
561 router is not uploading a corresponding extra-info document.)
563 [Versions before 0.2.0.1-alpha don't recognize this, and versions
564 before 0.1.2.5-alpha will reject descriptors containing it unless
565 it is prefixed with "opt"; it should be so prefixed until these
566 versions are obsolete.]
568 "hidden-service-dir" *(SP VersionNum) NL
572 Present only if this router stores and serves hidden service
573 descriptors. If any VersionNum(s) are specified, this router
574 supports those descriptor versions. If none are specified, it
575 defaults to version 2 descriptors.
577 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
578 with unrecognized items; the protocols line should be preceded with
579 an "opt" until these Tors are obsolete.]
581 "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
582 CIRCUIT-VERSION-LIST NL
586 Both lists are space-separated sequences of numbers, to indicate which
587 protocols the server supports. As of 30 Mar 2008, specified
588 protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt
589 for more information about link protocol versions.
591 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
592 with unrecognized items; the protocols line should be preceded with
593 an "opt" until these Tors are obsolete.]
595 "allow-single-hop-exits"
599 Present only if the router allows single-hop circuits to make exit
600 connections. Most Tor servers do not support this: this is
601 included for specialized controllers designed to support perspective
605 2.2. Extra-info documents
607 Extra-info documents consist of the following items:
609 "extra-info" Nickname Fingerprint NL
610 [At start, exactly once.]
612 Identifies what router this is an extra info descriptor for.
613 Fingerprint is encoded in hex (using upper-case letters), with
620 The time, in GMT, when this document (and its corresponding router
621 descriptor if any) was generated. It MUST match the published time
622 in the corresponding router descriptor.
624 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
626 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
629 As documented in 2.1 above. See migration notes in section 2.2.1.
631 "geoip-start" YYYY-MM-DD HH:MM:SS NL
632 "geoip-client-origins" CC=N,CC=N,... NL
634 Only generated by bridge routers (see blocking.pdf), and only
635 when they have been configured with a geoip database.
636 Non-bridges SHOULD NOT generate these fields. Contains a list
637 of mappings from two-letter country codes (CC) to the number
638 of clients that have connected to that bridge from that
639 country (approximate, and rounded up to the nearest multiple of 8
640 in order to hamper traffic analysis). A country is included
641 only if it has at least one address. The time in
642 "geoip-start" is the time at which we began collecting geoip
645 "router-signature" NL Signature NL
646 [At end, exactly once.]
648 A document signature as documented in section 1.3, using the
649 initial item "extra-info" and the final item "router-signature",
650 signed with the router's identity key.
652 2.2.1. Moving history fields to extra-info documents.
654 Tools that want to use the read-history and write-history values SHOULD
655 download extra-info documents as well as router descriptors. Such
656 tools SHOULD accept history values from both sources; if they appear in
657 both documents, the values in the extra-info documents are authoritative.
659 New versions of Tor no longer generate router descriptors
660 containing read-history or write-history. Tools should continue to
661 accept read-history and write-history values in router descriptors
662 produced by older versions of Tor until all Tor versions earlier
663 than 0.2.0.x are obsolete.
665 2.3. Nonterminals in router descriptors
667 nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
669 hexdigest ::= a '$', followed by 40 hexadecimal characters
670 ([A-Fa-f0-9]). [Represents a server by the digest of its identity
673 exitpattern ::= addrspec ":" portspec
674 portspec ::= "*" | port | port "-" port
675 port ::= an integer between 1 and 65535, inclusive.
677 [Some implementations incorrectly generate ports with value 0.
678 Implementations SHOULD accept this, and SHOULD NOT generate it.
679 Connections to port 0 are never permitted.]
681 addrspec ::= "*" | ip4spec | ip6spec
682 ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
683 ip4 ::= an IPv4 address in dotted-quad format
684 ip4mask ::= an IPv4 mask in dotted-quad format
685 num_ip4_bits ::= an integer between 0 and 32
686 ip6spec ::= ip6 | ip6 "/" num_ip6_bits
687 ip6 ::= an IPv6 address, surrounded by square brackets.
688 num_ip6_bits ::= an integer between 0 and 128
692 3. Formats produced by directory authorities.
694 Every authority has two keys used in this protocol: a signing key, and
695 an authority identity key. (Authorities also have a router identity
696 key used in their role as a router and by earlier versions of the
697 directory protocol.) The identity key is used from time to time to
698 sign new key certificates using new signing keys; it is very sensitive.
699 The signing key is used to sign key certificates and status documents.
701 There are three kinds of documents generated by directory authorities:
707 Each is discussed below.
709 3.1. Key certificates
711 Key certificates consist of the following items:
713 "dir-key-certificate-version" version NL
715 [At start, exactly once.]
717 Determines the version of the key certificate. MUST be "3" for
718 the protocol described in this document. Implementations MUST
719 reject formats they don't understand.
721 "dir-address" IPPort NL
724 An IP:Port for this authority's directory port.
726 "fingerprint" fingerprint NL
730 Hexadecimal encoding without spaces based on the authority's
733 "dir-identity-key" NL a public key in PEM format
737 The long-term authority identity key for this authority. This key
738 SHOULD be at least 2048 bits long; it MUST NOT be shorter than
741 "dir-key-published" YYYY-MM-DD HH:MM:SS NL
745 The time (in GMT) when this document and corresponding key were
748 "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
752 A time (in GMT) after which this key is no longer valid.
754 "dir-signing-key" NL a key in PEM format
758 The directory server's public signing key. This key MUST be at
759 least 1024 bits, and MAY be longer.
761 "dir-key-certification" NL Signature NL
763 [At end, exactly once.]
765 A document signature as documented in section 1.3, using the
766 initial item "dir-key-certificate-version" and the final item
767 "dir-key-certification", signed with the authority identity key.
769 Authorities MUST generate a new signing key and corresponding
770 certificate before the key expires.
772 3.2. Vote and consensus status documents
774 Votes and consensuses are more strictly formatted then other documents
775 in this specification, since different authorities must be able to
776 generate exactly the same consensus given the same set of votes.
778 The procedure for deciding when to generate vote and consensus status
779 documents are described in section XXX below.
781 Status documents contain a preamble, an authority section, a list of
782 router status entries, and one more footers signature, in that order.
784 Unlike other formats described above, a SP in these documents must be a
785 single space character (hex 20).
787 Some items appear only in votes, and some items appear only in
788 consensuses. Unless specified, items occur in both.
790 The preamble contains the following items. They MUST occur in the
793 "network-status-version" SP version NL.
795 [At start, exactly once.]
797 A document format version. For this specification, the version is
800 "vote-status" SP type NL
804 The status MUST be "vote" or "consensus", depending on the type of
807 "consensus-methods" SP IntegerList NL
809 [Exactly once for votes; does not occur in consensuses.]
811 A space-separated list of supported methods for generating
812 consensuses from votes. See section 3.4.1 for details. Method "1"
815 "consensus-method" SP Integer NL
817 [Exactly once for consensuses; does not occur in votes.]
819 See section 3.4.1 for details.
821 (Only included when the vote is generated with consensus-method 2 or
824 "published" SP YYYY-MM-DD SP HH:MM:SS NL
826 [Exactly once for votes; does not occur in consensuses.]
828 The publication time for this status document (if a vote).
830 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
834 The start of the Interval for this vote. Before this time, the
835 consensus document produced from this vote should not be used.
836 See 1.4 for voting timeline information.
838 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
842 The time at which the next consensus should be produced; before this
843 time, there is no point in downloading another consensus, since there
844 won't be a new one. See 1.4 for voting timeline information.
846 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
850 The end of the Interval for this vote. After this time, the
851 consensus produced by this vote should not be used. See 1.4 for
852 voting timeline information.
854 "voting-delay" SP VoteSeconds SP DistSeconds NL
858 VoteSeconds is the number of seconds that we will allow to collect
859 votes from all authorities; DistSeconds is the number of seconds
860 we'll allow to collect signatures from all authorities. See 1.4 for
861 voting timeline information.
863 "client-versions" SP VersionList NL
867 A comma-separated list of recommended client versions, in
868 ascending order. If absent, no opinion is held about client
871 "server-versions" SP VersionList NL
875 A comma-separated list of recommended server versions, in
876 ascending order. If absent, no opinion is held about server
879 "known-flags" SP FlagList NL
883 A space-separated list of all of the flags that this document
884 might contain. A flag is "known" either because the authority
885 knows about them and might set them (if in a vote), or because
886 enough votes were counted for the consensus for an authoritative
887 opinion to have been formed about their status.
890 The authority section of a vote contains the following items, followed
891 in turn by the authority's current key certificate:
893 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
896 [Exactly once, at start]
898 Describes this authority. The nickname is a convenient identifier
899 for the authority. The identity is an uppercase hex fingerprint of
900 the authority's current (v3 authority) identity key. The address is
901 the server's hostname. The IP is the server's current IP address,
902 and dirport is its current directory port. XXXXorport
904 "contact" SP string NL
908 An arbitrary string describing how to contact the directory
909 server's administrator. Administrators should include at least an
910 email address and a PGP fingerprint.
912 The authority section of a consensus contains groups the following items,
913 in the order given, with one group for each authority that contributed to
914 the consensus, with groups sorted by authority identity digest:
916 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
919 [Exactly once, at start]
921 As in the authority section of a vote.
923 "contact" SP string NL
927 As in the authority section of a vote.
929 "vote-digest" SP digest NL
933 A digest of the vote from the authority that contributed to this
934 consensus, as signed (that is, not including the signature).
937 Each router status entry contains the following items. Router status
938 entries are sorted in ascending order by identity digest.
940 "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
943 [At start, exactly once.]
945 "Nickname" is the OR's nickname. "Identity" is a hash of its
946 identity key, encoded in base64, with trailing equals sign(s)
947 removed. "Digest" is a hash of its most recent descriptor as
948 signed (that is, not including the signature), encoded in base64 as
949 "identity". "Publication" is the
950 publication time of its most recent descriptor, in the form
951 YYYY-MM-DD HH:MM:SS, in GMT. "IP" is its current IP address;
952 ORPort is its current OR port, "DirPort" is it's current directory
953 port, or "0" for "none".
959 A series of space-separated status flags, in alphabetical order.
960 Currently documented flags are:
962 "Authority" if the router is a directory authority.
963 "BadExit" if the router is believed to be useless as an exit node
964 (because its ISP censors it, because it is behind a restrictive
965 proxy, or for some similar reason).
966 "BadDirectory" if the router is believed to be useless as a
967 directory cache (because its directory port isn't working,
968 its bandwidth is always throttled, or for some similar
970 "Exit" if the router is more useful for building
971 general-purpose exit circuits than for relay circuits. The
972 path building algorithm uses this flag; see path-spec.txt.
973 "Fast" if the router is suitable for high-bandwidth circuits.
974 "Guard" if the router is suitable for use as an entry guard.
975 "HSDir" if the router is considered a v2 hidden service directory.
976 "Named" if the router's identity-nickname mapping is canonical,
977 and this authority binds names.
978 "Stable" if the router is suitable for long-lived circuits.
979 "Running" if the router is currently usable.
980 "Unnamed" if another router has bound the name used by this
981 router, and this authority binds names.
982 "Valid" if the router has been 'validated'.
983 "V2Dir" if the router implements the v2 directory protocol.
984 "V3Dir" if the router implements this protocol.
990 The version of the Tor protocol that this server is running. If
991 the value begins with "Tor" SP, the rest of the string is a Tor
992 version number, and the protocol is "The Tor protocol as supported
993 by the given version of Tor." Otherwise, if the value begins with
994 some other string, Tor has upgraded to a more sophisticated
995 protocol versioning system, and the protocol is "a version of the
996 Tor protocol more recent than any we recognize."
998 Directory authorities SHOULD omit version strings they receive from
999 descriptors if they would cause "v" lines to be over 128 characters
1002 "w" SP "Bandwidth=" INT NL
1006 An estimate of the bandwidth of this server, in an arbitrary
1007 unit (currently kilobytes per second). Used to weight router
1008 selection. Other weighting keywords may be added later.
1009 Clients MUST ignore keywords they do not recognize.
1011 "p" SP ("accept" / "reject") SP PortList NL
1015 PortList = PortOrRange
1016 PortList = PortList "," PortOrRange
1017 PortOrRange = INT "-" INT / INT
1019 A list of those ports that this router supports (if 'accept')
1020 or does not support (if 'reject') for exit to "most
1023 The signature section contains the following item, which appears
1024 Exactly Once for a vote, and At Least Once for a consensus.
1026 "directory-signature" SP identity SP signing-key-digest NL Signature
1028 This is a signature of the status document, with the initial item
1029 "network-status-version", and the signature item
1030 "directory-signature", using the signing key. (In this case, we take
1031 the hash through the _space_ after directory-signature, not the
1032 newline: this ensures that all authorities sign the same thing.)
1033 "identity" is the hex-encoded digest of the authority identity key of
1034 the signing authority, and "signing-key-digest" is the hex-encoded
1035 digest of the current authority signing key of the signing authority.
1037 3.3. Deciding how to vote.
1039 (This section describes how directory authorities choose which status
1040 flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
1041 authorities MAY do things differently, so long as clients keep working
1042 well. Clients MUST NOT depend on the exact behaviors in this section.)
1044 In the below definitions, a router is considered "active" if it is
1045 running, valid, and not hibernating.
1047 "Valid" -- a router is 'Valid' if it is running a version of Tor not
1048 known to be broken, and the directory authority has not blacklisted
1051 "Named" -- Directory authority administrators may decide to support name
1052 binding. If they do, then they must maintain a file of
1053 nickname-to-identity-key mappings, and try to keep this file consistent
1054 with other directory authorities. If they don't, they act as clients, and
1055 report bindings made by other directory authorities (name X is bound to
1056 identity Y if at least one binding directory lists it, and no directory
1057 binds X to some other Y'.) A router is called 'Named' if the router
1058 believes the given name should be bound to the given key.
1060 Two strategies exist on the current network for deciding on
1061 values for the Named flag. In the original version, server
1062 operators were asked to send nickname-identity pairs to a
1063 mailing list of Naming directory authorities operators. The
1064 operators were then supposed to add the pairs to their
1065 mapping files; in practice, they didn't get to this often.
1067 Newer Naming authorities run a script that registers routers
1068 in their mapping files once the routers have been online at
1069 least two weeks, no other router has that nickname, and no
1070 other router has wanted the nickname for a month. If a router
1071 has not been online for six months, the router is removed.
1073 "Unnamed" -- Directory authorities that support naming should vote for a
1074 router to be 'Unnamed' if its given nickname is mapped to a different
1077 "Running" -- A router is 'Running' if the authority managed to connect to
1078 it successfully within the last 30 minutes.
1080 "Stable" -- A router is 'Stable' if it is active, and either its Weighted
1081 MTBF is at least the median for known active routers or its Weighted MTBF
1082 corresponds to at least 7 days. Routers are never called Stable if they are
1083 running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
1084 through 0.1.1.16-rc are stupid this way.)
1086 To calculate weighted MTBF, compute the weighted mean of the lengths
1087 of all intervals when the router was observed to be up, weighting
1088 intervals by $\alpha^n$, where $n$ is the amount of time that has
1089 passed since the interval ended, and $\alpha$ is chosen so that
1090 measurements over approximately one month old no longer influence the
1093 [XXXX what happens when we have less than 4 days of MTBF info.]
1095 "Exit" -- A router is called an 'Exit' iff it allows exits to at
1096 least two of the ports 80, 443, and 6667 and allows exits to at
1097 least one /8 address space.
1099 "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
1100 either in the top 7/8ths for known active routers or at least 100KB/s.
1102 "Guard" -- A router is a possible 'Guard' if its Weighted Fractional
1103 Uptime is at least the median for "familiar" active routers, and if
1104 its bandwidth is at least median or at least 250KB/s.
1105 If the total bandwidth of active non-BadExit Exit servers is less
1106 than one third of the total bandwidth of all active servers, no Exit is
1109 To calculate weighted fractional uptime, compute the fraction
1110 of time that the router is up in any given day, weighting so that
1111 downtime and uptime in the past counts less.
1113 A node is 'familiar' if 1/8 of all active nodes have appeared more
1114 recently than it, OR it has been around for a few weeks.
1116 "Authority" -- A router is called an 'Authority' if the authority
1117 generating the network-status document believes it is an authority.
1119 "V2Dir" -- A router supports the v2 directory protocol if it has an open
1120 directory port, and it is running a version of the directory protocol that
1121 supports the functionality clients need. (Currently, this is
1122 0.1.1.9-alpha or later.)
1124 "V3Dir" -- A router supports the v3 directory protocol if it has an open
1125 directory port, and it is running a version of the directory protocol that
1126 supports the functionality clients need. (Currently, this is
1127 0.2.0.?????-alpha or later.)
1129 "HSDir" -- A router is a v2 hidden service directory if it stores and
1130 serves v2 hidden service descriptors and the authority managed to connect
1131 to it successfully within the last 24 hours.
1133 Directory server administrators may label some servers or IPs as
1134 blacklisted, and elect not to include them in their network-status lists.
1136 Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
1137 When there are more than 3 to choose from, authorities should first prefer
1138 authorities to non-authorities, then prefer Running to non-Running, and
1139 then prefer high-bandwidth to low-bandwidth. To 'disable' a server, the
1140 authority *should* advertise it without the Running or Valid flag.
1142 Thus, the network-status vote includes all non-blacklisted,
1143 non-expired, non-superseded descriptors.
1145 The bandwidth in a "w" line should be taken as the best estimate
1146 of the router's actual capacity that the authority has. For now,
1147 this should be the lesser of the observed bandwidth and bandwidth
1148 rate limit from the router descriptor. It is given in kilobytes
1149 per second, and capped at some arbitrary value (curently 10 MB/s).
1151 The ports listed in a "p" line should be taken as those ports for
1152 which the router's exit policy permits 'most' addresses, ignoring any
1153 accept not for all addresses, ignoring all rejects for private
1154 netblocks. "Most" addresses are permitted if no more than 2^25
1155 IPv4 addresses (two /8 networks) were blocked. The list is encoded
1156 as described in 3.4.2.
1158 3.4. Computing a consensus from a set of votes
1160 Given a set of votes, authorities compute the contents of the consensus
1161 document as follows:
1163 The "valid-after", "valid-until", and "fresh-until" times are taken as
1164 the median of the respective values from all the votes.
1166 The times in the "voting-delay" line are taken as the median of the
1167 VoteSeconds and DistSeconds times in the votes.
1169 Known-flags is the union of all flags known by any voter.
1171 "client-versions" and "server-versions" are sorted in ascending
1172 order; A version is recommended in the consensus if it is recommended
1173 by more than half of the voting authorities that included a
1174 client-versions or server-versions lines in their votes.
1176 The authority item groups (dir-source, contact, fingerprint,
1177 vote-digest) are taken from the votes of the voting
1178 authorities. These groups are sorted by the digests of the
1179 authorities identity keys, in ascending order.
1181 A router status entry:
1182 * is included in the result if some router status entry with the same
1183 identity is included by more than half of the authorities (total
1184 authorities, not just those whose votes we have).
1186 * For any given identity, we include at most one router status entry.
1188 * A router entry has a flag set if that is included by more than half
1189 of the authorities who care about that flag.
1191 * Two router entries are "the same" if they have the same
1192 <descriptor digest, published time, nickname, IP, ports> tuple.
1193 We choose the tuple for a given router as whichever tuple appears
1194 for that router in the most votes. We break ties first in favor of
1195 the more recently published, then in favor of smaller server
1198 * The Named flag appears if it is included for this routerstatus by
1199 _any_ authority, and if all authorities that list it list the same
1200 nickname. However, if consensus-method 2 or later is in use, and
1201 any authority calls this identity/nickname pair Unnamed, then
1202 this routerstatus does not get the Named flag.
1204 * If consensus-method 2 or later is in use, the Unnamed flag is
1205 set for a routerstatus if any authorities have voted for a different
1206 identities to be Named with that nickname, or if any authority
1207 lists that nickname/ID pair as Unnamed.
1209 (With consensus-method 1, Unnamed is set like any other flag.)
1211 * The version is given as whichever version is listed by the most
1212 voters, with ties decided in favor of more recent versions.
1214 * If consensus-method 4 or later is in use, then routers that
1215 do not have the Running flag are not listed at all.
1217 * If consensus-method 5 or later is in use, then the "w" line
1218 is generated using a low-median of the bandwidth values from
1219 the votes that included "w" lines for this router.
1221 * If consensus-method 5 or later is in use, then the "p" line
1222 is taken from the votes that have the same policy summary
1223 for the descriptor we are listing. (They should all be the
1224 same. If they are not, we pick the most commonly listed
1225 one, breaking ties in favor of the lexigraphically larger
1226 vote.) The port list is encoded as specified in 3.4.2.
1228 The signatures at the end of a consensus document are sorted in
1229 ascending order by identity digest.
1231 All ties in computing medians are broken in favor of the smaller or
1234 3.4.1. Forward compatibility
1236 Future versions of Tor will need to include new information in the
1237 consensus documents, but it is important that all authorities (or at least
1238 half) generate and sign the same signed consensus.
1240 To achieve this, authorities list in their votes their supported methods
1241 for generating consensuses from votes. Later methods will be assigned
1242 higher numbers. Currently recognized methods:
1243 "1" -- The first implemented version.
1244 "2" -- Added support for the Unnamed flag.
1245 "3" -- Added legacy ID key support to aid in authority ID key rollovers
1246 "4" -- No longer list routers that are not running in the consensus
1247 "5" -- adds support for "w" and "p" lines.
1249 Before generating a consensus, an authority must decide which consensus
1250 method to use. To do this, it looks for the highest version number
1251 supported by more than 2/3 of the authorities voting. If it supports this
1252 method, then it uses it. Otherwise, it falls back to method 1.
1254 (The consensuses generated by new methods must be parsable by
1255 implementations that only understand the old methods, and must not cause
1256 those implementations to compromise their anonymity. This is a means for
1257 making changes in the contents of consensus; not for making
1258 backward-incompatible changes in their format.)
1260 3.4.2. Encoding port lists
1262 Whether the summary shows the list of accepted ports or the list of
1263 rejected ports depends on which list is shorter (has a shorter string
1264 representation). In case of ties we choose the list of accepted
1265 ports. As an exception to this rule an allow-all policy is
1266 represented as "accept 1-65535" instead of "reject " and a reject-all
1267 policy is similarly given as "reject 1-65535".
1269 Summary items are compressed, that is instead of "80-88,89-100" there
1270 only is a single item of "80-100", similarly instead of "20,21" a
1271 summary will say "20-21".
1273 Port lists are sorted in ascending order.
1275 The maximum allowed length of a policy summary (including the "accept "
1276 or "reject ") is 1000 characters. If a summary exceeds that length we
1277 use an accept-style summary and list as much of the port list as is
1278 possible within these 1000 bytes. [XXXX be more specific.]
1280 3.5. Detached signatures
1282 Assuming full connectivity, every authority should compute and sign the
1283 same consensus directory in each period. Therefore, it isn't necessary to
1284 download the consensus computed by each authority; instead, the
1285 authorities only push/fetch each others' signatures. A "detached
1286 signature" document contains items as follows:
1288 "consensus-digest" SP Digest NL
1290 [At start, at most once.]
1292 The digest of the consensus being signed.
1294 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1295 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1296 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1298 [As in the consensus]
1300 "directory-signature"
1302 [As in the consensus; the signature object is the same as in the
1303 consensus document.]
1306 4. Directory server operation
1308 All directory authorities and directory caches ("directory servers")
1309 implement this section, except as noted.
1311 4.1. Accepting uploads (authorities only)
1313 When a router posts a signed descriptor to a directory authority, the
1314 authority first checks whether it is well-formed and correctly
1315 self-signed. If it is, the authority next verifies that the nickname
1316 in question is not already assigned to a router with a different
1318 Finally, the authority MAY check that the router is not blacklisted
1319 because of its key, IP, or another reason.
1321 If the descriptor passes these tests, and the authority does not already
1322 have a descriptor for a router with this public key, it accepts the
1323 descriptor and remembers it.
1325 If the authority _does_ have a descriptor with the same public key, the
1326 newly uploaded descriptor is remembered if its publication time is more
1327 recent than the most recent old descriptor for that router, and either:
1328 - There are non-cosmetic differences between the old descriptor and the
1330 - Enough time has passed between the descriptors' publication times.
1331 (Currently, 12 hours.)
1333 Differences between router descriptors are "non-cosmetic" if they would be
1334 sufficient to force an upload as described in section 2 above.
1336 Note that the "cosmetic difference" test only applies to uploaded
1337 descriptors, not to descriptors that the authority downloads from other
1340 When a router posts a signed extra-info document to a directory authority,
1341 the authority again checks it for well-formedness and correct signature,
1342 and checks that its matches the extra-info-digest in some router
1343 descriptor that it believes is currently useful. If so, it accepts it and
1344 stores it and serves it as requested. If not, it drops it.
1346 4.2. Voting (authorities only)
1348 Authorities divide time into Intervals. Authority administrators SHOULD
1349 try to all pick the same interval length, and SHOULD pick intervals that
1350 are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
1351 minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
1352 divide evenly into a 24-hour day.
1354 Authorities SHOULD act according to interval and delays in the
1355 latest consensus. Lacking a latest consensus, they SHOULD default to a
1356 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
1358 Authorities MUST take pains to ensure that their clocks remain accurate
1359 within a few seconds. (Running NTP is usually sufficient.)
1361 The first voting period of each day begins at 00:00 (midnight) GMT. If
1362 the last period of the day would be truncated by one-half or more, it is
1363 merged with the second-to-last period.
1365 An authority SHOULD publish its vote immediately at the start of each voting
1366 period (minus VoteSeconds+DistSeconds). It does this by making it
1368 http://<hostname>/tor/status-vote/next/authority.z
1369 and sending it in an HTTP POST request to each other authority at the URL
1370 http://<hostname>/tor/post/vote
1372 If, at the start of the voting period, minus DistSeconds, an authority
1373 does not have a current statement from another authority, the first
1374 authority downloads the other's statement.
1376 Once an authority has a vote from another authority, it makes it available
1378 http://<hostname>/tor/status-vote/next/<fp>.z
1379 where <fp> is the fingerprint of the other authority's identity key.
1381 http://<hostname>/tor/status-vote/next/d/<d>.z
1382 where <d> is the digest of the vote document.
1384 The consensus status, along with as many signatures as the server
1385 currently knows, should be available at
1386 http://<hostname>/tor/status-vote/next/consensus.z
1387 All of the detached signatures it knows for consensus status should be
1389 http://<hostname>/tor/status-vote/next/consensus-signatures.z
1391 Once there are enough signatures, or once the voting period starts,
1392 these documents are available at
1393 http://<hostname>/tor/status-vote/current/consensus.z
1395 http://<hostname>/tor/status-vote/current/consensus-signatures.z
1396 [XXX current/consensus-signatures is not currently implemented, as it
1397 is not used in the voting protocol.]
1399 The other vote documents are analogously made available under
1400 http://<hostname>/tor/status-vote/current/authority.z
1401 http://<hostname>/tor/status-vote/current/<fp>.z
1402 http://<hostname>/tor/status-vote/current/d/<d>.z
1403 once the consensus is complete.
1405 Once an authority has computed and signed a consensus network status, it
1406 should send its detached signature to each other authority in an HTTP POST
1408 http://<hostname>/tor/post/consensus-signature
1410 [XXX Note why we support push-and-then-pull.]
1412 [XXX possible future features include support for downloading old
1415 4.3. Downloading consensus status documents (caches only)
1417 All directory servers (authorities and caches) try to keep a recent
1418 network-status consensus document to serve to clients. A cache ALWAYS
1419 downloads a network-status consensus if any of the following are true:
1420 - The cache has no consensus document.
1421 - The cache's consensus document is no longer valid.
1422 Otherwise, the cache downloads a new consensus document at a randomly
1423 chosen time in the first half-interval after its current consensus
1424 stops being fresh. (This time is chosen at random to avoid swarming
1425 the authorities at the start of each period. The interval size is
1426 inferred from the difference between the valid-after time and the
1427 fresh-until time on the consensus.)
1429 [For example, if a cache has a consensus that became valid at 1:00,
1430 and is fresh until 2:00, that cache will fetch a new consensus at
1431 a random time between 2:00 and 2:30.]
1433 4.4. Downloading and storing router descriptors (authorities and caches)
1435 Periodically (currently, every 10 seconds), directory servers check
1436 whether there are any specific descriptors that they do not have and that
1437 they are not currently trying to download. Caches identify these
1438 descriptors by hash in the recent network-status consensus documents;
1439 authorities identify them by hash in vote (if publication date is more
1440 recent than the descriptor we currently have).
1442 [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
1445 If so, the directory server launches requests to the authorities for these
1446 descriptors, such that each authority is only asked for descriptors listed
1447 in its most recent vote (if the requester is an authority) or in the
1448 consensus (if the requester is a cache). If we're an authority, and more
1449 than one authority lists the descriptor, we choose which to ask at random.
1451 If one of these downloads fails, we do not try to download that descriptor
1452 from the authority that failed to serve it again unless we receive a newer
1453 network-status (consensus or vote) from that authority that lists the same
1456 Directory servers must potentially cache multiple descriptors for each
1457 router. Servers must not discard any descriptor listed by any recent
1458 consensus. If there is enough space to store additional descriptors,
1459 servers SHOULD try to hold those which clients are likely to download the
1460 most. (Currently, this is judged based on the interval for which each
1461 descriptor seemed newest.)
1462 [XXXX define recent]
1464 Authorities SHOULD NOT download descriptors for routers that they would
1465 immediately reject for reasons listed in 3.1.
1467 4.5. Downloading and storing extra-info documents
1469 All authorities, and any cache that chooses to cache extra-info documents,
1470 and any client that uses extra-info documents, should implement this
1473 Note that generally, clients don't need extra-info documents.
1475 Periodically, the Tor instance checks whether it is missing any extra-info
1476 documents: in other words, if it has any router descriptors with an
1477 extra-info-digest field that does not match any of the extra-info
1478 documents currently held. If so, it downloads whatever extra-info
1479 documents are missing. Caches download from authorities; non-caches try
1480 to download from caches. We follow the same splitting and back-off rules
1481 as in 4.4 (if a cache) or 5.3 (if a client).
1483 4.6. General-use HTTP URLs
1485 "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
1487 The most recent v3 consensus should be available at:
1488 http://<hostname>/tor/status-vote/current/consensus.z
1490 Starting with Tor version 0.2.1.1-alpha is also available at:
1491 http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
1493 Where F1, F2, etc. are authority identity fingerprints the client trusts.
1494 Servers will only return a consensus if more than half of the requested
1495 authorities have signed the document, otherwise a 404 error will be sent
1496 back. The fingerprints can be shortened to a length of any multiple of
1497 two, using only the leftmost part of the encoded fingerprint. Tor uses
1498 3 bytes (6 hex characters) of the fingerprint.
1500 Clients SHOULD sort the fingerprints in ascending order. Server MUST
1503 Clients SHOULD use this format when requesting consensus documents from
1504 directory authority servers and from caches running a version of Tor
1505 that is known to support this URL format.
1507 A concatenated set of all the current key certificates should be available
1509 http://<hostname>/tor/keys/all.z
1511 The key certificate for this server (if it is an authority) should be
1513 http://<hostname>/tor/keys/authority.z
1515 The key certificate for an authority whose authority identity fingerprint
1516 is <F> should be available at:
1517 http://<hostname>/tor/keys/fp/<F>.z
1519 The key certificate whose signing key fingerprint is <F> should be
1521 http://<hostname>/tor/keys/sk/<F>.z
1522 [XXX020 cross-certify?]
1524 The most recent descriptor for a server whose identity key has a
1525 fingerprint of <F> should be available at:
1526 http://<hostname>/tor/server/fp/<F>.z
1528 The most recent descriptors for servers with identity fingerprints
1529 <F1>,<F2>,<F3> should be available at:
1530 http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
1532 (NOTE: Implementations SHOULD NOT download descriptors by identity key
1533 fingerprint. This allows a corrupted server (in collusion with a cache) to
1534 provide a unique descriptor to a client, and thereby partition that client
1535 from the rest of the network.)
1537 The server descriptor with (descriptor) digest <D> (in hex) should be
1539 http://<hostname>/tor/server/d/<D>.z
1541 The most recent descriptors with digests <D1>,<D2>,<D3> should be
1543 http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
1545 The most recent descriptor for this server should be at:
1546 http://<hostname>/tor/server/authority.z
1547 [Nothing in the Tor protocol uses this resource yet, but it is useful
1548 for debugging purposes. Also, the official Tor implementations
1549 (starting at 0.1.1.x) use this resource to test whether a server's
1550 own DirPort is reachable.]
1552 A concatenated set of the most recent descriptors for all known servers
1553 should be available at:
1554 http://<hostname>/tor/server/all.z
1556 Extra-info documents are available at the URLS
1557 http://<hostname>/tor/extra/d/...
1558 http://<hostname>/tor/extra/fp/...
1559 http://<hostname>/tor/extra/all[.z]
1560 http://<hostname>/tor/extra/authority[.z]
1561 (As for /tor/server/ URLs: supports fetching extra-info
1562 documents by their digest, by the fingerprint of their servers,
1563 or all at once. When serving by fingerprint, we serve the
1564 extra-info that corresponds to the descriptor we would serve by
1565 that fingerprint. Only directory authorities of version
1566 0.2.0.1-alpha or later are guaranteed to support the first
1567 three classes of URLs. Caches may support them, and MUST
1568 support them if they have advertised "caches-extra-info".)
1570 For debugging, directories SHOULD expose non-compressed objects at URLs like
1571 the above, but without the final ".z".
1572 Clients MUST handle compressed concatenated information in two forms:
1573 - A concatenated list of zlib-compressed objects.
1574 - A zlib-compressed concatenated list of objects.
1575 Directory servers MAY generate either format: the former requires less
1576 CPU, but the latter requires less bandwidth.
1578 Clients SHOULD use upper case letters (A-F) when base16-encoding
1579 fingerprints. Servers MUST accept both upper and lower case fingerprints
1582 5. Client operation: downloading information
1584 Every Tor that is not a directory server (that is, those that do
1585 not have a DirPort set) implements this section.
1587 5.1. Downloading network-status documents
1589 Each client maintains a list of directory authorities. Insofar as
1590 possible, clients SHOULD all use the same list.
1592 Clients try to have a live consensus network-status document at all times.
1593 A network-status document is "live" if the time in its valid-until field
1596 If a client is missing a live network-status document, it tries to fetch
1597 it from a directory cache (or from an authority if it knows no caches).
1598 On failure, the client waits briefly, then tries that network-status
1599 document again from another cache. The client does not build circuits
1600 until it has a live network-status consensus document, and it has
1601 descriptors for more than 1/4 of the routers that it believes are running.
1603 (Note: clients can and should pick caches based on the network-status
1604 information they have: once they have first fetched network-status info
1605 from an authority, they should not need to go to the authority directly
1608 To avoid swarming the caches whenever a consensus expires, the
1609 clients download new consensuses at a randomly chosen time after the
1610 caches are expected to have a fresh consensus, but before their
1611 consensus will expire. (This time is chosen uniformly at random from
1612 the interval between the time 3/4 into the first interval after the
1613 consensus is no longer fresh, and 7/8 of the time remaining after
1614 that before the consensus is invalid.)
1616 [For example, if a cache has a consensus that became valid at 1:00,
1617 and is fresh until 2:00, and expires at 4:00, that cache will fetch
1618 a new consensus at a random time between 2:45 and 3:50, since 3/4
1619 of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
1620 minutes is 65 minutes.]
1622 5.2. Downloading and storing router descriptors
1624 Clients try to have the best descriptor for each router. A descriptor is
1626 * It is listed in the consensus network-status document.
1628 Periodically (currently every 10 seconds) clients check whether there are
1629 any "downloadable" descriptors. A descriptor is downloadable if:
1630 - It is the "best" descriptor for some router.
1631 - The descriptor was published at least 10 minutes in the past.
1632 (This prevents clients from trying to fetch descriptors that the
1633 mirrors have probably not yet retrieved and cached.)
1634 - The client does not currently have it.
1635 - The client is not currently trying to download it.
1636 - The client would not discard it immediately upon receiving it.
1637 - The client thinks it is running and valid (see 6.1 below).
1639 If at least 16 known routers have downloadable descriptors, or if
1640 enough time (currently 10 minutes) has passed since the last time the
1641 client tried to download descriptors, it launches requests for all
1642 downloadable descriptors, as described in 5.3 below.
1644 When a descriptor download fails, the client notes it, and does not
1645 consider the descriptor downloadable again until a certain amount of time
1646 has passed. (Currently 0 seconds for the first failure, 60 seconds for the
1647 second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
1648 thereafter.) Periodically (currently once an hour) clients reset the
1651 Clients retain the most recent descriptor they have downloaded for each
1652 router so long as it is not too old (currently, 48 hours), OR so long as
1653 no better descriptor has been downloaded for the same router.
1655 [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
1656 being published too far in the past.] [The code seems to discard
1657 descriptors in all cases after they're 5 days old. True? -RD]
1659 5.3. Managing downloads
1661 When a client has no consensus network-status document, it downloads it
1662 from a randomly chosen authority. In all other cases, the client
1663 downloads from caches randomly chosen from among those believed to be V2
1664 directory servers. (This information comes from the network-status
1665 documents; see 6 below.)
1667 When downloading multiple router descriptors, the client chooses multiple
1669 - At least 3 different mirrors are used, except when this would result
1670 in more than one request for under 4 descriptors.
1671 - No more than 128 descriptors are requested from a single mirror.
1672 - Otherwise, as few mirrors as possible are used.
1673 After choosing mirrors, the client divides the descriptors among them
1676 After receiving any response client MUST discard any network-status
1677 documents and descriptors that it did not request.
1679 6. Using directory information
1681 Everyone besides directory authorities uses the approaches in this section
1682 to decide which servers to use and what their keys are likely to be.
1683 (Directory authorities just believe their own opinions, as in 3.1 above.)
1685 6.1. Choosing routers for circuits.
1687 Circuits SHOULD NOT be built until the client has enough directory
1688 information: a live consensus network status [XXXX fallback?] and
1689 descriptors for at least 1/4 of the servers believed to be running.
1691 A server is "listed" if it is included by the consensus network-status
1692 document. Clients SHOULD NOT use unlisted servers.
1694 These flags are used as follows:
1696 - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
1699 - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
1700 very-low-bandwidth circuits (such as introduction circuits).
1702 - Clients SHOULD NOT use non-'Stable' routers for circuits that are
1703 likely to need to be open for a very long time (such as those used for
1704 IRC or SSH connections).
1706 - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
1709 - Clients SHOULD NOT download directory information from non-'V2Dir'
1712 See the "path-spec.txt" document for more details.
1714 6.2. Managing naming
1716 In order to provide human-memorable names for individual server
1717 identities, some directory servers bind names to IDs. Clients handle
1720 When a client encounters a name it has not mapped before:
1722 If the consensus lists any router with that name as "Named", or if
1723 consensus-method 2 or later is in use and the consensus lists any
1724 router with that name as having the "Unnamed" flag, then the name is
1725 bound. (It's bound to the ID listed in the entry with the Named,
1726 or to an unknown ID if no name is found.)
1728 When the user refers to a bound name, the implementation SHOULD provide
1729 only the router with ID bound to that name, and no other router, even
1730 if the router with the right ID can't be found.
1732 When a user tries to refer to a non-bound name, the implementation SHOULD
1733 warn the user. After warning the user, the implementation MAY use any
1734 router that advertises the name.
1736 Not every router needs a nickname. When a router doesn't configure a
1737 nickname, it publishes with the default nickname "Unnamed". Authorities
1738 SHOULD NOT ever mark a router with this nickname as Named; client software
1739 SHOULD NOT ever use a router in response to a user request for a router
1742 6.3. Software versions
1744 An implementation of Tor SHOULD warn when it has fetched a consensus
1745 network-status, and it is running a software version not listed.
1747 6.4. Warning about a router's status.
1749 If a router tries to publish its descriptor to a Naming authority
1750 that has its nickname mapped to another key, the router SHOULD
1751 warn the operator that it is either using the wrong key or is using
1752 an already claimed nickname.
1754 If a router has fetched a consensus document,, and the
1755 authorities do not publish a binding for the router's nickname, the
1756 router MAY remind the operator that the chosen nickname is not
1757 bound to this key at the authorities, and suggest contacting the
1758 authority operators.
1762 6.5. Router protocol versions
1764 A client should believe that a router supports a given feature if that
1765 feature is supported by the router or protocol versions in more than half
1766 of the live networkstatuses' "v" entries for that router. In other words,
1767 if the "v" entries for some router are:
1768 v Tor 0.0.8pre1 (from authority 1)
1769 v Tor 0.1.2.11 (from authority 2)
1770 v FutureProtocolDescription 99 (from authority 3)
1771 then the client should believe that the router supports any feature
1772 supported by 0.1.2.11.
1774 This is currently equivalent to believing the median declared version for
1775 a router in all live networkstatuses.
1777 7. Standards compliance
1779 All clients and servers MUST support HTTP 1.0. Clients and servers MAY
1780 support later versions of HTTP as well.
1784 Servers MAY set the Content-Length: header. Servers SHOULD set
1785 Content-Encoding to "deflate" or "identity".
1787 Servers MAY include an X-Your-Address-Is: header, whose value is the
1788 apparent IP address of the client connecting to them (as a dotted quad).
1789 For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
1790 report the IP from which the circuit carrying the BEGIN_DIR stream reached
1791 them. [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
1792 BEGIN_DIR-tunneled connections.]
1794 Servers SHOULD disable caching of multiple network statuses or multiple
1795 router descriptors. Servers MAY enable caching of single descriptors,
1796 single network statuses, the list of all router descriptors, a v1
1797 directory, or a v1 running routers document. XXX mention times.
1799 7.2. HTTP status codes
1801 Tor delivers the following status codes. Some were chosen without much
1802 thought; other code SHOULD NOT rely on specific status codes yet.
1804 200 -- the operation completed successfully
1805 -- the user requested statuses or serverdescs, and none of the ones we
1806 requested were found (0.2.0.4-alpha and earlier).
1808 304 -- the client specified an if-modified-since time, and none of the
1809 requested resources have changed since that time.
1811 400 -- the request is malformed, or
1812 -- the URL is for a malformed variation of one of the URLs we support,
1814 -- the client tried to post to a non-authority, or
1815 -- the authority rejected a malformed posted document, or
1817 404 -- the requested document was not found.
1818 -- the user requested statuses or serverdescs, and none of the ones
1819 requested were found (0.2.0.5-alpha and later).
1821 503 -- we are declining the request in order to save bandwidth
1822 -- user requested some items that we ordinarily generate or store,
1823 but we do not have any available.
1825 9. Backward compatibility and migration plans
1827 Until Tor versions before 0.1.1.x are completely obsolete, directory
1828 authorities should generate, and mirrors should download and cache, v1
1829 directories and running-routers lists, and allow old clients to download
1830 them. These documents and the rules for retrieving, serving, and caching
1831 them are described in dir-spec-v1.txt.
1833 Until Tor versions before 0.2.0.x are completely obsolete, directory
1834 authorities should generate, mirrors should download and cache, v2
1835 network-status documents, and allow old clients to download them.
1836 Additionally, all directory servers and caches should download, store, and
1837 serve any router descriptor that is required because of v2 network-status
1838 documents. These documents and the rules for retrieving, serving, and
1839 caching them are described in dir-spec-v1.txt.
1841 A. Consensus-negotiation timeline.
1844 Period begins: this is the Published time.
1845 Everybody sends votes
1846 Reconciliation: everybody tries to fetch missing votes.
1847 consensus may exist at this point.
1848 End of voting period:
1849 everyone swaps signatures.
1850 Now it's okay for caches to download
1851 Now it's okay for clients to download.
1853 Valid-after/valid-until switchover