| blob | c18efcf2b12e1ad9a929650f91adf240c87252d5 |
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.
22 XXX timeline
23 XXX fill in XXXXs
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
28 RFC 2119.
30 0.1. History
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
34 fetch a new list.
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
65 already had.
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
72 more.
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
81 the authorities.
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
87 clients.
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
96 issues:
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
102 fetch or use.
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
112 document.
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
127 concerned.
129 Too many things about the authorities are hardcoded by IP.
131 Perhaps we should start accepting longer identity keys for routers
132 too.
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
139 forever.
142 1. Outline
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
201 main descriptors.
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)
216 More formally:
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.
225 WS = (SP | TAB)+
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
235 described.
237 Other implementations that want to extend Tor's directory format MAY
238 introduce their own items. The keywords for extension items SHOULD start
239 with the characters "x-" or "X-", to guarantee that they will not conflict
240 with keywords used by future versions of Tor.
242 In our document descriptions below, we tag Items with a multiplicity in
243 brackets. Possible tags are:
245 "At start, exactly once": These items MUST occur in every instance of
246 the document type, and MUST appear exactly once, and MUST be the
247 first item in their documents.
249 "Exactly once": These items MUST occur exactly one time in every
250 instance of the document type.
252 "At end, exactly once": These items MUST occur in every instance of
253 the document type, and MUST appear exactly once, and MUST be the
254 last item in their documents.
256 "At most once": These items MAY occur zero or one times in any
257 instance of the document type, but MUST NOT occur more than once.
259 "Any number": These items MAY occur zero, one, or more times in any
260 instance of the document type.
262 "Once or more": These items MUST occur at least once in any instance
263 of the document type, and MAY occur more.
265 1.3. Signing documents
267 Every signable document below is signed in a similar manner, using a
268 given "Initial Item", a final "Signature Item", a digest algorithm, and
269 a signing key.
271 The Initial Item must be the first item in the document.
273 The Signature Item has the following format:
275 <signature item keyword> [arguments] NL SIGNATURE NL
277 The "SIGNATURE" Object contains a signature (using the signing key) of
278 the PKCS1-padded digest of the entire document, taken from the
279 beginning of the Initial item, through the newline after the Signature
280 Item's keyword and its arguments.
282 Unless otherwise, the digest algorithm is SHA-1.
284 All documents are invalid unless signed with the correct signing key.
286 The "Digest" of a document, unless stated otherwise, is its digest *as
287 signed by this signature scheme*.
289 1.4. Voting timeline
291 Every consensus document has a "valid-after" (VA) time, a "fresh-until"
292 (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
293 in turn precede VU. Times are chosen so that every consensus will be
294 "fresh" until the next consensus becomes valid, and "valid" for a while
295 after. At least 3 consensuses should be valid at any given time.
297 The timeline for a given consensus is as follows:
299 VA-DistSeconds-VoteSeconds: The authorities exchange votes.
301 VA-DistSeconds-VoteSeconds/2: The authorities try to download any
302 votes they don't have.
304 VA-DistSeconds: The authorities calculate the consensus and exchange
305 signatures.
307 VA-DistSeconds/2: The authorities try to download any signatures
308 they don't have.
310 VA: All authorities have a multiply signed consensus.
312 VA ... FU: Caches download the consensus. (Note that since caches have
313 no way of telling what VA and FU are until they have downloaded
314 the consensus, they assume that the present consensus's VA is
315 equal to the previous one's FU, and that its FU is one interval after
316 that.)
318 FU: The consensus is no longer the freshest consensus.
320 FU ... (the current consensus's VU): Clients download the consensus.
321 (See note above: clients guess that the next consensus's FU will be
322 two intervals after the current VA.)
324 VU: The consensus is no longer valid.
326 VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
327 VU-FU MUST each be at least 5 minutes.
329 2. Router operation and formats
331 ORs SHOULD generate a new router descriptor and a new extra-info
332 document whenever any of the following events have occurred:
334 - A period of time (18 hrs by default) has passed since the last
335 time a descriptor was generated.
337 - A descriptor field other than bandwidth or uptime has changed.
339 - Bandwidth has changed by a factor of 2 from the last time a
340 descriptor was generated, and at least a given interval of time
341 (20 mins by default) has passed since then.
343 - Its uptime has been reset (by restarting).
345 [XXX this list is incomplete; see router_differences_are_cosmetic()
346 in routerlist.c for others]
348 ORs SHOULD NOT publish a new router descriptor or extra-info document
349 if none of the above events have occurred and not much time has passed
350 (12 hours by default).
352 After generating a descriptor, ORs upload them to every directory
353 authority they know, by posting them (in order) to the URL
355 http://<hostname:port>/tor/
357 2.1. Router descriptor format
359 Router descriptors consist of the following items. For backward
360 compatibility, there should be an extra NL at the end of each router
361 descriptor.
363 In lines that take multiple arguments, extra arguments SHOULD be
364 accepted and ignored. Many of the nonterminals below are defined in
365 section 2.3.
367 "router" nickname address ORPort SOCKSPort DirPort NL
369 [At start, exactly once.]
371 Indicates the beginning of a router descriptor. "nickname" must be a
372 valid router nickname as specified in 2.3. "address" must be an IPv4
373 address in dotted-quad format. The last three numbers indicate the
374 TCP ports at which this OR exposes functionality. ORPort is a port at
375 which this OR accepts TLS connections for the main OR protocol;
376 SOCKSPort is deprecated and should always be 0; and DirPort is the
377 port at which this OR accepts directory-related HTTP connections. If
378 any port is not supported, the value 0 is given instead of a port
379 number. (At least one of DirPort and ORPort SHOULD be set;
380 authorities MAY reject any descriptor with both DirPort and ORPort of
381 0.)
383 "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
385 [Exactly once]
387 Estimated bandwidth for this router, in bytes per second. The
388 "average" bandwidth is the volume per second that the OR is willing to
389 sustain over long periods; the "burst" bandwidth is the volume that
390 the OR is willing to sustain in very short intervals. The "observed"
391 value is an estimate of the capacity this relay can handle. The
392 relay remembers the max bandwidth sustained output over any ten
393 second period in the past day, and another sustained input. The
394 "observed" value is the lesser of these two numbers.
396 "platform" string NL
398 [At most once]
400 A human-readable string describing the system on which this OR is
401 running. This MAY include the operating system, and SHOULD include
402 the name and version of the software implementing the Tor protocol.
404 "published" YYYY-MM-DD HH:MM:SS NL
406 [Exactly once]
408 The time, in GMT, when this descriptor (and its corresponding
409 extra-info document if any) was generated.
411 "fingerprint" fingerprint NL
413 [At most once]
415 A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
416 hex, with a single space after every 4 characters) for this router's
417 identity key. A descriptor is considered invalid (and MUST be
418 rejected) if the fingerprint line does not match the public key.
420 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
421 be marked with "opt" until earlier versions of Tor are obsolete.]
423 "hibernating" bool NL
425 [At most once]
427 If the value is 1, then the Tor relay was hibernating when the
428 descriptor was published, and shouldn't be used to build circuits.
430 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
431 marked with "opt" until earlier versions of Tor are obsolete.]
433 "uptime" number NL
435 [At most once]
437 The number of seconds that this OR process has been running.
439 "onion-key" NL a public key in PEM format
441 [Exactly once]
443 This key is used to encrypt EXTEND cells for this OR. The key MUST be
444 accepted for at least 1 week after any new key is published in a
445 subsequent descriptor. It MUST be 1024 bits.
447 "signing-key" NL a public key in PEM format
449 [Exactly once]
451 The OR's long-term identity key. It MUST be 1024 bits.
453 "accept" exitpattern NL
454 "reject" exitpattern NL
456 [Any number]
458 These lines describe an "exit policy": the rules that an OR follows
459 when deciding whether to allow a new stream to a given address. The
460 'exitpattern' syntax is described below. There MUST be at least one
461 such entry. The rules are considered in order; if no rule matches,
462 the address will be accepted. For clarity, the last such entry SHOULD
463 be accept *:* or reject *:*.
465 "router-signature" NL Signature NL
467 [At end, exactly once]
469 The "SIGNATURE" object contains a signature of the PKCS1-padded
470 hash of the entire router descriptor, taken from the beginning of the
471 "router" line, through the newline after the "router-signature" line.
472 The router descriptor is invalid unless the signature is performed
473 with the router's identity key.
475 "contact" info NL
477 [At most once]
479 Describes a way to contact the relay's administrator, preferably
480 including an email address and a PGP key fingerprint.
482 "family" names NL
484 [At most once]
486 'Names' is a space-separated list of relay nicknames or
487 hexdigests. If two ORs list one another in their "family" entries,
488 then OPs should treat them as a single OR for the purpose of path
489 selection.
491 For example, if node A's descriptor contains "family B", and node B's
492 descriptor contains "family A", then node A and node B should never
493 be used on the same circuit.
495 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
496 [At most once]
497 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
498 [At most once]
500 Declare how much bandwidth the OR has used recently. Usage is divided
501 into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
502 defines the end of the most recent interval. The numbers are the
503 number of bytes used in the most recent intervals, ordered from
504 oldest to newest.
506 [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
507 be marked with "opt" until earlier versions of Tor are obsolete.]
509 [See also migration notes in section 2.2.1.]
511 "eventdns" bool NL
513 [At most once]
515 Declare whether this version of Tor is using the newer enhanced
516 dns logic. Versions of Tor with this field set to false SHOULD NOT
517 be used for reverse hostname lookups.
519 [This option is obsolete. All Tor current relays should be presumed
520 to have the evdns backend.]
522 "caches-extra-info" NL
524 [At most once.]
526 Present only if this router is a directory cache that provides
527 extra-info documents.
529 [Versions before 0.2.0.1-alpha don't recognize this]
531 "extra-info-digest" digest NL
533 [At most once]
535 "Digest" is a hex-encoded digest (using upper-case characters) of the
536 router's extra-info document, as signed in the router's extra-info
537 (that is, not including the signature). (If this field is absent, the
538 router is not uploading a corresponding extra-info document.)
540 [Versions before 0.2.0.1-alpha don't recognize this]
542 "hidden-service-dir" *(SP VersionNum) NL
544 [At most once.]
546 Present only if this router stores and serves hidden service
547 descriptors. If any VersionNum(s) are specified, this router
548 supports those descriptor versions. If none are specified, it
549 defaults to version 2 descriptors.
551 "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
552 CIRCUIT-VERSION-LIST NL
554 [At most once.]
556 Both lists are space-separated sequences of numbers, to indicate which
557 protocols the server supports. As of 30 Mar 2008, specified
558 protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt
559 for more information about link protocol versions.
561 "allow-single-hop-exits" NL
563 [At most once.]
565 Present only if the router allows single-hop circuits to make exit
566 connections. Most Tor relays do not support this: this is
567 included for specialized controllers designed to support perspective
568 access and such.
570 "or-address" SP ADDRESS ":" PORTLIST NL
572 [Any number]
574 ADDRESS = IP6ADDR | IP4ADDR
575 IPV6ADDR = an ipv6 address, surrounded by square brackets.
576 IPV4ADDR = an ipv4 address, represented as a dotted quad.
577 PORTLIST = PORTSPEC | PORTSPEC "," PORTLIST
578 PORTSPEC = PORT
579 PORT = a number between 1 and 65535 inclusive.
581 An alternative for the address and ORPort of the "router" line, but with
582 two added capabilities:
584 * or-address can be either an IPv4 or IPv6 address
585 * or-address allows for multiple ORPorts and addresses
587 A descriptor SHOULD NOT include an or-address line that does nothing but
588 duplicate the address:port pair from its "router" line.
590 The ordering of or-address lines and their PORT entries matter because
591 Tor MAY accept a limited number of addresses or ports. As of Tor 0.2.3.x
592 only the first address and the first port are used.
594 2.2. Extra-info documents
596 Extra-info documents consist of the following items:
598 "extra-info" Nickname Fingerprint NL
599 [At start, exactly once.]
601 Identifies what router this is an extra info descriptor for.
602 Fingerprint is encoded in hex (using upper-case letters), with
603 no spaces.
605 "published" YYYY-MM-DD HH:MM:SS NL
607 [Exactly once.]
609 The time, in GMT, when this document (and its corresponding router
610 descriptor if any) was generated. It MUST match the published time
611 in the corresponding router descriptor.
613 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
614 [At most once.]
615 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
616 [At most once.]
618 As documented in 2.1 above. See migration notes in section 2.2.1.
620 "geoip-db-digest" Digest NL
621 [At most once.]
623 SHA1 digest of the GeoIP database file that is used to resolve IP
624 addresses to country codes.
626 ("geoip-start-time" YYYY-MM-DD HH:MM:SS NL)
627 ("geoip-client-origins" CC=N,CC=N,... NL)
629 Only generated by bridge routers (see blocking.pdf), and only
630 when they have been configured with a geoip database.
631 Non-bridges SHOULD NOT generate these fields. Contains a list
632 of mappings from two-letter country codes (CC) to the number
633 of clients that have connected to that bridge from that
634 country (approximate, and rounded up to the nearest multiple of 8
635 in order to hamper traffic analysis). A country is included
636 only if it has at least one address. The time in
637 "geoip-start-time" is the time at which we began collecting geoip
638 statistics.
640 "geoip-start-time" and "geoip-client-origins" have been replaced by
641 "bridge-stats-end" and "bridge-stats-ips" in 0.2.2.4-alpha. The
642 reason is that the measurement interval with "geoip-stats" as
643 determined by subtracting "geoip-start-time" from "published" could
644 have had a variable length, whereas the measurement interval in
645 0.2.2.4-alpha and later is set to be exactly 24 hours long. In
646 order to clearly distinguish the new measurement intervals from
647 the old ones, the new keywords have been introduced.
649 "bridge-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
650 [At most once.]
652 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
653 interval of length NSEC seconds (86400 seconds by default).
655 A "bridge-stats-end" line, as well as any other "bridge-*" line,
656 is only added when the relay has been running as a bridge for at
657 least 24 hours.
659 "bridge-ips" CC=N,CC=N,... NL
660 [At most once.]
662 List of mappings from two-letter country codes to the number of
663 unique IP addresses that have connected from that country to the
664 bridge and which are no known relays, rounded up to the nearest
665 multiple of 8.
667 "dirreq-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
668 [At most once.]
670 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
671 interval of length NSEC seconds (86400 seconds by default).
673 A "dirreq-stats-end" line, as well as any other "dirreq-*" line,
674 is only added when the relay has opened its Dir port and after 24
675 hours of measuring directory requests.
677 "dirreq-v2-ips" CC=N,CC=N,... NL
678 [At most once.]
679 "dirreq-v3-ips" CC=N,CC=N,... NL
680 [At most once.]
682 List of mappings from two-letter country codes to the number of
683 unique IP addresses that have connected from that country to
684 request a v2/v3 network status, rounded up to the nearest multiple
685 of 8. Only those IP addresses are counted that the directory can
686 answer with a 200 OK status code.
688 "dirreq-v2-reqs" CC=N,CC=N,... NL
689 [At most once.]
690 "dirreq-v3-reqs" CC=N,CC=N,... NL
691 [At most once.]
693 List of mappings from two-letter country codes to the number of
694 requests for v2/v3 network statuses from that country, rounded up
695 to the nearest multiple of 8. Only those requests are counted that
696 the directory can answer with a 200 OK status code.
698 "dirreq-v2-share" num% NL
699 [At most once.]
700 "dirreq-v3-share" num% NL
701 [At most once.]
703 The share of v2/v3 network status requests that the directory
704 expects to receive from clients based on its advertised bandwidth
705 compared to the overall network bandwidth capacity. Shares are
706 formatted in percent with two decimal places. Shares are
707 calculated as means over the whole 24-hour interval.
709 "dirreq-v2-resp" status=num,... NL
710 [At most once.]
711 "dirreq-v3-resp" status=nul,... NL
712 [At most once.]
714 List of mappings from response statuses to the number of requests
715 for v2/v3 network statuses that were answered with that response
716 status, rounded up to the nearest multiple of 4. Only response
717 statuses with at least 1 response are reported. New response
718 statuses can be added at any time. The current list of response
719 statuses is as follows:
721 "ok": a network status request is answered; this number
722 corresponds to the sum of all requests as reported in
723 "dirreq-v2-reqs" or "dirreq-v3-reqs", respectively, before
724 rounding up.
725 "not-enough-sigs: a version 3 network status is not signed by a
726 sufficient number of requested authorities.
727 "unavailable": a requested network status object is unavailable.
728 "not-found": a requested network status is not found.
729 "not-modified": a network status has not been modified since the
730 If-Modified-Since time that is included in the request.
731 "busy": the directory is busy.
733 "dirreq-v2-direct-dl" key=val,... NL
734 [At most once.]
735 "dirreq-v3-direct-dl" key=val,... NL
736 [At most once.]
737 "dirreq-v2-tunneled-dl" key=val,... NL
738 [At most once.]
739 "dirreq-v3-tunneled-dl" key=val,... NL
740 [At most once.]
742 List of statistics about possible failures in the download process
743 of v2/v3 network statuses. Requests are either "direct"
744 HTTP-encoded requests over the relay's directory port, or
745 "tunneled" requests using a BEGIN_DIR cell over the relay's OR
746 port. The list of possible statistics can change, and statistics
747 can be left out from reporting. The current list of statistics is
748 as follows:
750 Successful downloads and failures:
752 "complete": a client has finished the download successfully.
753 "timeout": a download did not finish within 10 minutes after
754 starting to send the response.
755 "running": a download is still running at the end of the
756 measurement period for less than 10 minutes after starting to
757 send the response.
759 Download times:
761 "min", "max": smallest and largest measured bandwidth in B/s.
762 "d[1-4,6-9]": 1st to 4th and 6th to 9th decile of measured
763 bandwidth in B/s. For a given decile i, i/10 of all downloads
764 had a smaller bandwidth than di, and (10-i)/10 of all downloads
765 had a larger bandwidth than di.
766 "q[1,3]": 1st and 3rd quartile of measured bandwidth in B/s. One
767 fourth of all downloads had a smaller bandwidth than q1, one
768 fourth of all downloads had a larger bandwidth than q3, and the
769 remaining half of all downloads had a bandwidth between q1 and
770 q3.
771 "md": median of measured bandwidth in B/s. Half of the downloads
772 had a smaller bandwidth than md, the other half had a larger
773 bandwidth than md.
775 "dirreq-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
776 [At most once]
777 "dirreq-write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
778 [At most once]
780 Declare how much bandwidth the OR has spent on answering directory
781 requests. Usage is divided into intervals of NSEC seconds. The
782 YYYY-MM-DD HH:MM:SS field defines the end of the most recent
783 interval. The numbers are the number of bytes used in the most
784 recent intervals, ordered from oldest to newest.
786 "entry-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
787 [At most once.]
789 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
790 interval of length NSEC seconds (86400 seconds by default).
792 An "entry-stats-end" line, as well as any other "entry-*"
793 line, is first added after the relay has been running for at least
794 24 hours.
796 "entry-ips" CC=N,CC=N,... NL
797 [At most once.]
799 List of mappings from two-letter country codes to the number of
800 unique IP addresses that have connected from that country to the
801 relay and which are no known other relays, rounded up to the
802 nearest multiple of 8.
804 "cell-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
805 [At most once.]
807 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
808 interval of length NSEC seconds (86400 seconds by default).
810 A "cell-stats-end" line, as well as any other "cell-*" line,
811 is first added after the relay has been running for at least 24
812 hours.
814 "cell-processed-cells" num,...,num NL
815 [At most once.]
817 Mean number of processed cells per circuit, subdivided into
818 deciles of circuits by the number of cells they have processed in
819 descending order from loudest to quietest circuits.
821 "cell-queued-cells" num,...,num NL
822 [At most once.]
824 Mean number of cells contained in queues by circuit decile. These
825 means are calculated by 1) determining the mean number of cells in
826 a single circuit between its creation and its termination and 2)
827 calculating the mean for all circuits in a given decile as
828 determined in "cell-processed-cells". Numbers have a precision of
829 two decimal places.
831 "cell-time-in-queue" num,...,num NL
832 [At most once.]
834 Mean time cells spend in circuit queues in milliseconds. Times are
835 calculated by 1) determining the mean time cells spend in the
836 queue of a single circuit and 2) calculating the mean for all
837 circuits in a given decile as determined in
838 "cell-processed-cells".
840 "cell-circuits-per-decile" num NL
841 [At most once.]
843 Mean number of circuits that are included in any of the deciles,
844 rounded up to the next integer.
846 "conn-bi-direct" YYYY-MM-DD HH:MM:SS (NSEC s) BELOW,READ,WRITE,BOTH NL
847 [At most once]
849 Number of connections, split into 10-second intervals, that are
850 used uni-directionally or bi-directionally as observed in the NSEC
851 seconds (usually 86400 seconds) before YYYY-MM-DD HH:MM:SS. Every
852 10 seconds, we determine for every connection whether we read and
853 wrote less than a threshold of 20 KiB (BELOW), read at least 10
854 times more than we wrote (READ), wrote at least 10 times more than
855 we read (WRITE), or read and wrote more than the threshold, but
856 not 10 times more in either direction (BOTH). After classifying a
857 connection, read and write counters are reset for the next
858 10-second interval.
860 "exit-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
861 [At most once.]
863 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
864 interval of length NSEC seconds (86400 seconds by default).
866 An "exit-stats-end" line, as well as any other "exit-*" line, is
867 first added after the relay has been running for at least 24 hours
868 and only if the relay permits exiting (where exiting to a single
869 port and IP address is sufficient).
871 "exit-kibibytes-written" port=N,port=N,... NL
872 [At most once.]
873 "exit-kibibytes-read" port=N,port=N,... NL
874 [At most once.]
876 List of mappings from ports to the number of kibibytes that the
877 relay has written to or read from exit connections to that port,
878 rounded up to the next full kibibyte. Relays may limit the
879 number of listed ports and subsume any remaining kibibytes under
880 port "other".
882 "exit-streams-opened" port=N,port=N,... NL
883 [At most once.]
885 List of mappings from ports to the number of opened exit streams
886 to that port, rounded up to the nearest multiple of 4. Relays may
887 limit the number of listed ports and subsume any remaining opened
888 streams under port "other".
890 "transport" transportname address:port [arglist] NL
891 [Any number.]
893 Signals that the router supports the 'transportname' pluggable
894 transport in IP address 'address' and TCP port 'port'. A single
895 descriptor MUST not have more than one transport line with the
896 same 'transportname'.
898 Pluggable transports are only relevant to bridges, but these entries
899 can appear in non-bridge relays as well.
901 "router-signature" NL Signature NL
902 [At end, exactly once.]
904 A document signature as documented in section 1.3, using the
905 initial item "extra-info" and the final item "router-signature",
906 signed with the router's identity key.
908 2.2.1. Moving history fields to extra-info documents.
910 Tools that want to use the read-history and write-history values SHOULD
911 download extra-info documents as well as router descriptors. Such
912 tools SHOULD accept history values from both sources; if they appear in
913 both documents, the values in the extra-info documents are authoritative.
915 New versions of Tor no longer generate router descriptors
916 containing read-history or write-history. Tools should continue to
917 accept read-history and write-history values in router descriptors
918 produced by older versions of Tor until all Tor versions earlier
919 than 0.2.0.x are obsolete.
921 2.3. Nonterminals in router descriptors
923 nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
924 case-insensitive.
925 hexdigest ::= a '$', followed by 40 hexadecimal characters
926 ([A-Fa-f0-9]). [Represents a relay by the digest of its identity
927 key.]
929 exitpattern ::= addrspec ":" portspec
930 portspec ::= "*" | port | port "-" port
931 port ::= an integer between 1 and 65535, inclusive.
933 [Some implementations incorrectly generate ports with value 0.
934 Implementations SHOULD accept this, and SHOULD NOT generate it.
935 Connections to port 0 are never permitted.]
937 addrspec ::= "*" | ip4spec | ip6spec
938 ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
939 ip4 ::= an IPv4 address in dotted-quad format
940 ip4mask ::= an IPv4 mask in dotted-quad format
941 num_ip4_bits ::= an integer between 0 and 32
942 ip6spec ::= ip6 | ip6 "/" num_ip6_bits
943 ip6 ::= an IPv6 address, surrounded by square brackets.
944 num_ip6_bits ::= an integer between 0 and 128
946 bool ::= "0" | "1"
948 3. Formats produced by directory authorities.
950 Every authority has two keys used in this protocol: a signing key, and
951 an authority identity key. (Authorities also have a router identity
952 key used in their role as a router and by earlier versions of the
953 directory protocol.) The identity key is used from time to time to
954 sign new key certificates using new signing keys; it is very sensitive.
955 The signing key is used to sign key certificates and status documents.
957 There are three kinds of documents generated by directory authorities:
959 Key certificates
960 Status votes
961 Status consensuses
963 Each is discussed below.
965 3.1. Key certificates
967 Key certificates consist of the following items:
969 "dir-key-certificate-version" version NL
971 [At start, exactly once.]
973 Determines the version of the key certificate. MUST be "3" for
974 the protocol described in this document. Implementations MUST
975 reject formats they don't understand.
977 "dir-address" IPPort NL
978 [At most once]
980 An IP:Port for this authority's directory port.
982 "fingerprint" fingerprint NL
984 [Exactly once.]
986 Hexadecimal encoding without spaces based on the authority's
987 identity key.
989 "dir-identity-key" NL a public key in PEM format
991 [Exactly once.]
993 The long-term authority identity key for this authority. This key
994 SHOULD be at least 2048 bits long; it MUST NOT be shorter than
995 1024 bits.
997 "dir-key-published" YYYY-MM-DD HH:MM:SS NL
999 [Exactly once.]
1001 The time (in GMT) when this document and corresponding key were
1002 last generated.
1004 "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
1006 [Exactly once.]
1008 A time (in GMT) after which this key is no longer valid.
1010 "dir-signing-key" NL a key in PEM format
1012 [Exactly once.]
1014 The directory server's public signing key. This key MUST be at
1015 least 1024 bits, and MAY be longer.
1017 "dir-key-crosscert" NL CrossSignature NL
1019 [At most once.]
1021 NOTE: Authorities MUST include this field in all newly generated
1022 certificates. A future version of this specification will make
1023 the field required.
1025 CrossSignature is a signature, made using the certificate's signing
1026 key, of the digest of the PKCS1-padded hash of the certificate's
1027 identity key. For backward compatibility with broken versions of the
1028 parser, we wrap the base64-encoded signature in -----BEGIN ID
1029 SIGNATURE---- and -----END ID SIGNATURE----- tags. Implementations
1030 MUST allow the "ID " portion to be omitted, however.
1032 When encountering a certificate with a dir-key-crosscert entry,
1033 implementations MUST verify that the signature is a correct signature
1034 of the hash of the identity key using the signing key.
1036 "dir-key-certification" NL Signature NL
1038 [At end, exactly once.]
1040 A document signature as documented in section 1.3, using the
1041 initial item "dir-key-certificate-version" and the final item
1042 "dir-key-certification", signed with the authority identity key.
1044 Authorities MUST generate a new signing key and corresponding
1045 certificate before the key expires.
1047 3.2. Microdescriptors
1049 Microdescriptors are a stripped-down version of router descriptors
1050 generated by the directory authorities which may additionally contain
1051 authority-generated information. Microdescriptors contain only the
1052 most relevant parts that clients care about. Microdescriptors are
1053 expected to be relatively static and only change about once per week.
1054 Microdescriptors do not contain any information that clients need to
1055 use to decide which servers to fetch information about, or which
1056 servers to fetch information from.
1058 Microdescriptors are a straight transform from the router descriptor
1059 and the consensus method. Microdescriptors have no header or footer.
1060 Microdescriptors are identified by the hash of its concatenated
1061 elements without a signature by the router. Microdescriptors do not
1062 contain any version information, because their version is determined
1063 by the consensus method.
1065 3.2.1. Microdescriptors in consensus method 8 or later
1067 Starting with consensus method 8, microdescriptors contain the
1068 following elements taken from or based on the router descriptor. Order
1069 matters here, because different directory authorities must be able to
1070 transform a given router descriptor and consensus method into the exact
1071 same microdescriptor.
1073 "onion-key" NL a public key in PEM format
1075 [Exactly once, at start]
1077 The "onion-key" element as specified in 2.1.
1079 "family" names NL
1081 [At most once]
1083 The "family" element as specified in 2.1.
1085 "p" SP ("accept" / "reject") SP PortList NL
1087 [At most once]
1089 The exit-policy summary as specified in 3.3 and 3.5.2. A missing
1090 "p" line is equivalent to "p reject 1-65535".
1092 [With microdescriptors, clients don't learn exact exit policies:
1093 clients can only guess whether a relay accepts their request, try the
1094 BEGIN request, and might get end-reason-exit-policy if they guessed
1095 wrong, in which case they'll have to try elsewhere.]
1097 (Note that with microdescriptors, clients do not learn the identity of
1098 their routers: they only learn a hash of the identity key. This is all
1099 they need to confirm the actual identity key when doing a TLS handshake,
1100 and all they need to put the identity key digest in their cREATE cells.)
1102 3.3. Vote and consensus status documents
1104 Votes and consensuses are more strictly formatted then other documents
1105 in this specification, since different authorities must be able to
1106 generate exactly the same consensus given the same set of votes.
1108 The procedure for deciding when to generate vote and consensus status
1109 documents are described in section 1.4 on the voting timeline.
1111 Status documents contain a preamble, an authority section, a list of
1112 router status entries, and one or more footer signature, in that order.
1114 Unlike other formats described above, a SP in these documents must be a
1115 single space character (hex 20).
1117 Some items appear only in votes, and some items appear only in
1118 consensuses. Unless specified, items occur in both.
1120 The preamble contains the following items. They MUST occur in the
1121 order given here:
1123 "network-status-version" SP version NL.
1125 [At start, exactly once.]
1127 A document format version. For this specification, the version is
1128 "3".
1130 "vote-status" SP type NL
1132 [Exactly once.]
1134 The status MUST be "vote" or "consensus", depending on the type of
1135 the document.
1137 "consensus-methods" SP IntegerList NL
1139 [At most once for votes; does not occur in consensuses.]
1141 A space-separated list of supported methods for generating
1142 consensuses from votes. See section 3.5.1 for details. Method "1"
1143 MUST be included.
1145 "consensus-method" SP Integer NL
1147 [At most once for consensuses; does not occur in votes.]
1149 See section 3.5.1 for details.
1151 (Only included when the vote is generated with consensus-method 2 or
1152 later.)
1154 "published" SP YYYY-MM-DD SP HH:MM:SS NL
1156 [Exactly once for votes; does not occur in consensuses.]
1158 The publication time for this status document (if a vote).
1160 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1162 [Exactly once.]
1164 The start of the Interval for this vote. Before this time, the
1165 consensus document produced from this vote should not be used.
1166 See 1.4 for voting timeline information.
1168 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1170 [Exactly once.]
1172 The time at which the next consensus should be produced; before this
1173 time, there is no point in downloading another consensus, since there
1174 won't be a new one. See 1.4 for voting timeline information.
1176 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1178 [Exactly once.]
1180 The end of the Interval for this vote. After this time, the
1181 consensus produced by this vote should not be used. See 1.4 for
1182 voting timeline information.
1184 "voting-delay" SP VoteSeconds SP DistSeconds NL
1186 [Exactly once.]
1188 VoteSeconds is the number of seconds that we will allow to collect
1189 votes from all authorities; DistSeconds is the number of seconds
1190 we'll allow to collect signatures from all authorities. See 1.4 for
1191 voting timeline information.
1193 "client-versions" SP VersionList NL
1195 [At most once.]
1197 A comma-separated list of recommended Tor versions for client
1198 usage, in ascending order. The versions are given as defined by
1199 version-spec.txt. If absent, no opinion is held about client
1200 versions.
1202 "server-versions" SP VersionList NL
1204 [At most once.]
1206 A comma-separated list of recommended Tor versions for relay
1207 usage, in ascending order. The versions are given as defined by
1208 version-spec.txt. If absent, no opinion is held about server
1209 versions.
1211 "known-flags" SP FlagList NL
1213 [Exactly once.]
1215 A space-separated list of all of the flags that this document
1216 might contain. A flag is "known" either because the authority
1217 knows about them and might set them (if in a vote), or because
1218 enough votes were counted for the consensus for an authoritative
1219 opinion to have been formed about their status.
1221 "params" SP [Parameters] NL
1223 [At most once]
1225 Parameter ::= Keyword '=' Int32
1226 Int32 ::= A decimal integer between -2147483648 and 2147483647.
1227 Parameters ::= Parameter | Parameters SP Parameter
1229 The parameters list, if present, contains a space-separated list of
1230 case-sensitive key-value pairs, sorted in lexical order by their
1231 keyword (as ASCII byte strings). Each parameter has its own meaning.
1233 (Only included when the vote is generated with consensus-method 7 or
1234 later.)
1236 Commonly used "param" arguments at this point include:
1238 "circwindow" -- the default package window that circuits should
1239 be established with. It started out at 1000 cells, but some
1240 research indicates that a lower value would mean fewer cells in
1241 transit in the network at any given time. Obeyed by Tor 0.2.1.20
1242 and later.
1243 Min: 100, Max: 1000
1245 "CircuitPriorityHalflifeMsec" -- the halflife parameter used when
1246 weighting which circuit will send the next cell. Obeyed by Tor
1247 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha
1248 and 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter,
1249 but mishandled it badly.)
1250 Min: -1, Max: 2147483647 (INT32_MAX)
1252 "perconnbwrate" and "perconnbwburst" -- if set, each relay sets
1253 up a separate token bucket for every client OR connection,
1254 and rate limits that connection indepedently. Typically left
1255 unset, except when used for performance experiments around trac
1256 entry 1750. Only honored by relays running Tor 0.2.2.16-alpha
1257 and later. (Note that relays running 0.2.2.7-alpha through
1258 0.2.2.14-alpha looked for bwconnrate and bwconnburst, but then
1259 did the wrong thing with them; see bug 1830 for details.)
1260 Min: 1, Max: 2147483647 (INT32_MAX)
1262 "refuseunknownexits" -- if set to one, exit relays look at
1263 the previous hop of circuits that ask to open an exit stream,
1264 and refuse to exit if they don't recognize it as a relay. The
1265 goal is to make it harder for people to use them as one-hop
1266 proxies. See trac entry 1751 for details.
1267 Min: 0, Max: 1
1269 "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts",
1270 "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq",
1271 "cbtmintimeout", and "cbtinitialtimeout" -- see "2.4.5. Consensus
1272 parameters governing behavior" in path-spec.txt for a series of
1273 circuit build time related consensus params.
1275 "UseOptimisticData" -- If set to zero, clients by default
1276 shouldn't try to send optimistic data to servers until they have
1277 received a RELAY_CONNECTED cell.
1278 Min: 0, Max: 1
1280 The authority section of a vote contains the following items, followed
1281 in turn by the authority's current key certificate:
1283 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
1284 orport NL
1286 [Exactly once, at start]
1288 Describes this authority. The nickname is a convenient identifier
1289 for the authority. The identity is an uppercase hex fingerprint of
1290 the authority's current (v3 authority) identity key. The address is
1291 the server's hostname. The IP is the server's current IP address,
1292 and dirport is its current directory port. XXXXorport
1294 "contact" SP string NL
1296 [Exactly once.]
1298 An arbitrary string describing how to contact the directory
1299 server's administrator. Administrators should include at least an
1300 email address and a PGP fingerprint.
1302 "legacy-dir-key" SP FINGERPRINT NL
1304 [At most once]
1306 Lists a fingerprint for an obsolete _identity_ key still used
1307 by this authority to keep older clients working. This option
1308 is used to keep key around for a little while in case the
1309 authorities need to migrate many identity keys at once.
1310 (Generally, this would only happen because of a security
1311 vulnerability that affected multiple authorities, like the
1312 Debian OpenSSL RNG bug of May 2008.)
1314 The authority section of a consensus contains groups the following items,
1315 in the order given, with one group for each authority that contributed to
1316 the consensus, with groups sorted by authority identity digest:
1318 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
1319 orport NL
1321 [Exactly once, at start]
1323 As in the authority section of a vote.
1325 "contact" SP string NL
1327 [Exactly once.]
1329 As in the authority section of a vote.
1331 "vote-digest" SP digest NL
1333 [Exactly once.]
1335 A digest of the vote from the authority that contributed to this
1336 consensus, as signed (that is, not including the signature).
1337 (Hex, upper-case.)
1339 Each router status entry contains the following items. Router status
1340 entries are sorted in ascending order by identity digest.
1342 "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
1343 SP DirPort NL
1345 [At start, exactly once.]
1347 "Nickname" is the OR's nickname. "Identity" is a hash of its
1348 identity key, encoded in base64, with trailing equals sign(s)
1349 removed. "Digest" is a hash of its most recent descriptor as
1350 signed (that is, not including the signature), encoded in base64.
1351 "Publication" is the
1352 publication time of its most recent descriptor, in the form
1353 YYYY-MM-DD HH:MM:SS, in GMT. "IP" is its current IP address;
1354 ORPort is its current OR port, "DirPort" is its current directory
1355 port, or "0" for "none".
1357 "s" SP Flags NL
1359 [Exactly once.]
1361 A series of space-separated status flags, in lexical order (as ASCII
1362 byte strings). Currently documented flags are:
1364 "Authority" if the router is a directory authority.
1365 "BadExit" if the router is believed to be useless as an exit node
1366 (because its ISP censors it, because it is behind a restrictive
1367 proxy, or for some similar reason).
1368 "BadDirectory" if the router is believed to be useless as a
1369 directory cache (because its directory port isn't working,
1370 its bandwidth is always throttled, or for some similar
1371 reason).
1372 "Exit" if the router is more useful for building
1373 general-purpose exit circuits than for relay circuits. The
1374 path building algorithm uses this flag; see path-spec.txt.
1375 "Fast" if the router is suitable for high-bandwidth circuits.
1376 "Guard" if the router is suitable for use as an entry guard.
1377 "HSDir" if the router is considered a v2 hidden service directory.
1378 "Named" if the router's identity-nickname mapping is canonical,
1379 and this authority binds names.
1380 "Stable" if the router is suitable for long-lived circuits.
1381 "Running" if the router is currently usable.
1382 "Unnamed" if another router has bound the name used by this
1383 router, and this authority binds names.
1384 "Valid" if the router has been 'validated'.
1385 "V2Dir" if the router implements the v2 directory protocol.
1386 "V3Dir" if the router implements this protocol.
1388 "v" SP version NL
1390 [At most once.]
1392 The version of the Tor protocol that this relay is running. If
1393 the value begins with "Tor" SP, the rest of the string is a Tor
1394 version number, and the protocol is "The Tor protocol as supported
1395 by the given version of Tor." Otherwise, if the value begins with
1396 some other string, Tor has upgraded to a more sophisticated
1397 protocol versioning system, and the protocol is "a version of the
1398 Tor protocol more recent than any we recognize."
1400 Directory authorities SHOULD omit version strings they receive from
1401 descriptors if they would cause "v" lines to be over 128 characters
1402 long.
1404 "w" SP "Bandwidth=" INT [SP "Measured=" INT] NL
1406 [At most once.]
1408 An estimate of the bandwidth of this relay, in an arbitrary
1409 unit (currently kilobytes per second). Used to weight router
1410 selection.
1412 Additionally, the Measured= keyword is present in votes by
1413 participating bandwidth measurement authorities to indicate
1414 a measured bandwidth currently produced by measuring stream
1415 capacities.
1417 Other weighting keywords may be added later.
1418 Clients MUST ignore keywords they do not recognize.
1420 "p" SP ("accept" / "reject") SP PortList NL
1422 [At most once.]
1424 PortList = PortOrRange
1425 PortList = PortList "," PortOrRange
1426 PortOrRange = INT "-" INT / INT
1428 A list of those ports that this router supports (if 'accept')
1429 or does not support (if 'reject') for exit to "most
1430 addresses".
1432 "m" SP methods 1*(SP algorithm "=" digest) NL
1434 [Any number, only in votes.]
1436 Microdescriptor hashes for all consensus methods that an authority
1437 supports and that use the same microdescriptor format. "methods"
1438 is a comma-separated list of the consensus methods that the
1439 authority believes will produce "digest". "algorithm" is the name
1440 of the hash algorithm producing "digest", which can be "sha256" or
1441 something else, depending on the consensus "methods" supporting
1442 this algorithm. "digest" is the base64 encoding of the hash of
1443 the router's microdescriptor with trailing =s omitted.
1445 The footer section is delineated in all votes and consensuses supporting
1446 consensus method 9 and above with the following:
1448 "directory-footer" NL
1450 It contains two subsections, a bandwidths-weights line and a
1451 directory-signature.
1453 The bandwidths-weights line appears At Most Once for a consensus. It does
1454 not appear in votes.
1456 "bandwidth-weights" SP
1457 "Wbd=" INT SP "Wbe=" INT SP "Wbg=" INT SP "Wbm=" INT SP
1458 "Wdb=" INT SP
1459 "Web=" INT SP "Wed=" INT SP "Wee=" INT SP "Weg=" INT SP "Wem=" INT SP
1460 "Wgb=" INT SP "Wgd=" INT SP "Wgg=" INT SP "Wgm=" INT SP
1461 "Wmb=" INT SP "Wmd=" INT SP "Wme=" INT SP "Wmg=" INT SP "Wmm=" INT NL
1463 These values represent the weights to apply to router bandwidths
1464 during path selection. They are sorted in lexical order (as ASCII byte
1465 strings). The integer values are divided by BW_WEIGHT_SCALE=10000 or
1466 the consensus param "bwweightscale". They are:
1468 Wgg - Weight for Guard-flagged nodes in the guard position
1469 Wgm - Weight for non-flagged nodes in the guard Position
1470 Wgd - Weight for Guard+Exit-flagged nodes in the guard Position
1472 Wmg - Weight for Guard-flagged nodes in the middle Position
1473 Wmm - Weight for non-flagged nodes in the middle Position
1474 Wme - Weight for Exit-flagged nodes in the middle Position
1475 Wmd - Weight for Guard+Exit flagged nodes in the middle Position
1477 Weg - Weight for Guard flagged nodes in the exit Position
1478 Wem - Weight for non-flagged nodes in the exit Position
1479 Wee - Weight for Exit-flagged nodes in the exit Position
1480 Wed - Weight for Guard+Exit-flagged nodes in the exit Position
1482 Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
1483 Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
1484 Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
1485 Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes
1487 Wbg - Weight for Guard flagged nodes for BEGIN_DIR requests
1488 Wbm - Weight for non-flagged nodes for BEGIN_DIR requests
1489 Wbe - Weight for Exit-flagged nodes for BEGIN_DIR requests
1490 Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
1492 These values are calculated as specified in Section 3.5.3.
1494 The signature contains the following item, which appears Exactly Once
1495 for a vote, and At Least Once for a consensus.
1497 "directory-signature" SP identity SP signing-key-digest NL Signature
1499 This is a signature of the status document, with the initial item
1500 "network-status-version", and the signature item
1501 "directory-signature", using the signing key. (In this case, we take
1502 the hash through the _space_ after directory-signature, not the
1503 newline: this ensures that all authorities sign the same thing.)
1504 "identity" is the hex-encoded digest of the authority identity key of
1505 the signing authority, and "signing-key-digest" is the hex-encoded
1506 digest of the current authority signing key of the signing authority.
1508 3.4. Assigning flags in a vote
1510 (This section describes how directory authorities choose which status
1511 flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
1512 authorities MAY do things differently, so long as clients keep working
1513 well. Clients MUST NOT depend on the exact behaviors in this section.)
1515 In the below definitions, a router is considered "active" if it is
1516 running, valid, and not hibernating.
1518 "Valid" -- a router is 'Valid' if it is running a version of Tor not
1519 known to be broken, and the directory authority has not blacklisted
1520 it as suspicious.
1522 "Named" -- Directory authority administrators may decide to support name
1523 binding. If they do, then they must maintain a file of
1524 nickname-to-identity-key mappings, and try to keep this file consistent
1525 with other directory authorities. If they don't, they act as clients, and
1526 report bindings made by other directory authorities (name X is bound to
1527 identity Y if at least one binding directory lists it, and no directory
1528 binds X to some other Y'.) A router is called 'Named' if the router
1529 believes the given name should be bound to the given key.
1531 Two strategies exist on the current network for deciding on
1532 values for the Named flag. In the original version, relay
1533 operators were asked to send nickname-identity pairs to a
1534 mailing list of Naming directory authorities' operators. The
1535 operators were then supposed to add the pairs to their
1536 mapping files; in practice, they didn't get to this often.
1538 Newer Naming authorities run a script that registers routers
1539 in their mapping files once the routers have been online at
1540 least two weeks, no other router has that nickname, and no
1541 other router has wanted the nickname for a month. If a router
1542 has not been online for six months, the router is removed.
1544 "Unnamed" -- Directory authorities that support naming should vote for a
1545 router to be 'Unnamed' if its given nickname is mapped to a different
1546 identity.
1548 "Running" -- A router is 'Running' if the authority managed to connect to
1549 it successfully within the last 45 minutes.
1551 "Stable" -- A router is 'Stable' if it is active, and either its Weighted
1552 MTBF is at least the median for known active routers or its Weighted MTBF
1553 corresponds to at least 7 days. Routers are never called Stable if they are
1554 running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
1555 through 0.1.1.16-rc are stupid this way.)
1557 To calculate weighted MTBF, compute the weighted mean of the lengths
1558 of all intervals when the router was observed to be up, weighting
1559 intervals by $\alpha^n$, where $n$ is the amount of time that has
1560 passed since the interval ended, and $\alpha$ is chosen so that
1561 measurements over approximately one month old no longer influence the
1562 weighted MTBF much.
1564 [XXXX what happens when we have less than 4 days of MTBF info.]
1566 "Exit" -- A router is called an 'Exit' iff it allows exits to at
1567 least two of the ports 80, 443, and 6667 and allows exits to at
1568 least one /8 address space.
1570 "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
1571 either in the top 7/8ths for known active routers or at least some
1572 minimum (20KB/s until 0.2.3.7-alpha, and 100KB/s after that).
1574 "Guard" -- A router is a possible 'Guard' if its Weighted Fractional
1575 Uptime is at least the median for "familiar" active routers, and if
1576 its bandwidth is at least median or at least 250KB/s.
1578 To calculate weighted fractional uptime, compute the fraction
1579 of time that the router is up in any given day, weighting so that
1580 downtime and uptime in the past counts less.
1582 A node is 'familiar' if 1/8 of all active nodes have appeared more
1583 recently than it, OR it has been around for a few weeks.
1585 "Authority" -- A router is called an 'Authority' if the authority
1586 generating the network-status document believes it is an authority.
1588 "V2Dir" -- A router supports the v2 directory protocol if it has an open
1589 directory port, and it is running a version of the directory protocol that
1590 supports the functionality clients need. (Currently, this is
1591 0.1.1.9-alpha or later.)
1593 "V3Dir" -- A router supports the v3 directory protocol if it has an open
1594 directory port, and it is running a version of the directory protocol that
1595 supports the functionality clients need. (Currently, this is
1596 0.2.0.?????-alpha or later.)
1598 "HSDir" -- A router is a v2 hidden service directory if it stores and
1599 serves v2 hidden service descriptors and the authority managed to connect
1600 to it successfully within the last 24 hours.
1602 Directory server administrators may label some relays or IPs as
1603 blacklisted, and elect not to include them in their network-status lists.
1605 Authorities SHOULD 'disable' any relays in excess of 3 on any single IP.
1606 When there are more than 3 to choose from, authorities should first prefer
1607 authorities to non-authorities, then prefer Running to non-Running, and
1608 then prefer high-bandwidth to low-bandwidth. To 'disable' a relay, the
1609 authority *should* advertise it without the Running or Valid flag.
1611 Thus, the network-status vote includes all non-blacklisted,
1612 non-expired, non-superseded descriptors.
1614 The bandwidth in a "w" line should be taken as the best estimate
1615 of the router's actual capacity that the authority has. For now,
1616 this should be the lesser of the observed bandwidth and bandwidth
1617 rate limit from the router descriptor. It is given in kilobytes
1618 per second, and capped at some arbitrary value (currently 10 MB/s).
1620 The Measured= keyword on a "w" line vote is currently computed
1621 by multiplying the previous published consensus bandwidth by the
1622 ratio of the measured average node stream capacity to the network
1623 average. If 3 or more authorities provide a Measured= keyword for
1624 a router, the authorities produce a consensus containing a "w"
1625 Bandwidth= keyword equal to the median of the Measured= votes.
1627 The ports listed in a "p" line should be taken as those ports for
1628 which the router's exit policy permits 'most' addresses, ignoring any
1629 accept not for all addresses, ignoring all rejects for private
1630 netblocks. "Most" addresses are permitted if no more than 2^25
1631 IPv4 addresses (two /8 networks) were blocked. The list is encoded
1632 as described in 3.5.2.
1634 3.5. Computing a consensus from a set of votes
1636 Given a set of votes, authorities compute the contents of the consensus
1637 document as follows:
1639 The "valid-after", "valid-until", and "fresh-until" times are taken as
1640 the median of the respective values from all the votes.
1642 The times in the "voting-delay" line are taken as the median of the
1643 VoteSeconds and DistSeconds times in the votes.
1645 Known-flags is the union of all flags known by any voter.
1647 Entries are given on the "params" line for every keyword on which a
1648 majority of authorities (total authorities, not just those
1649 participating in this vote) voted on, or if at least three
1650 authorities voted for that parameter. The values given are the
1651 low-median of all votes on that keyword.
1653 Consensus methods 11 and before, entries are given on the "params"
1654 line for every keyword on which any authority voted, the value given
1655 being the low-median of all votes on that keyword.
1657 "client-versions" and "server-versions" are sorted in ascending
1658 order; A version is recommended in the consensus if it is recommended
1659 by more than half of the voting authorities that included a
1660 client-versions or server-versions lines in their votes.
1662 The authority item groups (dir-source, contact, fingerprint,
1663 vote-digest) are taken from the votes of the voting
1664 authorities. These groups are sorted by the digests of the
1665 authorities identity keys, in ascending order. If the consensus
1666 method is 3 or later, a dir-source line must be included for
1667 every vote with legacy-key entry, using the legacy-key's
1668 fingerprint, the voter's ordinary nickname with the string
1669 "-legacy" appended, and all other fields as from the original
1670 vote's dir-source line.
1672 A router status entry:
1673 * is included in the result if some router status entry with the same
1674 identity is included by more than half of the authorities (total
1675 authorities, not just those whose votes we have).
1677 * For any given identity, we include at most one router status entry.
1679 * A router entry has a flag set if that is included by more than half
1680 of the authorities who care about that flag.
1682 * Two router entries are "the same" if they have the same
1683 <descriptor digest, published time, nickname, IP, ports> tuple.
1684 We choose the tuple for a given router as whichever tuple appears
1685 for that router in the most votes. We break ties first in favor of
1686 the more recently published, then in favor of smaller server
1687 descriptor digest.
1689 * The Named flag appears if it is included for this routerstatus by
1690 _any_ authority, and if all authorities that list it list the same
1691 nickname. However, if consensus-method 2 or later is in use, and
1692 any authority calls this identity/nickname pair Unnamed, then
1693 this routerstatus does not get the Named flag.
1695 * If consensus-method 2 or later is in use, the Unnamed flag is
1696 set for a routerstatus if any authorities have voted for a different
1697 identities to be Named with that nickname, or if any authority
1698 lists that nickname/ID pair as Unnamed.
1700 (With consensus-method 1, Unnamed is set like any other flag.)
1702 * The version is given as whichever version is listed by the most
1703 voters, with ties decided in favor of more recent versions.
1705 * If consensus-method 4 or later is in use, then routers that
1706 do not have the Running flag are not listed at all.
1708 * If consensus-method 5 or later is in use, then the "w" line
1709 is generated using a low-median of the bandwidth values from
1710 the votes that included "w" lines for this router.
1712 * If consensus-method 5 or later is in use, then the "p" line
1713 is taken from the votes that have the same policy summary
1714 for the descriptor we are listing. (They should all be the
1715 same. If they are not, we pick the most commonly listed
1716 one, breaking ties in favor of the lexicographically larger
1717 vote.) The port list is encoded as specified in 3.5.2.
1719 * If consensus-method 6 or later is in use and if 3 or more
1720 authorities provide a Measured= keyword in their votes for
1721 a router, the authorities produce a consensus containing a
1722 Bandwidth= keyword equal to the median of the Measured= votes.
1724 * If consensus-method 7 or later is in use, the params line is
1725 included in the output.
1727 * If the consensus method is under 11, bad exits are considered as
1728 possible exits when computing bandwidth weights. Otherwise, if
1729 method 11 or later is in use, any router that is determined to get
1730 the BadExit flag doesn't count when we're calculating weights.
1732 * If consensus method 12 or later is used, only consensus
1733 parameters that more than half of the total number of
1734 authorities voted for are included in the consensus.
1736 The signatures at the end of a consensus document are sorted in
1737 ascending order by identity digest.
1739 All ties in computing medians are broken in favor of the smaller or
1740 earlier item.
1742 3.5.1. Forward compatibility
1744 Future versions of Tor will need to include new information in the
1745 consensus documents, but it is important that all authorities (or at least
1746 half) generate and sign the same signed consensus.
1748 To achieve this, authorities list in their votes their supported methods
1749 for generating consensuses from votes. Later methods will be assigned
1750 higher numbers. Currently recognized methods:
1751 "1" -- The first implemented version.
1752 "2" -- Added support for the Unnamed flag.
1753 "3" -- Added legacy ID key support to aid in authority ID key rollovers
1754 "4" -- No longer list routers that are not running in the consensus
1755 "5" -- adds support for "w" and "p" lines.
1756 "6" -- Prefers measured bandwidth values rather than advertised
1757 "7" -- Provides keyword=integer pairs of consensus parameters
1758 "8" -- Provides microdescriptor summaries
1759 "9" -- Provides weights for selecting flagged routers in paths
1760 "10" -- Fixes edge case bugs in router flag selection weights
1761 "11" -- Don't consider BadExits when calculating bandwidth weights
1762 "12" -- Params are only included if enough auths voted for them
1765 Before generating a consensus, an authority must decide which consensus
1766 method to use. To do this, it looks for the highest version number
1767 supported by more than 2/3 of the authorities voting. If it supports this
1768 method, then it uses it. Otherwise, it falls back to method 1.
1770 (The consensuses generated by new methods must be parsable by
1771 implementations that only understand the old methods, and must not cause
1772 those implementations to compromise their anonymity. This is a means for
1773 making changes in the contents of consensus; not for making
1774 backward-incompatible changes in their format.)
1776 3.5.2. Encoding port lists
1778 Whether the summary shows the list of accepted ports or the list of
1779 rejected ports depends on which list is shorter (has a shorter string
1780 representation). In case of ties we choose the list of accepted
1781 ports. As an exception to this rule an allow-all policy is
1782 represented as "accept 1-65535" instead of "reject " and a reject-all
1783 policy is similarly given as "reject 1-65535".
1785 Summary items are compressed, that is instead of "80-88,89-100" there
1786 only is a single item of "80-100", similarly instead of "20,21" a
1787 summary will say "20-21".
1789 Port lists are sorted in ascending order.
1791 The maximum allowed length of a policy summary (including the "accept "
1792 or "reject ") is 1000 characters. If a summary exceeds that length we
1793 use an accept-style summary and list as much of the port list as is
1794 possible within these 1000 bytes. [XXXX be more specific.]
1796 3.5.3. Computing Bandwidth Weights
1798 Let weight_scale = 10000
1800 Let G be the total bandwidth for Guard-flagged nodes.
1801 Let M be the total bandwidth for non-flagged nodes.
1802 Let E be the total bandwidth for Exit-flagged nodes.
1803 Let D be the total bandwidth for Guard+Exit-flagged nodes.
1804 Let T = G+M+E+D
1806 Let Wgd be the weight for choosing a Guard+Exit for the guard position.
1807 Let Wmd be the weight for choosing a Guard+Exit for the middle position.
1808 Let Wed be the weight for choosing a Guard+Exit for the exit position.
1810 Let Wme be the weight for choosing an Exit for the middle position.
1811 Let Wmg be the weight for choosing a Guard for the middle position.
1813 Let Wgg be the weight for choosing a Guard for the guard position.
1814 Let Wee be the weight for choosing an Exit for the exit position.
1816 Balanced network conditions then arise from solutions to the following
1817 system of equations:
1819 Wgg*G + Wgd*D == M + Wmd*D + Wme*E + Wmg*G (guard bw = middle bw)
1820 Wgg*G + Wgd*D == Wee*E + Wed*D (guard bw = exit bw)
1821 Wed*D + Wmd*D + Wgd*D == D (aka: Wed+Wmd+Wdg = 1)
1822 Wmg*G + Wgg*G == G (aka: Wgg = 1-Wmg)
1823 Wme*E + Wee*E == E (aka: Wee = 1-Wme)
1825 We are short 2 constraints with the above set. The remaining constraints
1826 come from examining different cases of network load. The following
1827 constraints are used in consensus method 10 and above. There are another
1828 incorrect and obsolete set of constraints used for these same cases in
1829 consensus method 9. For those, see dir-spec.txt in Tor 0.2.2.10-alpha
1830 to 0.2.2.16-alpha.
1832 Case 1: E >= T/3 && G >= T/3 (Neither Exit nor Guard Scarce)
1834 In this case, the additional two constraints are: Wmg == Wmd,
1835 Wed == 1/3.
1837 This leads to the solution:
1838 Wgd = weight_scale/3
1839 Wed = weight_scale/3
1840 Wmd = weight_scale/3
1841 Wee = (weight_scale*(E+G+M))/(3*E)
1842 Wme = weight_scale - Wee
1843 Wmg = (weight_scale*(2*G-E-M))/(3*G)
1844 Wgg = weight_scale - Wmg
1846 Case 2: E < T/3 && G < T/3 (Both are scarce)
1848 Let R denote the more scarce class (Rare) between Guard vs Exit.
1849 Let S denote the less scarce class.
1851 Subcase a: R+D < S
1853 In this subcase, we simply devote all of D bandwidth to the
1854 scarce class.
1856 Wgg = Wee = weight_scale
1857 Wmg = Wme = Wmd = 0;
1858 if E < G:
1859 Wed = weight_scale
1860 Wgd = 0
1861 else:
1862 Wed = 0
1863 Wgd = weight_scale
1865 Subcase b: R+D >= S
1867 In this case, if M <= T/3, we have enough bandwidth to try to achieve
1868 a balancing condition.
1870 Add constraints Wgg = 1, Wmd == Wgd to maximize bandwidth in the guard
1871 position while still allowing exits to be used as middle nodes:
1873 Wee = (weight_scale*(E - G + M))/E
1874 Wed = (weight_scale*(D - 2*E + 4*G - 2*M))/(3*D)
1875 Wme = (weight_scale*(G-M))/E
1876 Wmg = 0
1877 Wgg = weight_scale
1878 Wmd = (weight_scale - Wed)/2
1879 Wgd = (weight_scale - Wed)/2
1881 If this system ends up with any values out of range (ie negative, or
1882 above weight_scale), use the constraints Wgg == 1 and Wee == 1, since
1883 both those positions are scarce:
1885 Wgg = weight_scale
1886 Wee = weight_scale
1887 Wed = (weight_scale*(D - 2*E + G + M))/(3*D)
1888 Wmd = (weight_Scale*(D - 2*M + G + E))/(3*D)
1889 Wme = 0
1890 Wmg = 0
1891 Wgd = weight_scale - Wed - Wmd
1893 If M > T/3, then the Wmd weight above will become negative. Set it to 0
1894 in this case:
1895 Wmd = 0
1896 Wgd = weight_scale - Wed
1898 Case 3: One of E < T/3 or G < T/3
1900 Let S be the scarce class (of E or G).
1902 Subcase a: (S+D) < T/3:
1903 if G=S:
1904 Wgg = Wgd = weight_scale;
1905 Wmd = Wed = Wmg = 0;
1906 // Minor subcase, if E is more scarce than M,
1907 // keep its bandwidth in place.
1908 if (E < M) Wme = 0;
1909 else Wme = (weight_scale*(E-M))/(2*E);
1910 Wee = weight_scale-Wme;
1911 if E=S:
1912 Wee = Wed = weight_scale;
1913 Wmd = Wgd = Wme = 0;
1914 // Minor subcase, if G is more scarce than M,
1915 // keep its bandwidth in place.
1916 if (G < M) Wmg = 0;
1917 else Wmg = (weight_scale*(G-M))/(2*G);
1918 Wgg = weight_scale-Wmg;
1920 Subcase b: (S+D) >= T/3
1921 if G=S:
1922 Add constraints Wgg = 1, Wmd == Wed to maximize bandwidth
1923 in the guard position, while still allowing exits to be
1924 used as middle nodes:
1925 Wgg = weight_scale
1926 Wgd = (weight_scale*(D - 2*G + E + M))/(3*D)
1927 Wmg = 0
1928 Wee = (weight_scale*(E+M))/(2*E)
1929 Wme = weight_scale - Wee
1930 Wmd = (weight_scale - Wgd)/2
1931 Wed = (weight_scale - Wgd)/2
1932 if E=S:
1933 Add constraints Wee == 1, Wmd == Wgd to maximize bandwidth
1934 in the exit position:
1935 Wee = weight_scale;
1936 Wed = (weight_scale*(D - 2*E + G + M))/(3*D);
1937 Wme = 0;
1938 Wgg = (weight_scale*(G+M))/(2*G);
1939 Wmg = weight_scale - Wgg;
1940 Wmd = (weight_scale - Wed)/2;
1941 Wgd = (weight_scale - Wed)/2;
1943 To ensure consensus, all calculations are performed using integer math
1944 with a fixed precision determined by the bwweightscale consensus
1945 parameter (defaults at 10000, Min: 1, Max: INT32_MAX).
1947 For future balancing improvements, Tor clients support 11 additional weights
1948 for directory requests and middle weighting. These weights are currently
1949 set at weight_scale, with the exception of the following groups of
1950 assignments:
1952 Directory requests use middle weights:
1953 Wbd=Wmd, Wbg=Wmg, Wbe=Wme, Wbm=Wmm
1955 Handle bridges and strange exit policies:
1956 Wgm=Wgg, Wem=Wee, Weg=Wed
1958 3.6. Consensus flavors
1960 Consensus flavors are variants of the consensus that clients can choose
1961 to download and use instead of the unflavored consensus. The purpose
1962 of a consensus flavor is to remove or replace information in the
1963 unflavored consensus without forcing clients to download information
1964 they would not use anyway.
1966 Directory authorities can produce and serve an arbitrary number of
1967 flavors of the same consensus. A downside of creating too many new
1968 flavors is that clients will be distinguishable based on which flavor
1969 they download. A new flavor should not be created when adding a field
1970 instead wouldn't be too onerous.
1972 Examples for consensus flavors include:
1973 - Publishing hashes of microdescriptors instead of hashes of
1974 full descriptors (see 3.6.2).
1975 - Including different digests of descriptors, instead of the
1976 perhaps-soon-to-be-totally-broken SHA1.
1978 Consensus flavors are derived from the unflavored consensus once the
1979 voting process is complete. This is to avoid consensus synchronization
1980 problems.
1982 Every consensus flavor has a name consisting of a sequence of one
1983 or more alphanumeric characters and dashes. For compatibility,
1984 current descriptor flavor is called "ns".
1986 The supported consensus flavors are defined as part of the
1987 authorities' consensus method.
1989 All consensus flavors have in common that their first line is
1990 "network-status-version" where version is 3 or higher, and the flavor
1991 is a string consisting of alphanumeric characters and dashes:
1993 "network-status-version" SP version SP flavor NL
1995 3.6.1. ns consensus
1997 The ns consensus flavor is equivalent to the unflavored consensus
1998 except for its first line which states its consensus flavor name:
2000 "network-status-version" SP version SP "ns" NL
2002 [At start, exactly once.]
2004 3.6.2. Microdescriptor consensus
2006 The microdescriptor consensus is a consensus flavor that contains
2007 microdescriptor hashes instead of descriptor hashes and that omits
2008 exit-policy summaries which are contained in microdescriptors. The
2009 microdescriptor consensus was designed to contain elements that are
2010 small and frequently changing. Clients use the information in the
2011 microdescriptor consensus to decide which servers to fetch information
2012 about and which servers to fetch information from.
2014 The microdescriptor consensus is based on the unflavored consensus with
2015 the exceptions as follows:
2017 "network-status-version" SP version SP "microdesc" NL
2019 [At start, exactly once.]
2021 The flavor name of a microdescriptor consensus is "microdesc".
2023 Changes to router status entries are as follows:
2025 "r" SP nickname SP identity SP publication SP IP SP ORPort
2026 SP DirPort NL
2028 [At start, exactly once.]
2030 Similar to "r" lines in 3.3, but without the digest element.
2032 "p" ... NL
2034 [Zero times.]
2036 Exit policy summaries are contained in microdescriptors and
2037 therefore omitted in the microdescriptor consensus.
2039 "m" SP digest NL
2041 [Exactly once.]
2043 "digest" is the base64 of the SHA256 hash of the router's
2044 microdescriptor with trailing =s omitted. For a given router
2045 descriptor digest and consensus method there should only be a
2046 single microdescriptor digest in the "m" lines of all votes.
2047 If different votes have different microdescriptor digests for
2048 the same descriptor digest and consensus method, at least one
2049 of the authorities is broken. If this happens, the microdesc
2050 consensus should contain whichever microdescriptor digest is
2051 most common. If there is no winner, we break ties in the favor
2052 of the lexically earliest.
2054 3.7. Detached signatures
2056 Assuming full connectivity, every authority should compute and sign the
2057 same consensus including any flavors in each period. Therefore, it
2058 isn't necessary to download the consensus or any flavors of it computed
2059 by each authority; instead, the authorities only push/fetch each
2060 others' signatures. A "detached signature" document contains items as
2061 follows:
2063 "consensus-digest" SP Digest NL
2065 [At start, at most once.]
2067 The digest of the consensus being signed.
2069 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
2070 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
2071 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
2073 [As in the consensus]
2075 "additional-digest" SP flavor SP algname SP digest NL
2077 [Any number.]
2079 For each supported consensus flavor, every directory authority
2080 adds one or more "additional-digest" lines. "flavor" is the name
2081 of the consensus flavor, "algname" is the name of the hash
2082 algorithm that is used to generate the digest, and "digest" is the
2083 hex-encoded digest.
2085 The hash algorithm for the microdescriptor consensus flavor is
2086 defined as SHA256 with algname "sha256".
2088 "additional-signature" SP flavor SP algname SP identity SP
2089 signing-key-digest NL signature.
2091 [Any number.]
2093 For each supported consensus flavor and defined digest algorithm,
2094 every directory authority adds an "additional-signature" line.
2095 "flavor" is the name of the consensus flavor. "algname" is the
2096 name of the algorithm that was used to hash the identity and
2097 signing keys, and to compute the signature. "identity" is the
2098 hex-encoded digest of the authority identity key of the signing
2099 authority, and "signing-key-digest" is the hex-encoded digest of
2100 the current authority signing key of the signing authority.
2102 The "sha256" signature format is defined as the RSA signature of
2103 the OAEP+-padded SHA256 digest of the item to be signed. When
2104 checking signatures, the signature MUST be treated as valid if the
2105 signature material begins with SHA256(document), so that other
2106 data can get added later.
2107 [To be honest, I didn't fully understand the previous paragraph
2108 and only copied it from the proposals. Review carefully. -KL]
2110 "directory-signature"
2112 [As in the consensus; the signature object is the same as in the
2113 consensus document.]
2115 4. Directory server operation
2117 All directory authorities and directory caches ("directory servers")
2118 implement this section, except as noted.
2120 4.1. Accepting uploads (authorities only)
2122 When a router posts a signed descriptor to a directory authority, the
2123 authority first checks whether it is well-formed and correctly
2124 self-signed. If it is, the authority next verifies that the nickname
2125 in question is not already assigned to a router with a different
2126 public key.
2127 Finally, the authority MAY check that the router is not blacklisted
2128 because of its key, IP, or another reason.
2130 If the descriptor passes these tests, and the authority does not already
2131 have a descriptor for a router with this public key, it accepts the
2132 descriptor and remembers it.
2134 If the authority _does_ have a descriptor with the same public key, the
2135 newly uploaded descriptor is remembered if its publication time is more
2136 recent than the most recent old descriptor for that router, and either:
2137 - There are non-cosmetic differences between the old descriptor and the
2138 new one.
2139 - Enough time has passed between the descriptors' publication times.
2140 (Currently, 12 hours.)
2142 Differences between router descriptors are "non-cosmetic" if they would be
2143 sufficient to force an upload as described in section 2 above.
2145 Note that the "cosmetic difference" test only applies to uploaded
2146 descriptors, not to descriptors that the authority downloads from other
2147 authorities.
2149 When a router posts a signed extra-info document to a directory authority,
2150 the authority again checks it for well-formedness and correct signature,
2151 and checks that its matches the extra-info-digest in some router
2152 descriptor that it believes is currently useful. If so, it accepts it and
2153 stores it and serves it as requested. If not, it drops it.
2155 4.2. Voting (authorities only)
2157 Authorities divide time into Intervals. Authority administrators SHOULD
2158 try to all pick the same interval length, and SHOULD pick intervals that
2159 are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
2160 minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
2161 divide evenly into a 24-hour day.
2163 Authorities SHOULD act according to interval and delays in the
2164 latest consensus. Lacking a latest consensus, they SHOULD default to a
2165 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
2167 Authorities MUST take pains to ensure that their clocks remain accurate
2168 within a few seconds. (Running NTP is usually sufficient.)
2170 The first voting period of each day begins at 00:00 (midnight) GMT. If
2171 the last period of the day would be truncated by one-half or more, it is
2172 merged with the second-to-last period.
2174 An authority SHOULD publish its vote immediately at the start of each voting
2175 period (minus VoteSeconds+DistSeconds). It does this by making it
2176 available at
2177 http://<hostname>/tor/status-vote/next/authority.z
2178 and sending it in an HTTP POST request to each other authority at the URL
2179 http://<hostname>/tor/post/vote
2181 If, at the start of the voting period, minus DistSeconds, an authority
2182 does not have a current statement from another authority, the first
2183 authority downloads the other's statement.
2185 Once an authority has a vote from another authority, it makes it available
2186 at
2187 http://<hostname>/tor/status-vote/next/<fp>.z
2188 where <fp> is the fingerprint of the other authority's identity key.
2189 And at
2190 http://<hostname>/tor/status-vote/next/d/<d>.z
2191 where <d> is the digest of the vote document.
2193 The consensus status, along with as many signatures as the server
2194 currently knows, should be available at
2195 http://<hostname>/tor/status-vote/next/consensus.z
2196 All of the detached signatures it knows for consensus status should be
2197 available at:
2198 http://<hostname>/tor/status-vote/next/consensus-signatures.z
2200 Once there are enough signatures, or once the voting period starts,
2201 these documents are available at
2202 http://<hostname>/tor/status-vote/current/consensus.z
2203 and
2204 http://<hostname>/tor/status-vote/current/consensus-signatures.z
2205 [XXX current/consensus-signatures is not currently implemented, as it
2206 is not used in the voting protocol.]
2208 The other vote documents are analogously made available under
2209 http://<hostname>/tor/status-vote/current/authority.z
2210 http://<hostname>/tor/status-vote/current/<fp>.z
2211 http://<hostname>/tor/status-vote/current/d/<d>.z
2212 once the consensus is complete.
2214 Once an authority has computed and signed a consensus network status, it
2215 should send its detached signature to each other authority in an HTTP POST
2216 request to the URL:
2217 http://<hostname>/tor/post/consensus-signature
2219 [XXX Note why we support push-and-then-pull.]
2221 [XXX possible future features include support for downloading old
2222 consensuses.]
2224 The authorities serve another consensus of each flavor "F" from the
2225 locations
2226 /tor/status-vote/(current|next)/consensus-F.z. and
2227 /tor/status-vote/(current|next)/consensus-F/<FP1>+....z.
2229 4.3. Downloading consensus status documents (caches only)
2231 All directory servers (authorities and caches) try to keep a recent
2232 network-status consensus document to serve to clients. A cache ALWAYS
2233 downloads a network-status consensus if any of the following are true:
2234 - The cache has no consensus document.
2235 - The cache's consensus document is no longer valid.
2236 Otherwise, the cache downloads a new consensus document at a randomly
2237 chosen time in the first half-interval after its current consensus
2238 stops being fresh. (This time is chosen at random to avoid swarming
2239 the authorities at the start of each period. The interval size is
2240 inferred from the difference between the valid-after time and the
2241 fresh-until time on the consensus.)
2243 [For example, if a cache has a consensus that became valid at 1:00,
2244 and is fresh until 2:00, that cache will fetch a new consensus at
2245 a random time between 2:00 and 2:30.]
2247 Directory caches also fetch consensus flavors from the authorities.
2248 Caches check the correctness of consensus flavors, but do not check
2249 anything about an unrecognized consensus document beyond its digest and
2250 length. Caches serve all consensus flavors from the same locations as
2251 the directory authorities.
2253 4.4. Downloading and storing router descriptors (authorities and caches)
2255 Periodically (currently, every 10 seconds), directory servers check
2256 whether there are any specific descriptors that they do not have and that
2257 they are not currently trying to download. Caches identify these
2258 descriptors by hash in the recent network-status consensus documents;
2259 authorities identify them by hash in vote (if publication date is more
2260 recent than the descriptor we currently have).
2262 [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
2263 do that for now.]
2265 If so, the directory server launches requests to the authorities for these
2266 descriptors, such that each authority is only asked for descriptors listed
2267 in its most recent vote (if the requester is an authority) or in the
2268 consensus (if the requester is a cache). If we're an authority, and more
2269 than one authority lists the descriptor, we choose which to ask at random.
2271 If one of these downloads fails, we do not try to download that descriptor
2272 from the authority that failed to serve it again unless we receive a newer
2273 network-status (consensus or vote) from that authority that lists the same
2274 descriptor.
2276 Directory servers must potentially cache multiple descriptors for each
2277 router. Servers must not discard any descriptor listed by any recent
2278 consensus. If there is enough space to store additional descriptors,
2279 servers SHOULD try to hold those which clients are likely to download the
2280 most. (Currently, this is judged based on the interval for which each
2281 descriptor seemed newest.)
2282 [XXXX define recent]
2284 Authorities SHOULD NOT download descriptors for routers that they would
2285 immediately reject for reasons listed in 3.1.
2287 4.5. Downloading and storing microdescriptors (caches only)
2289 Directory mirrors should fetch, cache, and serve each microdescriptor
2290 from the authorities.
2292 The microdescriptors with base64 hashes <D1>,<D2>,<D3> are available
2293 at:
2294 http://<hostname>/tor/micro/d/<D1>-<D2>-<D3>[.z]
2296 <Dn> are base-64 encoded with trailing =s omitted for size and for
2297 consistency with the microdescriptor consensus format. -s are used
2298 instead of +s to separate items, since the + character is used in
2299 base64 encoding.
2301 All the microdescriptors from the current consensus should also be
2302 available at:
2303 http://<hostname>/tor/micro/all[.z]
2304 so a client that's bootstrapping doesn't need to send a 70KB URL just
2305 to name every microdescriptor it's looking for.
2306 [Note that /tor/micro/all[.z] is not implemented as of February 21,
2307 2012. -KL]
2309 Directory mirrors should check to make sure that the microdescriptors
2310 they're about to serve match the right hashes (either the hashes from
2311 the fetch URL or the hashes from the consensus, respectively).
2313 4.6. Downloading and storing extra-info documents
2315 All authorities, and any cache that chooses to cache extra-info documents,
2316 and any client that uses extra-info documents, should implement this
2317 section.
2319 Note that generally, clients don't need extra-info documents.
2321 Periodically, the Tor instance checks whether it is missing any extra-info
2322 documents: in other words, if it has any router descriptors with an
2323 extra-info-digest field that does not match any of the extra-info
2324 documents currently held. If so, it downloads whatever extra-info
2325 documents are missing. Caches download from authorities; non-caches try
2326 to download from caches. We follow the same splitting and back-off rules
2327 as in 4.4 (if a cache) or 5.3 (if a client).
2329 4.7. General-use HTTP URLs
2331 "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
2333 The most recent v3 consensus should be available at:
2334 http://<hostname>/tor/status-vote/current/consensus.z
2336 Starting with Tor version 0.2.1.1-alpha is also available at:
2337 http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
2339 Where F1, F2, etc. are authority identity fingerprints the client trusts.
2340 Servers will only return a consensus if more than half of the requested
2341 authorities have signed the document, otherwise a 404 error will be sent
2342 back. The fingerprints can be shortened to a length of any multiple of
2343 two, using only the leftmost part of the encoded fingerprint. Tor uses
2344 3 bytes (6 hex characters) of the fingerprint.
2346 Clients SHOULD sort the fingerprints in ascending order. Server MUST
2347 accept any order.
2349 Clients SHOULD use this format when requesting consensus documents from
2350 directory authority servers and from caches running a version of Tor
2351 that is known to support this URL format.
2353 A concatenated set of all the current key certificates should be available
2354 at:
2355 http://<hostname>/tor/keys/all.z
2357 The key certificate for this server (if it is an authority) should be
2358 available at:
2359 http://<hostname>/tor/keys/authority.z
2361 The key certificate for an authority whose authority identity fingerprint
2362 is <F> should be available at:
2363 http://<hostname>/tor/keys/fp/<F>.z
2365 The key certificate whose signing key fingerprint is <F> should be
2366 available at:
2367 http://<hostname>/tor/keys/sk/<F>.z
2369 The key certificate whose identity key fingerprint is <F> and whose signing
2370 key fingerprint is <S> should be available at:
2372 http://<hostname>/tor/keys/fp-sk/<F>-<S>.z
2374 (As usual, clients may request multiple certificates using:
2375 http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z )
2376 [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]
2378 The most recent descriptor for a server whose identity key has a
2379 fingerprint of <F> should be available at:
2380 http://<hostname>/tor/server/fp/<F>.z
2382 The most recent descriptors for servers with identity fingerprints
2383 <F1>,<F2>,<F3> should be available at:
2384 http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
2386 (NOTE: Implementations SHOULD NOT download descriptors by identity key
2387 fingerprint. This allows a corrupted server (in collusion with a cache) to
2388 provide a unique descriptor to a client, and thereby partition that client
2389 from the rest of the network.)
2391 The server descriptor with (descriptor) digest <D> (in hex) should be
2392 available at:
2393 http://<hostname>/tor/server/d/<D>.z
2395 The most recent descriptors with digests <D1>,<D2>,<D3> should be
2396 available at:
2397 http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
2399 The most recent descriptor for this server should be at:
2400 http://<hostname>/tor/server/authority.z
2401 [Nothing in the Tor protocol uses this resource yet, but it is useful
2402 for debugging purposes. Also, the official Tor implementations
2403 (starting at 0.1.1.x) use this resource to test whether a server's
2404 own DirPort is reachable.]
2406 A concatenated set of the most recent descriptors for all known servers
2407 should be available at:
2408 http://<hostname>/tor/server/all.z
2410 Extra-info documents are available at the URLS
2411 http://<hostname>/tor/extra/d/...
2412 http://<hostname>/tor/extra/fp/...
2413 http://<hostname>/tor/extra/all[.z]
2414 http://<hostname>/tor/extra/authority[.z]
2415 (As for /tor/server/ URLs: supports fetching extra-info
2416 documents by their digest, by the fingerprint of their servers,
2417 or all at once. When serving by fingerprint, we serve the
2418 extra-info that corresponds to the descriptor we would serve by
2419 that fingerprint. Only directory authorities of version
2420 0.2.0.1-alpha or later are guaranteed to support the first
2421 three classes of URLs. Caches may support them, and MUST
2422 support them if they have advertised "caches-extra-info".)
2424 For debugging, directories SHOULD expose non-compressed objects at URLs like
2425 the above, but without the final ".z".
2426 Clients MUST handle compressed concatenated information in two forms:
2427 - A concatenated list of zlib-compressed objects.
2428 - A zlib-compressed concatenated list of objects.
2429 Directory servers MAY generate either format: the former requires less
2430 CPU, but the latter requires less bandwidth.
2432 Clients SHOULD use upper case letters (A-F) when base16-encoding
2433 fingerprints. Servers MUST accept both upper and lower case fingerprints
2434 in requests.
2436 [XXX Add new URLs for microdescriptors, consensus flavors, and
2437 microdescriptor consensus. -KL]
2439 5. Client operation: downloading information
2441 Every Tor that is not a directory server (that is, those that do
2442 not have a DirPort set) implements this section.
2444 5.1. Downloading network-status documents
2446 Each client maintains a list of directory authorities. Insofar as
2447 possible, clients SHOULD all use the same list.
2449 Clients try to have a live consensus network-status document at all times.
2450 A network-status document is "live" if the time in its valid-until field
2451 has not passed.
2453 If a client is missing a live network-status document, it tries to fetch
2454 it from a directory cache (or from an authority if it knows no caches).
2455 On failure, the client waits briefly, then tries that network-status
2456 document again from another cache. The client does not build circuits
2457 until it has a live network-status consensus document, and it has
2458 descriptors for more than 1/4 of the routers that it believes are running.
2460 (Note: clients can and should pick caches based on the network-status
2461 information they have: once they have first fetched network-status info
2462 from an authority, they should not need to go to the authority directly
2463 again.)
2465 To avoid swarming the caches whenever a consensus expires, the
2466 clients download new consensuses at a randomly chosen time after the
2467 caches are expected to have a fresh consensus, but before their
2468 consensus will expire. (This time is chosen uniformly at random from
2469 the interval between the time 3/4 into the first interval after the
2470 consensus is no longer fresh, and 7/8 of the time remaining after
2471 that before the consensus is invalid.)
2473 [For example, if a cache has a consensus that became valid at 1:00,
2474 and is fresh until 2:00, and expires at 4:00, that cache will fetch
2475 a new consensus at a random time between 2:45 and 3:50, since 3/4
2476 of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
2477 minutes is 65 minutes.]
2479 Clients may choose to download the microdescriptor consensus instead
2480 of the general network status consensus. In that case they should use
2481 the same update strategy as for the normal consensus. They should not
2482 download more than one consensus flavor.
2484 5.2. Downloading and storing router descriptors or microdescriptors
2486 Clients try to have the best descriptor for each router. A descriptor is
2487 "best" if:
2488 * It is listed in the consensus network-status document.
2490 Periodically (currently every 10 seconds) clients check whether there are
2491 any "downloadable" descriptors. A descriptor is downloadable if:
2492 - It is the "best" descriptor for some router.
2493 - The descriptor was published at least 10 minutes in the past.
2494 (This prevents clients from trying to fetch descriptors that the
2495 mirrors have probably not yet retrieved and cached.)
2496 - The client does not currently have it.
2497 - The client is not currently trying to download it.
2498 - The client would not discard it immediately upon receiving it.
2499 - The client thinks it is running and valid (see 6.1 below).
2501 If at least 16 known routers have downloadable descriptors, or if
2502 enough time (currently 10 minutes) has passed since the last time the
2503 client tried to download descriptors, it launches requests for all
2504 downloadable descriptors, as described in 5.3 below.
2506 When a descriptor download fails, the client notes it, and does not
2507 consider the descriptor downloadable again until a certain amount of time
2508 has passed. (Currently 0 seconds for the first failure, 60 seconds for the
2509 second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
2510 thereafter.) Periodically (currently once an hour) clients reset the
2511 failure count.
2513 Clients retain the most recent descriptor they have downloaded for each
2514 router so long as it is not too old (currently, 48 hours), OR so long as
2515 no better descriptor has been downloaded for the same router.
2517 [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
2518 being published too far in the past.] [The code seems to discard
2519 descriptors in all cases after they're 5 days old. True? -RD]
2521 Clients which chose to download the microdescriptor consensus instead
2522 of the general consensus must download the referenced microdescriptors
2523 instead of router descriptors. Clients fetch and cache
2524 microdescriptors preemptively from dir mirrors when starting up, like
2525 they currently fetch descriptors. After bootstrapping, clients only
2526 need to fetch the microdescriptors that have changed.
2528 Clients maintain a cache of microdescriptors along with metadata like
2529 when it was last referenced by a consensus, and which identity key
2530 it corresponds to. They keep a microdescriptor until it hasn't been
2531 mentioned in any consensus for a week. Future clients might cache them
2532 for longer or shorter times.
2534 5.3. Managing downloads
2536 When a client has no consensus network-status document, it downloads it
2537 from a randomly chosen authority. In all other cases, the client
2538 downloads from caches randomly chosen from among those believed to be V2
2539 directory servers. (This information comes from the network-status
2540 documents; see 6 below.)
2542 When downloading multiple router descriptors, the client chooses multiple
2543 mirrors so that:
2544 - At least 3 different mirrors are used, except when this would result
2545 in more than one request for under 4 descriptors.
2546 - No more than 128 descriptors are requested from a single mirror.
2547 - Otherwise, as few mirrors as possible are used.
2548 After choosing mirrors, the client divides the descriptors among them
2549 randomly.
2551 After receiving any response client MUST discard any network-status
2552 documents and descriptors that it did not request.
2554 When a client gets a new microdescriptor consensus, it looks to see if
2555 there are any microdescriptors it needs to learn. If it needs to learn
2556 more than half of the microdescriptors, it requests 'all', else it
2557 requests only the missing ones. Clients MAY try to determine whether
2558 the upload bandwidth for listing the microdescriptors they want is more
2559 or less than the download bandwidth for the microdescriptors they do
2560 not want.
2562 6. Using directory information
2564 Everyone besides directory authorities uses the approaches in this section
2565 to decide which relays to use and what their keys are likely to be.
2566 (Directory authorities just believe their own opinions, as in 3.1 above.)
2568 6.1. Choosing routers for circuits.
2570 Circuits SHOULD NOT be built until the client has enough directory
2571 information: a live consensus network status [XXXX fallback?] and
2572 descriptors for at least 1/4 of the relays believed to be running.
2574 A relay is "listed" if it is included by the consensus network-status
2575 document. Clients SHOULD NOT use unlisted relays.
2577 These flags are used as follows:
2579 - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
2580 requested to do so.
2582 - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
2583 very-low-bandwidth circuits (such as introduction circuits).
2585 - Clients SHOULD NOT use non-'Stable' routers for circuits that are
2586 likely to need to be open for a very long time (such as those used for
2587 IRC or SSH connections).
2589 - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
2590 nodes.
2592 - Clients SHOULD NOT download directory information from non-'V2Dir'
2593 caches.
2595 See the "path-spec.txt" document for more details.
2597 6.2. Managing naming
2599 In order to provide human-memorable names for individual router
2600 identities, some directory servers bind names to IDs. Clients handle
2601 names in two ways:
2603 When a client encounters a name it has not mapped before:
2605 If the consensus lists any router with that name as "Named", or if
2606 consensus-method 2 or later is in use and the consensus lists any
2607 router with that name as having the "Unnamed" flag, then the name is
2608 bound. (It's bound to the ID listed in the entry with the Named,
2609 or to an unknown ID if no name is found.)
2611 When the user refers to a bound name, the implementation SHOULD provide
2612 only the router with ID bound to that name, and no other router, even
2613 if the router with the right ID can't be found.
2615 When a user tries to refer to a non-bound name, the implementation SHOULD
2616 warn the user. After warning the user, the implementation MAY use any
2617 router that advertises the name.
2619 Not every router needs a nickname. When a router doesn't configure a
2620 nickname, it publishes with the default nickname "Unnamed". Authorities
2621 SHOULD NOT ever mark a router with this nickname as Named; client software
2622 SHOULD NOT ever use a router in response to a user request for a router
2623 called "Unnamed".
2625 6.3. Software versions
2627 An implementation of Tor SHOULD warn when it has fetched a consensus
2628 network-status, and it is running a software version not listed.
2630 6.4. Warning about a router's status.
2632 If a router tries to publish its descriptor to a Naming authority
2633 that has its nickname mapped to another key, the router SHOULD
2634 warn the operator that it is either using the wrong key or is using
2635 an already claimed nickname.
2637 If a router has fetched a consensus document,, and the
2638 authorities do not publish a binding for the router's nickname, the
2639 router MAY remind the operator that the chosen nickname is not
2640 bound to this key at the authorities, and suggest contacting the
2641 authority operators.
2643 ...
2645 6.5. Router protocol versions
2647 A client should believe that a router supports a given feature if that
2648 feature is supported by the router or protocol versions in more than half
2649 of the live networkstatuses' "v" entries for that router. In other words,
2650 if the "v" entries for some router are:
2651 v Tor 0.0.8pre1 (from authority 1)
2652 v Tor 0.1.2.11 (from authority 2)
2653 v FutureProtocolDescription 99 (from authority 3)
2654 then the client should believe that the router supports any feature
2655 supported by 0.1.2.11.
2657 This is currently equivalent to believing the median declared version for
2658 a router in all live networkstatuses.
2660 7. Standards compliance
2662 All clients and servers MUST support HTTP 1.0. Clients and servers MAY
2663 support later versions of HTTP as well.
2665 7.1. HTTP headers
2667 Servers MAY set the Content-Length: header. Servers SHOULD set
2668 Content-Encoding to "deflate" or "identity".
2670 Servers MAY include an X-Your-Address-Is: header, whose value is the
2671 apparent IP address of the client connecting to them (as a dotted quad).
2672 For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
2673 report the IP from which the circuit carrying the BEGIN_DIR stream reached
2674 them.
2676 Servers SHOULD disable caching of multiple network statuses or multiple
2677 router descriptors. Servers MAY enable caching of single descriptors,
2678 single network statuses, the list of all router descriptors, a v1
2679 directory, or a v1 running routers document. XXX mention times.
2681 7.2. HTTP status codes
2683 Tor delivers the following status codes. Some were chosen without much
2684 thought; other code SHOULD NOT rely on specific status codes yet.
2686 200 -- the operation completed successfully
2687 -- the user requested statuses or serverdescs, and none of the ones we
2688 requested were found (0.2.0.4-alpha and earlier).
2690 304 -- the client specified an if-modified-since time, and none of the
2691 requested resources have changed since that time.
2693 400 -- the request is malformed, or
2694 -- the URL is for a malformed variation of one of the URLs we support,
2695 or
2696 -- the client tried to post to a non-authority, or
2697 -- the authority rejected a malformed posted document, or
2699 404 -- the requested document was not found.
2700 -- the user requested statuses or serverdescs, and none of the ones
2701 requested were found (0.2.0.5-alpha and later).
2703 503 -- we are declining the request in order to save bandwidth
2704 -- user requested some items that we ordinarily generate or store,
2705 but we do not have any available.
2707 9. Backward compatibility and migration plans
2709 Until Tor versions before 0.1.1.x are completely obsolete, directory
2710 authorities should generate, and mirrors should download and cache, v1
2711 directories and running-routers lists, and allow old clients to download
2712 them. These documents and the rules for retrieving, serving, and caching
2713 them are described in dir-spec-v1.txt.
2715 Until Tor versions before 0.2.0.x are completely obsolete, directory
2716 authorities should generate, mirrors should download and cache, v2
2717 network-status documents, and allow old clients to download them.
2718 Additionally, all directory servers and caches should download, store, and
2719 serve any router descriptor that is required because of v2 network-status
2720 documents. These documents and the rules for retrieving, serving, and
2721 caching them are described in dir-spec-v1.txt.
2723 A. Consensus-negotiation timeline.
2725 Period begins: this is the Published time.
2726 Everybody sends votes
2727 Reconciliation: everybody tries to fetch missing votes.
2728 consensus may exist at this point.
2729 End of voting period:
2730 everyone swaps signatures.
2731 Now it's okay for caches to download
2732 Now it's okay for clients to download.
2734 Valid-after/valid-until switchover