2 Tor directory protocol, version 3
4 0. Scope and preliminaries
6 This directory protocol is used by Tor version 0.2.0.x-alpha and later.
7 See dir-spec-v1.txt for information on the protocol used up to the
8 0.1.0.x series, and dir-spec-v2.txt for information on the protocol
9 used by the 0.1.1.x and 0.1.2.x series.
11 Caches and authorities must still support older versions of the
12 directory protocols, until the versions of Tor that require them are
13 finally out of commission.
15 This document merges and supersedes the following proposals:
17 101 Voting on the Tor Directory System
18 103 Splitting identity key from regularly used signing key
19 104 Long and Short Router Descriptors
21 XXX when to download certificates.
25 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
26 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
27 "OPTIONAL" in this document are to be interpreted as described in
32 The earliest versions of Onion Routing shipped with a list of known
33 routers and their keys. When the set of routers changed, users needed to
36 The Version 1 Directory protocol
37 --------------------------------
39 Early versions of Tor (0.0.2) introduced "Directory authorities": servers
40 that served signed "directory" documents containing a list of signed
41 "router descriptors", along with short summary of the status of each
42 router. Thus, clients could get up-to-date information on the state of
43 the network automatically, and be certain that the list they were getting
44 was attested by a trusted directory authority.
46 Later versions (0.0.8) added directory caches, which download
47 directories from the authorities and serve them to clients. Non-caches
48 fetch from the caches in preference to fetching from the authorities, thus
49 distributing bandwidth requirements.
51 Also added during the version 1 directory protocol were "router status"
52 documents: short documents that listed only the up/down status of the
53 routers on the network, rather than a complete list of all the
54 descriptors. Clients and caches would fetch these documents far more
55 frequently than they would fetch full directories.
57 The Version 2 Directory Protocol
58 --------------------------------
60 During the Tor 0.1.1.x series, Tor revised its handling of directory
61 documents in order to address two major problems:
63 * Directories had grown quite large (over 1MB), and most directory
64 downloads consisted mainly of router descriptors that clients
67 * Every directory authority was a trust bottleneck: if a single
68 directory authority lied, it could make clients believe for a time
69 an arbitrarily distorted view of the Tor network. (Clients
70 trusted the most recent signed document they downloaded.) Thus,
71 adding more authorities would make the system less secure, not
74 To address these, we extended the directory protocol so that
75 authorities now published signed "network status" documents. Each
76 network status listed, for every router in the network: a hash of its
77 identity key, a hash of its most recent descriptor, and a summary of
78 what the authority believed about its status. Clients would download
79 the authorities' network status documents in turn, and believe
80 statements about routers iff they were attested to by more than half of
83 Instead of downloading all router descriptors at once, clients
84 downloaded only the descriptors that they did not have. Descriptors
85 were indexed by their digests, in order to prevent malicious caches
86 from giving different versions of a router descriptor to different
89 Routers began working harder to upload new descriptors only when their
90 contents were substantially changed.
93 0.2. Goals of the version 3 protocol
95 Version 3 of the Tor directory protocol tries to solve the following
98 * A great deal of bandwidth used to transmit router descriptors was
99 used by two fields that are not actually used by Tor routers
100 (namely read-history and write-history). We save about 60% by
101 moving them into a separate document that most clients do not
104 * It was possible under certain perverse circumstances for clients
105 to download an unusual set of network status documents, thus
106 partitioning themselves from clients who have a more recent and/or
107 typical set of documents. Even under the best of circumstances,
108 clients were sensitive to the ages of the network status documents
109 they downloaded. Therefore, instead of having the clients
110 correlate multiple network status documents, we have the
111 authorities collectively vote on a single consensus network status
114 * The most sensitive data in the entire network (the identity keys
115 of the directory authorities) needed to be stored unencrypted so
116 that the authorities can sign network-status documents on the fly.
117 Now, the authorities' identity keys are stored offline, and used
118 to certify medium-term signing keys that can be rotated.
120 0.3. Some Remaining questions
122 Things we could solve on a v3 timeframe:
124 The SHA-1 hash is showing its age. We should do something about our
125 dependency on it. We could probably future-proof ourselves here in
126 this revision, at least so far as documents from the authorities are
129 Too many things about the authorities are hardcoded by IP.
131 Perhaps we should start accepting longer identity keys for routers
134 Things to solve eventually:
136 Requiring every client to know about every router won't scale forever.
138 Requiring every directory cache to know every router won't scale
144 There is a small set (say, around 5-10) of semi-trusted directory
145 authorities. A default list of authorities is shipped with the Tor
146 software. Users can change this list, but are encouraged not to do so,
147 in order to avoid partitioning attacks.
149 Every authority has a very-secret, long-term "Authority Identity Key".
150 This is stored encrypted and/or offline, and is used to sign "key
151 certificate" documents. Every key certificate contains a medium-term
152 (3-12 months) "authority signing key", that is used by the authority to
153 sign other directory information. (Note that the authority identity
154 key is distinct from the router identity key that the authority uses
155 in its role as an ordinary router.)
157 Routers periodically upload signed "routers descriptors" to the
158 directory authorities describing their keys, capabilities, and other
159 information. Routers may also upload signed "extra info documents"
160 containing information that is not required for the Tor protocol.
161 Directory authorities serve router descriptors indexed by router
162 identity, or by hash of the descriptor.
164 Routers may act as directory caches to reduce load on the directory
165 authorities. They announce this in their descriptors.
167 Periodically, each directory authority generates a view of
168 the current descriptors and status for known routers. They send a
169 signed summary of this view (a "status vote") to the other
170 authorities. The authorities compute the result of this vote, and sign
171 a "consensus status" document containing the result of the vote.
173 Directory caches download, cache, and re-serve consensus documents.
175 Clients, directory caches, and directory authorities all use consensus
176 documents to find out when their list of routers is out-of-date.
177 (Directory authorities also use vote statuses.) If it is, they download
178 any missing router descriptors. Clients download missing descriptors
179 from caches; caches and authorities download from authorities.
180 Descriptors are downloaded by the hash of the descriptor, not by the
181 relay's identity key: this prevents directory servers from attacking
182 clients by giving them descriptors nobody else uses.
184 All directory information is uploaded and downloaded with HTTP.
186 [Authorities also generate and caches also cache documents produced and
187 used by earlier versions of this protocol; see dir-spec-v1.txt and
188 dir-spec-v2.txt for notes on those versions.]
190 1.1. What's different from version 2?
192 Clients used to download multiple network status documents,
193 corresponding roughly to "status votes" above. They would compute the
194 result of the vote on the client side.
196 Authorities used to sign documents using the same private keys they used
197 for their roles as routers. This forced them to keep these extremely
198 sensitive keys in memory unencrypted.
200 All of the information in extra-info documents used to be kept in the
203 1.2. Document meta-format
205 Router descriptors, directories, and running-routers documents all obey the
206 following lightweight extensible information format.
208 The highest level object is a Document, which consists of one or more
209 Items. Every Item begins with a KeywordLine, followed by zero or more
210 Objects. A KeywordLine begins with a Keyword, optionally followed by
211 whitespace and more non-newline characters, and ends with a newline. A
212 Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
213 An Object is a block of encoded data in pseudo-Open-PGP-style
214 armor. (cf. RFC 2440)
218 NL = The ascii LF character (hex value 0x0a).
219 Document ::= (Item | NL)+
220 Item ::= KeywordLine Object*
221 KeywordLine ::= Keyword NL | Keyword WS ArgumentChar+ NL
222 Keyword = KeywordChar+
223 KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
224 ArgumentChar ::= any printing ASCII character except NL.
226 Object ::= BeginLine Base-64-encoded-data EndLine
227 BeginLine ::= "-----BEGIN " Keyword "-----" NL
228 EndLine ::= "-----END " Keyword "-----" NL
230 The BeginLine and EndLine of an Object must use the same keyword.
232 When interpreting a Document, software MUST ignore any KeywordLine that
233 starts with a keyword it doesn't recognize; future implementations MUST NOT
234 require current clients to understand any KeywordLine not currently
237 The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
238 extensions. All implementations MUST ignore any item of the form "opt
239 keyword ....." when they would not recognize "keyword ....."; and MUST
240 treat "opt keyword ....." as synonymous with "keyword ......" when keyword
243 Implementations before 0.1.2.5-alpha rejected any document with a
244 KeywordLine that started with a keyword that they didn't recognize.
245 When generating documents that need to be read by older versions of Tor,
246 implementations MUST prefix items not recognized by older versions of
247 Tor with an "opt" until those versions of Tor are obsolete. [Note that
248 key certificates, status vote documents, extra info documents, and
249 status consensus documents will never be read by older versions of Tor.]
251 Other implementations that want to extend Tor's directory format MAY
252 introduce their own items. The keywords for extension items SHOULD start
253 with the characters "x-" or "X-", to guarantee that they will not conflict
254 with keywords used by future versions of Tor.
256 In our document descriptions below, we tag Items with a multiplicity in
257 brackets. Possible tags are:
259 "At start, exactly once": These items MUST occur in every instance of
260 the document type, and MUST appear exactly once, and MUST be the
261 first item in their documents.
263 "Exactly once": These items MUST occur exactly one time in every
264 instance of the document type.
266 "At end, exactly once": These items MUST occur in every instance of
267 the document type, and MUST appear exactly once, and MUST be the
268 last item in their documents.
270 "At most once": These items MAY occur zero or one times in any
271 instance of the document type, but MUST NOT occur more than once.
273 "Any number": These items MAY occur zero, one, or more times in any
274 instance of the document type.
276 "Once or more": These items MUST occur at least once in any instance
277 of the document type, and MAY occur more.
279 1.3. Signing documents
281 Every signable document below is signed in a similar manner, using a
282 given "Initial Item", a final "Signature Item", a digest algorithm, and
285 The Initial Item must be the first item in the document.
287 The Signature Item has the following format:
289 <signature item keyword> [arguments] NL SIGNATURE NL
291 The "SIGNATURE" Object contains a signature (using the signing key) of
292 the PKCS1-padded digest of the entire document, taken from the
293 beginning of the Initial item, through the newline after the Signature
294 Item's keyword and its arguments.
296 Unless otherwise, the digest algorithm is SHA-1.
298 All documents are invalid unless signed with the correct signing key.
300 The "Digest" of a document, unless stated otherwise, is its digest *as
301 signed by this signature scheme*.
305 Every consensus document has a "valid-after" (VA) time, a "fresh-until"
306 (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
307 in turn precede VU. Times are chosen so that every consensus will be
308 "fresh" until the next consensus becomes valid, and "valid" for a while
309 after. At least 3 consensuses should be valid at any given time.
311 The timeline for a given consensus is as follows:
313 VA-DistSeconds-VoteSeconds: The authorities exchange votes.
315 VA-DistSeconds-VoteSeconds/2: The authorities try to download any
316 votes they don't have.
318 VA-DistSeconds: The authorities calculate the consensus and exchange
321 VA-DistSeconds/2: The authorities try to download any signatures
324 VA: All authorities have a multiply signed consensus.
326 VA ... FU: Caches download the consensus. (Note that since caches have
327 no way of telling what VA and FU are until they have downloaded
328 the consensus, they assume that the present consensus's VA is
329 equal to the previous one's FU, and that its FU is one interval after
332 FU: The consensus is no longer the freshest consensus.
334 FU ... (the current consensus's VU): Clients download the consensus.
335 (See note above: clients guess that the next consensus's FU will be
336 two intervals after the current VA.)
338 VU: The consensus is no longer valid.
340 VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
341 VU-FU MUST each be at least 5 minutes.
343 2. Router operation and formats
345 ORs SHOULD generate a new router descriptor and a new extra-info
346 document whenever any of the following events have occurred:
348 - A period of time (18 hrs by default) has passed since the last
349 time a descriptor was generated.
351 - A descriptor field other than bandwidth or uptime has changed.
353 - Bandwidth has changed by a factor of 2 from the last time a
354 descriptor was generated, and at least a given interval of time
355 (20 mins by default) has passed since then.
357 - Its uptime has been reset (by restarting).
359 [XXX this list is incomplete; see router_differences_are_cosmetic()
360 in routerlist.c for others]
362 ORs SHOULD NOT publish a new router descriptor or extra-info document
363 if none of the above events have occurred and not much time has passed
364 (12 hours by default).
366 After generating a descriptor, ORs upload them to every directory
367 authority they know, by posting them (in order) to the URL
369 http://<hostname:port>/tor/
371 2.1. Router descriptor format
373 Router descriptors consist of the following items. For backward
374 compatibility, there should be an extra NL at the end of each router
377 In lines that take multiple arguments, extra arguments SHOULD be
378 accepted and ignored. Many of the nonterminals below are defined in
381 "router" nickname address ORPort SOCKSPort DirPort NL
383 [At start, exactly once.]
385 Indicates the beginning of a router descriptor. "nickname" must be a
386 valid router nickname as specified in 2.3. "address" must be an IPv4
387 address in dotted-quad format. The last three numbers indicate the
388 TCP ports at which this OR exposes functionality. ORPort is a port at
389 which this OR accepts TLS connections for the main OR protocol;
390 SOCKSPort is deprecated and should always be 0; and DirPort is the
391 port at which this OR accepts directory-related HTTP connections. If
392 any port is not supported, the value 0 is given instead of a port
393 number. (At least one of DirPort and ORPort SHOULD be set;
394 authorities MAY reject any descriptor with both DirPort and ORPort of
397 "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
401 Estimated bandwidth for this router, in bytes per second. The
402 "average" bandwidth is the volume per second that the OR is willing to
403 sustain over long periods; the "burst" bandwidth is the volume that
404 the OR is willing to sustain in very short intervals. The "observed"
405 value is an estimate of the capacity this relay can handle. The
406 relay remembers the max bandwidth sustained output over any ten
407 second period in the past day, and another sustained input. The
408 "observed" value is the lesser of these two numbers.
414 A human-readable string describing the system on which this OR is
415 running. This MAY include the operating system, and SHOULD include
416 the name and version of the software implementing the Tor protocol.
418 "published" YYYY-MM-DD HH:MM:SS NL
422 The time, in GMT, when this descriptor (and its corresponding
423 extra-info document if any) was generated.
425 "fingerprint" fingerprint NL
429 A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
430 hex, with a single space after every 4 characters) for this router's
431 identity key. A descriptor is considered invalid (and MUST be
432 rejected) if the fingerprint line does not match the public key.
434 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
435 be marked with "opt" until earlier versions of Tor are obsolete.]
437 "hibernating" bool NL
441 If the value is 1, then the Tor relay was hibernating when the
442 descriptor was published, and shouldn't be used to build circuits.
444 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
445 marked with "opt" until earlier versions of Tor are obsolete.]
451 The number of seconds that this OR process has been running.
453 "onion-key" NL a public key in PEM format
457 This key is used to encrypt EXTEND cells for this OR. The key MUST be
458 accepted for at least 1 week after any new key is published in a
459 subsequent descriptor. It MUST be 1024 bits.
461 "signing-key" NL a public key in PEM format
465 The OR's long-term identity key. It MUST be 1024 bits.
467 "accept" exitpattern NL
468 "reject" exitpattern NL
472 These lines describe an "exit policy": the rules that an OR follows
473 when deciding whether to allow a new stream to a given address. The
474 'exitpattern' syntax is described below. There MUST be at least one
475 such entry. The rules are considered in order; if no rule matches,
476 the address will be accepted. For clarity, the last such entry SHOULD
477 be accept *:* or reject *:*.
479 "router-signature" NL Signature NL
481 [At end, exactly once]
483 The "SIGNATURE" object contains a signature of the PKCS1-padded
484 hash of the entire router descriptor, taken from the beginning of the
485 "router" line, through the newline after the "router-signature" line.
486 The router descriptor is invalid unless the signature is performed
487 with the router's identity key.
493 Describes a way to contact the relay's administrator, preferably
494 including an email address and a PGP key fingerprint.
500 'Names' is a space-separated list of relay nicknames or
501 hexdigests. If two ORs list one another in their "family" entries,
502 then OPs should treat them as a single OR for the purpose of path
505 For example, if node A's descriptor contains "family B", and node B's
506 descriptor contains "family A", then node A and node B should never
507 be used on the same circuit.
509 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
511 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
514 Declare how much bandwidth the OR has used recently. Usage is divided
515 into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
516 defines the end of the most recent interval. The numbers are the
517 number of bytes used in the most recent intervals, ordered from
520 [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
521 be marked with "opt" until earlier versions of Tor are obsolete.]
523 [See also migration notes in section 2.2.1.]
529 Declare whether this version of Tor is using the newer enhanced
530 dns logic. Versions of Tor with this field set to false SHOULD NOT
531 be used for reverse hostname lookups.
533 [This option is obsolete. All Tor current relays should be presumed
534 to have the evdns backend.]
536 "caches-extra-info" NL
540 Present only if this router is a directory cache that provides
541 extra-info documents.
543 [Versions before 0.2.0.1-alpha don't recognize this, and versions
544 before 0.1.2.5-alpha will reject descriptors containing it unless
545 it is prefixed with "opt"; it should be so prefixed until these
546 versions are obsolete.]
548 "extra-info-digest" digest NL
552 "Digest" is a hex-encoded digest (using upper-case characters) of the
553 router's extra-info document, as signed in the router's extra-info
554 (that is, not including the signature). (If this field is absent, the
555 router is not uploading a corresponding extra-info document.)
557 [Versions before 0.2.0.1-alpha don't recognize this, and versions
558 before 0.1.2.5-alpha will reject descriptors containing it unless
559 it is prefixed with "opt"; it should be so prefixed until these
560 versions are obsolete.]
562 "hidden-service-dir" *(SP VersionNum) NL
566 Present only if this router stores and serves hidden service
567 descriptors. If any VersionNum(s) are specified, this router
568 supports those descriptor versions. If none are specified, it
569 defaults to version 2 descriptors.
571 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
572 with unrecognized items; the protocols line should be preceded with
573 an "opt" until these Tors are obsolete.]
575 "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
576 CIRCUIT-VERSION-LIST NL
580 Both lists are space-separated sequences of numbers, to indicate which
581 protocols the server supports. As of 30 Mar 2008, specified
582 protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt
583 for more information about link protocol versions.
585 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
586 with unrecognized items; the protocols line should be preceded with
587 an "opt" until these Tors are obsolete.]
589 "allow-single-hop-exits" NL
593 Present only if the router allows single-hop circuits to make exit
594 connections. Most Tor relays do not support this: this is
595 included for specialized controllers designed to support perspective
599 2.2. Extra-info documents
601 Extra-info documents consist of the following items:
603 "extra-info" Nickname Fingerprint NL
604 [At start, exactly once.]
606 Identifies what router this is an extra info descriptor for.
607 Fingerprint is encoded in hex (using upper-case letters), with
610 "published" YYYY-MM-DD HH:MM:SS NL
614 The time, in GMT, when this document (and its corresponding router
615 descriptor if any) was generated. It MUST match the published time
616 in the corresponding router descriptor.
618 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
620 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
623 As documented in 2.1 above. See migration notes in section 2.2.1.
625 "geoip-db-digest" Digest NL
628 SHA1 digest of the GeoIP database file that is used to resolve IP
629 addresses to country codes.
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 "geoip-start" and "geoip-client-origins" have been replaced by
646 "bridge-stats-end" and "bridge-stats-ips" in 0.2.2.4-alpha. The
647 reason is that the measurement interval with "geoip-stats" as
648 determined by subtracting "geoip-start" from "published" could
649 have had a variable length, whereas the measurement interval in
650 0.2.2.4-alpha and later is set to be exactly 24 hours long. In
651 order to clearly distinguish the new measurement intervals from
652 the old ones, the new keywords have been introduced.
654 "bridge-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
657 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
658 interval of length NSEC seconds (86400 seconds by default).
660 A "bridge-stats-end" line, as well as any other "bridge-*" line,
661 is only added when the relay has been running as a bridge for at
664 "bridge-ips" CC=N,CC=N,... NL
667 List of mappings from two-letter country codes to the number of
668 unique IP addresses that have connected from that country to the
669 bridge and which are no known relays, rounded up to the nearest
672 "dirreq-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
675 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
676 interval of length NSEC seconds (86400 seconds by default).
678 A "dirreq-stats-end" line, as well as any other "dirreq-*" line,
679 is only added when the relay has opened its Dir port and after 24
680 hours of measuring directory requests.
682 "dirreq-v2-ips" CC=N,CC=N,... NL
684 "dirreq-v3-ips" CC=N,CC=N,... NL
687 List of mappings from two-letter country codes to the number of
688 unique IP addresses that have connected from that country to
689 request a v2/v3 network status, rounded up to the nearest multiple
690 of 8. Only those IP addresses are counted that the directory can
691 answer with a 200 OK status code.
693 "dirreq-v2-reqs" CC=N,CC=N,... NL
695 "dirreq-v3-reqs" CC=N,CC=N,... NL
698 List of mappings from two-letter country codes to the number of
699 requests for v2/v3 network statuses from that country, rounded up
700 to the nearest multiple of 8. Only those requests are counted that
701 the directory can answer with a 200 OK status code.
703 "dirreq-v2-share" num% NL
705 "dirreq-v3-share" num% NL
708 The share of v2/v3 network status requests that the directory
709 expects to receive from clients based on its advertised bandwidth
710 compared to the overall network bandwidth capacity. Shares are
711 formatted in percent with two decimal places. Shares are
712 calculated as means over the whole 24-hour interval.
714 "dirreq-v2-resp" status=num,... NL
716 "dirreq-v3-resp" status=nul,... NL
719 List of mappings from response statuses to the number of requests
720 for v2/v3 network statuses that were answered with that response
721 status, rounded up to the nearest multiple of 4. Only response
722 statuses with at least 1 response are reported. New response
723 statuses can be added at any time. The current list of response
724 statuses is as follows:
726 "ok": a network status request is answered; this number
727 corresponds to the sum of all requests as reported in
728 "dirreq-v2-reqs" or "dirreq-v3-reqs", respectively, before
730 "not-enough-sigs: a version 3 network status is not signed by a
731 sufficient number of requested authorities.
732 "unavailable": a requested network status object is unavailable.
733 "not-found": a requested network status is not found.
734 "not-modified": a network status has not been modified since the
735 If-Modified-Since time that is included in the request.
736 "busy": the directory is busy.
738 "dirreq-v2-direct-dl" key=val,... NL
740 "dirreq-v3-direct-dl" key=val,... NL
742 "dirreq-v2-tunneled-dl" key=val,... NL
744 "dirreq-v3-tunneled-dl" key=val,... NL
747 List of statistics about possible failures in the download process
748 of v2/v3 network statuses. Requests are either "direct"
749 HTTP-encoded requests over the relay's directory port, or
750 "tunneled" requests using a BEGIN_DIR cell over the relay's OR
751 port. The list of possible statistics can change, and statistics
752 can be left out from reporting. The current list of statistics is
755 Successful downloads and failures:
757 "complete": a client has finished the download successfully.
758 "timeout": a download did not finish within 10 minutes after
759 starting to send the response.
760 "running": a download is still running at the end of the
761 measurement period for less than 10 minutes after starting to
766 "min", "max": smallest and largest measured bandwidth in B/s.
767 "d[1-4,6-9]": 1st to 4th and 6th to 9th decile of measured
768 bandwidth in B/s. For a given decile i, i/10 of all downloads
769 had a smaller bandwidth than di, and (10-i)/10 of all downloads
770 had a larger bandwidth than di.
771 "q[1,3]": 1st and 3rd quartile of measured bandwidth in B/s. One
772 fourth of all downloads had a smaller bandwidth than q1, one
773 fourth of all downloads had a larger bandwidth than q3, and the
774 remaining half of all downloads had a bandwidth between q1 and
776 "md": median of measured bandwidth in B/s. Half of the downloads
777 had a smaller bandwidth than md, the other half had a larger
780 "dirreq-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
782 "dirreq-write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
785 Declare how much bandwidth the OR has spent on answering directory
786 requests. Usage is divided into intervals of NSEC seconds. The
787 YYYY-MM-DD HH:MM:SS field defines the end of the most recent
788 interval. The numbers are the number of bytes used in the most
789 recent intervals, ordered from oldest to newest.
791 "entry-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
794 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
795 interval of length NSEC seconds (86400 seconds by default).
797 An "entry-stats-end" line, as well as any other "entry-*"
798 line, is first added after the relay has been running for at least
801 "entry-ips" CC=N,CC=N,... NL
804 List of mappings from two-letter country codes to the number of
805 unique IP addresses that have connected from that country to the
806 relay and which are no known other relays, rounded up to the
807 nearest multiple of 8.
809 "cell-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
812 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
813 interval of length NSEC seconds (86400 seconds by default).
815 A "cell-stats-end" line, as well as any other "cell-*" line,
816 is first added after the relay has been running for at least 24
819 "cell-processed-cells" num,...,num NL
822 Mean number of processed cells per circuit, subdivided into
823 deciles of circuits by the number of cells they have processed in
824 descending order from loudest to quietest circuits.
826 "cell-queued-cells" num,...,num NL
829 Mean number of cells contained in queues by circuit decile. These
830 means are calculated by 1) determining the mean number of cells in
831 a single circuit between its creation and its termination and 2)
832 calculating the mean for all circuits in a given decile as
833 determined in "cell-processed-cells". Numbers have a precision of
836 "cell-time-in-queue" num,...,num NL
839 Mean time cells spend in circuit queues in milliseconds. Times are
840 calculated by 1) determining the mean time cells spend in the
841 queue of a single circuit and 2) calculating the mean for all
842 circuits in a given decile as determined in
843 "cell-processed-cells".
845 "cell-circuits-per-decile" num NL
848 Mean number of circuits that are included in any of the deciles,
849 rounded up to the next integer.
851 "conn-bi-direct" YYYY-MM-DD HH:MM:SS (NSEC s) BELOW,READ,WRITE,BOTH NL
854 Number of connections, split into 10-second intervals, that are
855 used uni-directionally or bi-directionally as observed in the NSEC
856 seconds (usually 86400 seconds) before YYYY-MM-DD HH:MM:SS. Every
857 10 seconds, we determine for every connection whether we read and
858 wrote less than a threshold of 20 KiB (BELOW), read at least 10
859 times more than we wrote (READ), wrote at least 10 times more than
860 we read (WRITE), or read and wrote more than the threshold, but
861 not 10 times more in either direction (BOTH). After classifying a
862 connection, read and write counters are reset for the next
865 "exit-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
868 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
869 interval of length NSEC seconds (86400 seconds by default).
871 An "exit-stats-end" line, as well as any other "exit-*" line, is
872 first added after the relay has been running for at least 24 hours
873 and only if the relay permits exiting (where exiting to a single
874 port and IP address is sufficient).
876 "exit-kibibytes-written" port=N,port=N,... NL
878 "exit-kibibytes-read" port=N,port=N,... NL
881 List of mappings from ports to the number of kibibytes that the
882 relay has written to or read from exit connections to that port,
883 rounded up to the next full kibibyte.
885 "exit-streams-opened" port=N,port=N,... NL
888 List of mappings from ports to the number of opened exit streams
889 to that port, rounded up to the nearest multiple of 4.
891 "router-signature" NL Signature NL
892 [At end, exactly once.]
894 A document signature as documented in section 1.3, using the
895 initial item "extra-info" and the final item "router-signature",
896 signed with the router's identity key.
898 2.2.1. Moving history fields to extra-info documents.
900 Tools that want to use the read-history and write-history values SHOULD
901 download extra-info documents as well as router descriptors. Such
902 tools SHOULD accept history values from both sources; if they appear in
903 both documents, the values in the extra-info documents are authoritative.
905 New versions of Tor no longer generate router descriptors
906 containing read-history or write-history. Tools should continue to
907 accept read-history and write-history values in router descriptors
908 produced by older versions of Tor until all Tor versions earlier
909 than 0.2.0.x are obsolete.
911 2.3. Nonterminals in router descriptors
913 nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
915 hexdigest ::= a '$', followed by 40 hexadecimal characters
916 ([A-Fa-f0-9]). [Represents a relay by the digest of its identity
919 exitpattern ::= addrspec ":" portspec
920 portspec ::= "*" | port | port "-" port
921 port ::= an integer between 1 and 65535, inclusive.
923 [Some implementations incorrectly generate ports with value 0.
924 Implementations SHOULD accept this, and SHOULD NOT generate it.
925 Connections to port 0 are never permitted.]
927 addrspec ::= "*" | ip4spec | ip6spec
928 ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
929 ip4 ::= an IPv4 address in dotted-quad format
930 ip4mask ::= an IPv4 mask in dotted-quad format
931 num_ip4_bits ::= an integer between 0 and 32
932 ip6spec ::= ip6 | ip6 "/" num_ip6_bits
933 ip6 ::= an IPv6 address, surrounded by square brackets.
934 num_ip6_bits ::= an integer between 0 and 128
938 3. Formats produced by directory authorities.
940 Every authority has two keys used in this protocol: a signing key, and
941 an authority identity key. (Authorities also have a router identity
942 key used in their role as a router and by earlier versions of the
943 directory protocol.) The identity key is used from time to time to
944 sign new key certificates using new signing keys; it is very sensitive.
945 The signing key is used to sign key certificates and status documents.
947 There are three kinds of documents generated by directory authorities:
953 Each is discussed below.
955 3.1. Key certificates
957 Key certificates consist of the following items:
959 "dir-key-certificate-version" version NL
961 [At start, exactly once.]
963 Determines the version of the key certificate. MUST be "3" for
964 the protocol described in this document. Implementations MUST
965 reject formats they don't understand.
967 "dir-address" IPPort NL
970 An IP:Port for this authority's directory port.
972 "fingerprint" fingerprint NL
976 Hexadecimal encoding without spaces based on the authority's
979 "dir-identity-key" NL a public key in PEM format
983 The long-term authority identity key for this authority. This key
984 SHOULD be at least 2048 bits long; it MUST NOT be shorter than
987 "dir-key-published" YYYY-MM-DD HH:MM:SS NL
991 The time (in GMT) when this document and corresponding key were
994 "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
998 A time (in GMT) after which this key is no longer valid.
1000 "dir-signing-key" NL a key in PEM format
1004 The directory server's public signing key. This key MUST be at
1005 least 1024 bits, and MAY be longer.
1007 "dir-key-crosscert" NL CrossSignature NL
1011 NOTE: Authorities MUST include this field in all newly generated
1012 certificates. A future version of this specification will make
1015 CrossSignature is a signature, made using the certificate's signing
1016 key, of the digest of the PKCS1-padded hash of the certificate's
1017 identity key. For backward compatibility with broken versions of the
1018 parser, we wrap the base64-encoded signature in -----BEGIN ID
1019 SIGNATURE---- and -----END ID SIGNATURE----- tags. Implementations
1020 MUST allow the "ID " portion to be omitted, however.
1022 When encountering a certificate with a dir-key-crosscert entry,
1023 implementations MUST verify that the signature is a correct signature
1024 of the hash of the identity key using the signing key.
1026 "dir-key-certification" NL Signature NL
1028 [At end, exactly once.]
1030 A document signature as documented in section 1.3, using the
1031 initial item "dir-key-certificate-version" and the final item
1032 "dir-key-certification", signed with the authority identity key.
1034 Authorities MUST generate a new signing key and corresponding
1035 certificate before the key expires.
1037 3.2. Vote and consensus status documents
1039 Votes and consensuses are more strictly formatted then other documents
1040 in this specification, since different authorities must be able to
1041 generate exactly the same consensus given the same set of votes.
1043 The procedure for deciding when to generate vote and consensus status
1044 documents are described in section 1.4 on the voting timeline.
1046 Status documents contain a preamble, an authority section, a list of
1047 router status entries, and one or more footer signature, in that order.
1049 Unlike other formats described above, a SP in these documents must be a
1050 single space character (hex 20).
1052 Some items appear only in votes, and some items appear only in
1053 consensuses. Unless specified, items occur in both.
1055 The preamble contains the following items. They MUST occur in the
1058 "network-status-version" SP version NL.
1060 [At start, exactly once.]
1062 A document format version. For this specification, the version is
1065 "vote-status" SP type NL
1069 The status MUST be "vote" or "consensus", depending on the type of
1072 "consensus-methods" SP IntegerList NL
1074 [Exactly once for votes; does not occur in consensuses.]
1076 A space-separated list of supported methods for generating
1077 consensuses from votes. See section 3.4.1 for details. Method "1"
1080 "consensus-method" SP Integer NL
1082 [Exactly once for consensuses; does not occur in votes.]
1084 See section 3.4.1 for details.
1086 (Only included when the vote is generated with consensus-method 2 or
1089 "published" SP YYYY-MM-DD SP HH:MM:SS NL
1091 [Exactly once for votes; does not occur in consensuses.]
1093 The publication time for this status document (if a vote).
1095 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1099 The start of the Interval for this vote. Before this time, the
1100 consensus document produced from this vote should not be used.
1101 See 1.4 for voting timeline information.
1103 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1107 The time at which the next consensus should be produced; before this
1108 time, there is no point in downloading another consensus, since there
1109 won't be a new one. See 1.4 for voting timeline information.
1111 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1115 The end of the Interval for this vote. After this time, the
1116 consensus produced by this vote should not be used. See 1.4 for
1117 voting timeline information.
1119 "voting-delay" SP VoteSeconds SP DistSeconds NL
1123 VoteSeconds is the number of seconds that we will allow to collect
1124 votes from all authorities; DistSeconds is the number of seconds
1125 we'll allow to collect signatures from all authorities. See 1.4 for
1126 voting timeline information.
1128 "client-versions" SP VersionList NL
1132 A comma-separated list of recommended Tor versions for client
1133 usage, in ascending order. The versions are given as defined by
1134 version-spec.txt. If absent, no opinion is held about client
1137 "server-versions" SP VersionList NL
1141 A comma-separated list of recommended Tor versions for relay
1142 usage, in ascending order. The versions are given as defined by
1143 version-spec.txt. If absent, no opinion is held about server
1146 "known-flags" SP FlagList NL
1150 A space-separated list of all of the flags that this document
1151 might contain. A flag is "known" either because the authority
1152 knows about them and might set them (if in a vote), or because
1153 enough votes were counted for the consensus for an authoritative
1154 opinion to have been formed about their status.
1156 "params" SP [Parameters] NL
1160 Parameter ::= Keyword '=' Int32
1161 Int32 ::= A decimal integer between -2147483648 and 2147483647.
1162 Parameters ::= Parameter | Parameters SP Parameter
1164 The parameters list, if present, contains a space-separated list of
1165 case-sensitive key-value pairs, sorted in lexical order by their
1166 keyword (as ASCII byte strings). Each parameter has its own meaning.
1168 (Only included when the vote is generated with consensus-method 7 or
1171 Commonly used "param" arguments at this point include:
1173 "circwindow" -- the default package window that circuits should
1174 be established with. It started out at 1000 cells, but some
1175 research indicates that a lower value would mean fewer cells in
1176 transit in the network at any given time. Obeyed by Tor 0.2.1.20
1180 "CircuitPriorityHalflifeMsec" -- the halflife parameter used when
1181 weighting which circuit will send the next cell. Obeyed by Tor
1182 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha
1183 and 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter,
1184 but mishandled it badly.)
1185 Min: -1, Max: 2147483647 (INT32_MAX)
1187 "perconnbwrate" and "perconnbwburst" -- if set, each relay sets
1188 up a separate token bucket for every client OR connection,
1189 and rate limits that connection indepedently. Typically left
1190 unset, except when used for performance experiments around trac
1191 entry 1750. Only honored by relays running Tor 0.2.2.16-alpha
1192 and later. (Note that relays running 0.2.2.7-alpha through
1193 0.2.2.14-alpha looked for bwconnrate and bwconnburst, but then
1194 did the wrong thing with them; see bug 1830 for details.)
1195 Min: 1, Max: 2147483647 (INT32_MAX)
1197 "refuseunknownexits" -- if set to one, exit relays look at
1198 the previous hop of circuits that ask to open an exit stream,
1199 and refuse to exit if they don't recognize it as a relay. The
1200 goal is to make it harder for people to use them as one-hop
1201 proxies. See trac entry 1751 for details.
1204 "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts",
1205 "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq",
1206 "cbtmintimeout", and "cbtinitialtimeout" -- see "2.4.5. Consensus
1207 parameters governing behavior" in path-spec.txt for a series of
1208 circuit build time related consensus params.
1210 "UseOptimisticData" -- If set to zero, clients by default
1211 shouldn't try to send optimistic data to servers until they have
1212 received a RELAY_CONNECTED cell.
1215 The authority section of a vote contains the following items, followed
1216 in turn by the authority's current key certificate:
1218 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
1221 [Exactly once, at start]
1223 Describes this authority. The nickname is a convenient identifier
1224 for the authority. The identity is an uppercase hex fingerprint of
1225 the authority's current (v3 authority) identity key. The address is
1226 the server's hostname. The IP is the server's current IP address,
1227 and dirport is its current directory port. XXXXorport
1229 "contact" SP string NL
1233 An arbitrary string describing how to contact the directory
1234 server's administrator. Administrators should include at least an
1235 email address and a PGP fingerprint.
1237 "legacy-key" SP FINGERPRINT NL
1241 Lists a fingerprint for an obsolete _identity_ key still used
1242 by this authority to keep older clients working. This option
1243 is used to keep key around for a little while in case the
1244 authorities need to migrate many identity keys at once.
1245 (Generally, this would only happen because of a security
1246 vulnerability that affected multiple authorities, like the
1247 Debian OpenSSL RNG bug of May 2008.)
1249 The authority section of a consensus contains groups the following items,
1250 in the order given, with one group for each authority that contributed to
1251 the consensus, with groups sorted by authority identity digest:
1253 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
1256 [Exactly once, at start]
1258 As in the authority section of a vote.
1260 "contact" SP string NL
1264 As in the authority section of a vote.
1266 "vote-digest" SP digest NL
1270 A digest of the vote from the authority that contributed to this
1271 consensus, as signed (that is, not including the signature).
1274 Each router status entry contains the following items. Router status
1275 entries are sorted in ascending order by identity digest.
1277 "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
1280 [At start, exactly once.]
1282 "Nickname" is the OR's nickname. "Identity" is a hash of its
1283 identity key, encoded in base64, with trailing equals sign(s)
1284 removed. "Digest" is a hash of its most recent descriptor as
1285 signed (that is, not including the signature), encoded in base64.
1286 "Publication" is the
1287 publication time of its most recent descriptor, in the form
1288 YYYY-MM-DD HH:MM:SS, in GMT. "IP" is its current IP address;
1289 ORPort is its current OR port, "DirPort" is it's current directory
1290 port, or "0" for "none".
1296 A series of space-separated status flags, in lexical order (as ASCII
1297 byte strings). Currently documented flags are:
1299 "Authority" if the router is a directory authority.
1300 "BadExit" if the router is believed to be useless as an exit node
1301 (because its ISP censors it, because it is behind a restrictive
1302 proxy, or for some similar reason).
1303 "BadDirectory" if the router is believed to be useless as a
1304 directory cache (because its directory port isn't working,
1305 its bandwidth is always throttled, or for some similar
1307 "Exit" if the router is more useful for building
1308 general-purpose exit circuits than for relay circuits. The
1309 path building algorithm uses this flag; see path-spec.txt.
1310 "Fast" if the router is suitable for high-bandwidth circuits.
1311 "Guard" if the router is suitable for use as an entry guard.
1312 "HSDir" if the router is considered a v2 hidden service directory.
1313 "Named" if the router's identity-nickname mapping is canonical,
1314 and this authority binds names.
1315 "Stable" if the router is suitable for long-lived circuits.
1316 "Running" if the router is currently usable.
1317 "Unnamed" if another router has bound the name used by this
1318 router, and this authority binds names.
1319 "Valid" if the router has been 'validated'.
1320 "V2Dir" if the router implements the v2 directory protocol.
1321 "V3Dir" if the router implements this protocol.
1327 The version of the Tor protocol that this relay is running. If
1328 the value begins with "Tor" SP, the rest of the string is a Tor
1329 version number, and the protocol is "The Tor protocol as supported
1330 by the given version of Tor." Otherwise, if the value begins with
1331 some other string, Tor has upgraded to a more sophisticated
1332 protocol versioning system, and the protocol is "a version of the
1333 Tor protocol more recent than any we recognize."
1335 Directory authorities SHOULD omit version strings they receive from
1336 descriptors if they would cause "v" lines to be over 128 characters
1339 "w" SP "Bandwidth=" INT [SP "Measured=" INT] NL
1343 An estimate of the bandwidth of this relay, in an arbitrary
1344 unit (currently kilobytes per second). Used to weight router
1347 Additionally, the Measured= keyword is present in votes by
1348 participating bandwidth measurement authorities to indicate
1349 a measured bandwidth currently produced by measuring stream
1352 Other weighting keywords may be added later.
1353 Clients MUST ignore keywords they do not recognize.
1355 "p" SP ("accept" / "reject") SP PortList NL
1359 PortList = PortOrRange
1360 PortList = PortList "," PortOrRange
1361 PortOrRange = INT "-" INT / INT
1363 A list of those ports that this router supports (if 'accept')
1364 or does not support (if 'reject') for exit to "most
1367 The footer section is delineated in all votes and consensuses supporting
1368 consensus method 9 and above with the following:
1370 "directory-footer" NL
1372 It contains two subsections, a bandwidths-weights line and a
1373 directory-signature.
1375 The bandwidths-weights line appears At Most Once for a consensus. It does
1376 not appear in votes.
1378 "bandwidth-weights" SP
1379 "Wbd=" INT SP "Wbe=" INT SP "Wbg=" INT SP "Wbm=" INT SP
1381 "Web=" INT SP "Wed=" INT SP "Wee=" INT SP "Weg=" INT SP "Wem=" INT SP
1382 "Wgb=" INT SP "Wgd=" INT SP "Wgg=" INT SP "Wgm=" INT SP
1383 "Wmb=" INT SP "Wmd=" INT SP "Wme=" INT SP "Wmg=" INT SP "Wmm=" INT NL
1385 These values represent the weights to apply to router bandwidths
1386 during path selection. They are sorted in lexical order (as ASCII byte
1387 strings). The integer values are divided by BW_WEIGHT_SCALE=10000 or
1388 the consensus param "bwweightscale". They are:
1390 Wgg - Weight for Guard-flagged nodes in the guard position
1391 Wgm - Weight for non-flagged nodes in the guard Position
1392 Wgd - Weight for Guard+Exit-flagged nodes in the guard Position
1394 Wmg - Weight for Guard-flagged nodes in the middle Position
1395 Wmm - Weight for non-flagged nodes in the middle Position
1396 Wme - Weight for Exit-flagged nodes in the middle Position
1397 Wmd - Weight for Guard+Exit flagged nodes in the middle Position
1399 Weg - Weight for Guard flagged nodes in the exit Position
1400 Wem - Weight for non-flagged nodes in the exit Position
1401 Wee - Weight for Exit-flagged nodes in the exit Position
1402 Wed - Weight for Guard+Exit-flagged nodes in the exit Position
1404 Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
1405 Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
1406 Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
1407 Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes
1409 Wbg - Weight for Guard flagged nodes for BEGIN_DIR requests
1410 Wbm - Weight for non-flagged nodes for BEGIN_DIR requests
1411 Wbe - Weight for Exit-flagged nodes for BEGIN_DIR requests
1412 Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
1414 These values are calculated as specified in Section 3.4.3.
1416 The signature contains the following item, which appears Exactly Once
1417 for a vote, and At Least Once for a consensus.
1419 "directory-signature" SP identity SP signing-key-digest NL Signature
1421 This is a signature of the status document, with the initial item
1422 "network-status-version", and the signature item
1423 "directory-signature", using the signing key. (In this case, we take
1424 the hash through the _space_ after directory-signature, not the
1425 newline: this ensures that all authorities sign the same thing.)
1426 "identity" is the hex-encoded digest of the authority identity key of
1427 the signing authority, and "signing-key-digest" is the hex-encoded
1428 digest of the current authority signing key of the signing authority.
1430 3.3. Assigning flags in a vote
1432 (This section describes how directory authorities choose which status
1433 flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
1434 authorities MAY do things differently, so long as clients keep working
1435 well. Clients MUST NOT depend on the exact behaviors in this section.)
1437 In the below definitions, a router is considered "active" if it is
1438 running, valid, and not hibernating.
1440 "Valid" -- a router is 'Valid' if it is running a version of Tor not
1441 known to be broken, and the directory authority has not blacklisted
1444 "Named" -- Directory authority administrators may decide to support name
1445 binding. If they do, then they must maintain a file of
1446 nickname-to-identity-key mappings, and try to keep this file consistent
1447 with other directory authorities. If they don't, they act as clients, and
1448 report bindings made by other directory authorities (name X is bound to
1449 identity Y if at least one binding directory lists it, and no directory
1450 binds X to some other Y'.) A router is called 'Named' if the router
1451 believes the given name should be bound to the given key.
1453 Two strategies exist on the current network for deciding on
1454 values for the Named flag. In the original version, relay
1455 operators were asked to send nickname-identity pairs to a
1456 mailing list of Naming directory authorities' operators. The
1457 operators were then supposed to add the pairs to their
1458 mapping files; in practice, they didn't get to this often.
1460 Newer Naming authorities run a script that registers routers
1461 in their mapping files once the routers have been online at
1462 least two weeks, no other router has that nickname, and no
1463 other router has wanted the nickname for a month. If a router
1464 has not been online for six months, the router is removed.
1466 "Unnamed" -- Directory authorities that support naming should vote for a
1467 router to be 'Unnamed' if its given nickname is mapped to a different
1470 "Running" -- A router is 'Running' if the authority managed to connect to
1471 it successfully within the last 30 minutes.
1473 "Stable" -- A router is 'Stable' if it is active, and either its Weighted
1474 MTBF is at least the median for known active routers or its Weighted MTBF
1475 corresponds to at least 7 days. Routers are never called Stable if they are
1476 running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
1477 through 0.1.1.16-rc are stupid this way.)
1479 To calculate weighted MTBF, compute the weighted mean of the lengths
1480 of all intervals when the router was observed to be up, weighting
1481 intervals by $\alpha^n$, where $n$ is the amount of time that has
1482 passed since the interval ended, and $\alpha$ is chosen so that
1483 measurements over approximately one month old no longer influence the
1486 [XXXX what happens when we have less than 4 days of MTBF info.]
1488 "Exit" -- A router is called an 'Exit' iff it allows exits to at
1489 least two of the ports 80, 443, and 6667 and allows exits to at
1490 least one /8 address space.
1492 "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
1493 either in the top 7/8ths for known active routers or at least 20KB/s.
1495 "Guard" -- A router is a possible 'Guard' if its Weighted Fractional
1496 Uptime is at least the median for "familiar" active routers, and if
1497 its bandwidth is at least median or at least 250KB/s.
1499 To calculate weighted fractional uptime, compute the fraction
1500 of time that the router is up in any given day, weighting so that
1501 downtime and uptime in the past counts less.
1503 A node is 'familiar' if 1/8 of all active nodes have appeared more
1504 recently than it, OR it has been around for a few weeks.
1506 "Authority" -- A router is called an 'Authority' if the authority
1507 generating the network-status document believes it is an authority.
1509 "V2Dir" -- A router supports the v2 directory protocol if it has an open
1510 directory port, and it is running a version of the directory protocol that
1511 supports the functionality clients need. (Currently, this is
1512 0.1.1.9-alpha or later.)
1514 "V3Dir" -- A router supports the v3 directory protocol if it has an open
1515 directory port, and it is running a version of the directory protocol that
1516 supports the functionality clients need. (Currently, this is
1517 0.2.0.?????-alpha or later.)
1519 "HSDir" -- A router is a v2 hidden service directory if it stores and
1520 serves v2 hidden service descriptors and the authority managed to connect
1521 to it successfully within the last 24 hours.
1523 Directory server administrators may label some relays or IPs as
1524 blacklisted, and elect not to include them in their network-status lists.
1526 Authorities SHOULD 'disable' any relays in excess of 3 on any single IP.
1527 When there are more than 3 to choose from, authorities should first prefer
1528 authorities to non-authorities, then prefer Running to non-Running, and
1529 then prefer high-bandwidth to low-bandwidth. To 'disable' a relay, the
1530 authority *should* advertise it without the Running or Valid flag.
1532 Thus, the network-status vote includes all non-blacklisted,
1533 non-expired, non-superseded descriptors.
1535 The bandwidth in a "w" line should be taken as the best estimate
1536 of the router's actual capacity that the authority has. For now,
1537 this should be the lesser of the observed bandwidth and bandwidth
1538 rate limit from the router descriptor. It is given in kilobytes
1539 per second, and capped at some arbitrary value (currently 10 MB/s).
1541 The Measured= keyword on a "w" line vote is currently computed
1542 by multiplying the previous published consensus bandwidth by the
1543 ratio of the measured average node stream capacity to the network
1544 average. If 3 or more authorities provide a Measured= keyword for
1545 a router, the authorities produce a consensus containing a "w"
1546 Bandwidth= keyword equal to the median of the Measured= votes.
1548 The ports listed in a "p" line should be taken as those ports for
1549 which the router's exit policy permits 'most' addresses, ignoring any
1550 accept not for all addresses, ignoring all rejects for private
1551 netblocks. "Most" addresses are permitted if no more than 2^25
1552 IPv4 addresses (two /8 networks) were blocked. The list is encoded
1553 as described in 3.4.2.
1555 3.4. Computing a consensus from a set of votes
1557 Given a set of votes, authorities compute the contents of the consensus
1558 document as follows:
1560 The "valid-after", "valid-until", and "fresh-until" times are taken as
1561 the median of the respective values from all the votes.
1563 The times in the "voting-delay" line are taken as the median of the
1564 VoteSeconds and DistSeconds times in the votes.
1566 Known-flags is the union of all flags known by any voter.
1568 Entries are given on the "params" line for every keyword on which any
1569 authority voted. The values given are the low-median of all votes on
1572 "client-versions" and "server-versions" are sorted in ascending
1573 order; A version is recommended in the consensus if it is recommended
1574 by more than half of the voting authorities that included a
1575 client-versions or server-versions lines in their votes.
1577 The authority item groups (dir-source, contact, fingerprint,
1578 vote-digest) are taken from the votes of the voting
1579 authorities. These groups are sorted by the digests of the
1580 authorities identity keys, in ascending order. If the consensus
1581 method is 3 or later, a dir-source line must be included for
1582 every vote with legacy-key entry, using the legacy-key's
1583 fingerprint, the voter's ordinary nickname with the string
1584 "-legacy" appended, and all other fields as from the original
1585 vote's dir-source line.
1587 A router status entry:
1588 * is included in the result if some router status entry with the same
1589 identity is included by more than half of the authorities (total
1590 authorities, not just those whose votes we have).
1592 * For any given identity, we include at most one router status entry.
1594 * A router entry has a flag set if that is included by more than half
1595 of the authorities who care about that flag.
1597 * Two router entries are "the same" if they have the same
1598 <descriptor digest, published time, nickname, IP, ports> tuple.
1599 We choose the tuple for a given router as whichever tuple appears
1600 for that router in the most votes. We break ties first in favor of
1601 the more recently published, then in favor of smaller server
1604 * The Named flag appears if it is included for this routerstatus by
1605 _any_ authority, and if all authorities that list it list the same
1606 nickname. However, if consensus-method 2 or later is in use, and
1607 any authority calls this identity/nickname pair Unnamed, then
1608 this routerstatus does not get the Named flag.
1610 * If consensus-method 2 or later is in use, the Unnamed flag is
1611 set for a routerstatus if any authorities have voted for a different
1612 identities to be Named with that nickname, or if any authority
1613 lists that nickname/ID pair as Unnamed.
1615 (With consensus-method 1, Unnamed is set like any other flag.)
1617 * The version is given as whichever version is listed by the most
1618 voters, with ties decided in favor of more recent versions.
1620 * If consensus-method 4 or later is in use, then routers that
1621 do not have the Running flag are not listed at all.
1623 * If consensus-method 5 or later is in use, then the "w" line
1624 is generated using a low-median of the bandwidth values from
1625 the votes that included "w" lines for this router.
1627 * If consensus-method 5 or later is in use, then the "p" line
1628 is taken from the votes that have the same policy summary
1629 for the descriptor we are listing. (They should all be the
1630 same. If they are not, we pick the most commonly listed
1631 one, breaking ties in favor of the lexicographically larger
1632 vote.) The port list is encoded as specified in 3.4.2.
1634 * If consensus-method 6 or later is in use and if 3 or more
1635 authorities provide a Measured= keyword in their votes for
1636 a router, the authorities produce a consensus containing a
1637 Bandwidth= keyword equal to the median of the Measured= votes.
1639 * If consensus-method 7 or later is in use, the params line is
1640 included in the output.
1642 * If the consensus method is under 11, bad exits are considered as
1643 possible exits when computing bandwidth weights. Otherwise, if
1644 method 11 or later is in use, any router that is determined to get
1645 the BadExit flag doesn't count when we're calculating weights.
1647 The signatures at the end of a consensus document are sorted in
1648 ascending order by identity digest.
1650 All ties in computing medians are broken in favor of the smaller or
1653 3.4.1. Forward compatibility
1655 Future versions of Tor will need to include new information in the
1656 consensus documents, but it is important that all authorities (or at least
1657 half) generate and sign the same signed consensus.
1659 To achieve this, authorities list in their votes their supported methods
1660 for generating consensuses from votes. Later methods will be assigned
1661 higher numbers. Currently recognized methods:
1662 "1" -- The first implemented version.
1663 "2" -- Added support for the Unnamed flag.
1664 "3" -- Added legacy ID key support to aid in authority ID key rollovers
1665 "4" -- No longer list routers that are not running in the consensus
1666 "5" -- adds support for "w" and "p" lines.
1667 "6" -- Prefers measured bandwidth values rather than advertised
1668 "7" -- Provides keyword=integer pairs of consensus parameters
1669 "8" -- Provides microdescriptor summaries
1670 "9" -- Provides weights for selecting flagged routers in paths
1671 "10" -- Fixes edge case bugs in router flag selection weights
1672 "11" -- Don't consider BadExits when calculating bandwidth weights
1675 Before generating a consensus, an authority must decide which consensus
1676 method to use. To do this, it looks for the highest version number
1677 supported by more than 2/3 of the authorities voting. If it supports this
1678 method, then it uses it. Otherwise, it falls back to method 1.
1680 (The consensuses generated by new methods must be parsable by
1681 implementations that only understand the old methods, and must not cause
1682 those implementations to compromise their anonymity. This is a means for
1683 making changes in the contents of consensus; not for making
1684 backward-incompatible changes in their format.)
1686 3.4.2. Encoding port lists
1688 Whether the summary shows the list of accepted ports or the list of
1689 rejected ports depends on which list is shorter (has a shorter string
1690 representation). In case of ties we choose the list of accepted
1691 ports. As an exception to this rule an allow-all policy is
1692 represented as "accept 1-65535" instead of "reject " and a reject-all
1693 policy is similarly given as "reject 1-65535".
1695 Summary items are compressed, that is instead of "80-88,89-100" there
1696 only is a single item of "80-100", similarly instead of "20,21" a
1697 summary will say "20-21".
1699 Port lists are sorted in ascending order.
1701 The maximum allowed length of a policy summary (including the "accept "
1702 or "reject ") is 1000 characters. If a summary exceeds that length we
1703 use an accept-style summary and list as much of the port list as is
1704 possible within these 1000 bytes. [XXXX be more specific.]
1706 3.4.3. Computing Bandwidth Weights
1708 Let weight_scale = 10000
1710 Let G be the total bandwidth for Guard-flagged nodes.
1711 Let M be the total bandwidth for non-flagged nodes.
1712 Let E be the total bandwidth for Exit-flagged nodes.
1713 Let D be the total bandwidth for Guard+Exit-flagged nodes.
1716 Let Wgd be the weight for choosing a Guard+Exit for the guard position.
1717 Let Wmd be the weight for choosing a Guard+Exit for the middle position.
1718 Let Wed be the weight for choosing a Guard+Exit for the exit position.
1720 Let Wme be the weight for choosing an Exit for the middle position.
1721 Let Wmg be the weight for choosing a Guard for the middle position.
1723 Let Wgg be the weight for choosing a Guard for the guard position.
1724 Let Wee be the weight for choosing an Exit for the exit position.
1726 Balanced network conditions then arise from solutions to the following
1727 system of equations:
1729 Wgg*G + Wgd*D == M + Wmd*D + Wme*E + Wmg*G (guard bw = middle bw)
1730 Wgg*G + Wgd*D == Wee*E + Wed*D (guard bw = exit bw)
1731 Wed*D + Wmd*D + Wgd*D == D (aka: Wed+Wmd+Wdg = 1)
1732 Wmg*G + Wgg*G == G (aka: Wgg = 1-Wmg)
1733 Wme*E + Wee*E == E (aka: Wee = 1-Wme)
1735 We are short 2 constraints with the above set. The remaining constraints
1736 come from examining different cases of network load. The following
1737 constraints are used in consensus method 10 and above. There are another
1738 incorrect and obsolete set of constraints used for these same cases in
1739 consensus method 9. For those, see dir-spec.txt in Tor 0.2.2.10-alpha
1742 Case 1: E >= T/3 && G >= T/3 (Neither Exit nor Guard Scarce)
1744 In this case, the additional two constraints are: Wmg == Wmd,
1747 This leads to the solution:
1748 Wgd = weight_scale/3
1749 Wed = weight_scale/3
1750 Wmd = weight_scale/3
1751 Wee = (weight_scale*(E+G+M))/(3*E)
1752 Wme = weight_scale - Wee
1753 Wmg = (weight_scale*(2*G-E-M))/(3*G)
1754 Wgg = weight_scale - Wmg
1756 Case 2: E < T/3 && G < T/3 (Both are scarce)
1758 Let R denote the more scarce class (Rare) between Guard vs Exit.
1759 Let S denote the less scarce class.
1763 In this subcase, we simply devote all of D bandwidth to the
1766 Wgg = Wee = weight_scale
1767 Wmg = Wme = Wmd = 0;
1777 In this case, if M <= T/3, we have enough bandwidth to try to achieve
1778 a balancing condition.
1780 Add constraints Wgg = 1, Wmd == Wgd to maximize bandwidth in the guard
1781 position while still allowing exits to be used as middle nodes:
1783 Wee = (weight_scale*(E - G + M))/E
1784 Wed = (weight_scale*(D - 2*E + 4*G - 2*M))/(3*D)
1785 Wme = (weight_scale*(G-M))/E
1788 Wmd = (weight_scale - Wed)/2
1789 Wgd = (weight_scale - Wed)/2
1791 If this system ends up with any values out of range (ie negative, or
1792 above weight_scale), use the constraints Wgg == 1 and Wee == 1, since
1793 both those positions are scarce:
1797 Wed = (weight_scale*(D - 2*E + G + M))/(3*D)
1798 Wmd = (weight_Scale*(D - 2*M + G + E))/(3*D)
1801 Wgd = weight_scale - Wed - Wmd
1803 If M > T/3, then the Wmd weight above will become negative. Set it to 0
1806 Wgd = weight_scale - Wed
1808 Case 3: One of E < T/3 or G < T/3
1810 Let S be the scarce class (of E or G).
1812 Subcase a: (S+D) < T/3:
1814 Wgg = Wgd = weight_scale;
1815 Wmd = Wed = Wmg = 0;
1816 // Minor subcase, if E is more scarce than M,
1817 // keep its bandwidth in place.
1819 else Wme = (weight_scale*(E-M))/(2*E);
1820 Wee = weight_scale-Wme;
1822 Wee = Wed = weight_scale;
1823 Wmd = Wgd = Wme = 0;
1824 // Minor subcase, if G is more scarce than M,
1825 // keep its bandwidth in place.
1827 else Wmg = (weight_scale*(G-M))/(2*G);
1828 Wgg = weight_scale-Wmg;
1830 Subcase b: (S+D) >= T/3
1832 Add constraints Wgg = 1, Wmd == Wed to maximize bandwidth
1833 in the guard position, while still allowing exits to be
1834 used as middle nodes:
1836 Wgd = (weight_scale*(D - 2*G + E + M))/(3*D)
1838 Wee = (weight_scale*(E+M))/(2*E)
1839 Wme = weight_scale - Wee
1840 Wmd = (weight_scale - Wgd)/2
1841 Wed = (weight_scale - Wgd)/2
1843 Add constraints Wee == 1, Wmd == Wgd to maximize bandwidth
1844 in the exit position:
1846 Wed = (weight_scale*(D - 2*E + G + M))/(3*D);
1848 Wgg = (weight_scale*(G+M))/(2*G);
1849 Wmg = weight_scale - Wgg;
1850 Wmd = (weight_scale - Wed)/2;
1851 Wgd = (weight_scale - Wed)/2;
1853 To ensure consensus, all calculations are performed using integer math
1854 with a fixed precision determined by the bwweightscale consensus
1855 parameter (defaults at 10000, Min: 1, Max: INT32_MAX).
1857 For future balancing improvements, Tor clients support 11 additional weights
1858 for directory requests and middle weighting. These weights are currently
1859 set at weight_scale, with the exception of the following groups of
1862 Directory requests use middle weights:
1863 Wbd=Wmd, Wbg=Wmg, Wbe=Wme, Wbm=Wmm
1865 Handle bridges and strange exit policies:
1866 Wgm=Wgg, Wem=Wee, Weg=Wed
1868 3.5. Detached signatures
1870 Assuming full connectivity, every authority should compute and sign the
1871 same consensus directory in each period. Therefore, it isn't necessary to
1872 download the consensus computed by each authority; instead, the
1873 authorities only push/fetch each others' signatures. A "detached
1874 signature" document contains items as follows:
1876 "consensus-digest" SP Digest NL
1878 [At start, at most once.]
1880 The digest of the consensus being signed.
1882 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1883 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1884 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1886 [As in the consensus]
1888 "directory-signature"
1890 [As in the consensus; the signature object is the same as in the
1891 consensus document.]
1894 4. Directory server operation
1896 All directory authorities and directory caches ("directory servers")
1897 implement this section, except as noted.
1899 4.1. Accepting uploads (authorities only)
1901 When a router posts a signed descriptor to a directory authority, the
1902 authority first checks whether it is well-formed and correctly
1903 self-signed. If it is, the authority next verifies that the nickname
1904 in question is not already assigned to a router with a different
1906 Finally, the authority MAY check that the router is not blacklisted
1907 because of its key, IP, or another reason.
1909 If the descriptor passes these tests, and the authority does not already
1910 have a descriptor for a router with this public key, it accepts the
1911 descriptor and remembers it.
1913 If the authority _does_ have a descriptor with the same public key, the
1914 newly uploaded descriptor is remembered if its publication time is more
1915 recent than the most recent old descriptor for that router, and either:
1916 - There are non-cosmetic differences between the old descriptor and the
1918 - Enough time has passed between the descriptors' publication times.
1919 (Currently, 12 hours.)
1921 Differences between router descriptors are "non-cosmetic" if they would be
1922 sufficient to force an upload as described in section 2 above.
1924 Note that the "cosmetic difference" test only applies to uploaded
1925 descriptors, not to descriptors that the authority downloads from other
1928 When a router posts a signed extra-info document to a directory authority,
1929 the authority again checks it for well-formedness and correct signature,
1930 and checks that its matches the extra-info-digest in some router
1931 descriptor that it believes is currently useful. If so, it accepts it and
1932 stores it and serves it as requested. If not, it drops it.
1934 4.2. Voting (authorities only)
1936 Authorities divide time into Intervals. Authority administrators SHOULD
1937 try to all pick the same interval length, and SHOULD pick intervals that
1938 are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
1939 minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
1940 divide evenly into a 24-hour day.
1942 Authorities SHOULD act according to interval and delays in the
1943 latest consensus. Lacking a latest consensus, they SHOULD default to a
1944 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
1946 Authorities MUST take pains to ensure that their clocks remain accurate
1947 within a few seconds. (Running NTP is usually sufficient.)
1949 The first voting period of each day begins at 00:00 (midnight) GMT. If
1950 the last period of the day would be truncated by one-half or more, it is
1951 merged with the second-to-last period.
1953 An authority SHOULD publish its vote immediately at the start of each voting
1954 period (minus VoteSeconds+DistSeconds). It does this by making it
1956 http://<hostname>/tor/status-vote/next/authority.z
1957 and sending it in an HTTP POST request to each other authority at the URL
1958 http://<hostname>/tor/post/vote
1960 If, at the start of the voting period, minus DistSeconds, an authority
1961 does not have a current statement from another authority, the first
1962 authority downloads the other's statement.
1964 Once an authority has a vote from another authority, it makes it available
1966 http://<hostname>/tor/status-vote/next/<fp>.z
1967 where <fp> is the fingerprint of the other authority's identity key.
1969 http://<hostname>/tor/status-vote/next/d/<d>.z
1970 where <d> is the digest of the vote document.
1972 The consensus status, along with as many signatures as the server
1973 currently knows, should be available at
1974 http://<hostname>/tor/status-vote/next/consensus.z
1975 All of the detached signatures it knows for consensus status should be
1977 http://<hostname>/tor/status-vote/next/consensus-signatures.z
1979 Once there are enough signatures, or once the voting period starts,
1980 these documents are available at
1981 http://<hostname>/tor/status-vote/current/consensus.z
1983 http://<hostname>/tor/status-vote/current/consensus-signatures.z
1984 [XXX current/consensus-signatures is not currently implemented, as it
1985 is not used in the voting protocol.]
1987 The other vote documents are analogously made available under
1988 http://<hostname>/tor/status-vote/current/authority.z
1989 http://<hostname>/tor/status-vote/current/<fp>.z
1990 http://<hostname>/tor/status-vote/current/d/<d>.z
1991 once the consensus is complete.
1993 Once an authority has computed and signed a consensus network status, it
1994 should send its detached signature to each other authority in an HTTP POST
1996 http://<hostname>/tor/post/consensus-signature
1998 [XXX Note why we support push-and-then-pull.]
2000 [XXX possible future features include support for downloading old
2003 4.3. Downloading consensus status documents (caches only)
2005 All directory servers (authorities and caches) try to keep a recent
2006 network-status consensus document to serve to clients. A cache ALWAYS
2007 downloads a network-status consensus if any of the following are true:
2008 - The cache has no consensus document.
2009 - The cache's consensus document is no longer valid.
2010 Otherwise, the cache downloads a new consensus document at a randomly
2011 chosen time in the first half-interval after its current consensus
2012 stops being fresh. (This time is chosen at random to avoid swarming
2013 the authorities at the start of each period. The interval size is
2014 inferred from the difference between the valid-after time and the
2015 fresh-until time on the consensus.)
2017 [For example, if a cache has a consensus that became valid at 1:00,
2018 and is fresh until 2:00, that cache will fetch a new consensus at
2019 a random time between 2:00 and 2:30.]
2021 4.4. Downloading and storing router descriptors (authorities and caches)
2023 Periodically (currently, every 10 seconds), directory servers check
2024 whether there are any specific descriptors that they do not have and that
2025 they are not currently trying to download. Caches identify these
2026 descriptors by hash in the recent network-status consensus documents;
2027 authorities identify them by hash in vote (if publication date is more
2028 recent than the descriptor we currently have).
2030 [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
2033 If so, the directory server launches requests to the authorities for these
2034 descriptors, such that each authority is only asked for descriptors listed
2035 in its most recent vote (if the requester is an authority) or in the
2036 consensus (if the requester is a cache). If we're an authority, and more
2037 than one authority lists the descriptor, we choose which to ask at random.
2039 If one of these downloads fails, we do not try to download that descriptor
2040 from the authority that failed to serve it again unless we receive a newer
2041 network-status (consensus or vote) from that authority that lists the same
2044 Directory servers must potentially cache multiple descriptors for each
2045 router. Servers must not discard any descriptor listed by any recent
2046 consensus. If there is enough space to store additional descriptors,
2047 servers SHOULD try to hold those which clients are likely to download the
2048 most. (Currently, this is judged based on the interval for which each
2049 descriptor seemed newest.)
2050 [XXXX define recent]
2052 Authorities SHOULD NOT download descriptors for routers that they would
2053 immediately reject for reasons listed in 3.1.
2055 4.5. Downloading and storing extra-info documents
2057 All authorities, and any cache that chooses to cache extra-info documents,
2058 and any client that uses extra-info documents, should implement this
2061 Note that generally, clients don't need extra-info documents.
2063 Periodically, the Tor instance checks whether it is missing any extra-info
2064 documents: in other words, if it has any router descriptors with an
2065 extra-info-digest field that does not match any of the extra-info
2066 documents currently held. If so, it downloads whatever extra-info
2067 documents are missing. Caches download from authorities; non-caches try
2068 to download from caches. We follow the same splitting and back-off rules
2069 as in 4.4 (if a cache) or 5.3 (if a client).
2071 4.6. General-use HTTP URLs
2073 "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
2075 The most recent v3 consensus should be available at:
2076 http://<hostname>/tor/status-vote/current/consensus.z
2078 Starting with Tor version 0.2.1.1-alpha is also available at:
2079 http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
2081 Where F1, F2, etc. are authority identity fingerprints the client trusts.
2082 Servers will only return a consensus if more than half of the requested
2083 authorities have signed the document, otherwise a 404 error will be sent
2084 back. The fingerprints can be shortened to a length of any multiple of
2085 two, using only the leftmost part of the encoded fingerprint. Tor uses
2086 3 bytes (6 hex characters) of the fingerprint.
2088 Clients SHOULD sort the fingerprints in ascending order. Server MUST
2091 Clients SHOULD use this format when requesting consensus documents from
2092 directory authority servers and from caches running a version of Tor
2093 that is known to support this URL format.
2095 A concatenated set of all the current key certificates should be available
2097 http://<hostname>/tor/keys/all.z
2099 The key certificate for this server (if it is an authority) should be
2101 http://<hostname>/tor/keys/authority.z
2103 The key certificate for an authority whose authority identity fingerprint
2104 is <F> should be available at:
2105 http://<hostname>/tor/keys/fp/<F>.z
2107 The key certificate whose signing key fingerprint is <F> should be
2109 http://<hostname>/tor/keys/sk/<F>.z
2111 The key certificate whose identity key fingerprint is <F> and whose signing
2112 key fingerprint is <S> should be available at:
2114 http://<hostname>/tor/keys/fp-sk/<F>-<S>.z
2116 (As usual, clients may request multiple certificates using:
2117 http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z )
2118 [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]
2120 The most recent descriptor for a server whose identity key has a
2121 fingerprint of <F> should be available at:
2122 http://<hostname>/tor/server/fp/<F>.z
2124 The most recent descriptors for servers with identity fingerprints
2125 <F1>,<F2>,<F3> should be available at:
2126 http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
2128 (NOTE: Implementations SHOULD NOT download descriptors by identity key
2129 fingerprint. This allows a corrupted server (in collusion with a cache) to
2130 provide a unique descriptor to a client, and thereby partition that client
2131 from the rest of the network.)
2133 The server descriptor with (descriptor) digest <D> (in hex) should be
2135 http://<hostname>/tor/server/d/<D>.z
2137 The most recent descriptors with digests <D1>,<D2>,<D3> should be
2139 http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
2141 The most recent descriptor for this server should be at:
2142 http://<hostname>/tor/server/authority.z
2143 [Nothing in the Tor protocol uses this resource yet, but it is useful
2144 for debugging purposes. Also, the official Tor implementations
2145 (starting at 0.1.1.x) use this resource to test whether a server's
2146 own DirPort is reachable.]
2148 A concatenated set of the most recent descriptors for all known servers
2149 should be available at:
2150 http://<hostname>/tor/server/all.z
2152 Extra-info documents are available at the URLS
2153 http://<hostname>/tor/extra/d/...
2154 http://<hostname>/tor/extra/fp/...
2155 http://<hostname>/tor/extra/all[.z]
2156 http://<hostname>/tor/extra/authority[.z]
2157 (As for /tor/server/ URLs: supports fetching extra-info
2158 documents by their digest, by the fingerprint of their servers,
2159 or all at once. When serving by fingerprint, we serve the
2160 extra-info that corresponds to the descriptor we would serve by
2161 that fingerprint. Only directory authorities of version
2162 0.2.0.1-alpha or later are guaranteed to support the first
2163 three classes of URLs. Caches may support them, and MUST
2164 support them if they have advertised "caches-extra-info".)
2166 For debugging, directories SHOULD expose non-compressed objects at URLs like
2167 the above, but without the final ".z".
2168 Clients MUST handle compressed concatenated information in two forms:
2169 - A concatenated list of zlib-compressed objects.
2170 - A zlib-compressed concatenated list of objects.
2171 Directory servers MAY generate either format: the former requires less
2172 CPU, but the latter requires less bandwidth.
2174 Clients SHOULD use upper case letters (A-F) when base16-encoding
2175 fingerprints. Servers MUST accept both upper and lower case fingerprints
2178 5. Client operation: downloading information
2180 Every Tor that is not a directory server (that is, those that do
2181 not have a DirPort set) implements this section.
2183 5.1. Downloading network-status documents
2185 Each client maintains a list of directory authorities. Insofar as
2186 possible, clients SHOULD all use the same list.
2188 Clients try to have a live consensus network-status document at all times.
2189 A network-status document is "live" if the time in its valid-until field
2192 If a client is missing a live network-status document, it tries to fetch
2193 it from a directory cache (or from an authority if it knows no caches).
2194 On failure, the client waits briefly, then tries that network-status
2195 document again from another cache. The client does not build circuits
2196 until it has a live network-status consensus document, and it has
2197 descriptors for more than 1/4 of the routers that it believes are running.
2199 (Note: clients can and should pick caches based on the network-status
2200 information they have: once they have first fetched network-status info
2201 from an authority, they should not need to go to the authority directly
2204 To avoid swarming the caches whenever a consensus expires, the
2205 clients download new consensuses at a randomly chosen time after the
2206 caches are expected to have a fresh consensus, but before their
2207 consensus will expire. (This time is chosen uniformly at random from
2208 the interval between the time 3/4 into the first interval after the
2209 consensus is no longer fresh, and 7/8 of the time remaining after
2210 that before the consensus is invalid.)
2212 [For example, if a cache has a consensus that became valid at 1:00,
2213 and is fresh until 2:00, and expires at 4:00, that cache will fetch
2214 a new consensus at a random time between 2:45 and 3:50, since 3/4
2215 of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
2216 minutes is 65 minutes.]
2218 5.2. Downloading and storing router descriptors
2220 Clients try to have the best descriptor for each router. A descriptor is
2222 * It is listed in the consensus network-status document.
2224 Periodically (currently every 10 seconds) clients check whether there are
2225 any "downloadable" descriptors. A descriptor is downloadable if:
2226 - It is the "best" descriptor for some router.
2227 - The descriptor was published at least 10 minutes in the past.
2228 (This prevents clients from trying to fetch descriptors that the
2229 mirrors have probably not yet retrieved and cached.)
2230 - The client does not currently have it.
2231 - The client is not currently trying to download it.
2232 - The client would not discard it immediately upon receiving it.
2233 - The client thinks it is running and valid (see 6.1 below).
2235 If at least 16 known routers have downloadable descriptors, or if
2236 enough time (currently 10 minutes) has passed since the last time the
2237 client tried to download descriptors, it launches requests for all
2238 downloadable descriptors, as described in 5.3 below.
2240 When a descriptor download fails, the client notes it, and does not
2241 consider the descriptor downloadable again until a certain amount of time
2242 has passed. (Currently 0 seconds for the first failure, 60 seconds for the
2243 second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
2244 thereafter.) Periodically (currently once an hour) clients reset the
2247 Clients retain the most recent descriptor they have downloaded for each
2248 router so long as it is not too old (currently, 48 hours), OR so long as
2249 no better descriptor has been downloaded for the same router.
2251 [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
2252 being published too far in the past.] [The code seems to discard
2253 descriptors in all cases after they're 5 days old. True? -RD]
2255 5.3. Managing downloads
2257 When a client has no consensus network-status document, it downloads it
2258 from a randomly chosen authority. In all other cases, the client
2259 downloads from caches randomly chosen from among those believed to be V2
2260 directory servers. (This information comes from the network-status
2261 documents; see 6 below.)
2263 When downloading multiple router descriptors, the client chooses multiple
2265 - At least 3 different mirrors are used, except when this would result
2266 in more than one request for under 4 descriptors.
2267 - No more than 128 descriptors are requested from a single mirror.
2268 - Otherwise, as few mirrors as possible are used.
2269 After choosing mirrors, the client divides the descriptors among them
2272 After receiving any response client MUST discard any network-status
2273 documents and descriptors that it did not request.
2275 6. Using directory information
2277 Everyone besides directory authorities uses the approaches in this section
2278 to decide which relays to use and what their keys are likely to be.
2279 (Directory authorities just believe their own opinions, as in 3.1 above.)
2281 6.1. Choosing routers for circuits.
2283 Circuits SHOULD NOT be built until the client has enough directory
2284 information: a live consensus network status [XXXX fallback?] and
2285 descriptors for at least 1/4 of the relays believed to be running.
2287 A relay is "listed" if it is included by the consensus network-status
2288 document. Clients SHOULD NOT use unlisted relays.
2290 These flags are used as follows:
2292 - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
2295 - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
2296 very-low-bandwidth circuits (such as introduction circuits).
2298 - Clients SHOULD NOT use non-'Stable' routers for circuits that are
2299 likely to need to be open for a very long time (such as those used for
2300 IRC or SSH connections).
2302 - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
2305 - Clients SHOULD NOT download directory information from non-'V2Dir'
2308 See the "path-spec.txt" document for more details.
2310 6.2. Managing naming
2312 In order to provide human-memorable names for individual router
2313 identities, some directory servers bind names to IDs. Clients handle
2316 When a client encounters a name it has not mapped before:
2318 If the consensus lists any router with that name as "Named", or if
2319 consensus-method 2 or later is in use and the consensus lists any
2320 router with that name as having the "Unnamed" flag, then the name is
2321 bound. (It's bound to the ID listed in the entry with the Named,
2322 or to an unknown ID if no name is found.)
2324 When the user refers to a bound name, the implementation SHOULD provide
2325 only the router with ID bound to that name, and no other router, even
2326 if the router with the right ID can't be found.
2328 When a user tries to refer to a non-bound name, the implementation SHOULD
2329 warn the user. After warning the user, the implementation MAY use any
2330 router that advertises the name.
2332 Not every router needs a nickname. When a router doesn't configure a
2333 nickname, it publishes with the default nickname "Unnamed". Authorities
2334 SHOULD NOT ever mark a router with this nickname as Named; client software
2335 SHOULD NOT ever use a router in response to a user request for a router
2338 6.3. Software versions
2340 An implementation of Tor SHOULD warn when it has fetched a consensus
2341 network-status, and it is running a software version not listed.
2343 6.4. Warning about a router's status.
2345 If a router tries to publish its descriptor to a Naming authority
2346 that has its nickname mapped to another key, the router SHOULD
2347 warn the operator that it is either using the wrong key or is using
2348 an already claimed nickname.
2350 If a router has fetched a consensus document,, and the
2351 authorities do not publish a binding for the router's nickname, the
2352 router MAY remind the operator that the chosen nickname is not
2353 bound to this key at the authorities, and suggest contacting the
2354 authority operators.
2358 6.5. Router protocol versions
2360 A client should believe that a router supports a given feature if that
2361 feature is supported by the router or protocol versions in more than half
2362 of the live networkstatuses' "v" entries for that router. In other words,
2363 if the "v" entries for some router are:
2364 v Tor 0.0.8pre1 (from authority 1)
2365 v Tor 0.1.2.11 (from authority 2)
2366 v FutureProtocolDescription 99 (from authority 3)
2367 then the client should believe that the router supports any feature
2368 supported by 0.1.2.11.
2370 This is currently equivalent to believing the median declared version for
2371 a router in all live networkstatuses.
2373 7. Standards compliance
2375 All clients and servers MUST support HTTP 1.0. Clients and servers MAY
2376 support later versions of HTTP as well.
2380 Servers MAY set the Content-Length: header. Servers SHOULD set
2381 Content-Encoding to "deflate" or "identity".
2383 Servers MAY include an X-Your-Address-Is: header, whose value is the
2384 apparent IP address of the client connecting to them (as a dotted quad).
2385 For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
2386 report the IP from which the circuit carrying the BEGIN_DIR stream reached
2387 them. [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
2388 BEGIN_DIR-tunneled connections.]
2390 Servers SHOULD disable caching of multiple network statuses or multiple
2391 router descriptors. Servers MAY enable caching of single descriptors,
2392 single network statuses, the list of all router descriptors, a v1
2393 directory, or a v1 running routers document. XXX mention times.
2395 7.2. HTTP status codes
2397 Tor delivers the following status codes. Some were chosen without much
2398 thought; other code SHOULD NOT rely on specific status codes yet.
2400 200 -- the operation completed successfully
2401 -- the user requested statuses or serverdescs, and none of the ones we
2402 requested were found (0.2.0.4-alpha and earlier).
2404 304 -- the client specified an if-modified-since time, and none of the
2405 requested resources have changed since that time.
2407 400 -- the request is malformed, or
2408 -- the URL is for a malformed variation of one of the URLs we support,
2410 -- the client tried to post to a non-authority, or
2411 -- the authority rejected a malformed posted document, or
2413 404 -- the requested document was not found.
2414 -- the user requested statuses or serverdescs, and none of the ones
2415 requested were found (0.2.0.5-alpha and later).
2417 503 -- we are declining the request in order to save bandwidth
2418 -- user requested some items that we ordinarily generate or store,
2419 but we do not have any available.
2421 9. Backward compatibility and migration plans
2423 Until Tor versions before 0.1.1.x are completely obsolete, directory
2424 authorities should generate, and mirrors should download and cache, v1
2425 directories and running-routers lists, and allow old clients to download
2426 them. These documents and the rules for retrieving, serving, and caching
2427 them are described in dir-spec-v1.txt.
2429 Until Tor versions before 0.2.0.x are completely obsolete, directory
2430 authorities should generate, mirrors should download and cache, v2
2431 network-status documents, and allow old clients to download them.
2432 Additionally, all directory servers and caches should download, store, and
2433 serve any router descriptor that is required because of v2 network-status
2434 documents. These documents and the rules for retrieving, serving, and
2435 caching them are described in dir-spec-v1.txt.
2437 A. Consensus-negotiation timeline.
2439 Period begins: this is the Published time.
2440 Everybody sends votes
2441 Reconciliation: everybody tries to fetch missing votes.
2442 consensus may exist at this point.
2443 End of voting period:
2444 everyone swaps signatures.
2445 Now it's okay for caches to download
2446 Now it's okay for clients to download.
2448 Valid-after/valid-until switchover