| blob | faa3a6609b32cea084e41773e044cf6c7e028cd2 |
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. See Section XXXX on backward compatibility.
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 AS OF 14 JUNE 2007, THIS SPECIFICATION HAS NOT YET BEEN COMPLETELY
22 IMPLEMENTED, OR COMPLETELY COMPLETED.
24 XXX when to download certificates.
25 XXX timeline
26 XXX fill in XXXXs
28 0.1. History
30 The earliest versions of Onion Routing shipped with a list of known
31 routers and their keys. When the set of routers changed, users needed to
32 fetch a new list.
34 The Version 1 Directory protocol
35 --------------------------------
37 Early versions of Tor (0.0.2) introduced "Directory authorities": servers
38 that served signed "directory" documents containing a list of signed
39 "router descriptors", along with short summary of the status of each
40 router. Thus, clients could get up-to-date information on the state of
41 the network automatically, and be certain that the list they were getting
42 was attested by a trusted directory authority.
44 Later versions (0.0.8) added directory caches, which download
45 directories from the authorities and serve them to clients. Non-caches
46 fetch from the caches in preference to fetching from the authorities, thus
47 distributing bandwidth requirements.
49 Also added during the version 1 directory protocol were "router status"
50 documents: short documents that listed only the up/down status of the
51 routers on the network, rather than a complete list of all the
52 descriptors. Clients and caches would fetch these documents far more
53 frequently than they would fetch full directories.
55 The Version 2 Directory Protocol
56 --------------------------------
58 During the Tor 0.1.1.x series, Tor revised its handling of directory
59 documents in order to address two major problems:
61 * Directories had grown quite large (over 1MB), and most directory
62 downloads consisted mainly of router descriptors that clients
63 already had.
65 * Every directory authority was a trust bottleneck: if a single
66 directory authority lied, it could make clients believe for a time
67 an arbitrarily distorted view of the Tor network. (Clients
68 trusted the most recent signed document they downloaded.) Thus,
69 adding more authorities would make the system less secure, not
70 more.
72 To address these, we extended the directory protocol so that
73 authorities now published signed "network status" documents. Each
74 network status listed, for every router in the network: a hash of its
75 identity key, a hash of its most recent descriptor, and a summary of
76 what the authority believed about its status. Clients would download
77 the authorities' network status documents in turn, and believe
78 statements about routers iff they were attested to by more than half of
79 the authorities.
81 Instead of downloading all router descriptors at once, clients
82 downloaded only the descriptors that they did not have. Descriptors
83 were indexed by their digests, in order to prevent malicious caches
84 from giving different versions of a router descriptor to different
85 clients.
87 Routers began working harder to upload new descriptors only when their
88 contents were substantially changed.
91 0.2. Goals of the version 3 protocol
93 Version 3 of the Tor directory protocol tries to solve the following
94 issues:
96 * A great deal of bandwidth used to transmit router descriptors was
97 used by two fields that are not actually used by Tor routers
98 (namely read-history and write-history). We save about 60% by
99 moving them into a separate document that most clients do not
100 fetch or use.
102 * It was possible under certain perverse circumstances for clients
103 to download an unusual set of network status documents, thus
104 partitioning themselves from clients who have a more recent and/or
105 typical set of documents. Even under the best of circumstances,
106 clients were sensitive to the ages of the network status documents
107 they downloaded. Therefore, instead of having the clients
108 correlate multiple network status documents, we have the
109 authorities collectively vote on a single consensus network status
110 document.
112 * The most sensitive data in the entire network (the identity keys
113 of the directory authorities) needed to be stored unencrypted so
114 that the authorities can sign network-status documents on the fly.
115 Now, the authorities' identity keys are stored offline, and used
116 to certify medium-term signing keys that can be rotated.
118 0.3. Some Remaining questions
120 Things we could solve on a v3 timeframe:
122 The SHA-1 hash is showing its age. We should do something about our
123 dependency on it. We could probably future-proof ourselves here in
124 this revision, at least so far as documents from the authorities are
125 concerned.
127 Too many things about the authorities are hardcoded by IP.
129 Perhaps we should start accepting longer identity keys for routers
130 too.
132 Things to solve eventually:
134 Requiring every client to know about every router won't scale forever.
136 Requiring every directory cache to know every router won't scale
137 forever.
140 1. Outline
142 There is a small set (say, around 5-10) of semi-trusted directory
143 authorities. A default list of authorities is shipped with the Tor
144 software. Users can change this list, but are encouraged not to do so,
145 in order to avoid partitioning attacks.
147 Every authority has a very-secret, long-term "Authority Identity Key".
148 This is stored encrypted and/or offline, and is used to sign "key
149 certificate" documents. Every key certificate contains a medium-term
150 (3-12 months) "authority signing key", that is used by the authority to
151 sign other directory information. (Note that the authority identity
152 key is distinct from the router identity key that the authority uses
153 in its role as an ordinary router.)
155 Routers periodically upload signed "routers descriptors" to the
156 directory authorities describing their keys, capabilities, and other
157 information. Routers may also upload signed "extra info documents"
158 containing information that is not required for the Tor protocol.
159 Directory authorities serve router descriptors indexed by router
160 identity, or by hash of the descriptor.
162 Routers may act as directory caches to reduce load on the directory
163 authorities. They announce this in their descriptors.
165 Periodically, each directory authority generates a view of
166 the current descriptors and status for known routers. They send a
167 signed summary of this view (a "status vote") to the other
168 authorities. The authorities compute the result of this vote, and sign
169 a "consensus status" document containing the result of the vote.
171 Directory caches download, cache, and re-serve consensus documents.
173 Clients, directory caches, and directory authorities all use consensus
174 documents to find out when their list of routers is out-of-date.
175 (Directory authorities also use vote statuses.) If it is, they download
176 any missing router descriptors. Clients download missing descriptors
177 from caches; caches and authorities download from authorities.
178 Descriptors are downloaded by the hash of the descriptor, not by the
179 server's identity key: this prevents servers from attacking clients by
180 giving them descriptors nobody else uses.
182 All directory information is uploaded and downloaded with HTTP.
184 [Authorities also generate and caches also cache documents produced and
185 used by earlier versions of this protocol; see section XXX for notes.]
187 1.1. What's different from version 2?
189 Clients used to download multiple network status documents,
190 corresponding roughly to "status votes" above. They would compute the
191 result of the vote on the client side.
193 Authorities used to sign documents using the same private keys they used
194 for their roles as routers. This forced them to keep these extremely
195 sensitive keys in memory unencrypted.
197 All of the information in extra-info documents used to be kept in the
198 main descriptors.
200 1.2. Document meta-format
202 Router descriptors, directories, and running-routers documents all obey the
203 following lightweight extensible information format.
205 The highest level object is a Document, which consists of one or more
206 Items. Every Item begins with a KeywordLine, followed by zero or more
207 Objects. A KeywordLine begins with a Keyword, optionally followed by
208 whitespace and more non-newline characters, and ends with a newline. A
209 Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
210 An Object is a block of encoded data in pseudo-Open-PGP-style
211 armor. (cf. RFC 2440)
213 More formally:
215 NL = The ascii LF character (hex value 0x0a).
216 Document ::= (Item | NL)+
217 Item ::= KeywordLine Object*
218 KeywordLine ::= Keyword NL | Keyword WS ArgumentChar+ NL
219 Keyword = KeywordChar+
220 KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
221 ArgumentChar ::= any printing ASCII character except NL.
222 WS = (SP | TAB)+
223 Object ::= BeginLine Base-64-encoded-data EndLine
224 BeginLine ::= "-----BEGIN " Keyword "-----" NL
225 EndLine ::= "-----END " Keyword "-----" NL
227 The BeginLine and EndLine of an Object must use the same keyword.
229 When interpreting a Document, software MUST ignore any KeywordLine that
230 starts with a keyword it doesn't recognize; future implementations MUST NOT
231 require current clients to understand any KeywordLine not currently
232 described.
234 The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
235 extensions. All implementations MUST ignore any item of the form "opt
236 keyword ....." when they would not recognize "keyword ....."; and MUST
237 treat "opt keyword ....." as synonymous with "keyword ......" when keyword
238 is recognized.
240 Implementations before 0.1.2.5-alpha rejected any document with a
241 KeywordLine that started with a keyword that they didn't recognize.
242 When generating documents that need to be read by older versions of Tor,
243 implementations MUST prefix items not recognized by older versions of
244 Tor with an "opt" until those versions of Tor are obsolete. [Note that
245 key certificates, status vote documents, extra info documents, and
246 status consensus documents will never be read by older versions of Tor.]
248 Other implementations that want to extend Tor's directory format MAY
249 introduce their own items. The keywords for extension items SHOULD start
250 with the characters "x-" or "X-", to guarantee that they will not conflict
251 with keywords used by future versions of Tor.
253 In our document descriptions below, we tag Items with a multiplicity in
254 brackets. Possible tags are:
256 "At start, exactly once": These items MUST occur in every instance of
257 the document type, and MUST appear exactly once, and MUST be the
258 first item in their documents.
260 "Exactly once": These items MUST occur exactly one time in every
261 instance of the document type.
263 "At end, exactly once": These items MUST occur in every instance of
264 the document type, and MUST appear exactly once, and MUST be the
265 last item in their documents.
267 "At most once": These items MAY occur zero or one times in any
268 instance of the document type, but MUST NOT occur more than once.
270 "Any number": These items MAY occur zero, one, or more times in any
271 instance of the document type.
273 "Once or more": These items MUST occur at least once in any instance
274 of the document type, and MAY occur more.
276 1.3. Signing documents
278 Every signable document below is signed in a similar manner, using a
279 given "Initial Item", a final "Signature Item", a digest algorithm, and
280 a signing key.
282 The Initial Item must be the first item in the document.
284 The Signature Item has the following format:
286 <signature item keyword> [arguments] NL SIGNATURE NL
288 The "SIGNATURE" Object contains a signature (using the signing key) of
289 the PKCS1-padded digest of the entire document, taken from the
290 beginning of the Initial item, through the newline after the Signature
291 Item's keyword and its arguments.
293 Unless otherwise, the digest algorithm is SHA-1.
295 All documents are invalid unless signed with the correct signing key.
297 The "Digest" of a document, unless stated otherwise, is its digest *as
298 signed by this signature scheme*.
300 1.4. Voting timeline
302 Every consensus document has a "valid-after" (VA) time, a "fresh-until"
303 (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
304 in turn precede VU. Times are chosen so that every consensus will be
305 "fresh" until the next consensus becomes valid, and "valid" for a while
306 after. At least 3 consensuses should be valid at any given time.
308 The timeline for a given consensus is as follows:
310 VA-DistSeconds-VoteSeconds: The authorities exchange votes.
312 VA-DistSeconds-VoteSeconds/2: The authorities try to download any
313 votes they don't have.
315 VA-DistSeconds: The authorities calculate the consensus and exchange
316 signatures.
318 VA-DistSeconds/2: The authorities try to download any signatures
319 they don't have.
321 VA: All authorities have a multiply signed consensus.
323 VA ... FU: Caches download the consensus. (Note that since caches have
324 no way of telling what VA and FU are until they have downloaded
325 the consensus, they assume that the present consensus's VA is
326 equal to the previous one's FU, and that its FU is one interval after
327 that.)
329 FU: The consensus is no longer the freshest consensus.
331 FU ... (the current consensus's VU): Clients download the consensus.
332 (See note above: clients guess that the next consensus's FU will be
333 two intervals after the current VA.)
335 VU: The consensus is no longer valid.
337 VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
338 VU-FU MUST each be at least 5 minutes.
340 2. Router operation and formats
342 ORs SHOULD generate a new router descriptor and a new extra-info
343 document whenever any of the following events have occurred:
345 - A period of time (18 hrs by default) has passed since the last
346 time a descriptor was generated.
348 - A descriptor field other than bandwidth or uptime has changed.
350 - Bandwidth has changed by a factor of 2 from the last time a
351 descriptor was generated, and at least a given interval of time
352 (20 mins by default) has passed since then.
354 - Its uptime has been reset (by restarting).
356 [XXX this list is incomplete; see router_differences_are_cosmetic()
357 in routerlist.c for others]
359 ORs SHOULD NOT publish a new router descriptor or extra-info document
360 if none of the above events have occurred and not much time has passed
361 (12 hours by default).
363 After generating a descriptor, ORs upload them to every directory
364 authority they know, by posting them (in order) to the URL
366 http://<hostname:port>/tor/
368 2.1. Router descriptor format
370 Router descriptors consist of the following items. For backward
371 compatibility, there should be an extra NL at the end of each router
372 descriptor.
374 In lines that take multiple arguments, extra arguments SHOULD be
375 accepted and ignored. Many of the nonterminals below are defined in
376 section 2.3.
378 "router" nickname address ORPort SOCKSPort DirPort NL
380 [At start, exactly once.]
382 Indicates the beginning of a router descriptor. "nickname" must be a
383 valid router nickname as specified in 2.3. "address" must be an IPv4
384 address in dotted-quad format. The last three numbers indicate the
385 TCP ports at which this OR exposes functionality. ORPort is a port at
386 which this OR accepts TLS connections for the main OR protocol;
387 SOCKSPort is deprecated and should always be 0; and DirPort is the
388 port at which this OR accepts directory-related HTTP connections. If
389 any port is not supported, the value 0 is given instead of a port
390 number. (At least one of DirPort and ORPort SHOULD be set;
391 authorities MAY reject any descriptor with both DirPort and ORPort of
392 0.)
394 "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
396 [Exactly once]
398 Estimated bandwidth for this router, in bytes per second. The
399 "average" bandwidth is the volume per second that the OR is willing to
400 sustain over long periods; the "burst" bandwidth is the volume that
401 the OR is willing to sustain in very short intervals. The "observed"
402 value is an estimate of the capacity this server can handle. The
403 server remembers the max bandwidth sustained output over any ten
404 second period in the past day, and another sustained input. The
405 "observed" value is the lesser of these two numbers.
407 "platform" string NL
409 [At most once]
411 A human-readable string describing the system on which this OR is
412 running. This MAY include the operating system, and SHOULD include
413 the name and version of the software implementing the Tor protocol.
415 "published" YYYY-MM-DD HH:MM:SS NL
417 [Exactly once]
419 The time, in GMT, when this descriptor (and its corresponding
420 extra-info document if any) was generated.
422 "fingerprint" fingerprint NL
424 [At most once]
426 A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
427 hex, with a single space after every 4 characters) for this router's
428 identity key. A descriptor is considered invalid (and MUST be
429 rejected) if the fingerprint line does not match the public key.
431 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
432 be marked with "opt" until earlier versions of Tor are obsolete.]
434 "hibernating" bool NL
436 [At most once]
438 If the value is 1, then the Tor server was hibernating when the
439 descriptor was published, and shouldn't be used to build circuits.
441 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
442 marked with "opt" until earlier versions of Tor are obsolete.]
444 "uptime" number NL
446 [At most once]
448 The number of seconds that this OR process has been running.
450 "onion-key" NL a public key in PEM format
452 [Exactly once]
454 This key is used to encrypt EXTEND cells for this OR. The key MUST be
455 accepted for at least 1 week after any new key is published in a
456 subsequent descriptor. It MUST be 1024 bits.
458 "signing-key" NL a public key in PEM format
460 [Exactly once]
462 The OR's long-term identity key. It MUST be 1024 bits.
464 "accept" exitpattern NL
465 "reject" exitpattern NL
467 [Any number]
469 These lines describe an "exit policy": the rules that an OR follows
470 when deciding whether to allow a new stream to a given address. The
471 'exitpattern' syntax is described below. There MUST be at least one
472 such entry. The rules are considered in order; if no rule matches,
473 the address will be accepted. For clarity, the last such entry SHOULD
474 be accept *:* or reject *:*.
476 "router-signature" NL Signature NL
478 [At end, exactly once]
480 The "SIGNATURE" object contains a signature of the PKCS1-padded
481 hash of the entire router descriptor, taken from the beginning of the
482 "router" line, through the newline after the "router-signature" line.
483 The router descriptor is invalid unless the signature is performed
484 with the router's identity key.
486 "contact" info NL
488 [At most once]
490 Describes a way to contact the server's administrator, preferably
491 including an email address and a PGP key fingerprint.
493 "family" names NL
495 [At most once]
497 'Names' is a space-separated list of server nicknames or
498 hexdigests. If two ORs list one another in their "family" entries,
499 then OPs should treat them as a single OR for the purpose of path
500 selection.
502 For example, if node A's descriptor contains "family B", and node B's
503 descriptor contains "family A", then node A and node B should never
504 be used on the same circuit.
506 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
507 [At most once]
508 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
509 [At most once]
511 Declare how much bandwidth the OR has used recently. Usage is divided
512 into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
513 defines the end of the most recent interval. The numbers are the
514 number of bytes used in the most recent intervals, ordered from
515 oldest to newest.
517 [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
518 be marked with "opt" until earlier versions of Tor are obsolete.]
520 [See also migration notes in section 2.2.1.]
522 "eventdns" bool NL
524 [At most once]
526 Declare whether this version of Tor is using the newer enhanced
527 dns logic. Versions of Tor with this field set to false SHOULD NOT
528 be used for reverse hostname lookups.
530 [All versions of Tor before 0.1.2.2-alpha should be assumed to have
531 this option set to 0 if it is not present. All Tor versions at
532 0.1.2.2-alpha or later should be assumed to have this option set to
533 1 if it is not present. Until 0.1.2.1-alpha-dev, this option was
534 not generated, even when the new DNS code was in use. Versions of Tor
535 before 0.1.2.1-alpha-dev did not parse this option, so it should be
536 marked "opt". The dnsworker logic has been removed, so this option
537 should not be used by new server code. However, it can still be
538 used, and should still be recognized by new code until Tor 0.1.2.x
539 is obsolete.]
541 "caches-extra-info" NL
543 [At most once.]
545 Present only if this router is a directory cache that provides
546 extra-info documents.
548 [Versions before 0.2.0.1-alpha don't recognize this, and versions
549 before 0.1.2.5-alpha will reject descriptors containing it unless
550 it is prefixed with "opt"; it should be so prefixed until these
551 versions are obsolete.]
553 "extra-info-digest" digest NL
555 [At most once]
557 "Digest" is a hex-encoded digest (using upper-case characters) of the
558 router's extra-info document, as signed in the router's extra-info
559 (that is, not including the signature). (If this field is absent, the
560 router is not uploading a corresponding extra-info document.)
562 [Versions before 0.2.0.1-alpha don't recognize this, and versions
563 before 0.1.2.5-alpha will reject descriptors containing it unless
564 it is prefixed with "opt"; it should be so prefixed until these
565 versions are obsolete.]
567 "hidden-service-dir" *(SP VersionNum) NL
569 [At most once.]
571 Present only if this router stores and serves hidden service
572 descriptors. If any VersionNum(s) are specified, this router
573 supports those descriptor versions. If none are specified, it
574 defaults to version 2 descriptors.
576 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
577 with unrecognized items; the protocols line should be preceded with
578 an "opt" until these Tors are obsolete.]
580 "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
581 CIRCUIT-VERSION-LIST NL
583 [At most once.]
585 Both lists are space-separated sequences of numbers, to indicate which
586 protocols the server supports. As of 30 Mar 2008, specified
587 protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt
588 for more information about link protocol versions.
590 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
591 with unrecognized items; the protocols line should be preceded with
592 an "opt" until these Tors are obsolete.]
594 "allow-single-hop-exits"
596 [At most once.]
598 Present only if the router allows single-hop circuits to make exit
599 connections. Most Tor servers do not support this: this is
600 included for specialized controllers designed to support perspective
601 access and such.
604 2.2. Extra-info documents
606 Extra-info documents consist of the following items:
608 "extra-info" Nickname Fingerprint NL
609 [At start, exactly once.]
611 Identifies what router this is an extra info descriptor for.
612 Fingerprint is encoded in hex (using upper-case letters), with
613 no spaces.
615 "published"
617 [Exactly once.]
619 The time, in GMT, when this document (and its corresponding router
620 descriptor if any) was generated. It MUST match the published time
621 in the corresponding router descriptor.
623 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
624 [At most once.]
625 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
626 [At most once.]
628 As documented in 2.1 above. See migration notes in section 2.2.1.
630 "geoip-start" YYYY-MM-DD HH:MM:SS NL
631 "geoip-client-origins" CC=N,CC=N,... NL
633 Only generated by bridge routers (see blocking.pdf), and only
634 when they have been configured with a geoip database.
635 Non-bridges SHOULD NOT generate these fields. Contains a list
636 of mappings from two-letter country codes (CC) to the number
637 of clients that have connected to that bridge from that
638 country (approximate, and rounded up to the nearest multiple of 8
639 in order to hamper traffic analysis). A country is included
640 only if it has at least one address. The time in
641 "geoip-start" is the time at which we began collecting geoip
642 statistics.
644 "dirreq-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
645 [At most once.]
647 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
648 interval of length NSEC seconds (86400 seconds by default).
650 A "dirreq-stats-end" line, as well as any other "dirreq-*" line,
651 is only added when the relay has opened its Dir port and after 24
652 hours of measuring directory requests.
654 "dirreq-v2-ips" CC=N,CC=N,... NL
655 [At most once.]
656 "dirreq-v3-ips" CC=N,CC=N,... NL
657 [At most once.]
659 List of mappings from two-letter country codes to the number of
660 unique IP addresses that have connected from that country to
661 request a v2/v3 network status, rounded up to the nearest multiple
662 of 8. Only those IP addresses are counted that the directory can
663 answer with a 200 OK status code.
665 "dirreq-v2-reqs" CC=N,CC=N,... NL
666 [At most once.]
667 "dirreq-v3-reqs" CC=N,CC=N,... NL
668 [At most once.]
670 List of mappings from two-letter country codes to the number of
671 requests for v2/v3 network statuses from that country, rounded up
672 to the nearest multiple of 8. Only those requests are counted that
673 the directory can answer with a 200 OK status code.
675 "dirreq-v2-share" num% NL
676 [At most once.]
677 "dirreq-v3-share" num% NL
678 [At most once.]
680 The share of v2/v3 network status requests that the directory
681 expects to receive from clients based on its advertised bandwidth
682 compared to the overall network bandwidth capacity. Shares are
683 formatted in percent with two decimal places. Shares are
684 calculated as means over the whole 24-hour interval.
686 "dirreq-v2-resp" status=num,... NL
687 [At most once.]
688 "dirreq-v3-resp" status=nul,... NL
689 [At most once.]
691 List of mappings from response statuses to the number of requests
692 for v2/v3 network statuses that were answered with that response
693 status, rounded up to the nearest multiple of 4. Only response
694 statuses with at least 1 response are reported. New response
695 statuses can be added at any time. The current list of response
696 statuses is as follows:
698 "ok": a network status request is answered; this number
699 corresponds to the sum of all requests as reported in
700 "dirreq-v2-reqs" or "dirreq-v3-reqs", respectively, before
701 rounding up.
702 "not-enough-sigs: a version 3 network status is not signed by a
703 sufficient number of requested authorities.
704 "unavailable": a requested network status object is unavailable.
705 "not-found": a requested network status is not found.
706 "not-modified": a network status has not been modified since the
707 If-Modified-Since time that is included in the request.
708 "busy": the directory is busy.
710 "dirreq-v2-direct-dl" key=val,... NL
711 [At most once.]
712 "dirreq-v3-direct-dl" key=val,... NL
713 [At most once.]
714 "dirreq-v2-tunneled-dl" key=val,... NL
715 [At most once.]
716 "dirreq-v3-tunneled-dl" key=val,... NL
717 [At most once.]
719 List of statistics about possible failures in the download process
720 of v2/v3 network statuses. Requests are either "direct"
721 HTTP-encoded requests over the relay's directory port, or
722 "tunneled" requests using a BEGIN_DIR cell over the relay's OR
723 port. The list of possible statistics can change, and statistics
724 can be left out from reporting. The current list of statistics is
725 as follows:
727 Successful downloads and failures:
729 "complete": a client has finished the download successfully.
730 "timeout": a download did not finish within 10 minutes after
731 starting to send the response.
732 "running": a download is still running at the end of the
733 measurement period for less than 10 minutes after starting to
734 send the response.
736 Download times:
738 "min", "max": smallest and largest measured bandwidth in B/s.
739 "d[1-4,6-9]": 1st to 4th and 6th to 9th decile of measured
740 bandwidth in B/s. For a given decile i, i/10 of all downloads
741 had a smaller bandwidth than di, and (10-i)/10 of all downloads
742 had a larger bandwidth than di.
743 "q[1,3]": 1st and 3rd quartile of measured bandwidth in B/s. One
744 fourth of all downloads had a smaller bandwidth than q1, one
745 fourth of all downloads had a larger bandwidth than q3, and the
746 remaining half of all downloads had a bandwidth between q1 and
747 q3.
748 "md": median of measured bandwidth in B/s. Half of the downloads
749 had a smaller bandwidth than md, the other half had a larger
750 bandwidth than md.
752 "entry-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
753 [At most once.]
755 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
756 interval of length NSEC seconds (86400 seconds by default).
758 An "entry-stats-end" line, as well as any other "entry-*"
759 line, is first added after the relay has been running for at least
760 24 hours.
762 "entry-ips" CC=N,CC=N,... NL
763 [At most once.]
765 List of mappings from two-letter country codes to the number of
766 unique IP addresses that have connected from that country to the
767 relay and which are no known other relays, rounded up to the
768 nearest multiple of 8.
770 "cell-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
771 [At most once.]
773 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
774 interval of length NSEC seconds (86400 seconds by default).
776 A "cell-stats-end" line, as well as any other "cell-*" line,
777 is first added after the relay has been running for at least 24
778 hours.
780 "cell-processed-cells" num,...,num NL
781 [At most once.]
783 Mean number of processed cells per circuit, subdivided into
784 deciles of circuits by the number of cells they have processed in
785 descending order from loudest to quietest circuits.
787 "cell-queued-cells" num,...,num NL
788 [At most once.]
790 Mean number of cells contained in queues by circuit decile. These
791 means are calculated by 1) determining the mean number of cells in
792 a single circuit between its creation and its termination and 2)
793 calculating the mean for all circuits in a given decile as
794 determined in "cell-processed-cells". Numbers have a precision of
795 two decimal places.
797 "cell-time-in-queue" num,...,num NL
798 [At most once.]
800 Mean time cells spend in circuit queues in milliseconds. Times are
801 calculated by 1) determining the mean time cells spend in the
802 queue of a single circuit and 2) calculating the mean for all
803 circuits in a given decile as determined in
804 "cell-processed-cells".
806 "cell-circuits-per-decile" num NL
807 [At most once.]
809 Mean number of circuits that are included in any of the deciles,
810 rounded up to the next integer.
812 "exit-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
813 [At most once.]
815 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
816 interval of length NSEC seconds (86400 seconds by default).
818 An "exit-stats-end" line, as well as any other "exit-*" line, is
819 first added after the relay has been running for at least 24 hours
820 and only if the relay permits exiting (where exiting to a single
821 port and IP address is sufficient).
823 "exit-kibibytes-written" port=N,port=N,... NL
824 [At most once.]
825 "exit-kibibytes-read" port=N,port=N,... NL
826 [At most once.]
828 List of mappings from ports to the number of kibibytes that the
829 relay has written to or read from exit connections to that port,
830 rounded up to the next full kibibyte.
832 "exit-streams-opened" port=N,port=N,... NL
833 [At most once.]
835 List of mappings from ports to the number of opened exit streams
836 to that port, rounded up to the nearest multiple of 4.
838 "router-signature" NL Signature NL
839 [At end, exactly once.]
841 A document signature as documented in section 1.3, using the
842 initial item "extra-info" and the final item "router-signature",
843 signed with the router's identity key.
845 2.2.1. Moving history fields to extra-info documents.
847 Tools that want to use the read-history and write-history values SHOULD
848 download extra-info documents as well as router descriptors. Such
849 tools SHOULD accept history values from both sources; if they appear in
850 both documents, the values in the extra-info documents are authoritative.
852 New versions of Tor no longer generate router descriptors
853 containing read-history or write-history. Tools should continue to
854 accept read-history and write-history values in router descriptors
855 produced by older versions of Tor until all Tor versions earlier
856 than 0.2.0.x are obsolete.
858 2.3. Nonterminals in router descriptors
860 nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
861 case-insensitive.
862 hexdigest ::= a '$', followed by 40 hexadecimal characters
863 ([A-Fa-f0-9]). [Represents a server by the digest of its identity
864 key.]
866 exitpattern ::= addrspec ":" portspec
867 portspec ::= "*" | port | port "-" port
868 port ::= an integer between 1 and 65535, inclusive.
870 [Some implementations incorrectly generate ports with value 0.
871 Implementations SHOULD accept this, and SHOULD NOT generate it.
872 Connections to port 0 are never permitted.]
874 addrspec ::= "*" | ip4spec | ip6spec
875 ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
876 ip4 ::= an IPv4 address in dotted-quad format
877 ip4mask ::= an IPv4 mask in dotted-quad format
878 num_ip4_bits ::= an integer between 0 and 32
879 ip6spec ::= ip6 | ip6 "/" num_ip6_bits
880 ip6 ::= an IPv6 address, surrounded by square brackets.
881 num_ip6_bits ::= an integer between 0 and 128
883 bool ::= "0" | "1"
885 3. Formats produced by directory authorities.
887 Every authority has two keys used in this protocol: a signing key, and
888 an authority identity key. (Authorities also have a router identity
889 key used in their role as a router and by earlier versions of the
890 directory protocol.) The identity key is used from time to time to
891 sign new key certificates using new signing keys; it is very sensitive.
892 The signing key is used to sign key certificates and status documents.
894 There are three kinds of documents generated by directory authorities:
896 Key certificates
897 Status votes
898 Status consensuses
900 Each is discussed below.
902 3.1. Key certificates
904 Key certificates consist of the following items:
906 "dir-key-certificate-version" version NL
908 [At start, exactly once.]
910 Determines the version of the key certificate. MUST be "3" for
911 the protocol described in this document. Implementations MUST
912 reject formats they don't understand.
914 "dir-address" IPPort NL
915 [At most once]
917 An IP:Port for this authority's directory port.
919 "fingerprint" fingerprint NL
921 [Exactly once.]
923 Hexadecimal encoding without spaces based on the authority's
924 identity key.
926 "dir-identity-key" NL a public key in PEM format
928 [Exactly once.]
930 The long-term authority identity key for this authority. This key
931 SHOULD be at least 2048 bits long; it MUST NOT be shorter than
932 1024 bits.
934 "dir-key-published" YYYY-MM-DD HH:MM:SS NL
936 [Exactly once.]
938 The time (in GMT) when this document and corresponding key were
939 last generated.
941 "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
943 [Exactly once.]
945 A time (in GMT) after which this key is no longer valid.
947 "dir-signing-key" NL a key in PEM format
949 [Exactly once.]
951 The directory server's public signing key. This key MUST be at
952 least 1024 bits, and MAY be longer.
954 "dir-key-crosscert" NL CrossSignature NL
956 [At most once.]
958 NOTE: Authorities MUST include this field in all newly generated
959 certificates. A future version of this specification will make
960 the field required.
962 CrossSignature is a signature, made using the certificate's signing
963 key, of the digest of the PKCS1-padded hash of the certificate's
964 identity key. For backward compatibility with broken versions of the
965 parser, we wrap the base64-encoded signature in -----BEGIN ID
966 SIGNATURE---- and -----END ID SIGNATURE----- tags. Implementations
967 MUST allow the "ID " portion to be omitted, however.
969 When encountering a certificate with a dir-key-crosscert entry,
970 implementations MUST verify that the signature is a correct signature
971 of the hash of the identity key using the signing key.
973 "dir-key-certification" NL Signature NL
975 [At end, exactly once.]
977 A document signature as documented in section 1.3, using the
978 initial item "dir-key-certificate-version" and the final item
979 "dir-key-certification", signed with the authority identity key.
981 Authorities MUST generate a new signing key and corresponding
982 certificate before the key expires.
984 3.2. Vote and consensus status documents
986 Votes and consensuses are more strictly formatted then other documents
987 in this specification, since different authorities must be able to
988 generate exactly the same consensus given the same set of votes.
990 The procedure for deciding when to generate vote and consensus status
991 documents are described in section XXX below.
993 Status documents contain a preamble, an authority section, a list of
994 router status entries, and one or more footer signature, in that order.
996 Unlike other formats described above, a SP in these documents must be a
997 single space character (hex 20).
999 Some items appear only in votes, and some items appear only in
1000 consensuses. Unless specified, items occur in both.
1002 The preamble contains the following items. They MUST occur in the
1003 order given here:
1005 "network-status-version" SP version NL.
1007 [At start, exactly once.]
1009 A document format version. For this specification, the version is
1010 "3".
1012 "vote-status" SP type NL
1014 [Exactly once.]
1016 The status MUST be "vote" or "consensus", depending on the type of
1017 the document.
1019 "consensus-methods" SP IntegerList NL
1021 [Exactly once for votes; does not occur in consensuses.]
1023 A space-separated list of supported methods for generating
1024 consensuses from votes. See section 3.4.1 for details. Method "1"
1025 MUST be included.
1027 "consensus-method" SP Integer NL
1029 [Exactly once for consensuses; does not occur in votes.]
1031 See section 3.4.1 for details.
1033 (Only included when the vote is generated with consensus-method 2 or
1034 later.)
1036 "published" SP YYYY-MM-DD SP HH:MM:SS NL
1038 [Exactly once for votes; does not occur in consensuses.]
1040 The publication time for this status document (if a vote).
1042 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1044 [Exactly once.]
1046 The start of the Interval for this vote. Before this time, the
1047 consensus document produced from this vote should not be used.
1048 See 1.4 for voting timeline information.
1050 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1052 [Exactly once.]
1054 The time at which the next consensus should be produced; before this
1055 time, there is no point in downloading another consensus, since there
1056 won't be a new one. See 1.4 for voting timeline information.
1058 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1060 [Exactly once.]
1062 The end of the Interval for this vote. After this time, the
1063 consensus produced by this vote should not be used. See 1.4 for
1064 voting timeline information.
1066 "voting-delay" SP VoteSeconds SP DistSeconds NL
1068 [Exactly once.]
1070 VoteSeconds is the number of seconds that we will allow to collect
1071 votes from all authorities; DistSeconds is the number of seconds
1072 we'll allow to collect signatures from all authorities. See 1.4 for
1073 voting timeline information.
1075 "client-versions" SP VersionList NL
1077 [At most once.]
1079 A comma-separated list of recommended client versions, in
1080 ascending order. If absent, no opinion is held about client
1081 versions.
1083 "server-versions" SP VersionList NL
1085 [At most once.]
1087 A comma-separated list of recommended server versions, in
1088 ascending order. If absent, no opinion is held about server
1089 versions.
1091 "known-flags" SP FlagList NL
1093 [Exactly once.]
1095 A space-separated list of all of the flags that this document
1096 might contain. A flag is "known" either because the authority
1097 knows about them and might set them (if in a vote), or because
1098 enough votes were counted for the consensus for an authoritative
1099 opinion to have been formed about their status.
1101 "params" SP [Parameters] NL
1103 [At most once]
1105 Parameter ::= Keyword '=' Int32
1106 Int32 ::= A decimal integer between -2147483648 and 2147483647.
1107 Parameters ::= Parameter | Parameters SP Parameter
1109 The parameters list, if present, contains a space-separated list of
1110 key-value pairs, sorted in lexical order by their keyword. Each
1111 parameter has its own meaning.
1113 (Only included when the vote is generated with consensus-method 7 or
1114 later.)
1116 The authority section of a vote contains the following items, followed
1117 in turn by the authority's current key certificate:
1119 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
1120 orport NL
1122 [Exactly once, at start]
1124 Describes this authority. The nickname is a convenient identifier
1125 for the authority. The identity is an uppercase hex fingerprint of
1126 the authority's current (v3 authority) identity key. The address is
1127 the server's hostname. The IP is the server's current IP address,
1128 and dirport is its current directory port. XXXXorport
1130 "contact" SP string NL
1132 [At most once.]
1134 An arbitrary string describing how to contact the directory
1135 server's administrator. Administrators should include at least an
1136 email address and a PGP fingerprint.
1138 "legacy-key" SP FINGERPRINT NL
1140 [At most once]
1142 Lists a fingerprint for an obsolete _identity_ key still used
1143 by this authority to keep older clients working. This option
1144 is used to keep key around for a little while in case the
1145 authorities need to migrate many identity keys at once.
1146 (Generally, this would only happen because of a security
1147 vulnerability that affected multiple authorities, like the
1148 Debian OpenSSL RNG bug of May 2008.)
1150 The authority section of a consensus contains groups the following items,
1151 in the order given, with one group for each authority that contributed to
1152 the consensus, with groups sorted by authority identity digest:
1154 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
1155 orport NL
1157 [Exactly once, at start]
1159 As in the authority section of a vote.
1161 "contact" SP string NL
1163 [At most once.]
1165 As in the authority section of a vote.
1167 "vote-digest" SP digest NL
1169 [Exactly once.]
1171 A digest of the vote from the authority that contributed to this
1172 consensus, as signed (that is, not including the signature).
1173 (Hex, upper-case.)
1175 Each router status entry contains the following items. Router status
1176 entries are sorted in ascending order by identity digest.
1178 "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
1179 SP DirPort NL
1181 [At start, exactly once.]
1183 "Nickname" is the OR's nickname. "Identity" is a hash of its
1184 identity key, encoded in base64, with trailing equals sign(s)
1185 removed. "Digest" is a hash of its most recent descriptor as
1186 signed (that is, not including the signature), encoded in base64.
1187 "Publication" is the
1188 publication time of its most recent descriptor, in the form
1189 YYYY-MM-DD HH:MM:SS, in GMT. "IP" is its current IP address;
1190 ORPort is its current OR port, "DirPort" is it's current directory
1191 port, or "0" for "none".
1193 "s" SP Flags NL
1195 [At most once.]
1197 A series of space-separated status flags, in alphabetical order.
1198 Currently documented flags are:
1200 "Authority" if the router is a directory authority.
1201 "BadExit" if the router is believed to be useless as an exit node
1202 (because its ISP censors it, because it is behind a restrictive
1203 proxy, or for some similar reason).
1204 "BadDirectory" if the router is believed to be useless as a
1205 directory cache (because its directory port isn't working,
1206 its bandwidth is always throttled, or for some similar
1207 reason).
1208 "Exit" if the router is more useful for building
1209 general-purpose exit circuits than for relay circuits. The
1210 path building algorithm uses this flag; see path-spec.txt.
1211 "Fast" if the router is suitable for high-bandwidth circuits.
1212 "Guard" if the router is suitable for use as an entry guard.
1213 "HSDir" if the router is considered a v2 hidden service directory.
1214 "Named" if the router's identity-nickname mapping is canonical,
1215 and this authority binds names.
1216 "Stable" if the router is suitable for long-lived circuits.
1217 "Running" if the router is currently usable.
1218 "Unnamed" if another router has bound the name used by this
1219 router, and this authority binds names.
1220 "Valid" if the router has been 'validated'.
1221 "V2Dir" if the router implements the v2 directory protocol.
1222 "V3Dir" if the router implements this protocol.
1224 "v" SP version NL
1226 [At most once.]
1228 The version of the Tor protocol that this server is running. If
1229 the value begins with "Tor" SP, the rest of the string is a Tor
1230 version number, and the protocol is "The Tor protocol as supported
1231 by the given version of Tor." Otherwise, if the value begins with
1232 some other string, Tor has upgraded to a more sophisticated
1233 protocol versioning system, and the protocol is "a version of the
1234 Tor protocol more recent than any we recognize."
1236 Directory authorities SHOULD omit version strings they receive from
1237 descriptors if they would cause "v" lines to be over 128 characters
1238 long.
1240 "w" SP "Bandwidth=" INT [SP "Measured=" INT] NL
1242 [At most once.]
1244 An estimate of the bandwidth of this server, in an arbitrary
1245 unit (currently kilobytes per second). Used to weight router
1246 selection.
1248 Additionally, the Measured= keyword is present in votes by
1249 participating bandwidth measurement authorites to indicate
1250 a measured bandwidth currently produced by measuring stream
1251 capacities.
1253 Other weighting keywords may be added later.
1254 Clients MUST ignore keywords they do not recognize.
1256 "p" SP ("accept" / "reject") SP PortList NL
1258 [At most once.]
1260 PortList = PortOrRange
1261 PortList = PortList "," PortOrRange
1262 PortOrRange = INT "-" INT / INT
1264 A list of those ports that this router supports (if 'accept')
1265 or does not support (if 'reject') for exit to "most
1266 addresses".
1268 The signature section contains the following item, which appears
1269 Exactly Once for a vote, and At Least Once for a consensus.
1271 "directory-signature" SP identity SP signing-key-digest NL Signature
1273 This is a signature of the status document, with the initial item
1274 "network-status-version", and the signature item
1275 "directory-signature", using the signing key. (In this case, we take
1276 the hash through the _space_ after directory-signature, not the
1277 newline: this ensures that all authorities sign the same thing.)
1278 "identity" is the hex-encoded digest of the authority identity key of
1279 the signing authority, and "signing-key-digest" is the hex-encoded
1280 digest of the current authority signing key of the signing authority.
1282 3.3. Deciding how to vote.
1284 (This section describes how directory authorities choose which status
1285 flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
1286 authorities MAY do things differently, so long as clients keep working
1287 well. Clients MUST NOT depend on the exact behaviors in this section.)
1289 In the below definitions, a router is considered "active" if it is
1290 running, valid, and not hibernating.
1292 "Valid" -- a router is 'Valid' if it is running a version of Tor not
1293 known to be broken, and the directory authority has not blacklisted
1294 it as suspicious.
1296 "Named" -- Directory authority administrators may decide to support name
1297 binding. If they do, then they must maintain a file of
1298 nickname-to-identity-key mappings, and try to keep this file consistent
1299 with other directory authorities. If they don't, they act as clients, and
1300 report bindings made by other directory authorities (name X is bound to
1301 identity Y if at least one binding directory lists it, and no directory
1302 binds X to some other Y'.) A router is called 'Named' if the router
1303 believes the given name should be bound to the given key.
1305 Two strategies exist on the current network for deciding on
1306 values for the Named flag. In the original version, server
1307 operators were asked to send nickname-identity pairs to a
1308 mailing list of Naming directory authorities operators. The
1309 operators were then supposed to add the pairs to their
1310 mapping files; in practice, they didn't get to this often.
1312 Newer Naming authorities run a script that registers routers
1313 in their mapping files once the routers have been online at
1314 least two weeks, no other router has that nickname, and no
1315 other router has wanted the nickname for a month. If a router
1316 has not been online for six months, the router is removed.
1318 "Unnamed" -- Directory authorities that support naming should vote for a
1319 router to be 'Unnamed' if its given nickname is mapped to a different
1320 identity.
1322 "Running" -- A router is 'Running' if the authority managed to connect to
1323 it successfully within the last 30 minutes.
1325 "Stable" -- A router is 'Stable' if it is active, and either its Weighted
1326 MTBF is at least the median for known active routers or its Weighted MTBF
1327 corresponds to at least 7 days. Routers are never called Stable if they are
1328 running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
1329 through 0.1.1.16-rc are stupid this way.)
1331 To calculate weighted MTBF, compute the weighted mean of the lengths
1332 of all intervals when the router was observed to be up, weighting
1333 intervals by $\alpha^n$, where $n$ is the amount of time that has
1334 passed since the interval ended, and $\alpha$ is chosen so that
1335 measurements over approximately one month old no longer influence the
1336 weighted MTBF much.
1338 [XXXX what happens when we have less than 4 days of MTBF info.]
1340 "Exit" -- A router is called an 'Exit' iff it allows exits to at
1341 least two of the ports 80, 443, and 6667 and allows exits to at
1342 least one /8 address space.
1344 "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
1345 either in the top 7/8ths for known active routers or at least 100KB/s.
1347 "Guard" -- A router is a possible 'Guard' if its Weighted Fractional
1348 Uptime is at least the median for "familiar" active routers, and if
1349 its bandwidth is at least median or at least 250KB/s.
1350 If the total bandwidth of active non-BadExit Exit servers is less
1351 than one third of the total bandwidth of all active servers, no Exit is
1352 listed as a Guard.
1354 To calculate weighted fractional uptime, compute the fraction
1355 of time that the router is up in any given day, weighting so that
1356 downtime and uptime in the past counts less.
1358 A node is 'familiar' if 1/8 of all active nodes have appeared more
1359 recently than it, OR it has been around for a few weeks.
1361 "Authority" -- A router is called an 'Authority' if the authority
1362 generating the network-status document believes it is an authority.
1364 "V2Dir" -- A router supports the v2 directory protocol if it has an open
1365 directory port, and it is running a version of the directory protocol that
1366 supports the functionality clients need. (Currently, this is
1367 0.1.1.9-alpha or later.)
1369 "V3Dir" -- A router supports the v3 directory protocol if it has an open
1370 directory port, and it is running a version of the directory protocol that
1371 supports the functionality clients need. (Currently, this is
1372 0.2.0.?????-alpha or later.)
1374 "HSDir" -- A router is a v2 hidden service directory if it stores and
1375 serves v2 hidden service descriptors and the authority managed to connect
1376 to it successfully within the last 24 hours.
1378 Directory server administrators may label some servers or IPs as
1379 blacklisted, and elect not to include them in their network-status lists.
1381 Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
1382 When there are more than 3 to choose from, authorities should first prefer
1383 authorities to non-authorities, then prefer Running to non-Running, and
1384 then prefer high-bandwidth to low-bandwidth. To 'disable' a server, the
1385 authority *should* advertise it without the Running or Valid flag.
1387 Thus, the network-status vote includes all non-blacklisted,
1388 non-expired, non-superseded descriptors.
1390 The bandwidth in a "w" line should be taken as the best estimate
1391 of the router's actual capacity that the authority has. For now,
1392 this should be the lesser of the observed bandwidth and bandwidth
1393 rate limit from the router descriptor. It is given in kilobytes
1394 per second, and capped at some arbitrary value (currently 10 MB/s).
1396 The Measured= keyword on a "w" line vote is currently computed
1397 by multiplying the previous published consensus bandwidth by the
1398 ratio of the measured average node stream capacity to the network
1399 average. If 3 or more authorities provide a Measured= keyword for
1400 a router, the authorites produce a consensus containing a "w"
1401 Bandwidth= keyword equal to the median of the Measured= votes.
1403 The ports listed in a "p" line should be taken as those ports for
1404 which the router's exit policy permits 'most' addresses, ignoring any
1405 accept not for all addresses, ignoring all rejects for private
1406 netblocks. "Most" addresses are permitted if no more than 2^25
1407 IPv4 addresses (two /8 networks) were blocked. The list is encoded
1408 as described in 3.4.2.
1410 3.4. Computing a consensus from a set of votes
1412 Given a set of votes, authorities compute the contents of the consensus
1413 document as follows:
1415 The "valid-after", "valid-until", and "fresh-until" times are taken as
1416 the median of the respective values from all the votes.
1418 The times in the "voting-delay" line are taken as the median of the
1419 VoteSeconds and DistSeconds times in the votes.
1421 Known-flags is the union of all flags known by any voter.
1423 Entries are given on the "params" line for every keyword on which any
1424 authority voted. The values given are the low-median of all votes on
1425 that keyword.
1427 "client-versions" and "server-versions" are sorted in ascending
1428 order; A version is recommended in the consensus if it is recommended
1429 by more than half of the voting authorities that included a
1430 client-versions or server-versions lines in their votes.
1432 The authority item groups (dir-source, contact, fingerprint,
1433 vote-digest) are taken from the votes of the voting
1434 authorities. These groups are sorted by the digests of the
1435 authorities identity keys, in ascending order. If the consensus
1436 method is 3 or later, a dir-source line must be included for
1437 every vote with legacy-key entry, using the legacy-key's
1438 fingerprint, the voter's ordinary nickname with the string
1439 "-legacy" appended, and all other fields as from the original
1440 vote's dir-source line.
1442 A router status entry:
1443 * is included in the result if some router status entry with the same
1444 identity is included by more than half of the authorities (total
1445 authorities, not just those whose votes we have).
1447 * For any given identity, we include at most one router status entry.
1449 * A router entry has a flag set if that is included by more than half
1450 of the authorities who care about that flag.
1452 * Two router entries are "the same" if they have the same
1453 <descriptor digest, published time, nickname, IP, ports> tuple.
1454 We choose the tuple for a given router as whichever tuple appears
1455 for that router in the most votes. We break ties first in favor of
1456 the more recently published, then in favor of smaller server
1457 descriptor digest.
1459 * The Named flag appears if it is included for this routerstatus by
1460 _any_ authority, and if all authorities that list it list the same
1461 nickname. However, if consensus-method 2 or later is in use, and
1462 any authority calls this identity/nickname pair Unnamed, then
1463 this routerstatus does not get the Named flag.
1465 * If consensus-method 2 or later is in use, the Unnamed flag is
1466 set for a routerstatus if any authorities have voted for a different
1467 identities to be Named with that nickname, or if any authority
1468 lists that nickname/ID pair as Unnamed.
1470 (With consensus-method 1, Unnamed is set like any other flag.)
1472 * The version is given as whichever version is listed by the most
1473 voters, with ties decided in favor of more recent versions.
1475 * If consensus-method 4 or later is in use, then routers that
1476 do not have the Running flag are not listed at all.
1478 * If consensus-method 5 or later is in use, then the "w" line
1479 is generated using a low-median of the bandwidth values from
1480 the votes that included "w" lines for this router.
1482 * If consensus-method 5 or later is in use, then the "p" line
1483 is taken from the votes that have the same policy summary
1484 for the descriptor we are listing. (They should all be the
1485 same. If they are not, we pick the most commonly listed
1486 one, breaking ties in favor of the lexicographically larger
1487 vote.) The port list is encoded as specified in 3.4.2.
1489 * If consensus-method 6 or later is in use and if 3 or more
1490 authorities provide a Measured= keyword in their votes for
1491 a router, the authorities produce a consensus containing a
1492 Bandwidth= keyword equal to the median of the Measured= votes.
1494 * If consensus-method 7 or later is in use, the params line is
1495 included in the output.
1497 The signatures at the end of a consensus document are sorted in
1498 ascending order by identity digest.
1500 All ties in computing medians are broken in favor of the smaller or
1501 earlier item.
1503 3.4.1. Forward compatibility
1505 Future versions of Tor will need to include new information in the
1506 consensus documents, but it is important that all authorities (or at least
1507 half) generate and sign the same signed consensus.
1509 To achieve this, authorities list in their votes their supported methods
1510 for generating consensuses from votes. Later methods will be assigned
1511 higher numbers. Currently recognized methods:
1512 "1" -- The first implemented version.
1513 "2" -- Added support for the Unnamed flag.
1514 "3" -- Added legacy ID key support to aid in authority ID key rollovers
1515 "4" -- No longer list routers that are not running in the consensus
1516 "5" -- adds support for "w" and "p" lines.
1517 "6" -- Prefers measured bandwidth values rather than advertised
1519 Before generating a consensus, an authority must decide which consensus
1520 method to use. To do this, it looks for the highest version number
1521 supported by more than 2/3 of the authorities voting. If it supports this
1522 method, then it uses it. Otherwise, it falls back to method 1.
1524 (The consensuses generated by new methods must be parsable by
1525 implementations that only understand the old methods, and must not cause
1526 those implementations to compromise their anonymity. This is a means for
1527 making changes in the contents of consensus; not for making
1528 backward-incompatible changes in their format.)
1530 3.4.2. Encoding port lists
1532 Whether the summary shows the list of accepted ports or the list of
1533 rejected ports depends on which list is shorter (has a shorter string
1534 representation). In case of ties we choose the list of accepted
1535 ports. As an exception to this rule an allow-all policy is
1536 represented as "accept 1-65535" instead of "reject " and a reject-all
1537 policy is similarly given as "reject 1-65535".
1539 Summary items are compressed, that is instead of "80-88,89-100" there
1540 only is a single item of "80-100", similarly instead of "20,21" a
1541 summary will say "20-21".
1543 Port lists are sorted in ascending order.
1545 The maximum allowed length of a policy summary (including the "accept "
1546 or "reject ") is 1000 characters. If a summary exceeds that length we
1547 use an accept-style summary and list as much of the port list as is
1548 possible within these 1000 bytes. [XXXX be more specific.]
1550 3.5. Detached signatures
1552 Assuming full connectivity, every authority should compute and sign the
1553 same consensus directory in each period. Therefore, it isn't necessary to
1554 download the consensus computed by each authority; instead, the
1555 authorities only push/fetch each others' signatures. A "detached
1556 signature" document contains items as follows:
1558 "consensus-digest" SP Digest NL
1560 [At start, at most once.]
1562 The digest of the consensus being signed.
1564 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1565 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1566 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1568 [As in the consensus]
1570 "directory-signature"
1572 [As in the consensus; the signature object is the same as in the
1573 consensus document.]
1576 4. Directory server operation
1578 All directory authorities and directory caches ("directory servers")
1579 implement this section, except as noted.
1581 4.1. Accepting uploads (authorities only)
1583 When a router posts a signed descriptor to a directory authority, the
1584 authority first checks whether it is well-formed and correctly
1585 self-signed. If it is, the authority next verifies that the nickname
1586 in question is not already assigned to a router with a different
1587 public key.
1588 Finally, the authority MAY check that the router is not blacklisted
1589 because of its key, IP, or another reason.
1591 If the descriptor passes these tests, and the authority does not already
1592 have a descriptor for a router with this public key, it accepts the
1593 descriptor and remembers it.
1595 If the authority _does_ have a descriptor with the same public key, the
1596 newly uploaded descriptor is remembered if its publication time is more
1597 recent than the most recent old descriptor for that router, and either:
1598 - There are non-cosmetic differences between the old descriptor and the
1599 new one.
1600 - Enough time has passed between the descriptors' publication times.
1601 (Currently, 12 hours.)
1603 Differences between router descriptors are "non-cosmetic" if they would be
1604 sufficient to force an upload as described in section 2 above.
1606 Note that the "cosmetic difference" test only applies to uploaded
1607 descriptors, not to descriptors that the authority downloads from other
1608 authorities.
1610 When a router posts a signed extra-info document to a directory authority,
1611 the authority again checks it for well-formedness and correct signature,
1612 and checks that its matches the extra-info-digest in some router
1613 descriptor that it believes is currently useful. If so, it accepts it and
1614 stores it and serves it as requested. If not, it drops it.
1616 4.2. Voting (authorities only)
1618 Authorities divide time into Intervals. Authority administrators SHOULD
1619 try to all pick the same interval length, and SHOULD pick intervals that
1620 are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
1621 minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
1622 divide evenly into a 24-hour day.
1624 Authorities SHOULD act according to interval and delays in the
1625 latest consensus. Lacking a latest consensus, they SHOULD default to a
1626 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
1628 Authorities MUST take pains to ensure that their clocks remain accurate
1629 within a few seconds. (Running NTP is usually sufficient.)
1631 The first voting period of each day begins at 00:00 (midnight) GMT. If
1632 the last period of the day would be truncated by one-half or more, it is
1633 merged with the second-to-last period.
1635 An authority SHOULD publish its vote immediately at the start of each voting
1636 period (minus VoteSeconds+DistSeconds). It does this by making it
1637 available at
1638 http://<hostname>/tor/status-vote/next/authority.z
1639 and sending it in an HTTP POST request to each other authority at the URL
1640 http://<hostname>/tor/post/vote
1642 If, at the start of the voting period, minus DistSeconds, an authority
1643 does not have a current statement from another authority, the first
1644 authority downloads the other's statement.
1646 Once an authority has a vote from another authority, it makes it available
1647 at
1648 http://<hostname>/tor/status-vote/next/<fp>.z
1649 where <fp> is the fingerprint of the other authority's identity key.
1650 And at
1651 http://<hostname>/tor/status-vote/next/d/<d>.z
1652 where <d> is the digest of the vote document.
1654 The consensus status, along with as many signatures as the server
1655 currently knows, should be available at
1656 http://<hostname>/tor/status-vote/next/consensus.z
1657 All of the detached signatures it knows for consensus status should be
1658 available at:
1659 http://<hostname>/tor/status-vote/next/consensus-signatures.z
1661 Once there are enough signatures, or once the voting period starts,
1662 these documents are available at
1663 http://<hostname>/tor/status-vote/current/consensus.z
1664 and
1665 http://<hostname>/tor/status-vote/current/consensus-signatures.z
1666 [XXX current/consensus-signatures is not currently implemented, as it
1667 is not used in the voting protocol.]
1669 The other vote documents are analogously made available under
1670 http://<hostname>/tor/status-vote/current/authority.z
1671 http://<hostname>/tor/status-vote/current/<fp>.z
1672 http://<hostname>/tor/status-vote/current/d/<d>.z
1673 once the consensus is complete.
1675 Once an authority has computed and signed a consensus network status, it
1676 should send its detached signature to each other authority in an HTTP POST
1677 request to the URL:
1678 http://<hostname>/tor/post/consensus-signature
1680 [XXX Note why we support push-and-then-pull.]
1682 [XXX possible future features include support for downloading old
1683 consensuses.]
1685 4.3. Downloading consensus status documents (caches only)
1687 All directory servers (authorities and caches) try to keep a recent
1688 network-status consensus document to serve to clients. A cache ALWAYS
1689 downloads a network-status consensus if any of the following are true:
1690 - The cache has no consensus document.
1691 - The cache's consensus document is no longer valid.
1692 Otherwise, the cache downloads a new consensus document at a randomly
1693 chosen time in the first half-interval after its current consensus
1694 stops being fresh. (This time is chosen at random to avoid swarming
1695 the authorities at the start of each period. The interval size is
1696 inferred from the difference between the valid-after time and the
1697 fresh-until time on the consensus.)
1699 [For example, if a cache has a consensus that became valid at 1:00,
1700 and is fresh until 2:00, that cache will fetch a new consensus at
1701 a random time between 2:00 and 2:30.]
1703 4.4. Downloading and storing router descriptors (authorities and caches)
1705 Periodically (currently, every 10 seconds), directory servers check
1706 whether there are any specific descriptors that they do not have and that
1707 they are not currently trying to download. Caches identify these
1708 descriptors by hash in the recent network-status consensus documents;
1709 authorities identify them by hash in vote (if publication date is more
1710 recent than the descriptor we currently have).
1712 [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
1713 do that for now.]
1715 If so, the directory server launches requests to the authorities for these
1716 descriptors, such that each authority is only asked for descriptors listed
1717 in its most recent vote (if the requester is an authority) or in the
1718 consensus (if the requester is a cache). If we're an authority, and more
1719 than one authority lists the descriptor, we choose which to ask at random.
1721 If one of these downloads fails, we do not try to download that descriptor
1722 from the authority that failed to serve it again unless we receive a newer
1723 network-status (consensus or vote) from that authority that lists the same
1724 descriptor.
1726 Directory servers must potentially cache multiple descriptors for each
1727 router. Servers must not discard any descriptor listed by any recent
1728 consensus. If there is enough space to store additional descriptors,
1729 servers SHOULD try to hold those which clients are likely to download the
1730 most. (Currently, this is judged based on the interval for which each
1731 descriptor seemed newest.)
1732 [XXXX define recent]
1734 Authorities SHOULD NOT download descriptors for routers that they would
1735 immediately reject for reasons listed in 3.1.
1737 4.5. Downloading and storing extra-info documents
1739 All authorities, and any cache that chooses to cache extra-info documents,
1740 and any client that uses extra-info documents, should implement this
1741 section.
1743 Note that generally, clients don't need extra-info documents.
1745 Periodically, the Tor instance checks whether it is missing any extra-info
1746 documents: in other words, if it has any router descriptors with an
1747 extra-info-digest field that does not match any of the extra-info
1748 documents currently held. If so, it downloads whatever extra-info
1749 documents are missing. Caches download from authorities; non-caches try
1750 to download from caches. We follow the same splitting and back-off rules
1751 as in 4.4 (if a cache) or 5.3 (if a client).
1753 4.6. General-use HTTP URLs
1755 "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
1757 The most recent v3 consensus should be available at:
1758 http://<hostname>/tor/status-vote/current/consensus.z
1760 Starting with Tor version 0.2.1.1-alpha is also available at:
1761 http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
1763 Where F1, F2, etc. are authority identity fingerprints the client trusts.
1764 Servers will only return a consensus if more than half of the requested
1765 authorities have signed the document, otherwise a 404 error will be sent
1766 back. The fingerprints can be shortened to a length of any multiple of
1767 two, using only the leftmost part of the encoded fingerprint. Tor uses
1768 3 bytes (6 hex characters) of the fingerprint.
1770 Clients SHOULD sort the fingerprints in ascending order. Server MUST
1771 accept any order.
1773 Clients SHOULD use this format when requesting consensus documents from
1774 directory authority servers and from caches running a version of Tor
1775 that is known to support this URL format.
1777 A concatenated set of all the current key certificates should be available
1778 at:
1779 http://<hostname>/tor/keys/all.z
1781 The key certificate for this server (if it is an authority) should be
1782 available at:
1783 http://<hostname>/tor/keys/authority.z
1785 The key certificate for an authority whose authority identity fingerprint
1786 is <F> should be available at:
1787 http://<hostname>/tor/keys/fp/<F>.z
1789 The key certificate whose signing key fingerprint is <F> should be
1790 available at:
1791 http://<hostname>/tor/keys/sk/<F>.z
1793 The key certificate whose identity key fingerprint is <F> and whose signing
1794 key fingerprint is <S> should be available at:
1796 http://<hostname>/tor/keys/fp-sk/<F>-<S>.z
1798 (As usual, clients may request multiple certificates using:
1799 http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z )
1800 [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]
1802 The most recent descriptor for a server whose identity key has a
1803 fingerprint of <F> should be available at:
1804 http://<hostname>/tor/server/fp/<F>.z
1806 The most recent descriptors for servers with identity fingerprints
1807 <F1>,<F2>,<F3> should be available at:
1808 http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
1810 (NOTE: Implementations SHOULD NOT download descriptors by identity key
1811 fingerprint. This allows a corrupted server (in collusion with a cache) to
1812 provide a unique descriptor to a client, and thereby partition that client
1813 from the rest of the network.)
1815 The server descriptor with (descriptor) digest <D> (in hex) should be
1816 available at:
1817 http://<hostname>/tor/server/d/<D>.z
1819 The most recent descriptors with digests <D1>,<D2>,<D3> should be
1820 available at:
1821 http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
1823 The most recent descriptor for this server should be at:
1824 http://<hostname>/tor/server/authority.z
1825 [Nothing in the Tor protocol uses this resource yet, but it is useful
1826 for debugging purposes. Also, the official Tor implementations
1827 (starting at 0.1.1.x) use this resource to test whether a server's
1828 own DirPort is reachable.]
1830 A concatenated set of the most recent descriptors for all known servers
1831 should be available at:
1832 http://<hostname>/tor/server/all.z
1834 Extra-info documents are available at the URLS
1835 http://<hostname>/tor/extra/d/...
1836 http://<hostname>/tor/extra/fp/...
1837 http://<hostname>/tor/extra/all[.z]
1838 http://<hostname>/tor/extra/authority[.z]
1839 (As for /tor/server/ URLs: supports fetching extra-info
1840 documents by their digest, by the fingerprint of their servers,
1841 or all at once. When serving by fingerprint, we serve the
1842 extra-info that corresponds to the descriptor we would serve by
1843 that fingerprint. Only directory authorities of version
1844 0.2.0.1-alpha or later are guaranteed to support the first
1845 three classes of URLs. Caches may support them, and MUST
1846 support them if they have advertised "caches-extra-info".)
1848 For debugging, directories SHOULD expose non-compressed objects at URLs like
1849 the above, but without the final ".z".
1850 Clients MUST handle compressed concatenated information in two forms:
1851 - A concatenated list of zlib-compressed objects.
1852 - A zlib-compressed concatenated list of objects.
1853 Directory servers MAY generate either format: the former requires less
1854 CPU, but the latter requires less bandwidth.
1856 Clients SHOULD use upper case letters (A-F) when base16-encoding
1857 fingerprints. Servers MUST accept both upper and lower case fingerprints
1858 in requests.
1860 5. Client operation: downloading information
1862 Every Tor that is not a directory server (that is, those that do
1863 not have a DirPort set) implements this section.
1865 5.1. Downloading network-status documents
1867 Each client maintains a list of directory authorities. Insofar as
1868 possible, clients SHOULD all use the same list.
1870 Clients try to have a live consensus network-status document at all times.
1871 A network-status document is "live" if the time in its valid-until field
1872 has not passed.
1874 If a client is missing a live network-status document, it tries to fetch
1875 it from a directory cache (or from an authority if it knows no caches).
1876 On failure, the client waits briefly, then tries that network-status
1877 document again from another cache. The client does not build circuits
1878 until it has a live network-status consensus document, and it has
1879 descriptors for more than 1/4 of the routers that it believes are running.
1881 (Note: clients can and should pick caches based on the network-status
1882 information they have: once they have first fetched network-status info
1883 from an authority, they should not need to go to the authority directly
1884 again.)
1886 To avoid swarming the caches whenever a consensus expires, the
1887 clients download new consensuses at a randomly chosen time after the
1888 caches are expected to have a fresh consensus, but before their
1889 consensus will expire. (This time is chosen uniformly at random from
1890 the interval between the time 3/4 into the first interval after the
1891 consensus is no longer fresh, and 7/8 of the time remaining after
1892 that before the consensus is invalid.)
1894 [For example, if a cache has a consensus that became valid at 1:00,
1895 and is fresh until 2:00, and expires at 4:00, that cache will fetch
1896 a new consensus at a random time between 2:45 and 3:50, since 3/4
1897 of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
1898 minutes is 65 minutes.]
1900 5.2. Downloading and storing router descriptors
1902 Clients try to have the best descriptor for each router. A descriptor is
1903 "best" if:
1904 * It is listed in the consensus network-status document.
1906 Periodically (currently every 10 seconds) clients check whether there are
1907 any "downloadable" descriptors. A descriptor is downloadable if:
1908 - It is the "best" descriptor for some router.
1909 - The descriptor was published at least 10 minutes in the past.
1910 (This prevents clients from trying to fetch descriptors that the
1911 mirrors have probably not yet retrieved and cached.)
1912 - The client does not currently have it.
1913 - The client is not currently trying to download it.
1914 - The client would not discard it immediately upon receiving it.
1915 - The client thinks it is running and valid (see 6.1 below).
1917 If at least 16 known routers have downloadable descriptors, or if
1918 enough time (currently 10 minutes) has passed since the last time the
1919 client tried to download descriptors, it launches requests for all
1920 downloadable descriptors, as described in 5.3 below.
1922 When a descriptor download fails, the client notes it, and does not
1923 consider the descriptor downloadable again until a certain amount of time
1924 has passed. (Currently 0 seconds for the first failure, 60 seconds for the
1925 second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
1926 thereafter.) Periodically (currently once an hour) clients reset the
1927 failure count.
1929 Clients retain the most recent descriptor they have downloaded for each
1930 router so long as it is not too old (currently, 48 hours), OR so long as
1931 no better descriptor has been downloaded for the same router.
1933 [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
1934 being published too far in the past.] [The code seems to discard
1935 descriptors in all cases after they're 5 days old. True? -RD]
1937 5.3. Managing downloads
1939 When a client has no consensus network-status document, it downloads it
1940 from a randomly chosen authority. In all other cases, the client
1941 downloads from caches randomly chosen from among those believed to be V2
1942 directory servers. (This information comes from the network-status
1943 documents; see 6 below.)
1945 When downloading multiple router descriptors, the client chooses multiple
1946 mirrors so that:
1947 - At least 3 different mirrors are used, except when this would result
1948 in more than one request for under 4 descriptors.
1949 - No more than 128 descriptors are requested from a single mirror.
1950 - Otherwise, as few mirrors as possible are used.
1951 After choosing mirrors, the client divides the descriptors among them
1952 randomly.
1954 After receiving any response client MUST discard any network-status
1955 documents and descriptors that it did not request.
1957 6. Using directory information
1959 Everyone besides directory authorities uses the approaches in this section
1960 to decide which servers to use and what their keys are likely to be.
1961 (Directory authorities just believe their own opinions, as in 3.1 above.)
1963 6.1. Choosing routers for circuits.
1965 Circuits SHOULD NOT be built until the client has enough directory
1966 information: a live consensus network status [XXXX fallback?] and
1967 descriptors for at least 1/4 of the servers believed to be running.
1969 A server is "listed" if it is included by the consensus network-status
1970 document. Clients SHOULD NOT use unlisted servers.
1972 These flags are used as follows:
1974 - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
1975 requested to do so.
1977 - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
1978 very-low-bandwidth circuits (such as introduction circuits).
1980 - Clients SHOULD NOT use non-'Stable' routers for circuits that are
1981 likely to need to be open for a very long time (such as those used for
1982 IRC or SSH connections).
1984 - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
1985 nodes.
1987 - Clients SHOULD NOT download directory information from non-'V2Dir'
1988 caches.
1990 See the "path-spec.txt" document for more details.
1992 6.2. Managing naming
1994 In order to provide human-memorable names for individual server
1995 identities, some directory servers bind names to IDs. Clients handle
1996 names in two ways:
1998 When a client encounters a name it has not mapped before:
2000 If the consensus lists any router with that name as "Named", or if
2001 consensus-method 2 or later is in use and the consensus lists any
2002 router with that name as having the "Unnamed" flag, then the name is
2003 bound. (It's bound to the ID listed in the entry with the Named,
2004 or to an unknown ID if no name is found.)
2006 When the user refers to a bound name, the implementation SHOULD provide
2007 only the router with ID bound to that name, and no other router, even
2008 if the router with the right ID can't be found.
2010 When a user tries to refer to a non-bound name, the implementation SHOULD
2011 warn the user. After warning the user, the implementation MAY use any
2012 router that advertises the name.
2014 Not every router needs a nickname. When a router doesn't configure a
2015 nickname, it publishes with the default nickname "Unnamed". Authorities
2016 SHOULD NOT ever mark a router with this nickname as Named; client software
2017 SHOULD NOT ever use a router in response to a user request for a router
2018 called "Unnamed".
2020 6.3. Software versions
2022 An implementation of Tor SHOULD warn when it has fetched a consensus
2023 network-status, and it is running a software version not listed.
2025 6.4. Warning about a router's status.
2027 If a router tries to publish its descriptor to a Naming authority
2028 that has its nickname mapped to another key, the router SHOULD
2029 warn the operator that it is either using the wrong key or is using
2030 an already claimed nickname.
2032 If a router has fetched a consensus document,, and the
2033 authorities do not publish a binding for the router's nickname, the
2034 router MAY remind the operator that the chosen nickname is not
2035 bound to this key at the authorities, and suggest contacting the
2036 authority operators.
2038 ...
2040 6.5. Router protocol versions
2042 A client should believe that a router supports a given feature if that
2043 feature is supported by the router or protocol versions in more than half
2044 of the live networkstatuses' "v" entries for that router. In other words,
2045 if the "v" entries for some router are:
2046 v Tor 0.0.8pre1 (from authority 1)
2047 v Tor 0.1.2.11 (from authority 2)
2048 v FutureProtocolDescription 99 (from authority 3)
2049 then the client should believe that the router supports any feature
2050 supported by 0.1.2.11.
2052 This is currently equivalent to believing the median declared version for
2053 a router in all live networkstatuses.
2055 7. Standards compliance
2057 All clients and servers MUST support HTTP 1.0. Clients and servers MAY
2058 support later versions of HTTP as well.
2060 7.1. HTTP headers
2062 Servers MAY set the Content-Length: header. Servers SHOULD set
2063 Content-Encoding to "deflate" or "identity".
2065 Servers MAY include an X-Your-Address-Is: header, whose value is the
2066 apparent IP address of the client connecting to them (as a dotted quad).
2067 For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
2068 report the IP from which the circuit carrying the BEGIN_DIR stream reached
2069 them. [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
2070 BEGIN_DIR-tunneled connections.]
2072 Servers SHOULD disable caching of multiple network statuses or multiple
2073 router descriptors. Servers MAY enable caching of single descriptors,
2074 single network statuses, the list of all router descriptors, a v1
2075 directory, or a v1 running routers document. XXX mention times.
2077 7.2. HTTP status codes
2079 Tor delivers the following status codes. Some were chosen without much
2080 thought; other code SHOULD NOT rely on specific status codes yet.
2082 200 -- the operation completed successfully
2083 -- the user requested statuses or serverdescs, and none of the ones we
2084 requested were found (0.2.0.4-alpha and earlier).
2086 304 -- the client specified an if-modified-since time, and none of the
2087 requested resources have changed since that time.
2089 400 -- the request is malformed, or
2090 -- the URL is for a malformed variation of one of the URLs we support,
2091 or
2092 -- the client tried to post to a non-authority, or
2093 -- the authority rejected a malformed posted document, or
2095 404 -- the requested document was not found.
2096 -- the user requested statuses or serverdescs, and none of the ones
2097 requested were found (0.2.0.5-alpha and later).
2099 503 -- we are declining the request in order to save bandwidth
2100 -- user requested some items that we ordinarily generate or store,
2101 but we do not have any available.
2103 9. Backward compatibility and migration plans
2105 Until Tor versions before 0.1.1.x are completely obsolete, directory
2106 authorities should generate, and mirrors should download and cache, v1
2107 directories and running-routers lists, and allow old clients to download
2108 them. These documents and the rules for retrieving, serving, and caching
2109 them are described in dir-spec-v1.txt.
2111 Until Tor versions before 0.2.0.x are completely obsolete, directory
2112 authorities should generate, mirrors should download and cache, v2
2113 network-status documents, and allow old clients to download them.
2114 Additionally, all directory servers and caches should download, store, and
2115 serve any router descriptor that is required because of v2 network-status
2116 documents. These documents and the rules for retrieving, serving, and
2117 caching them are described in dir-spec-v1.txt.
2119 A. Consensus-negotiation timeline.
2122 Period begins: this is the Published time.
2123 Everybody sends votes
2124 Reconciliation: everybody tries to fetch missing votes.
2125 consensus may exist at this point.
2126 End of voting period:
2127 everyone swaps signatures.
2128 Now it's okay for caches to download
2129 Now it's okay for clients to download.
2131 Valid-after/valid-until switchover