| blob | d75432714c9153b97ea393088c3ccff13a277777 |
2 Tor directory protocol, version 3
4 Table of Contents
6 0. Scope and preliminaries
7 0.1. History
8 0.2. Goals of the version 3 protoc
9 0.3. Some Remaining questions
10 1. Outline
11 1.1. What's different from version 2?
12 1.2. Document meta-format
13 1.3. Signing documents
14 1.4. Voting timeline
15 2. Router operation and formats
16 2.1. Uploading server descriptors and extra-info documents
17 2.1.1. Server descriptor format
18 2.1.2. Extra-info document format
19 2.1.3. Nonterminals in server descriptors
20 3. Directory authority operation and formats
21 3.1. Creating key certificates
22 3.2. Accepting server descriptor and extra-info document uploads
23 3.3. Computing microdescriptors
24 3.4. Exchanging votes
25 3.4.1. Vote and consensus status document formats
26 3.4.2. Assigning flags in a vote
27 3.4.3. Serving bandwidth list files
28 3.5. Downloading missing certificates from other directory authorities
29 3.6. Downloading server descriptors from other directory authorities
30 3.7. Downloading extra-info documents from other directory authorities
31 3.8. Computing a consensus from a set of votes
32 3.8.0.1. Deciding which Ids to include.
33 3.8.0.2. Deciding which descriptors to include
34 3.8.1. Forward compatibility
35 3.8.2. Encoding port lists
36 3.8.3. Computing Bandwidth Weights
37 3.9. Computing consensus flavors
38 3.9.1. ns consensus
39 3.9.2. Microdescriptor consensus
40 3.10. Exchanging detached signatures
41 3.11. Publishing the signed consensus
42 4. Directory cache operation
43 4.1. Downloading consensus status documents from directory authorities
44 4.2. Downloading server descriptors from directory authorities
45 4.3. Downloading microdescriptors from directory authorities
46 4.4. Downloading extra-info documents from directory authorities
47 4.5. Consensus diffs
48 4.5.1. Consensus diff format
49 4.5.2. Serving and requesting diff
50 4.6 Retrying failed downloads
51 5. Client operation
52 5.1. Downloading network-status documents
53 5.2. Downloading server descriptors or microdescriptors
54 5.3. Downloading extra-info documents
55 5.4. Using directory information
56 5.4.1. Choosing routers for circuits.
57 5.4.2. Managing naming
58 5.4.3. Software versions
59 5.4.4. Warning about a router's status.
60 5.5. Retrying failed downloads
61 6. Standards compliance
62 6.1. HTTP headers
63 6.2. HTTP status codes
64 A. Consensus-negotiation timeline.
65 B. General-use HTTP URLs
66 C. Converting a curve25519 public key to an ed25519 public key
67 D. Inferring missing proto lines.
68 E. Limited ed diff format
70 0. Scope and preliminaries
72 This directory protocol is used by Tor version 0.2.0.x-alpha and later.
73 See dir-spec-v1.txt for information on the protocol used up to the
74 0.1.0.x series, and dir-spec-v2.txt for information on the protocol
75 used by the 0.1.1.x and 0.1.2.x series.
77 This document merges and supersedes the following proposals:
79 101 Voting on the Tor Directory System
80 103 Splitting identity key from regularly used signing key
81 104 Long and Short Router Descriptors
83 XXX timeline
84 XXX fill in XXXXs
86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
87 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
88 "OPTIONAL" in this document are to be interpreted as described in
89 RFC 2119.
91 0.1. History
93 The earliest versions of Onion Routing shipped with a list of known
94 routers and their keys. When the set of routers changed, users needed to
95 fetch a new list.
97 The Version 1 Directory protocol
98 --------------------------------
100 Early versions of Tor (0.0.2) introduced "Directory authorities": servers
101 that served signed "directory" documents containing a list of signed
102 "server descriptors", along with short summary of the status of each
103 router. Thus, clients could get up-to-date information on the state of
104 the network automatically, and be certain that the list they were getting
105 was attested by a trusted directory authority.
107 Later versions (0.0.8) added directory caches, which download
108 directories from the authorities and serve them to clients. Non-caches
109 fetch from the caches in preference to fetching from the authorities, thus
110 distributing bandwidth requirements.
112 Also added during the version 1 directory protocol were "router status"
113 documents: short documents that listed only the up/down status of the
114 routers on the network, rather than a complete list of all the
115 descriptors. Clients and caches would fetch these documents far more
116 frequently than they would fetch full directories.
118 The Version 2 Directory Protocol
119 --------------------------------
121 During the Tor 0.1.1.x series, Tor revised its handling of directory
122 documents in order to address two major problems:
124 * Directories had grown quite large (over 1MB), and most directory
125 downloads consisted mainly of server descriptors that clients
126 already had.
128 * Every directory authority was a trust bottleneck: if a single
129 directory authority lied, it could make clients believe for a time
130 an arbitrarily distorted view of the Tor network. (Clients
131 trusted the most recent signed document they downloaded.) Thus,
132 adding more authorities would make the system less secure, not
133 more.
135 To address these, we extended the directory protocol so that
136 authorities now published signed "network status" documents. Each
137 network status listed, for every router in the network: a hash of its
138 identity key, a hash of its most recent descriptor, and a summary of
139 what the authority believed about its status. Clients would download
140 the authorities' network status documents in turn, and believe
141 statements about routers iff they were attested to by more than half of
142 the authorities.
144 Instead of downloading all server descriptors at once, clients
145 downloaded only the descriptors that they did not have. Descriptors
146 were indexed by their digests, in order to prevent malicious caches
147 from giving different versions of a server descriptor to different
148 clients.
150 Routers began working harder to upload new descriptors only when their
151 contents were substantially changed.
154 0.2. Goals of the version 3 protocol
156 Version 3 of the Tor directory protocol tries to solve the following
157 issues:
159 * A great deal of bandwidth used to transmit server descriptors was
160 used by two fields that are not actually used by Tor routers
161 (namely read-history and write-history). We save about 60% by
162 moving them into a separate document that most clients do not
163 fetch or use.
165 * It was possible under certain perverse circumstances for clients
166 to download an unusual set of network status documents, thus
167 partitioning themselves from clients who have a more recent and/or
168 typical set of documents. Even under the best of circumstances,
169 clients were sensitive to the ages of the network status documents
170 they downloaded. Therefore, instead of having the clients
171 correlate multiple network status documents, we have the
172 authorities collectively vote on a single consensus network status
173 document.
175 * The most sensitive data in the entire network (the identity keys
176 of the directory authorities) needed to be stored unencrypted so
177 that the authorities can sign network-status documents on the fly.
178 Now, the authorities' identity keys are stored offline, and used
179 to certify medium-term signing keys that can be rotated.
181 0.3. Some Remaining questions
183 Things we could solve on a v3 timeframe:
185 The SHA-1 hash is showing its age. We should do something about our
186 dependency on it. We could probably future-proof ourselves here in
187 this revision, at least so far as documents from the authorities are
188 concerned.
190 Too many things about the authorities are hardcoded by IP.
192 Perhaps we should start accepting longer identity keys for routers
193 too.
195 Things to solve eventually:
197 Requiring every client to know about every router won't scale forever.
199 Requiring every directory cache to know every router won't scale
200 forever.
203 1. Outline
205 There is a small set (say, around 5-10) of semi-trusted directory
206 authorities. A default list of authorities is shipped with the Tor
207 software. Users can change this list, but are encouraged not to do so,
208 in order to avoid partitioning attacks.
210 Every authority has a very-secret, long-term "Authority Identity Key".
211 This is stored encrypted and/or offline, and is used to sign "key
212 certificate" documents. Every key certificate contains a medium-term
213 (3-12 months) "authority signing key", that is used by the authority to
214 sign other directory information. (Note that the authority identity
215 key is distinct from the router identity key that the authority uses
216 in its role as an ordinary router.)
218 Routers periodically upload signed "routers descriptors" to the
219 directory authorities describing their keys, capabilities, and other
220 information. Routers may also upload signed "extra-info documents"
221 containing information that is not required for the Tor protocol.
222 Directory authorities serve server descriptors indexed by router
223 identity, or by hash of the descriptor.
225 Routers may act as directory caches to reduce load on the directory
226 authorities. They announce this in their descriptors.
228 Periodically, each directory authority generates a view of
229 the current descriptors and status for known routers. They send a
230 signed summary of this view (a "status vote") to the other
231 authorities. The authorities compute the result of this vote, and sign
232 a "consensus status" document containing the result of the vote.
234 Directory caches download, cache, and re-serve consensus documents.
236 Clients, directory caches, and directory authorities all use consensus
237 documents to find out when their list of routers is out-of-date.
238 (Directory authorities also use vote statuses.) If it is, they download
239 any missing server descriptors. Clients download missing descriptors
240 from caches; caches and authorities download from authorities.
241 Descriptors are downloaded by the hash of the descriptor, not by the
242 relay's identity key: this prevents directory servers from attacking
243 clients by giving them descriptors nobody else uses.
245 All directory information is uploaded and downloaded with HTTP.
247 1.1. What's different from version 2?
249 Clients used to download multiple network status documents,
250 corresponding roughly to "status votes" above. They would compute the
251 result of the vote on the client side.
253 Authorities used to sign documents using the same private keys they used
254 for their roles as routers. This forced them to keep these extremely
255 sensitive keys in memory unencrypted.
257 All of the information in extra-info documents used to be kept in the
258 main descriptors.
260 1.2. Document meta-format
262 Server descriptors, directories, and running-routers documents all obey the
263 following lightweight extensible information format.
265 The highest level object is a Document, which consists of one or more
266 Items. Every Item begins with a KeywordLine, followed by zero or more
267 Objects. A KeywordLine begins with a Keyword, optionally followed by
268 whitespace and more non-newline characters, and ends with a newline. A
269 Keyword is a sequence of one or more characters in the set [A-Za-z0-9-],
270 but may not start with -.
271 An Object is a block of encoded data in pseudo-Privacy-Enhanced-Mail (PEM)
272 style format: that is, lines of encoded data MAY be wrapped by inserting
273 an ascii linefeed ("LF", also called newline, or "NL" here) character
274 (cf. RFC 4648 §3.1). When line wrapping, implementations MUST wrap lines
275 at 64 characters. Upon decoding, implementations MUST ignore and discard
276 all linefeed characters.
278 More formally:
280 NL = The ascii LF character (hex value 0x0a).
281 Document ::= (Item | NL)+
282 Item ::= KeywordLine Object?
283 KeywordLine ::= Keyword (WS Argument)* NL
284 Keyword = KeywordStart KeywordChar*
285 KeywordStart ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9'
286 KeywordChar ::= KeywordStart | '-'
287 Argument := ArgumentChar+
288 ArgumentChar ::= any graphical printing ASCII character.
289 WS = (SP | TAB)+
290 Object ::= BeginLine Base64-encoded-data EndLine
291 BeginLine ::= "-----BEGIN " Keyword (" " Keyword)* "-----" NL
292 EndLine ::= "-----END " Keyword (" " Keyword)* "-----" NL
294 A Keyword may not be "-----BEGIN".
296 The BeginLine and EndLine of an Object must use the same keyword.
298 When interpreting a Document, software MUST ignore any KeywordLine that
299 starts with a keyword it doesn't recognize; future implementations MUST NOT
300 require current clients to understand any KeywordLine not currently
301 described.
303 Other implementations that want to extend Tor's directory format MAY
304 introduce their own items. The keywords for extension items SHOULD start
305 with the characters "x-" or "X-", to guarantee that they will not conflict
306 with keywords used by future versions of Tor.
308 In our document descriptions below, we tag Items with a multiplicity in
309 brackets. Possible tags are:
311 "At start, exactly once": These items MUST occur in every instance of
312 the document type, and MUST appear exactly once, and MUST be the
313 first item in their documents.
315 "Exactly once": These items MUST occur exactly one time in every
316 instance of the document type.
318 "At end, exactly once": These items MUST occur in every instance of
319 the document type, and MUST appear exactly once, and MUST be the
320 last item in their documents.
322 "At most once": These items MAY occur zero or one times in any
323 instance of the document type, but MUST NOT occur more than once.
325 "Any number": These items MAY occur zero, one, or more times in any
326 instance of the document type.
328 "Once or more": These items MUST occur at least once in any instance
329 of the document type, and MAY occur more.
331 For forward compatibility, each item MUST allow extra arguments at the
332 end of the line unless otherwise noted. So if an item's description below
333 is given as:
335 "thing" int int int NL
337 then implementations SHOULD accept this string as well:
339 "thing 5 9 11 13 16 12" NL
341 but not this string:
343 "thing 5" NL
345 and not this string:
347 "thing 5 10 thing" NL
348 .
350 Whenever an item DOES NOT allow extra arguments, we will tag it with
351 "no extra arguments".
353 1.3. Signing documents
355 Every signable document below is signed in a similar manner, using a
356 given "Initial Item", a final "Signature Item", a digest algorithm, and
357 a signing key.
359 The Initial Item must be the first item in the document.
361 The Signature Item has the following format:
363 <signature item keyword> [arguments] NL SIGNATURE NL
365 The "SIGNATURE" Object contains a signature (using the signing key) of
366 the PKCS#1 1.5 padded digest of the entire document, taken from the
367 beginning of the Initial item, through the newline after the Signature
368 Item's keyword and its arguments.
370 The signature does not include the algorithmIdentifier specified in PKCS #1.
372 Unless specified otherwise, the digest algorithm is SHA-1.
374 All documents are invalid unless signed with the correct signing key.
376 The "Digest" of a document, unless stated otherwise, is its digest *as
377 signed by this signature scheme*.
379 1.4. Voting timeline
381 Every consensus document has a "valid-after" (VA) time, a "fresh-until"
382 (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
383 in turn precede VU. Times are chosen so that every consensus will be
384 "fresh" until the next consensus becomes valid, and "valid" for a while
385 after. At least 3 consensuses should be valid at any given time.
387 The timeline for a given consensus is as follows:
389 VA-DistSeconds-VoteSeconds: The authorities exchange votes. Each authority
390 uploads their vote to all other authorities.
392 VA-DistSeconds-VoteSeconds/2: The authorities try to download any
393 votes they don't have.
395 Authorities SHOULD also reject any votes that other authorities try to
396 upload after this time. (0.4.4.1-alpha was the first version to reject votes
397 in this way.)
399 Note: Refusing late uploaded votes minimizes the chance of a consensus
400 split, particular when authorities are under bandwidth pressure. If an
401 authority is struggling to upload its vote, and finally uploads to a
402 fraction of authorities after this period, they will compute a consensus
403 different from the others. By refusing uploaded votes after this time,
404 we increase the likelihood that most authorities will use the same vote
405 set.
407 Rejecting late uploaded votes does not fix the problem entirely. If
408 some authorities are able to download a specific vote, but others fail
409 to do so, then there may still be a consensus split. However, this
410 change does remove one common cause of consensus splits.
412 VA-DistSeconds: The authorities calculate the consensus and exchange
413 signatures. (This is the earliest point at which anybody can
414 possibly get a given consensus if they ask for it.)
416 VA-DistSeconds/2: The authorities try to download any signatures
417 they don't have.
419 VA: All authorities have a multiply signed consensus.
421 VA ... FU: Caches download the consensus. (Note that since caches have
422 no way of telling what VA and FU are until they have downloaded
423 the consensus, they assume that the present consensus's VA is
424 equal to the previous one's FU, and that its FU is one interval after
425 that.)
427 FU: The consensus is no longer the freshest consensus.
429 FU ... (the current consensus's VU): Clients download the consensus.
430 (See note above: clients guess that the next consensus's FU will be
431 two intervals after the current VA.)
433 VU: The consensus is no longer valid; clients should continue to try to
434 download a new consensus if they have not done so already.
436 VU + 24 hours: Clients will no longer use the consensus at all.
438 VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
439 VU-FU MUST each be at least 5 minutes.
441 2. Router operation and formats
443 2.1. Uploading server descriptors and extra-info documents
445 ORs SHOULD generate a new server descriptor and a new extra-info
446 document whenever any of the following events have occurred:
448 - A period of time (18 hrs by default) has passed since the last
449 time a descriptor was generated.
451 - A descriptor field other than bandwidth or uptime has changed.
453 - Its uptime is less than 24h and bandwidth has changed by a factor of 2
454 from the last time a descriptor was generated, and at least a given
455 interval of time (3 hours by default) has passed since then.
457 - Its uptime has been reset (by restarting).
459 - It receives a networkstatus consensus in which it is not listed.
461 - It receives a networkstatus consensus in which it is listed
462 with the StaleDesc flag.
464 [XXX this list is incomplete; see router_differences_are_cosmetic()
465 in routerlist.c for others]
467 ORs SHOULD NOT publish a new server descriptor or extra-info document
468 if none of the above events have occurred and not much time has passed
469 (12 hours by default).
471 Tor versions older than 0.3.5.1-alpha ignore uptime when checking for
472 bandwidth changes.
474 After generating a descriptor, ORs upload them to every directory
475 authority they know, by posting them (in order) to the URL
477 http://<hostname:port>/tor/
479 Server descriptors may not exceed 20,000 bytes in length; extra-info
480 documents may not exceed 50,000 bytes in length. If they do, the
481 authorities SHOULD reject them.
483 2.1.1. Server descriptor format
485 Server descriptors consist of the following items.
487 In lines that take multiple arguments, extra arguments SHOULD be
488 accepted and ignored. Many of the nonterminals below are defined in
489 section 2.1.3.
491 Note that many versions of Tor will generate an extra newline at the
492 end of their descriptors. Implementations MUST tolerate one or
493 more blank lines at the end of a single descriptor or a list of
494 concatenated descriptors. New implementations SHOULD NOT generate
495 such blank lines.
497 "router" nickname address ORPort SOCKSPort DirPort NL
499 [At start, exactly once.]
501 Indicates the beginning of a server descriptor. "nickname" must be a
502 valid router nickname as specified in section 2.1.3. "address" must
503 be an IPv4
504 address in dotted-quad format. The last three numbers indicate the
505 TCP ports at which this OR exposes functionality. ORPort is a port at
506 which this OR accepts TLS connections for the main OR protocol;
507 SOCKSPort is deprecated and should always be 0; and DirPort is the
508 port at which this OR accepts directory-related HTTP connections. If
509 any port is not supported, the value 0 is given instead of a port
510 number. (At least one of DirPort and ORPort SHOULD be set;
511 authorities MAY reject any descriptor with both DirPort and ORPort of
512 0.)
514 "identity-ed25519" NL "-----BEGIN ED25519 CERT-----" NL certificate
515 "-----END ED25519 CERT-----" NL
517 [Exactly once, in second position in document.]
518 [No extra arguments]
520 The certificate is a base64-encoded Ed25519 certificate (see
521 cert-spec.txt) with terminating =s removed. When this element
522 is present, it MUST appear as the first or second element in
523 the router descriptor.
525 The certificate has CERT_TYPE of [04]. It must include a
526 signed-with-ed25519-key extension (see cert-spec.txt,
527 section 2.2.1), so that we can extract the master identity key.
529 [Before Tor 0.4.5.1-alpha, this field was optional.]
531 "master-key-ed25519" SP MasterKey NL
533 [Exactly once]
535 Contains the base-64 encoded ed25519 master key as a single
536 argument. If it is present, it MUST match the identity key
537 in the identity-ed25519 entry.
539 [Before Tor 0.4.5.1-alpha, this field was optional.]
541 "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
543 [Exactly once]
545 Estimated bandwidth for this router, in bytes per second. The
546 "average" bandwidth is the volume per second that the OR is willing to
547 sustain over long periods; the "burst" bandwidth is the volume that
548 the OR is willing to sustain in very short intervals. The "observed"
549 value is an estimate of the capacity this relay can handle. The
550 relay remembers the max bandwidth sustained output over any ten
551 second period in the past 5 days, and another sustained input. The
552 "observed" value is the lesser of these two numbers.
554 Tor versions released before 2018 only kept bandwidth-observed for one
555 day. These versions are no longer supported or recommended.
557 "platform" string NL
559 [At most once]
561 A human-readable string describing the system on which this OR is
562 running. This MAY include the operating system, and SHOULD include
563 the name and version of the software implementing the Tor protocol.
565 "published" YYYY-MM-DD HH:MM:SS NL
567 [Exactly once]
569 The time, in UTC, when this descriptor (and its corresponding
570 extra-info document if any) was generated.
572 "fingerprint" fingerprint NL
574 [At most once]
576 A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
577 hex, with a single space after every 4 characters) for this router's
578 identity key. A descriptor is considered invalid (and MUST be
579 rejected) if the fingerprint line does not match the public key.
581 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
582 be marked with "opt" until earlier versions of Tor are obsolete.]
584 "hibernating" bool NL
586 [At most once]
588 If the value is 1, then the Tor relay was hibernating when the
589 descriptor was published, and shouldn't be used to build circuits.
591 [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
592 marked with "opt" until earlier versions of Tor are obsolete.]
594 "uptime" number NL
596 [At most once]
598 The number of seconds that this OR process has been running.
600 "onion-key" NL a public key in PEM format
602 [Exactly once]
603 [No extra arguments]
605 This key is used to encrypt CREATE cells for this OR. The key MUST be
606 accepted for at least 1 week after any new key is published in a
607 subsequent descriptor. It MUST be 1024 bits.
609 The key encoding is the encoding of the key as a PKCS#1 RSAPublicKey
610 structure, encoded in base64, and wrapped in "-----BEGIN RSA PUBLIC
611 KEY-----" and "-----END RSA PUBLIC KEY-----".
613 "onion-key-crosscert" NL a RSA signature in PEM format.
615 [Exactly once]
616 [No extra arguments]
618 This element contains an RSA signature, generated using the
619 onion-key, of the following:
621 A SHA1 hash of the RSA identity key,
622 i.e. RSA key from "signing-key" (see below) [20 bytes]
623 The Ed25519 identity key,
624 i.e. Ed25519 key from "master-key-ed25519" [32 bytes]
626 If there is no Ed25519 identity key, or if in some future version
627 there is no RSA identity key, the corresponding field must be
628 zero-filled.
630 Parties verifying this signature MUST allow additional data
631 beyond the 52 bytes listed above.
633 This signature proves that the party creating the descriptor
634 had control over the secret key corresponding to the
635 onion-key.
637 [Before Tor 0.4.5.1-alpha, this field was optional whenever
638 identity-ed25519 was absent.]
640 "ntor-onion-key" base-64-encoded-key
642 [Exactly once]
644 A curve25519 public key used for the ntor circuit extended
645 handshake. It's the standard encoding of the OR's curve25519
646 public key, encoded in base 64. The trailing '=' sign MAY be
647 omitted from the base64 encoding. The key MUST be accepted
648 for at least 1 week after any new key is published in a
649 subsequent descriptor.
651 [Before Tor 0.4.5.1-alpha, this field was optional.]
653 "ntor-onion-key-crosscert" SP Bit NL
654 "-----BEGIN ED25519 CERT-----" NL certificate
655 "-----END ED25519 CERT-----" NL
657 [Exactly once]
658 [No extra arguments]
660 A signature created with the ntor-onion-key, using the
661 certificate format documented in cert-spec.txt, with type
662 [0a]. The signed key here is the master identity key.
664 Bit must be "0" or "1". It indicates the sign of the ed25519
665 public key corresponding to the ntor onion key. If Bit is "0",
666 then implementations MUST guarantee that the x-coordinate of
667 the resulting ed25519 public key is positive. Otherwise, if
668 Bit is "1", then the sign of the x-coordinate MUST be negative.
670 To compute the ed25519 public key corresponding to a curve25519
671 key, and for further explanation on key formats, see appendix C.
673 This signature proves that the party creating the descriptor
674 had control over the secret key corresponding to the
675 ntor-onion-key.
677 [Before Tor 0.4.5.1-alpha, this field was optional whenever
678 identity-ed25519 was absent.]
680 "signing-key" NL a public key in PEM format
682 [Exactly once]
683 [No extra arguments]
685 The OR's long-term RSA identity key. It MUST be 1024 bits.
687 The encoding is as for "onion-key" above.
689 "accept" exitpattern NL
690 "reject" exitpattern NL
692 [Any number]
694 These lines describe an "exit policy": the rules that an OR follows
695 when deciding whether to allow a new stream to a given address. The
696 'exitpattern' syntax is described below. There MUST be at least one
697 such entry. The rules are considered in order; if no rule matches,
698 the address will be accepted. For clarity, the last such entry SHOULD
699 be accept *:* or reject *:*.
701 "ipv6-policy" SP ("accept" / "reject") SP PortList NL
703 [At most once.]
705 An exit-policy summary as specified in sections 3.4.1 and 3.8.2,
706 summarizing
707 the router's rules for connecting to IPv6 addresses. A missing
708 "ipv6-policy" line is equivalent to "ipv6-policy reject
709 1-65535".
711 "overload-general" SP version SP YYYY-MM-DD HH:MM:SS NL
713 [At most once.]
715 Indicates that a relay has reached an "overloaded state" which can be
716 one or many of the following load metrics:
718 - Any OOM invocation due to memory pressure
719 - Any ntor onionskins are dropped
720 - TCP port exhaustion
722 The timestamp is when at least one metrics was detected. It should always
723 be at the hour and thus, as an example, "2020-01-10 13:00:00" is an
724 expected timestamp. Because this is a binary state, if the line is
725 present, we consider that it was hit at the very least once somewhere
726 between the provided timestamp and the "published" timestamp of the
727 document which is when the document was generated.
729 The overload-general line should remain in place for 72 hours since last
730 triggered. If the limits are reached again in this period, the timestamp
731 is updated, and this 72 hour period restarts.
733 The 'version' field is set to '1' for now.
735 (Introduced in tor-0.4.6.1-alpha, but moved from extra-info to general
736 descriptor in tor-0.4.6.2-alpha)
738 "router-sig-ed25519" SP Signature NL
740 [Exactly once.]
742 It MUST be the next-to-last element in the descriptor, appearing
743 immediately before the RSA signature. It MUST contain an Ed25519
744 signature of a SHA256 digest of the entire document. This digest is
745 taken from the first character up to and including the first space
746 after the "router-sig-ed25519" string. Before computing the digest,
747 the string "Tor router descriptor signature v1" is prefixed to the
748 document.
750 The signature is encoded in Base64, with terminating =s removed.
752 The signing key in the identity-ed25519 certificate MUST
753 be the one used to sign the document.
755 [Before Tor 0.4.5.1-alpha, this field was optional whenever
756 identity-ed25519 was absent.]
758 "router-signature" NL Signature NL
760 [At end, exactly once]
761 [No extra arguments]
763 The "SIGNATURE" object contains a signature of the PKCS1-padded
764 hash of the entire server descriptor, taken from the beginning of the
765 "router" line, through the newline after the "router-signature" line.
766 The server descriptor is invalid unless the signature is performed
767 with the router's identity key.
769 "contact" info NL
771 [At most once]
773 Describes a way to contact the relay's administrator, preferably
774 including an email address and a PGP key fingerprint.
776 "bridge-distribution-request" SP Method NL
778 [At most once, bridges only.]
780 The "Method" describes how a Bridge address is distributed by
781 BridgeDB. Recognized methods are: "none", "any", "https", "email",
782 "moat". If set to "none", BridgeDB will avoid distributing your bridge
783 address. If set to "any", BridgeDB will choose how to distribute your
784 bridge address. Choosing any of the other methods will tell BridgeDB to
785 distribute your bridge via a specific method:
787 - "https" specifies distribution via the web interface at
788 https://bridges.torproject.org;
789 - "email" specifies distribution via the email autoresponder at
790 bridges@torproject.org;
791 - "moat" specifies distribution via an interactive menu inside Tor
792 Browser; and
794 Potential future "Method" specifiers must be as follows:
795 Method = (KeywordChar | "_") +
797 All bridges SHOULD include this line. Non-bridges MUST NOT include
798 it.
800 BridgeDB SHOULD treat unrecognized Method values as if they were
801 "none".
803 (Default: "any")
805 [This line was introduced in 0.3.2.3-alpha, with a minimal backport
806 to 0.2.5.16, 0.2.8.17, 0.2.9.14, 0.3.0.13, 0.3.1.9, and later.]
808 "family" names NL
810 [At most once]
812 'Names' is a space-separated list of relay nicknames or
813 hexdigests. If two ORs list one another in their "family" entries,
814 then OPs should treat them as a single OR for the purpose of path
815 selection.
817 For example, if node A's descriptor contains "family B", and node B's
818 descriptor contains "family A", then node A and node B should never
819 be used on the same circuit.
821 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
822 [At most once]
823 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
824 [At most once]
826 (These fields once appeared in router descriptors, but have
827 appeared in extra-info descriptors since 0.2.0.x.)
829 "eventdns" bool NL
831 [At most once]
833 Declare whether this version of Tor is using the newer enhanced
834 dns logic. Versions of Tor with this field set to false SHOULD NOT
835 be used for reverse hostname lookups.
837 [This option is obsolete. All Tor current relays should be presumed
838 to have the evdns backend.]
840 "caches-extra-info" NL
842 [At most once.]
843 [No extra arguments]
845 Present only if this router is a directory cache that provides
846 extra-info documents.
848 [Versions before 0.2.0.1-alpha don't recognize this]
850 "extra-info-digest" SP sha1-digest [SP sha256-digest] NL
852 [At most once]
854 "sha1-digest" is a hex-encoded SHA1 digest (using upper-case characters)
855 of the router's extra-info document, as signed in the router's
856 extra-info (that is, not including the signature). (If this field is
857 absent, the router is not uploading a corresponding extra-info
858 document.)
860 "sha256-digest" is a base64-encoded SHA256 digest of the extra-info
861 document. Unlike the "sha1-digest", this digest is calculated over the
862 entire document, including the signature. This difference is due to
863 a long-lived bug in the tor implementation that it would be difficult
864 to roll out an incremental fix for, not a design choice. Future digest
865 algorithms specified should not include the signature in the data used
866 to compute the digest.
868 [Versions before 0.2.7.2-alpha did not include a SHA256 digest.]
869 [Versions before 0.2.0.1-alpha don't recognize this field at all.]
871 "hidden-service-dir" NL
873 [At most once.]
875 Present only if this router stores and serves hidden service
876 descriptors. This router supports the descriptor versions declared
877 in the HSDir "proto" entry. If there is no "proto" entry, this
878 router supports version 2 descriptors.
880 "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
881 CIRCUIT-VERSION-LIST NL
883 [At most once.]
885 An obsolete list of protocol versions, superseded by the "proto"
886 entry. This list was never parsed, and has not been emitted
887 since Tor 0.2.9.4-alpha. New code should neither generate nor
888 parse this line.
890 "allow-single-hop-exits" NL
892 [At most once.]
893 [No extra arguments]
895 Present only if the router allows single-hop circuits to make exit
896 connections. Most Tor relays do not support this: this is
897 included for specialized controllers designed to support perspective
898 access and such. This is obsolete in tor version >= 0.3.1.0-alpha.
900 "or-address" SP ADDRESS ":" PORT NL
902 [Any number]
904 ADDRESS = IP6ADDR | IP4ADDR
905 IPV6ADDR = an ipv6 address, surrounded by square brackets.
906 IPV4ADDR = an ipv4 address, represented as a dotted quad.
907 PORT = a number between 1 and 65535 inclusive.
909 An alternative for the address and ORPort of the "router" line, but with
910 two added capabilities:
912 * or-address can be either an IPv4 or IPv6 address
913 * or-address allows for multiple ORPorts and addresses
915 A descriptor SHOULD NOT include an or-address line that does nothing but
916 duplicate the address:port pair from its "router" line.
918 The ordering of or-address lines and their PORT entries matter because
919 Tor MAY accept a limited number of address/port pairs. As of
920 Tor 0.2.3.x only the first address/port pair is advertised and used.
922 "tunnelled-dir-server" NL
924 [At most once.]
925 [No extra arguments]
927 Present if the router accepts "tunneled" directory requests using a
928 BEGIN_DIR cell over the router's OR port.
929 (Added in 0.2.8.1-alpha. Before this, Tor relays accepted
930 tunneled directory requests only if they had a DirPort open,
931 or if they were bridges.)
933 "proto" SP Entries NL
935 [Exactly once.]
937 Entries =
938 Entries = Entry
939 Entries = Entry SP Entries
941 Entry = Keyword "=" Values
943 Values =
944 Values = Value
945 Values = Value "," Values
947 Value = Int
948 Value = Int "-" Int
950 Int = NON_ZERO_DIGIT
951 Int = Int DIGIT
953 Each 'Entry' in the "proto" line indicates that the Tor relay supports
954 one or more versions of the protocol in question. Entries should be
955 sorted by keyword. Values should be numerically ascending within each
956 entry. (This implies that there should be no overlapping ranges.)
957 Ranges should be represented as compactly as possible. Ints must be no
958 larger than 63.
960 This field was first added in Tor 0.2.9.x.
962 [Before Tor 0.4.5.1-alpha, this field was optional.]
965 2.1.2. Extra-info document format
967 Extra-info documents consist of the following items:
969 "extra-info" Nickname Fingerprint NL
970 [At start, exactly once.]
972 Identifies what router this is an extra-info descriptor for.
973 Fingerprint is encoded in hex (using upper-case letters), with
974 no spaces.
976 "identity-ed25519"
977 [As in router descriptors]
979 "published" YYYY-MM-DD HH:MM:SS NL
981 [Exactly once.]
983 The time, in UTC, when this document (and its corresponding router
984 descriptor if any) was generated. It MUST match the published time
985 in the corresponding server descriptor.
987 "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
988 [At most once.]
989 "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
990 [At most once.]
992 Declare how much bandwidth the OR has used recently. Usage is divided
993 into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
994 defines the end of the most recent interval. The numbers are the
995 number of bytes used in the most recent intervals, ordered from
996 oldest to newest.
998 These fields include both IPv4 and IPv6 traffic.
1000 "ipv6-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
1001 [At most once]
1002 "ipv6-write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
1003 [At most once]
1005 Declare how much bandwidth the OR has used recently, on IPv6
1006 connections. See "read-history" and "write-history" for full details.
1008 "geoip-db-digest" Digest NL
1009 [At most once.]
1011 SHA1 digest of the IPv4 GeoIP database file that is used to
1012 resolve IPv4 addresses to country codes.
1014 "geoip6-db-digest" Digest NL
1015 [At most once.]
1017 SHA1 digest of the IPv6 GeoIP database file that is used to
1018 resolve IPv6 addresses to country codes.
1020 ("geoip-start-time" YYYY-MM-DD HH:MM:SS NL)
1021 ("geoip-client-origins" CC=NUM,CC=NUM,... NL)
1023 Only generated by bridge routers (see blocking.pdf), and only
1024 when they have been configured with a geoip database.
1025 Non-bridges SHOULD NOT generate these fields. Contains a list
1026 of mappings from two-letter country codes (CC) to the number
1027 of clients that have connected to that bridge from that
1028 country (approximate, and rounded up to the nearest multiple of 8
1029 in order to hamper traffic analysis). A country is included
1030 only if it has at least one address. The time in
1031 "geoip-start-time" is the time at which we began collecting geoip
1032 statistics.
1034 "geoip-start-time" and "geoip-client-origins" have been replaced by
1035 "bridge-stats-end" and "bridge-ips" in 0.2.2.4-alpha. The
1036 reason is that the measurement interval with "geoip-stats" as
1037 determined by subtracting "geoip-start-time" from "published" could
1038 have had a variable length, whereas the measurement interval in
1039 0.2.2.4-alpha and later is set to be exactly 24 hours long. In
1040 order to clearly distinguish the new measurement intervals from
1041 the old ones, the new keywords have been introduced.
1043 "bridge-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1044 [At most once.]
1046 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1047 interval of length NSEC seconds (86400 seconds by default).
1049 A "bridge-stats-end" line, as well as any other "bridge-*" line,
1050 is only added when the relay has been running as a bridge for at
1051 least 24 hours.
1053 "bridge-ips" CC=NUM,CC=NUM,... NL
1054 [At most once.]
1056 List of mappings from two-letter country codes to the number of
1057 unique IP addresses that have connected from that country to the
1058 bridge and which are no known relays, rounded up to the nearest
1059 multiple of 8.
1061 "bridge-ip-versions" FAM=NUM,FAM=NUM,... NL
1062 [At most once.]
1064 List of unique IP addresses that have connected to the bridge
1065 per protocol family.
1067 "bridge-ip-transports" PT=NUM,PT=NUM,... NL
1068 [At most once.]
1070 List of mappings from pluggable transport names to the number
1071 of unique IP addresses that have connected using that
1072 pluggable transport. Unobfuscated connections are counted
1073 using the reserved pluggable transport name "<OR>" (without
1074 quotes). If we received a connection from a transport proxy
1075 but we couldn't figure out the name of the pluggable
1076 transport, we use the reserved pluggable transport name
1077 "<??>".
1079 ("<OR>" and "<??>" are reserved because normal pluggable
1080 transport names MUST match the following regular expression:
1081 "[a-zA-Z_][a-zA-Z0-9_]*" )
1083 The pluggable transport name list is sorted into lexically
1084 ascending order.
1086 If no clients have connected to the bridge yet, we only write
1087 "bridge-ip-transports" to the stats file.
1089 "dirreq-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1090 [At most once.]
1092 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1093 interval of length NSEC seconds (86400 seconds by default).
1095 A "dirreq-stats-end" line, as well as any other "dirreq-*" line,
1096 is only added when the relay has opened its Dir port and after 24
1097 hours of measuring directory requests.
1099 "dirreq-v2-ips" CC=NUM,CC=NUM,... NL
1100 [At most once.]
1101 "dirreq-v3-ips" CC=NUM,CC=NUM,... NL
1102 [At most once.]
1104 List of mappings from two-letter country codes to the number of
1105 unique IP addresses that have connected from that country to
1106 request a v2/v3 network status, rounded up to the nearest multiple
1107 of 8. Only those IP addresses are counted that the directory can
1108 answer with a 200 OK status code. (Note here and below: current Tor
1109 versions, as of 0.2.5.2-alpha, no longer cache or serve v2
1110 networkstatus documents.)
1112 "dirreq-v2-reqs" CC=NUM,CC=NUM,... NL
1113 [At most once.]
1114 "dirreq-v3-reqs" CC=NUM,CC=NUM,... NL
1115 [At most once.]
1117 List of mappings from two-letter country codes to the number of
1118 requests for v2/v3 network statuses from that country, rounded up
1119 to the nearest multiple of 8. Only those requests are counted that
1120 the directory can answer with a 200 OK status code.
1122 "dirreq-v2-share" NUM% NL
1123 [At most once.]
1124 "dirreq-v3-share" NUM% NL
1125 [At most once.]
1127 The share of v2/v3 network status requests that the directory
1128 expects to receive from clients based on its advertised bandwidth
1129 compared to the overall network bandwidth capacity. Shares are
1130 formatted in percent with two decimal places. Shares are
1131 calculated as means over the whole 24-hour interval.
1133 "dirreq-v2-resp" status=NUM,... NL
1134 [At most once.]
1135 "dirreq-v3-resp" status=NUM,... NL
1136 [At most once.]
1138 List of mappings from response statuses to the number of requests
1139 for v2/v3 network statuses that were answered with that response
1140 status, rounded up to the nearest multiple of 4. Only response
1141 statuses with at least 1 response are reported. New response
1142 statuses can be added at any time. The current list of response
1143 statuses is as follows:
1145 "ok": a network status request is answered; this number
1146 corresponds to the sum of all requests as reported in
1147 "dirreq-v2-reqs" or "dirreq-v3-reqs", respectively, before
1148 rounding up.
1149 "not-enough-sigs: a version 3 network status is not signed by a
1150 sufficient number of requested authorities.
1151 "unavailable": a requested network status object is unavailable.
1152 "not-found": a requested network status is not found.
1153 "not-modified": a network status has not been modified since the
1154 If-Modified-Since time that is included in the request.
1155 "busy": the directory is busy.
1157 "dirreq-v2-direct-dl" key=NUM,... NL
1158 [At most once.]
1159 "dirreq-v3-direct-dl" key=NUM,... NL
1160 [At most once.]
1161 "dirreq-v2-tunneled-dl" key=NUM,... NL
1162 [At most once.]
1163 "dirreq-v3-tunneled-dl" key=NUM,... NL
1164 [At most once.]
1166 List of statistics about possible failures in the download process
1167 of v2/v3 network statuses. Requests are either "direct"
1168 HTTP-encoded requests over the relay's directory port, or
1169 "tunneled" requests using a BEGIN_DIR cell over the relay's OR
1170 port. The list of possible statistics can change, and statistics
1171 can be left out from reporting. The current list of statistics is
1172 as follows:
1174 Successful downloads and failures:
1176 "complete": a client has finished the download successfully.
1177 "timeout": a download did not finish within 10 minutes after
1178 starting to send the response.
1179 "running": a download is still running at the end of the
1180 measurement period for less than 10 minutes after starting to
1181 send the response.
1183 Download times:
1185 "min", "max": smallest and largest measured bandwidth in B/s.
1186 "d[1-4,6-9]": 1st to 4th and 6th to 9th decile of measured
1187 bandwidth in B/s. For a given decile i, i/10 of all downloads
1188 had a smaller bandwidth than di, and (10-i)/10 of all downloads
1189 had a larger bandwidth than di.
1190 "q[1,3]": 1st and 3rd quartile of measured bandwidth in B/s. One
1191 fourth of all downloads had a smaller bandwidth than q1, one
1192 fourth of all downloads had a larger bandwidth than q3, and the
1193 remaining half of all downloads had a bandwidth between q1 and
1194 q3.
1195 "md": median of measured bandwidth in B/s. Half of the downloads
1196 had a smaller bandwidth than md, the other half had a larger
1197 bandwidth than md.
1199 "dirreq-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
1200 [At most once]
1201 "dirreq-write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
1202 [At most once]
1204 Declare how much bandwidth the OR has spent on answering directory
1205 requests. Usage is divided into intervals of NSEC seconds. The
1206 YYYY-MM-DD HH:MM:SS field defines the end of the most recent
1207 interval. The numbers are the number of bytes used in the most
1208 recent intervals, ordered from oldest to newest.
1210 "entry-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1211 [At most once.]
1213 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1214 interval of length NSEC seconds (86400 seconds by default).
1216 An "entry-stats-end" line, as well as any other "entry-*"
1217 line, is first added after the relay has been running for at least
1218 24 hours.
1220 "entry-ips" CC=NUM,CC=NUM,... NL
1221 [At most once.]
1223 List of mappings from two-letter country codes to the number of
1224 unique IP addresses that have connected from that country to the
1225 relay and which are no known other relays, rounded up to the
1226 nearest multiple of 8.
1228 "cell-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1229 [At most once.]
1231 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1232 interval of length NSEC seconds (86400 seconds by default).
1234 A "cell-stats-end" line, as well as any other "cell-*" line,
1235 is first added after the relay has been running for at least 24
1236 hours.
1238 "cell-processed-cells" NUM,...,NUM NL
1239 [At most once.]
1241 Mean number of processed cells per circuit, subdivided into
1242 deciles of circuits by the number of cells they have processed in
1243 descending order from loudest to quietest circuits.
1245 "cell-queued-cells" NUM,...,NUM NL
1246 [At most once.]
1248 Mean number of cells contained in queues by circuit decile. These
1249 means are calculated by 1) determining the mean number of cells in
1250 a single circuit between its creation and its termination and 2)
1251 calculating the mean for all circuits in a given decile as
1252 determined in "cell-processed-cells". Numbers have a precision of
1253 two decimal places.
1255 Note that this statistic can be inaccurate for circuits that had
1256 queued cells at the start or end of the measurement interval.
1258 "cell-time-in-queue" NUM,...,NUM NL
1259 [At most once.]
1261 Mean time cells spend in circuit queues in milliseconds. Times are
1262 calculated by 1) determining the mean time cells spend in the
1263 queue of a single circuit and 2) calculating the mean for all
1264 circuits in a given decile as determined in
1265 "cell-processed-cells".
1267 Note that this statistic can be inaccurate for circuits that had
1268 queued cells at the start or end of the measurement interval.
1270 "cell-circuits-per-decile" NUM NL
1271 [At most once.]
1273 Mean number of circuits that are included in any of the deciles,
1274 rounded up to the next integer.
1276 "conn-bi-direct" YYYY-MM-DD HH:MM:SS (NSEC s) BELOW,READ,WRITE,BOTH NL
1277 [At most once]
1279 Number of connections, split into 10-second intervals, that are
1280 used uni-directionally or bi-directionally as observed in the NSEC
1281 seconds (usually 86400 seconds) before YYYY-MM-DD HH:MM:SS. Every
1282 10 seconds, we determine for every connection whether we read and
1283 wrote less than a threshold of 20 KiB (BELOW), read at least 10
1284 times more than we wrote (READ), wrote at least 10 times more than
1285 we read (WRITE), or read and wrote more than the threshold, but
1286 not 10 times more in either direction (BOTH). After classifying a
1287 connection, read and write counters are reset for the next
1288 10-second interval.
1290 This measurement includes both IPv4 and IPv6 connections.
1292 "ipv6-conn-bi-direct" YYYY-MM-DD HH:MM:SS (NSEC s) BELOW,READ,WRITE,BOTH NL
1293 [At most once]
1295 Number of IPv6 connections that are used uni-directionally or
1296 bi-directionally. See "conn-bi-direct" for more details.
1298 "exit-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1299 [At most once.]
1301 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1302 interval of length NSEC seconds (86400 seconds by default).
1304 An "exit-stats-end" line, as well as any other "exit-*" line, is
1305 first added after the relay has been running for at least 24 hours
1306 and only if the relay permits exiting (where exiting to a single
1307 port and IP address is sufficient).
1309 "exit-kibibytes-written" port=N,port=N,... NL
1310 [At most once.]
1311 "exit-kibibytes-read" port=N,port=N,... NL
1312 [At most once.]
1314 List of mappings from ports to the number of kibibytes that the
1315 relay has written to or read from exit connections to that port,
1316 rounded up to the next full kibibyte. Relays may limit the
1317 number of listed ports and subsume any remaining kibibytes under
1318 port "other".
1320 "exit-streams-opened" port=N,port=N,... NL
1321 [At most once.]
1323 List of mappings from ports to the number of opened exit streams
1324 to that port, rounded up to the nearest multiple of 4. Relays may
1325 limit the number of listed ports and subsume any remaining opened
1326 streams under port "other".
1328 "hidserv-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1329 [At most once.]
1330 "hidserv-v3-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
1331 [At most once.]
1333 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1334 interval of length NSEC seconds (86400 seconds by default).
1336 A "hidserv-stats-end" line, as well as any other "hidserv-*" line,
1337 is first added after the relay has been running for at least 24
1338 hours.
1340 (Introduced in tor-0.4.6.1-alpha)
1342 "hidserv-rend-relayed-cells" SP NUM SP key=val SP key=val ... NL
1343 [At most once.]
1344 "hidserv-rend-v3-relayed-cells" SP NUM SP key=val SP key=val ... NL
1345 [At most once.]
1347 Approximate number of RELAY cells seen in either direction on a
1348 circuit after receiving and successfully processing a RENDEZVOUS1
1349 cell.
1351 The original measurement value is obfuscated in several steps:
1352 first, it is rounded up to the nearest multiple of 'bin_size'
1353 which is reported in the key=val part of this line; second, a
1354 (possibly negative) noise value is added to the result of the
1355 first step by randomly sampling from a Laplace distribution with
1356 mu = 0 and b = (delta_f / epsilon) with 'delta_f' and 'epsilon'
1357 being reported in the key=val part, too; third, the result of the
1358 previous obfuscation steps is truncated to the next smaller
1359 integer and included as 'NUM'. Note that the overall reported
1360 value can be negative.
1362 (Introduced in tor-0.4.6.1-alpha)
1364 "hidserv-dir-onions-seen" SP NUM SP key=val SP key=val ... NL
1365 [At most once.]
1366 "hidserv-dir-v3-onions-seen" SP NUM SP key=val SP key=val ... NL
1367 [At most once.]
1369 Approximate number of unique hidden-service identities seen in
1370 descriptors published to and accepted by this hidden-service
1371 directory.
1373 The original measurement value is obfuscated in the same way as
1374 the 'NUM' value reported in "hidserv-rend-relayed-cells", but
1375 possibly with different parameters as reported in the key=val part
1376 of this line. Note that the overall reported value can be
1377 negative.
1379 (Introduced in tor-0.4.6.1-alpha)
1381 "transport" transportname address:port [arglist] NL
1382 [Any number.]
1384 Signals that the router supports the 'transportname' pluggable
1385 transport in IP address 'address' and TCP port 'port'. A single
1386 descriptor MUST not have more than one transport line with the
1387 same 'transportname'.
1389 Pluggable transports are only relevant to bridges, but these entries
1390 can appear in non-bridge relays as well.
1392 "padding-counts" YYYY-MM-DD HH:MM:SS (NSEC s) key=NUM key=NUM ... NL
1393 [At most once.]
1395 YYYY-MM-DD HH:MM:SS defines the end of the included measurement
1396 interval of length NSEC seconds (86400 seconds by default). Counts
1397 are reset to 0 at the end of this interval.
1399 The keyword list is currently as follows:
1401 bin-size
1402 - The current rounding value for cell count fields (10000 by
1403 default)
1404 write-drop
1405 - The number of RELAY_DROP cells this relay sent
1406 write-pad
1407 - The number of CELL_PADDING cells this relay sent
1408 write-total
1409 - The total number of cells this relay cent
1410 read-drop
1411 - The number of RELAY_DROP cells this relay received
1412 read-pad
1413 - The number of CELL_PADDING cells this relay received
1414 read-total
1415 - The total number of cells this relay received
1416 enabled-read-pad
1417 - The number of CELL_PADDING cells this relay received on
1418 connections that support padding
1419 enabled-read-total
1420 - The total number of cells this relay received on connections
1421 that support padding
1422 enabled-write-pad
1423 - The total number of cells this relay received on connections
1424 that support padding
1425 enabled-write-total
1426 - The total number of cells sent by this relay on connections
1427 that support padding
1428 max-chanpad-timers
1429 - The maximum number of timers that this relay scheduled for
1430 padding in the previous NSEC interval
1432 "overload-ratelimits" SP version SP YYYY-MM-DD SP HH:MM:SS
1433 SP rate-limit SP burst-limit
1434 SP read-overload-count SP write-overload-count NL
1435 [At most once.]
1437 Indicates that a bandwidth limit was exhausted for this relay.
1439 The "rate-limit" and "burst-limit" are the raw values from the
1440 BandwidthRate and BandwidthBurst found in the torrc configuration file.
1442 The "{read|write}-overload-count" are the counts of how many times the
1443 reported limits of burst/rate were exhausted and thus the maximum
1444 between the read and write count occurrences. To make the counter more
1445 meaningful and to avoid multiple connections saturating the counter
1446 when a relay is overloaded, we only increment it once a minute.
1448 The 'version' field is set to '1' for now.
1450 (Introduced in tor-0.4.6.1-alpha)
1452 "overload-fd-exhausted" SP version YYYY-MM-DD HH:MM:SS NL
1453 [At most once.]
1455 Indicates that a file descriptor exhaustion was experienced by this
1456 relay.
1458 The timestamp indicates that the maximum was reached between the
1459 timestamp and the "published" timestamp of the document.
1461 This overload field should remain in place for 72 hours since last
1462 triggered. If the limits are reached again in this period, the
1463 timestamp is updated, and this 72 hour period restarts.
1465 The 'version' field is set to '1' for the initial implementation which
1466 detects fd exhaustion only when a socket open fails.
1468 (Introduced in tor-0.4.6.1-alpha)
1470 "router-sig-ed25519"
1471 [As in router descriptors]
1473 "router-signature" NL Signature NL
1474 [At end, exactly once.]
1475 [No extra arguments]
1477 A document signature as documented in section 1.3, using the
1478 initial item "extra-info" and the final item "router-signature",
1479 signed with the router's identity key.
1481 2.1.3. Nonterminals in server descriptors
1483 nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
1484 case-insensitive.
1485 hexdigest ::= a '$', followed by 40 hexadecimal characters
1486 ([A-Fa-f0-9]). [Represents a relay by the digest of its identity
1487 key.]
1489 exitpattern ::= addrspec ":" portspec
1490 portspec ::= "*" | port | port "-" port
1491 port ::= an integer between 1 and 65535, inclusive.
1493 [Some implementations incorrectly generate ports with value 0.
1494 Implementations SHOULD accept this, and SHOULD NOT generate it.
1495 Connections to port 0 are never permitted.]
1497 addrspec ::= "*" | ip4spec | ip6spec
1498 ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
1499 ip4 ::= an IPv4 address in dotted-quad format
1500 ip4mask ::= an IPv4 mask in dotted-quad format
1501 num_ip4_bits ::= an integer between 0 and 32
1502 ip6spec ::= ip6 | ip6 "/" num_ip6_bits
1503 ip6 ::= an IPv6 address, surrounded by square brackets.
1504 num_ip6_bits ::= an integer between 0 and 128
1506 bool ::= "0" | "1"
1508 3. Directory authority operation and formats
1510 Every authority has two keys used in this protocol: a signing key, and
1511 an authority identity key. (Authorities also have a router identity
1512 key used in their role as a router and by earlier versions of the
1513 directory protocol.) The identity key is used from time to time to
1514 sign new key certificates using new signing keys; it is very sensitive.
1515 The signing key is used to sign key certificates and status documents.
1517 3.1. Creating key certificates
1519 Key certificates consist of the following items:
1521 "dir-key-certificate-version" version NL
1523 [At start, exactly once.]
1525 Determines the version of the key certificate. MUST be "3" for
1526 the protocol described in this document. Implementations MUST
1527 reject formats they don't understand.
1529 "dir-address" IPPort NL
1530 [At most once]
1532 An IP:Port for this authority's directory port.
1534 "fingerprint" fingerprint NL
1536 [Exactly once.]
1538 Hexadecimal encoding without spaces based on the authority's
1539 identity key.
1541 "dir-identity-key" NL a public key in PEM format
1543 [Exactly once.]
1544 [No extra arguments]
1546 The long-term authority identity key for this authority. This key
1547 SHOULD be at least 2048 bits long; it MUST NOT be shorter than
1548 1024 bits.
1550 "dir-key-published" YYYY-MM-DD HH:MM:SS NL
1552 [Exactly once.]
1554 The time (in UTC) when this document and corresponding key were
1555 last generated.
1557 Implementations SHOULD reject certificates that are published
1558 too far in the future, though they MAY tolerate some clock skew.
1560 "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
1562 [Exactly once.]
1564 A time (in UTC) after which this key is no longer valid.
1566 Implementations SHOULD reject expired certificates, though they
1567 MAY tolerate some clock skew.
1569 "dir-signing-key" NL a key in PEM format
1571 [Exactly once.]
1572 [No extra arguments]
1574 The directory server's public signing key. This key MUST be at
1575 least 1024 bits, and MAY be longer.
1577 "dir-key-crosscert" NL CrossSignature NL
1579 [Exactly once.]
1580 [No extra arguments]
1582 CrossSignature is a signature, made using the certificate's signing
1583 key, of the digest of the PKCS1-padded hash of the certificate's
1584 identity key. For backward compatibility with broken versions of the
1585 parser, we wrap the base64-encoded signature in -----BEGIN ID
1586 SIGNATURE---- and -----END ID SIGNATURE----- tags. Implementations
1587 MUST allow the "ID " portion to be omitted, however.
1589 Implementations MUST verify that the signature is a correct signature
1590 of the hash of the identity key using the signing key.
1592 "dir-key-certification" NL Signature NL
1594 [At end, exactly once.]
1595 [No extra arguments]
1597 A document signature as documented in section 1.3, using the
1598 initial item "dir-key-certificate-version" and the final item
1599 "dir-key-certification", signed with the authority identity key.
1601 Authorities MUST generate a new signing key and corresponding
1602 certificate before the key expires.
1604 3.2. Accepting server descriptor and extra-info document uploads
1606 When a router posts a signed descriptor to a directory authority, the
1607 authority first checks whether it is well-formed and correctly
1608 self-signed. If it is, the authority next verifies that the nickname
1609 in question is not already assigned to a router with a different
1610 public key.
1611 Finally, the authority MAY check that the router is not blacklisted
1612 because of its key, IP, or another reason.
1614 An authority also keeps a record of all the Ed25519/RSA1024
1615 identity key pairs that it has seen before. It rejects any
1616 descriptor that has a known Ed/RSA identity key that it has
1617 already seen accompanied by a different RSA/Ed identity key
1618 in an older descriptor.
1620 At a future date, authorities will begin rejecting all
1621 descriptors whose RSA key was previously accompanied by an
1622 Ed25519 key, if the descriptor does not list an Ed25519 key.
1624 At a future date, authorities will begin rejecting all descriptors
1625 that do not list an Ed25519 key.
1627 If the descriptor passes these tests, and the authority does not already
1628 have a descriptor for a router with this public key, it accepts the
1629 descriptor and remembers it.
1631 If the authority _does_ have a descriptor with the same public key, the
1632 newly uploaded descriptor is remembered if its publication time is more
1633 recent than the most recent old descriptor for that router, and either:
1635 - There are non-cosmetic differences between the old descriptor and the
1636 new one.
1637 - Enough time has passed between the descriptors' publication times.
1638 (Currently, 2 hours.)
1640 Differences between server descriptors are "non-cosmetic" if they would be
1641 sufficient to force an upload as described in section 2.1 above.
1643 Note that the "cosmetic difference" test only applies to uploaded
1644 descriptors, not to descriptors that the authority downloads from other
1645 authorities.
1647 When a router posts a signed extra-info document to a directory authority,
1648 the authority again checks it for well-formedness and correct signature,
1649 and checks that its matches the extra-info-digest in some router
1650 descriptor that it believes is currently useful. If so, it accepts it and
1651 stores it and serves it as requested. If not, it drops it.
1654 3.3. Computing microdescriptors
1656 Microdescriptors are a stripped-down version of server descriptors
1657 generated by the directory authorities which may additionally contain
1658 authority-generated information. Microdescriptors contain only the
1659 most relevant parts that clients care about. Microdescriptors are
1660 expected to be relatively static and only change about once per week.
1661 Microdescriptors do not contain any information that clients need to
1662 use to decide which servers to fetch information about, or which
1663 servers to fetch information from.
1665 Microdescriptors are a straight transform from the server descriptor
1666 and the consensus method. Microdescriptors have no header or footer.
1667 Microdescriptors are identified by the hash of its concatenated
1668 elements without a signature by the router. Microdescriptors do not
1669 contain any version information, because their version is determined
1670 by the consensus method.
1672 Starting with consensus method 8, microdescriptors contain the
1673 following elements taken from or based on the server descriptor. Order
1674 matters here, because different directory authorities must be able to
1675 transform a given server descriptor and consensus method into the exact
1676 same microdescriptor.
1678 "onion-key" NL a public key in PEM format
1680 [Exactly once, at start]
1681 [No extra arguments]
1683 The "onion-key" element as specified in section 2.1.1.
1685 When generating microdescriptors for consensus method 30 or later,
1686 the trailing = sign must be absent. For consensus method 29 or
1687 earlier, the trailing = sign must be present.
1689 "ntor-onion-key" SP base-64-encoded-key NL
1691 [Exactly once]
1693 The "ntor-onion-key" element as specified in section 2.1.1.
1695 (Only included when generating microdescriptors for
1696 consensus-method 16 or later.)
1698 [Before Tor 0.4.5.1-alpha, this field was optional.]
1700 "a" SP address ":" port NL
1702 [Any number]
1704 Additional advertised addresses for the OR.
1706 Present currently only if the OR advertises at least one IPv6
1707 address; currently, the first address is included and all others are
1708 omitted. Any other IPv4 or IPv6 addresses should be ignored.
1710 Address and port are as for "or-address" as specified in
1711 section 2.1.1.
1713 (Only included when generating microdescriptors for
1714 consensus-methods 14 to 27.)
1716 "family" names NL
1718 [At most once]
1720 The "family" element as specified in section 2.1.1.
1722 When generating microdescriptors for consensus method 29 or later,
1723 the following canonicalization algorithm is applied to improve
1724 compression:
1726 For all entries of the form $hexid=name or $hexid~name,
1727 remove the =name or ~name portion.
1729 Remove all entries of the form $hexid, where hexid is not
1730 40 hexadecimal characters long.
1732 If an entry is a valid nickname, put it into lower case.
1734 If an entry is a valid $hexid, put it into upper case.
1736 If there are any entries, add a single $hexid entry for
1737 the relay in question, so that it is a member of its own
1738 family.
1740 Sort all entries in lexical order.
1742 Remove duplicate entries.
1744 (Note that if an entry is not of the form "nickname", "$hexid",
1745 "$hexid=nickname" or "$hexid~nickname", then it will be unchanged:
1746 this is what makes the algorithm forward-compatible.)
1748 "p" SP ("accept" / "reject") SP PortList NL
1750 [Exactly once.]
1752 The exit-policy summary as specified in sections 3.4.1 and 3.8.2.
1754 [With microdescriptors, clients don't learn exact exit policies:
1755 clients can only guess whether a relay accepts their request, try the
1756 BEGIN request, and might get end-reason-exit-policy if they guessed
1757 wrong, in which case they'll have to try elsewhere.]
1759 [In consensus methods before 5, this line was omitted.]
1761 "p6" SP ("accept" / "reject") SP PortList NL
1763 [At most once]
1765 The IPv6 exit policy summary as specified in sections 3.4.1 and
1766 3.8.2. A missing "p6" line is equivalent to "p6 reject 1-65535".
1768 (Only included when generating microdescriptors for
1769 consensus-method 15 or later.)
1771 "id" SP "rsa1024" SP base64-encoded-identity-digest NL
1773 [At most once]
1775 The node identity digest (as described in tor-spec.txt), base64
1776 encoded, without trailing =s. This line is included to prevent
1777 collisions between microdescriptors.
1779 Implementations SHOULD ignore these lines: they are
1780 added to microdescriptors only to prevent collisions.
1782 (Only included when generating microdescriptors for
1783 consensus-method 18 or later.)
1785 "id" SP "ed25519" SP base64-encoded-ed25519-identity NL
1787 [At most once]
1789 The node's master Ed25519 identity key, base64 encoded,
1790 without trailing =s.
1792 All implementations MUST ignore this key for any microdescriptor
1793 whose corresponding entry in the consensus includes the
1794 'NoEdConsensus' flag.
1796 (Only included when generating microdescriptors for
1797 consensus-method 21 or later.)
1799 "id" SP keytype ... NL
1801 [At most once per distinct keytype.]
1803 Implementations MUST ignore "id" lines with unrecognized
1804 key-types in place of "rsa1024" or "ed25519"
1806 "pr" SP Entries NL
1808 [Exactly once.]
1810 The "proto" element as specified in section 2.1.1.
1812 [Before Tor 0.4.5.1-alpha, this field was optional.]
1814 (Note that with microdescriptors, clients do not learn the RSA identity of
1815 their routers: they only learn a hash of the RSA identity key. This is
1816 all they need to confirm the actual identity key when doing a TLS
1817 handshake, and all they need to put the identity key digest in their
1818 CREATE cells.)
1820 3.4. Exchanging votes
1822 Authorities divide time into Intervals. Authority administrators SHOULD
1823 try to all pick the same interval length, and SHOULD pick intervals that
1824 are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
1825 minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
1826 divide evenly into a 24-hour day.
1828 Authorities SHOULD act according to interval and delays in the
1829 latest consensus. Lacking a latest consensus, they SHOULD default to a
1830 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
1832 Authorities MUST take pains to ensure that their clocks remain accurate
1833 within a few seconds. (Running NTP is usually sufficient.)
1835 The first voting period of each day begins at 00:00 (midnight) UTC. If
1836 the last period of the day would be truncated by one-half or more, it is
1837 merged with the second-to-last period.
1839 An authority SHOULD publish its vote immediately at the start of each voting
1840 period (minus VoteSeconds+DistSeconds). It does this by making it
1841 available at
1843 http://<hostname>/tor/status-vote/next/authority.z
1845 and sending it in an HTTP POST request to each other authority at the URL
1847 http://<hostname>/tor/post/vote
1849 If, at the start of the voting period, minus DistSeconds, an authority
1850 does not have a current statement from another authority, the first
1851 authority downloads the other's statement.
1853 Once an authority has a vote from another authority, it makes it available
1854 at
1856 http://<hostname>/tor/status-vote/next/<fp>.z
1858 where <fp> is the fingerprint of the other authority's identity key.
1859 And at
1861 http://<hostname>/tor/status-vote/next/d/<d>.z
1863 where <d> is the digest of the vote document.
1865 Also, once an authority receives a vote from another authority, it
1866 examines it for new descriptors and fetches them from that authority.
1867 This may be the only way for an authority to hear about relays that didn't
1868 publish their descriptor to all authorities, and, while it's too late
1869 for the authority to include relays in its current vote, it can include
1870 them in its next vote. See section 3.6 below for details.
1872 3.4.1. Vote and consensus status document formats
1874 Votes and consensuses are more strictly formatted than other documents
1875 in this specification, since different authorities must be able to
1876 generate exactly the same consensus given the same set of votes.
1878 The procedure for deciding when to generate vote and consensus status
1879 documents are described in section 1.4 on the voting timeline.
1881 Status documents contain a preamble, an authority section, a list of
1882 router status entries, and one or more footer signature, in that order.
1884 Unlike other formats described above, a SP in these documents must be a
1885 single space character (hex 20).
1887 Some items appear only in votes, and some items appear only in
1888 consensuses. Unless specified, items occur in both.
1890 The preamble contains the following items. They SHOULD occur in the
1891 order given here:
1893 "network-status-version" SP version NL
1895 [At start, exactly once.]
1897 A document format version. For this specification, the version is
1898 "3".
1900 "vote-status" SP type NL
1902 [Exactly once.]
1904 The status MUST be "vote" or "consensus", depending on the type of
1905 the document.
1907 "consensus-methods" SP IntegerList NL
1909 [At most once for votes; does not occur in consensuses.]
1911 A space-separated list of supported methods for generating
1912 consensuses from votes. See section 3.8.1 for details. Absence of
1913 the line means that only method "1" is supported.
1915 "consensus-method" SP Integer NL
1917 [At most once for consensuses; does not occur in votes.]
1918 [No extra arguments]
1920 See section 3.8.1 for details.
1922 (Only included when the vote is generated with consensus-method 2 or
1923 later.)
1925 "published" SP YYYY-MM-DD SP HH:MM:SS NL
1927 [Exactly once for votes; does not occur in consensuses.]
1929 The publication time for this status document (if a vote).
1931 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
1933 [Exactly once.]
1935 The start of the Interval for this vote. Before this time, the
1936 consensus document produced from this vote is not officially in
1937 use.
1939 (Note that because of propagation delays, clients and relays
1940 may see consensus documents that are up to `DistSeconds`
1941 earlier than this time, and should not warn about them.)
1943 See section 1.4 for voting timeline information.
1945 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
1947 [Exactly once.]
1949 The time at which the next consensus should be produced; before this
1950 time, there is no point in downloading another consensus, since there
1951 won't be a new one. See section 1.4 for voting timeline information.
1953 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
1955 [Exactly once.]
1957 The end of the Interval for this vote. After this time, all
1958 clients should try to find a more recent consensus. See section 1.4
1959 for voting timeline information.
1961 In practice, clients continue to use the consensus for up to 24 hours
1962 after it is no longer valid, if no more recent consensus can be
1963 downloaded.
1965 "voting-delay" SP VoteSeconds SP DistSeconds NL
1967 [Exactly once.]
1969 VoteSeconds is the number of seconds that we will allow to collect
1970 votes from all authorities; DistSeconds is the number of seconds
1971 we'll allow to collect signatures from all authorities. See
1972 section 1.4 for voting timeline information.
1974 "client-versions" SP VersionList NL
1976 [At most once.]
1978 A comma-separated list of recommended Tor versions for client
1979 usage, in ascending order. The versions are given as defined by
1980 version-spec.txt. If absent, no opinion is held about client
1981 versions.
1983 "server-versions" SP VersionList NL
1985 [At most once.]
1987 A comma-separated list of recommended Tor versions for relay
1988 usage, in ascending order. The versions are given as defined by
1989 version-spec.txt. If absent, no opinion is held about server
1990 versions.
1992 "package" SP PackageName SP Version SP URL SP DIGESTS NL
1994 [Any number of times.]
1996 For this element:
1998 PACKAGENAME = NONSPACE
1999 VERSION = NONSPACE
2000 URL = NONSPACE
2001 DIGESTS = DIGEST | DIGESTS SP DIGEST
2002 DIGEST = DIGESTTYPE "=" DIGESTVAL
2003 NONSPACE = one or more non-space printing characters
2004 DIGESTVAL = DIGESTTYPE = one or more non-space printing characters
2005 other than "=".
2007 Indicates that a package called "package" of version VERSION may be
2008 found at URL, and its digest as computed with DIGESTTYPE is equal to
2009 DIGESTVAL. In consensuses, these lines are sorted lexically by
2010 "PACKAGENAME VERSION" pairs, and DIGESTTYPES must appear in ascending
2011 order. A consensus must not contain the same "PACKAGENAME VERSION"
2012 more than once. If a vote contains the same "PACKAGENAME VERSION"
2013 more than once, all but the last is ignored.
2015 Included in consensuses only for methods 19-33. Earlier methods
2016 did not include this; method 34 removed it.
2018 "known-flags" SP FlagList NL
2020 [Exactly once.]
2022 A space-separated list of all of the flags that this document
2023 might contain. A flag is "known" either because the authority
2024 knows about them and might set them (if in a vote), or because
2025 enough votes were counted for the consensus for an authoritative
2026 opinion to have been formed about their status.
2028 "flag-thresholds" SP Thresholds NL
2030 [At most once for votes; does not occur in consensuses.]
2032 A space-separated list of the internal performance thresholds
2033 that the directory authority had at the moment it was forming
2034 a vote.
2036 The metaformat is:
2037 Thresholds = Threshold | Threshold SP Thresholds
2038 Threshold = ThresholdKey '=' ThresholdVal
2039 ThresholdKey = (KeywordChar | "_") +
2040 ThresholdVal = [0-9]+("."[0-9]+)? "%"?
2042 Commonly used Thresholds at this point include:
2044 "stable-uptime" -- Uptime (in seconds) required for a relay
2045 to be marked as stable.
2047 "stable-mtbf" -- MTBF (in seconds) required for a relay to be
2048 marked as stable.
2050 "enough-mtbf" -- Whether we have measured enough MTBF to look
2051 at stable-mtbf instead of stable-uptime.
2053 "fast-speed" -- Bandwidth (in bytes per second) required for
2054 a relay to be marked as fast.
2056 "guard-wfu" -- WFU (in seconds) required for a relay to be
2057 marked as guard.
2059 "guard-tk" -- Weighted Time Known (in seconds) required for a
2060 relay to be marked as guard.
2062 "guard-bw-inc-exits" -- If exits can be guards, then all guards
2063 must have a bandwidth this high.
2065 "guard-bw-exc-exits" -- If exits can't be guards, then all guards
2066 must have a bandwidth this high.
2068 "ignoring-advertised-bws" -- 1 if we have enough measured bandwidths
2069 that we'll ignore the advertised bandwidth
2070 claims of routers without measured bandwidth.
2072 "recommended-client-protocols" SP Entries NL
2073 "recommended-relay-protocols" SP Entries NL
2074 "required-client-protocols" SP Entries NL
2075 "required-relay-protocols" SP Entries NL
2077 [At most once for each.]
2079 The "proto" element as specified in section 2.1.1.
2081 To vote on these entries, a protocol/version combination is included
2082 only if it is listed by a majority of the voters.
2084 These lines should be voted on. A majority of votes is sufficient to
2085 make a protocol un-supported. A supermajority of authorities (2/3)
2086 are needed to make a protocol required. The required protocols
2087 should not be torrc-configurable, but rather should be hardwired in
2088 the Tor code.
2090 The tor-spec.txt section 9 details how a relay and a client should
2091 behave when they encounter these lines in the consensus.
2093 "params" SP [Parameters] NL
2095 [At most once]
2097 Parameter ::= Keyword '=' Int32
2098 Int32 ::= A decimal integer between -2147483648 and 2147483647.
2099 Parameters ::= Parameter | Parameters SP Parameter
2101 The parameters list, if present, contains a space-separated list of
2102 case-sensitive key-value pairs, sorted in lexical order by their
2103 keyword (as ASCII byte strings). Each parameter has its own meaning.
2105 (Only included when the vote is generated with consensus-method 7 or
2106 later.)
2108 See param-spec.txt for a list of parameters and their meanings.
2110 "shared-rand-previous-value" SP NumReveals SP Value NL
2112 [At most once]
2114 NumReveals ::= An integer greater or equal to 0.
2115 Value ::= Base64-encoded-data
2117 The shared_random_value that was generated during the second-to-last
2118 shared randomness protocol run. For example, if this document was
2119 created on the 5th of November, this field carries the shared random
2120 value generated during the protocol run of the 3rd of November.
2122 See section [SRCALC] of srv-spec.txt for instructions on how to compute
2123 this value, and see section [CONS] for why we include old shared random
2124 values in votes and consensus.
2126 Value is the actual shared random value encoded in base64. It will
2127 be exactly 256 bits long. NumReveals is the number of commits used
2128 to generate this SRV.
2130 "shared-rand-current-value" SP NumReveals SP Value NL
2132 [At most once]
2134 NumReveals ::= An integer greater or equal to 0.
2135 Value ::= Base64-encoded-data
2137 The shared_random_value that was generated during the latest shared
2138 randomness protocol run. For example, if this document was created on
2139 the 5th of November, this field carries the shared random value
2140 generated during the protocol run of the 4th of November
2142 See section [SRCALC] of srv-spec.txt for instructions on how to compute
2143 this value given the active commits.
2145 Value is the actual shared random value encoded in base64. It will
2146 be exactly 256 bits long. NumReveals is the number of commits used to
2147 generate this SRV.
2149 "bandwidth-file-headers" SP KeyValues NL
2151 [At most once for votes; does not occur in consensuses.]
2153 KeyValues ::= "" | KeyValue | KeyValues SP KeyValue
2154 KeyValue ::= Keyword '=' Value
2155 Value ::= ArgumentCharValue+
2156 ArgumentCharValue ::= any printing ASCII character except NL and SP.
2158 The headers from the bandwidth file used to generate this vote.
2159 The bandwidth file headers are described in bandwidth-file-spec.txt.
2161 If an authority is not configured with a V3BandwidthsFile, this line
2162 SHOULD NOT appear in its vote.
2164 If an authority is configured with a V3BandwidthsFile, but parsing
2165 fails, this line SHOULD appear in its vote, but without any headers.
2167 First-appeared: Tor 0.3.5.1-alpha.
2169 "bandwidth-file-digest" 1*(SP algorithm "=" digest) NL
2171 [At most once for votes; does not occur in consensuses.]
2173 A digest of the bandwidth file used to generate this vote.
2174 "algorithm" is the name of the hash algorithm producing "digest",
2175 which can be "sha256" or another algorithm. "digest" is the
2176 base64 encoding of the hash of the bandwidth file, with trailing =s
2177 omitted.
2179 If an authority is not configured with a V3BandwidthsFile, this line
2180 SHOULD NOT appear in its vote.
2182 If an authority is configured with a V3BandwidthsFile, but parsing
2183 fails, this line SHOULD appear in its vote, with the digest(s) of the
2184 unparseable file.
2186 First-appeared: Tor 0.4.0.4-alpha
2188 The authority section of a vote contains the following items, followed
2189 in turn by the authority's current key certificate:
2191 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
2192 orport NL
2194 [Exactly once, at start]
2196 Describes this authority. The nickname is a convenient identifier
2197 for the authority. The identity is an uppercase hex fingerprint of
2198 the authority's current (v3 authority) identity key. The address is
2199 the server's hostname. The IP is the server's current IP address,
2200 and dirport is its current directory port. The orport is the
2201 port at that address where the authority listens for OR
2202 connections.
2204 "contact" SP string NL
2206 [Exactly once]
2208 An arbitrary string describing how to contact the directory
2209 server's administrator. Administrators should include at least an
2210 email address and a PGP fingerprint.
2212 "legacy-dir-key" SP FINGERPRINT NL
2214 [At most once]
2216 Lists a fingerprint for an obsolete _identity_ key still used
2217 by this authority to keep older clients working. This option
2218 is used to keep key around for a little while in case the
2219 authorities need to migrate many identity keys at once.
2220 (Generally, this would only happen because of a security
2221 vulnerability that affected multiple authorities, like the
2222 Debian OpenSSL RNG bug of May 2008.)
2224 "shared-rand-participate" NL
2226 [At most once]
2228 Denotes that the directory authority supports and can participate in the
2229 shared random protocol.
2231 "shared-rand-commit" SP Version SP AlgName SP Identity SP Commit [SP Reveal] NL
2233 [Any number of times]
2235 Version ::= An integer greater or equal to 0.
2236 AlgName ::= 1*(ALPHA / DIGIT / "_" / "-")
2237 Identity ::= 40 * HEXDIG
2238 Commit ::= Base64-encoded-data
2239 Reveal ::= Base64-encoded-data
2241 Denotes a directory authority commit for the shared randomness
2242 protocol, containing the commitment value and potentially also the
2243 reveal value. See sections [COMMITREVEAL] and [VALIDATEVALUES] of
2244 srv-spec.txt on how to generate and validate these values.
2246 Version is the current shared randomness protocol version. AlgName is
2247 the hash algorithm that is used (e.g. "sha3-256") and Identity is the
2248 authority's SHA1 v3 identity fingerprint. Commit is the encoded
2249 commitment value in base64. Reveal is optional and if it's set, it
2250 contains the reveal value in base64.
2252 If a vote contains multiple commits from the same authority, the
2253 receiver MUST only consider the first commit listed.
2255 "shared-rand-previous-value" SP NumReveals SP Value NL
2257 [At most once]
2259 See shared-rand-previous-value description above.
2261 "shared-rand-current-value" SP NumReveals SP Value NL
2263 [At most once]
2265 See shared-rand-current-value description above.
2267 The authority section of a consensus contains groups of the following items,
2268 in the order given, with one group for each authority that contributed to
2269 the consensus, with groups sorted by authority identity digest:
2271 "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
2272 orport NL
2274 [Exactly once, at start]
2276 As in the authority section of a vote.
2278 "contact" SP string NL
2280 [Exactly once.]
2282 As in the authority section of a vote.
2284 "vote-digest" SP digest NL
2286 [Exactly once.]
2288 A digest of the vote from the authority that contributed to this
2289 consensus, as signed (that is, not including the signature).
2290 (Hex, upper-case.)
2292 For each "legacy-dir-key" in the vote, there is an additional "dir-source"
2293 line containing that legacy key's fingerprint, the authority's nickname
2294 with "-legacy" appended, and all other fields as in the main "dir-source"
2295 line for that authority. These "dir-source" lines do not have
2296 corresponding "contact" or "vote-digest" entries.
2298 Each router status entry contains the following items. Router status
2299 entries are sorted in ascending order by identity digest.
2301 "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
2302 SP DirPort NL
2304 [At start, exactly once.]
2306 "Nickname" is the OR's nickname. "Identity" is a hash of its
2307 identity key, encoded in base64, with trailing equals sign(s)
2308 removed. "Digest" is a hash of its most recent descriptor as
2309 signed (that is, not including the signature) by the RSA identity
2310 key (see section 1.3.), encoded in base64.
2312 "Publication" was once the publication time of the router's most
2313 recent descriptor, in the form YYYY-MM-DD HH:MM:SS, in UTC. Now
2314 it is only used in votes, and may be set to a fixed value in
2315 consensus documents. Implementations SHOULD ignore this value
2316 in non-vote documents.
2318 "IP" is its current IP address; ORPort is its current OR port,
2319 "DirPort" is its current directory port, or "0" for "none".
2321 "a" SP address ":" port NL
2323 [Any number]
2325 The first advertised IPv6 address for the OR, if it is reachable.
2327 Present only if the OR advertises at least one IPv6 address, and the
2328 authority believes that the first advertised address is reachable.
2329 Any other IPv4 or IPv6 addresses should be ignored.
2331 Address and port are as for "or-address" as specified in
2332 section 2.1.1.
2334 (Only included when the vote or consensus is generated with
2335 consensus-method 14 or later.)
2337 "s" SP Flags NL
2339 [Exactly once.]
2341 A series of space-separated status flags, in lexical order (as ASCII
2342 byte strings). Currently documented flags are:
2344 "Authority" if the router is a directory authority.
2345 "BadExit" if the router is believed to be useless as an exit node
2346 (because its ISP censors it, because it is behind a restrictive
2347 proxy, or for some similar reason).
2348 "Exit" if the router is more useful for building
2349 general-purpose exit circuits than for relay circuits. The
2350 path building algorithm uses this flag; see path-spec.txt.
2351 "Fast" if the router is suitable for high-bandwidth circuits.
2352 "Guard" if the router is suitable for use as an entry guard.
2353 "HSDir" if the router is considered a v2 hidden service directory.
2354 "MiddleOnly" if the router is considered unsuitable for
2355 usage other than as a middle relay. Clients do not need
2356 to handle this option, since when it is present, the authorities
2357 will automatically vote against flags that would make the router
2358 usable in other positions. (Since 0.4.7.2-alpha.)
2359 "NoEdConsensus" if any Ed25519 key in the router's descriptor or
2360 microdescriptor does not reflect authority consensus.
2361 "Stable" if the router is suitable for long-lived circuits.
2362 "StaleDesc" if the router should upload a new descriptor because
2363 the old one is too old.
2364 "Running" if the router is currently usable over all its published
2365 ORPorts. (Authorities ignore IPv6 ORPorts unless configured to
2366 check IPv6 reachability.) Relays without this flag are omitted
2367 from the consensus, and current clients (since 0.2.9.4-alpha)
2368 assume that every listed relay has this flag.
2369 "Valid" if the router has been 'validated'. Clients before
2370 0.2.9.4-alpha would not use routers without this flag by
2371 default. Currently, relays without this flag are omitted
2372 from the consensus, and current (post-0.2.9.4-alpha) clients
2373 assume that every listed relay has this flag.
2374 "V2Dir" if the router implements the v2 directory protocol or
2375 higher.
2377 "v" SP version NL
2379 [At most once.]
2381 The version of the Tor protocol that this relay is running. If
2382 the value begins with "Tor" SP, the rest of the string is a Tor
2383 version number, and the protocol is "The Tor protocol as supported
2384 by the given version of Tor." Otherwise, if the value begins with
2385 some other string, Tor has upgraded to a more sophisticated
2386 protocol versioning system, and the protocol is "a version of the
2387 Tor protocol more recent than any we recognize."
2389 Directory authorities SHOULD omit version strings they receive from
2390 descriptors if they would cause "v" lines to be over 128 characters
2391 long.
2393 "pr" SP Entries NL
2395 [At most once.]
2397 The "proto" family element as specified in section 2.1.1.
2399 During voting, authorities copy these lines immediately below the "v"
2400 lines. When a descriptor does not contain a "proto" entry, the
2401 authorities should reconstruct it using the approach described below
2402 in section D. They are included in the consensus using the same rules
2403 as currently used for "v" lines, if a sufficiently late consensus
2404 method is in use.
2406 "w" SP "Bandwidth=" INT [SP "Measured=" INT] [SP "Unmeasured=1"] NL
2408 [At most once.]
2410 An estimate of the bandwidth of this relay, in an arbitrary
2411 unit (currently kilobytes per second). Used to weight router
2412 selection. See section 3.4.2 for details on how the value of
2413 Bandwidth is determined in a consensus.
2415 Additionally, the Measured= keyword is present in votes by
2416 participating bandwidth measurement authorities to indicate
2417 a measured bandwidth currently produced by measuring stream
2418 capacities. It does not occur in consensuses.
2420 'Bandwidth=' and 'Measured=' values must be between 0 and
2421 2^32 - 1 inclusive.
2423 The "Unmeasured=1" value is included in consensuses generated
2424 with method 17 or later when the 'Bandwidth=' value is not
2425 based on a threshold of 3 or more measurements for this relay.
2427 Other weighting keywords may be added later.
2428 Clients MUST ignore keywords they do not recognize.
2430 "p" SP ("accept" / "reject") SP PortList NL
2432 [At most once.]
2434 PortList = PortOrRange
2435 PortList = PortList "," PortOrRange
2436 PortOrRange = INT "-" INT / INT
2438 A list of those ports that this router supports (if 'accept')
2439 or does not support (if 'reject') for exit to "most
2440 addresses".
2442 "m" SP methods 1*(SP algorithm "=" digest) NL
2444 [Any number, only in votes.]
2446 Microdescriptor hashes for all consensus methods that an authority
2447 supports and that use the same microdescriptor format. "methods"
2448 is a comma-separated list of the consensus methods that the
2449 authority believes will produce "digest". "algorithm" is the name
2450 of the hash algorithm producing "digest", which can be "sha256" or
2451 something else, depending on the consensus "methods" supporting
2452 this algorithm. "digest" is the base64 encoding of the hash of
2453 the router's microdescriptor with trailing =s omitted.
2455 "id" SP "ed25519" SP ed25519-identity NL
2456 "id" SP "ed25519" SP "none" NL
2457 [vote only, at most once]
2459 "stats" SP [KeyValues] NL
2461 [At most once. Vote only]
2463 KeyValue ::= Keyword '=' Number
2464 Number ::= [0-9]+("."[0-9]+)?
2465 KeyValues ::= KeyValue | KeyValues SP KeyValue
2467 Line containing various statistics that an authority has computed for
2468 this relay. Each stats is represented as a key + value. Reported keys
2469 are:
2471 "wfu" - Weighted Fractional Uptime
2472 "tk" - Weighted Time Known
2473 "mtbf" - Mean Time Between Failure (stability)
2475 (As of tor-0.4.6.1-alpha)
2477 The footer section is delineated in all votes and consensuses supporting
2478 consensus method 9 and above with the following:
2480 "directory-footer" NL
2481 [No extra arguments]
2483 It contains two subsections, a bandwidths-weights line and a
2484 directory-signature. (Prior to consensus method 9, footers only contained
2485 directory-signatures without a 'directory-footer' line or
2486 bandwidth-weights.)
2488 The bandwidths-weights line appears At Most Once for a consensus. It does
2489 not appear in votes.
2491 "bandwidth-weights" [SP Weights] NL
2493 Weight ::= Keyword '=' Int32
2494 Int32 ::= A decimal integer between -2147483648 and 2147483647.
2495 Weights ::= Weight | Weights SP Weight
2497 List of optional weights to apply to router bandwidths during path
2498 selection. They are sorted in lexical order (as ASCII byte strings) and
2499 values are divided by the consensus' "bwweightscale" param. Definition
2500 of our known entries are...
2502 Wgg - Weight for Guard-flagged nodes in the guard position
2503 Wgm - Weight for non-flagged nodes in the guard Position
2504 Wgd - Weight for Guard+Exit-flagged nodes in the guard Position
2506 Wmg - Weight for Guard-flagged nodes in the middle Position
2507 Wmm - Weight for non-flagged nodes in the middle Position
2508 Wme - Weight for Exit-flagged nodes in the middle Position
2509 Wmd - Weight for Guard+Exit flagged nodes in the middle Position
2511 Weg - Weight for Guard flagged nodes in the exit Position
2512 Wem - Weight for non-flagged nodes in the exit Position
2513 Wee - Weight for Exit-flagged nodes in the exit Position
2514 Wed - Weight for Guard+Exit-flagged nodes in the exit Position
2516 Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
2517 Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
2518 Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
2519 Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes
2521 Wbg - Weight for Guard flagged nodes for BEGIN_DIR requests
2522 Wbm - Weight for non-flagged nodes for BEGIN_DIR requests
2523 Wbe - Weight for Exit-flagged nodes for BEGIN_DIR requests
2524 Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
2526 These values are calculated as specified in section 3.8.3.
2528 The signature contains the following item, which appears Exactly Once
2529 for a vote, and At Least Once for a consensus.
2531 "directory-signature" [SP Algorithm] SP identity SP signing-key-digest
2532 NL Signature
2534 This is a signature of the status document, with the initial item
2535 "network-status-version", and the signature item
2536 "directory-signature", using the signing key. (In this case, we take
2537 the hash through the _space_ after directory-signature, not the
2538 newline: this ensures that all authorities sign the same thing.)
2539 "identity" is the hex-encoded digest of the authority identity key of
2540 the signing authority, and "signing-key-digest" is the hex-encoded
2541 digest of the current authority signing key of the signing authority.
2543 The Algorithm is one of "sha1" or "sha256" if it is present;
2544 implementations MUST ignore directory-signature entries with an
2545 unrecognized Algorithm. "sha1" is the default, if no Algorithm is
2546 given. The algorithm describes how to compute the hash of the
2547 document before signing it.
2549 "ns"-flavored consensus documents must contain only sha1 signatures.
2550 Votes and microdescriptor documents may contain other signature
2551 types. Note that only one signature from each authority should be
2552 "counted" as meaning that the authority has signed the consensus.
2554 (Tor clients before 0.2.3.x did not understand the 'algorithm'
2555 field.)
2557 3.4.2. Assigning flags in a vote
2559 (This section describes how directory authorities choose which status
2560 flags to apply to routers. Later directory authorities MAY do things
2561 differently, so long as clients keep working well. Clients MUST NOT
2562 depend on the exact behaviors in this section.)
2564 In the below definitions, a router is considered "active" if it is
2565 running, valid, and not hibernating.
2567 When we speak of a router's bandwidth in this section, we mean either
2568 its measured bandwidth, or its advertised bandwidth. If a sufficient
2569 threshold (configurable with MinMeasuredBWsForAuthToIgnoreAdvertised,
2570 500 by default) of routers have measured bandwidth values, then the
2571 authority bases flags on _measured_ bandwidths, and treats nodes with
2572 non-measured bandwidths as if their bandwidths were zero. Otherwise,
2573 it uses measured bandwidths for nodes that have them, and advertised
2574 bandwidths for other nodes.
2576 When computing thresholds based on percentiles of nodes, an authority
2577 only considers nodes that are active, that have not been
2578 omitted as a sybil (see below), and whose bandwidth is at least
2579 4 KB. Nodes that don't meet these criteria do not influence any
2580 threshold calculations (including calculation of stability and uptime
2581 and bandwidth thresholds) and also do not have their Exit status
2582 change.
2584 "Valid" -- a router is 'Valid' if it is running a version of Tor not
2585 known to be broken, and the directory authority has not blacklisted
2586 it as suspicious.
2588 "Named" --
2589 "Unnamed" -- Directory authorities no longer assign these flags.
2590 They were once used to determine whether a relay's nickname was
2591 canonically linked to its public key.
2593 "Running" -- A router is 'Running' if the authority managed to connect to
2594 it successfully within the last 45 minutes on all its published ORPorts.
2595 Authorities check reachability on:
2597 * the IPv4 ORPort in the "r" line, and
2598 * the IPv6 ORPort considered for the "a" line, if:
2599 * the router advertises at least one IPv6 ORPort, and
2600 * AuthDirHasIPv6Connectivity 1 is set on the authority.
2602 A minority of voting authorities that set AuthDirHasIPv6Connectivity will
2603 drop unreachable IPv6 ORPorts from the full consensus. Consensus method 27
2604 in 0.3.3.x puts IPv6 ORPorts in the microdesc consensus, so that
2605 authorities can drop unreachable IPv6 ORPorts from all consensus flavors.
2606 Consensus method 28 removes IPv6 ORPorts from microdescriptors.
2608 "Stable" -- A router is 'Stable' if it is active, and either its Weighted
2609 MTBF is at least the median for known active routers or its Weighted MTBF
2610 corresponds to at least 7 days. Routers are never called Stable if they are
2611 running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
2612 through 0.1.1.16-rc are stupid this way.)
2614 To calculate weighted MTBF, compute the weighted mean of the lengths
2615 of all intervals when the router was observed to be up, weighting
2616 intervals by $\alpha^n$, where $n$ is the amount of time that has
2617 passed since the interval ended, and $\alpha$ is chosen so that
2618 measurements over approximately one month old no longer influence the
2619 weighted MTBF much.
2621 [XXXX what happens when we have less than 4 days of MTBF info.]
2623 "Exit" -- A router is called an 'Exit' iff it allows exits to at
2624 least one /8 address space on each of ports 80 and 443. (Up until
2625 Tor version 0.3.2, the flag was assigned if relays exit to at least
2626 two of the ports 80, 443, and 6667.)
2628 "Fast" -- A router is 'Fast' if it is active, and its bandwidth is either in
2629 the top 7/8ths for known active routers or at least 100KB/s.
2631 "Guard" -- A router is a possible Guard if all of the following apply:
2633 - It is Fast,
2634 - It is Stable,
2635 - Its Weighted Fractional Uptime is at least the median for "familiar"
2636 active routers,
2637 - It is "familiar",
2638 - Its bandwidth is at least AuthDirGuardBWGuarantee (if set, 2 MB by
2639 default), OR its bandwidth is among the 25% fastest relays,
2640 - It qualifies for the V2Dir flag as described below (this
2641 constraint was added in 0.3.3.x, because in 0.3.0.x clients
2642 started avoiding guards that didn't also have the V2Dir flag).
2644 To calculate weighted fractional uptime, compute the fraction
2645 of time that the router is up in any given day, weighting so that
2646 downtime and uptime in the past counts less.
2648 A node is 'familiar' if 1/8 of all active nodes have appeared more
2649 recently than it, OR it has been around for a few weeks.
2651 "Authority" -- A router is called an 'Authority' if the authority
2652 generating the network-status document believes it is an authority.
2654 "V2Dir" -- A router supports the v2 directory protocol or higher if it has
2655 an open directory port OR a tunnelled-dir-server line in its router
2656 descriptor, and it is running a version of the directory
2657 protocol that supports the functionality clients need. (Currently, every
2658 supported version of Tor supports the functionality that clients need,
2659 but some relays might set "DirCache 0" or set really low rate limiting,
2660 making them unqualified to be a directory mirror, i.e. they will omit
2661 the tunnelled-dir-server line from their descriptor.)
2663 "HSDir" -- A router is a v2 hidden service directory if it stores and
2664 serves v2 hidden service descriptors, has the Stable and Fast flag, and the
2665 authority believes that it's been up for at least 96 hours (or the current
2666 value of MinUptimeHidServDirectoryV2).
2668 "MiddleOnly" -- An authority should vote for this flag if it believes
2669 that a relay is unsuitable for use except as a middle relay. When
2670 voting for this flag, the authority should also vote against "Exit",
2671 "Guard", "HsDir", and "V2Dir". When voting for this flag, if the
2672 authority votes on the "BadExit" flag, the authority should vote in
2673 favor of "BadExit". (This flag was added in 0.4.7.2-alpha.)
2675 "NoEdConsensus" -- authorities should not vote on this flag; it is
2676 produced as part of the consensus for consensus method 22 or later.
2678 "StaleDesc" -- authorities should vote to assign this flag if the
2679 published time on the descriptor is over 18 hours in the past. (This flag
2680 was added in 0.4.0.1-alpha.)
2682 "Sybil" -- authorities SHOULD NOT accept more than 2 relays on a single IP.
2683 If this happens, the authority *should* vote for the excess relays, but
2684 should omit the Running or Valid flags and instead should assign the "Sybil"
2685 flag. When there are more than 2 (or AuthDirMaxServersPerAddr) relays to
2686 choose from, authorities should first prefer authorities to non-authorities,
2687 then prefer Running to non-Running, and then prefer high-bandwidth to
2688 low-bandwidth relays. In this comparison, measured bandwidth is used unless
2689 it is not present for a router, in which case advertised bandwidth is used.
2691 Thus, the network-status vote includes all non-blacklisted,
2692 non-expired, non-superseded descriptors.
2694 The bandwidth in a "w" line should be taken as the best estimate
2695 of the router's actual capacity that the authority has. For now,
2696 this should be the lesser of the observed bandwidth and bandwidth
2697 rate limit from the server descriptor. It is given in kilobytes
2698 per second, and capped at some arbitrary value (currently 10 MB/s).
2700 The Measured= keyword on a "w" line vote is currently computed
2701 by multiplying the previous published consensus bandwidth by the
2702 ratio of the measured average node stream capacity to the network
2703 average. If 3 or more authorities provide a Measured= keyword for
2704 a router, the authorities produce a consensus containing a "w"
2705 Bandwidth= keyword equal to the median of the Measured= votes.
2707 As a special case, if the "w" line in a vote is about a relay with the
2708 Authority flag, it should not include a Measured= keyword. The goal is
2709 to leave such relays marked as Unmeasured, so they can reserve their
2710 attention for authority-specific activities. "w" lines for votes about
2711 authorities may include the bandwidth authority's measurement using
2712 a different keyword, e.g. MeasuredButAuthority=, so it can still be
2713 reported and recorded for posterity.
2715 The ports listed in a "p" line should be taken as those ports for
2716 which the router's exit policy permits 'most' addresses, ignoring any
2717 accept not for all addresses, ignoring all rejects for private
2718 netblocks. "Most" addresses are permitted if no more than 2^25
2719 IPv4 addresses (two /8 networks) were blocked. The list is encoded
2720 as described in section 3.8.2.
2722 3.4.3. Serving bandwidth list files
2724 If an authority has used a bandwidth list file to generate a vote
2725 document it SHOULD make it available at
2727 http://<hostname>/tor/status-vote/next/bandwidth.z
2729 at the start of each voting period.
2731 It MUST NOT attempt to send its bandwidth list file in a HTTP POST to
2732 other authorities and it SHOULD NOT make bandwidth list files from other
2733 authorities available.
2735 If an authority makes this file available, it MUST be the bandwidth file
2736 used to create the vote document available at
2738 http://<hostname>/tor/status-vote/next/authority.z
2740 To avoid inconsistent reads, authorities SHOULD only read the bandwidth
2741 file once per voting period. Further processing and serving SHOULD use a
2742 cached copy.
2744 The bandwidth list format is described in bandwidth-file-spec.txt.
2746 The standard URLs for bandwidth list files first-appeared in
2747 Tor 0.4.0.4-alpha.
2749 3.5. Downloading missing certificates from other directory authorities
2751 XXX when to download certificates.
2753 3.6. Downloading server descriptors from other directory authorities
2755 Periodically (currently, every 10 seconds), directory authorities check
2756 whether there are any specific descriptors that they do not have and that
2757 they are not currently trying to download.
2758 Authorities identify them by hash in vote (if publication date is more
2759 recent than the descriptor we currently have).
2761 [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
2762 do that for now.]
2764 If so, the directory authority launches requests to the authorities for these
2765 descriptors, such that each authority is only asked for descriptors listed
2766 in its most recent vote. If more
2767 than one authority lists the descriptor, we choose which to ask at random.
2769 If one of these downloads fails, we do not try to download that descriptor
2770 from the authority that failed to serve it again unless we receive a newer
2771 network-status (consensus or vote) from that authority that lists the same
2772 descriptor.
2774 Directory authorities must potentially cache multiple descriptors for each
2775 router. Authorities must not discard any descriptor listed by any recent
2776 consensus. If there is enough space to store additional descriptors,
2777 authorities SHOULD try to hold those which clients are likely to download the
2778 most. (Currently, this is judged based on the interval for which each
2779 descriptor seemed newest.)
2780 [XXXX define recent]
2782 Authorities SHOULD NOT download descriptors for routers that they would
2783 immediately reject for reasons listed in section 3.2.
2785 3.7. Downloading extra-info documents from other directory authorities
2787 Periodically, an authority checks whether it is missing any extra-info
2788 documents: in other words, if it has any server descriptors with an
2789 extra-info-digest field that does not match any of the extra-info
2790 documents currently held. If so, it downloads whatever extra-info
2791 documents are missing. We follow the same splitting and back-off rules
2792 as in section 3.6.
2794 3.8. Computing a consensus from a set of votes
2796 Given a set of votes, authorities compute the contents of the consensus.
2798 The consensus status, along with as many signatures as the server
2799 currently knows (see section 3.10 below), should be available at
2801 http://<hostname>/tor/status-vote/next/consensus.z
2803 The contents of the consensus document are as follows:
2805 The "valid-after", "valid-until", and "fresh-until" times are taken as
2806 the median of the respective values from all the votes.
2808 The times in the "voting-delay" line are taken as the median of the
2809 VoteSeconds and DistSeconds times in the votes.
2811 Known-flags is the union of all flags known by any voter.
2813 Entries are given on the "params" line for every keyword on which a
2814 majority of authorities (total authorities, not just those
2815 participating in this vote) voted on, or if at least three
2816 authorities voted for that parameter. The values given are the
2817 low-median of all votes on that keyword.
2819 (In consensus methods 7 to 11 inclusive, entries were given on
2820 the "params" line for every keyword on which *any* authority voted,
2821 the value given being the low-median of all votes on that keyword.)
2823 "client-versions" and "server-versions" are sorted in ascending
2824 order; A version is recommended in the consensus if it is recommended
2825 by more than half of the voting authorities that included a
2826 client-versions or server-versions lines in their votes.
2828 With consensus methods 19 through 33, a package line is generated for a
2829 given PACKAGENAME/VERSION pair if at least three authorities list such a
2830 package in their votes. (Call these lines the "input" lines for
2831 PACKAGENAME.) The consensus will contain every "package" line that is
2832 listed verbatim by more than half of the authorities listing a line for
2833 the PACKAGENAME/VERSION pair, and no others.
2835 The authority item groups (dir-source, contact, fingerprint,
2836 vote-digest) are taken from the votes of the voting
2837 authorities. These groups are sorted by the digests of the
2838 authorities identity keys, in ascending order. If the consensus
2839 method is 3 or later, a dir-source line must be included for
2840 every vote with legacy-key entry, using the legacy-key's
2841 fingerprint, the voter's ordinary nickname with the string
2842 "-legacy" appended, and all other fields as from the original
2843 vote's dir-source line.
2845 A router status entry:
2846 * is included in the result if some router status entry with the same
2847 identity is included by more than half of the authorities (total
2848 authorities, not just those whose votes we have).
2849 (Consensus method earlier than 21)
2851 * is included according to the rules in section 3.8.0.1 and
2852 3.8.0.2 below. (Consensus method 22 or later)
2854 * For any given RSA identity digest, we include at most
2855 one router status entry.
2857 * For any given Ed25519 identity, we include at most one router
2858 status entry.
2860 * A router entry has a flag set if that is included by more than half
2861 of the authorities who care about that flag.
2863 * Two router entries are "the same" if they have the same
2864 <descriptor digest, published time, nickname, IP, ports> tuple.
2865 We choose the tuple for a given router as whichever tuple appears
2866 for that router in the most votes. We break ties first in favor of
2867 the more recently published, then in favor of smaller server
2868 descriptor digest.
2870 [
2871 * The Named flag appears if it is included for this routerstatus by
2872 _any_ authority, and if all authorities that list it list the same
2873 nickname. However, if consensus-method 2 or later is in use, and
2874 any authority calls this identity/nickname pair Unnamed, then
2875 this routerstatus does not get the Named flag.
2877 * If consensus-method 2 or later is in use, the Unnamed flag is
2878 set for a routerstatus if any authorities have voted for a different
2879 identities to be Named with that nickname, or if any authority
2880 lists that nickname/ID pair as Unnamed.
2882 (With consensus-method 1, Unnamed is set like any other flag.)
2884 [But note that authorities no longer vote for the Named flag,
2885 and the above two bulletpoints are now irrelevant.]
2886 ]
2888 * The version is given as whichever version is listed by the most
2889 voters, with ties decided in favor of more recent versions.
2891 * If consensus-method 4 or later is in use, then routers that
2892 do not have the Running flag are not listed at all.
2894 * If consensus-method 5 or later is in use, then the "w" line
2895 is generated using a low-median of the bandwidth values from
2896 the votes that included "w" lines for this router.
2898 * If consensus-method 5 or later is in use, then the "p" line
2899 is taken from the votes that have the same policy summary
2900 for the descriptor we are listing. (They should all be the
2901 same. If they are not, we pick the most commonly listed
2902 one, breaking ties in favor of the lexicographically larger
2903 vote.) The port list is encoded as specified in section 3.8.2.
2905 * If consensus-method 6 or later is in use and if 3 or more
2906 authorities provide a Measured= keyword in their votes for
2907 a router, the authorities produce a consensus containing a
2908 Bandwidth= keyword equal to the median of the Measured= votes.
2910 * If consensus-method 7 or later is in use, the params line is
2911 included in the output.
2913 * If the consensus method is under 11, bad exits are considered as
2914 possible exits when computing bandwidth weights. Otherwise, if
2915 method 11 or later is in use, any router that is determined to get
2916 the BadExit flag doesn't count when we're calculating weights.
2918 * If consensus method 12 or later is used, only consensus
2919 parameters that more than half of the total number of
2920 authorities voted for are included in the consensus.
2922 [ As of 0.2.6.1-alpha, authorities no longer advertise or negotiate
2923 any consensus methods lower than 13. ]
2925 * If consensus method 13 or later is used, microdesc consensuses
2926 omit any router for which no microdesc was agreed upon.
2928 * If consensus method 14 or later is used, the ns consensus and
2929 microdescriptors may include an "a" line for each router, listing
2930 an IPv6 OR port.
2932 * If consensus method 15 or later is used, microdescriptors
2933 include "p6" lines including IPv6 exit policies.
2935 * If consensus method 16 or later is used, ntor-onion-key
2936 are included in microdescriptors
2938 * If consensus method 17 or later is used, authorities impose a
2939 maximum on the Bandwidth= values that they'll put on a 'w'
2940 line for any router that doesn't have at least 3 measured
2941 bandwidth values in votes. They also add an "Unmeasured=1"
2942 flag to such 'w' lines.
2944 * If consensus method 18 or later is used, authorities include
2945 "id" lines in microdescriptors. This method adds RSA ids.
2947 * If consensus method 19 or later is used, authorities may include
2948 "package" lines in consensuses.
2950 * If consensus method 20 or later is used, authorities may include
2951 GuardFraction information in microdescriptors.
2953 * If consensus method 21 or later is used, authorities may include
2954 an "id" line for ed25519 identities in microdescriptors.
2956 [ As of 0.2.8.2-alpha, authorities no longer advertise or negotiate
2957 consensus method 21, because it contains bugs. ]
2959 * If consensus method 22 or later is used, and the votes do not
2960 produce a majority consensus about a relay's Ed25519 key (see
2961 3.8.0.1 below), the consensus must include a NoEdConsensus flag on
2962 the "s" line for every relay whose listed Ed key does not reflect
2963 consensus.
2965 * If consensus method 23 or later is used, authorities include
2966 shared randomness protocol data on their votes and consensus.
2968 * If consensus-method 24 or later is in use, then routers that
2969 do not have the Valid flag are not listed at all.
2971 [ As of 0.3.4.1-alpha, authorities no longer advertise or negotiate
2972 any consensus methods lower than 25. ]
2974 * If consensus-method 25 or later is in use, then we vote
2975 on recommended-protocols and required-protocols lines in the
2976 consensus. We also include protocols lines in routerstatus
2977 entries.
2979 * If consensus-method 26 or later is in use, then we initialize
2980 bandwidth weights to 1 in our calculations, to avoid
2981 division-by-zero errors on unusual networks.
2983 * If consensus method 27 or later is used, the microdesc consensus
2984 may include an "a" line for each router, listing an IPv6 OR port.
2986 [ As of 0.4.3.1-alpha, authorities no longer advertise or negotiate
2987 any consensus methods lower than 28. ]
2989 * If consensus method 28 or later is used, microdescriptors no longer
2990 include "a" lines.
2992 * If consensus method 29 or later is used, microdescriptor "family"
2993 lines are canonicalized to improve compression.
2995 * If consensus method 30 or later is used, the base64 encoded
2996 ntor-onion-key does not include the trailing = sign.
2998 * If consensus method 31 or later is used, authorities parse the
2999 "bwweightscale" and "maxunmeasuredbw" parameters correctly when
3000 computing votes.
3002 * If consensus method 32 or later is used, authorities handle the
3003 "MiddleOnly" flag specially when computing a consensus. When the
3004 voters agree to include "MiddleOnly" in a routerstatus, they
3005 automatically remove "Exit", "Guard", "V2Dir", and "HSDir". If
3006 the BadExit flag is included in the consensus, they automatically
3007 add it to the routerstatus.
3009 * If consensus method 33 or later is used, and the consensus
3010 flavor is "microdesc", then the "Publication" field in the "r"
3011 line is set to "2038-01-01 00:00:00".
3013 * If consensus method 34 or later is used, the consensus
3014 does not include any "package" lines.
3016 The signatures at the end of a consensus document are sorted in
3017 ascending order by identity digest.
3019 All ties in computing medians are broken in favor of the smaller or
3020 earlier item.
3022 3.8.0.1. Deciding which Ids to include.
3024 This sorting algorithm is used for consensus-method 22 and later.
3026 First, consider each listing by tuple of <Ed,Rsa> identities, where 'Ed'
3027 may be "None" if the voter included "id ed25519 none" to indicate that
3028 the authority knows what ed25519 identities are, and thinks that the RSA
3029 key doesn't have one.
3031 For each such <Ed, RSA> tuple that is listed by more than half of the
3032 total authorities (not just total votes), include it. (It is not
3033 possible for any other <id-Ed, id-RSA'> to have as many votes.) If more
3034 than half of the authorities list a single <Ed,Rsa> pair of this type, we
3035 consider that Ed key to be "consensus"; see description of the
3036 NoEdConsensus flag.
3038 Log any other id-RSA values corresponding to an id-Ed we included, and any
3039 other id-Ed values corresponding to an id-RSA we included.
3041 For each <id-RSA> that is not yet included, if it is listed by more than
3042 half of the total authorities, and we do not already have it listed with
3043 some <id-Ed>, include it, but do not consider its Ed identity canonical.
3045 3.8.0.2. Deciding which descriptors to include
3047 Deciding which descriptors to include.
3049 A tuple belongs to an <id-RSA, id-Ed> identity if it is a new tuple that
3050 matches both ID parts, or if it is an old tuple (one with no Ed opinion)
3051 that matches the RSA part. A tuple belongs to an <id-RSA> identity if its
3052 RSA identity matches.
3054 A tuple matches another tuple if all the fields that are present in both
3055 tuples are the same.
3057 For every included identity, consider the tuples belonging to that
3058 identity. Group them into sets of matching tuples. Include the tuple
3059 that matches the largest set, breaking ties in favor of the most recently
3060 published, and then in favor of the smaller server descriptor digest.
3062 3.8.1. Forward compatibility
3064 Future versions of Tor will need to include new information in the
3065 consensus documents, but it is important that all authorities (or at least
3066 half) generate and sign the same signed consensus.
3068 To achieve this, authorities list in their votes their supported methods
3069 for generating consensuses from votes. Later methods will be assigned
3070 higher numbers. Currently specified methods:
3072 "1" -- The first implemented version.
3073 "2" -- Added support for the Unnamed flag.
3074 "3" -- Added legacy ID key support to aid in authority ID key rollovers
3075 "4" -- No longer list routers that are not running in the consensus
3076 "5" -- adds support for "w" and "p" lines.
3077 "6" -- Prefers measured bandwidth values rather than advertised
3078 "7" -- Provides keyword=integer pairs of consensus parameters
3079 "8" -- Provides microdescriptor summaries
3080 "9" -- Provides weights for selecting flagged routers in paths
3081 "10" -- Fixes edge case bugs in router flag selection weights
3082 "11" -- Don't consider BadExits when calculating bandwidth weights
3083 "12" -- Params are only included if enough auths voted for them
3084 "13" -- Omit router entries with missing microdescriptors.
3085 "14" -- Adds support for "a" lines in ns consensuses and microdescriptors.
3086 "15" -- Adds support for "p6" lines.
3087 "16" -- Adds ntor keys to microdescriptors
3088 "17" -- Adds "Unmeasured=1" flags to "w" lines
3089 "18" -- Adds 'id' to microdescriptors.
3090 "19" -- Adds "package" lines to consensuses
3091 "20" -- Adds GuardFraction information to microdescriptors.
3092 "21" -- Adds Ed25519 keys to microdescriptors.
3093 "22" -- Instantiates Ed25519 voting algorithm correctly.
3094 "23" -- Adds shared randomness protocol data.
3095 "24" -- No longer lists routers that are not Valid in the consensus.
3096 "25" -- Vote on recommended-protocols and required-protocols.
3097 "26" -- Initialize bandwidth weights to 1 to avoid division-by-zero.
3098 "27" -- Adds support for "a" lines in microdescriptor consensuses.
3099 "28" -- Removes "a" lines from microdescriptors.
3100 "29" -- Canonicalizes families in microdescriptors.
3101 "30" -- Removes padding from ntor-onion-key.
3102 "31" -- Uses correct parsing for bwweightscale and maxunmeasuredbw
3103 when computing weights
3104 "32" -- Adds special handling for MiddleOnly flag.
3105 "33" -- Sets "publication" field in microdesc consensus "r" lines
3106 to a meaningless value.
3107 "34" -- Removes "package" lines from consensus.
3109 Before generating a consensus, an authority must decide which consensus
3110 method to use. To do this, it looks for the highest version number
3111 supported by more than 2/3 of the authorities voting. If it supports this
3112 method, then it uses it. Otherwise, it falls back to the newest consensus
3113 method that it supports (which will probably not result in a sufficiently
3114 signed consensus).
3116 All authorities MUST support method 25; authorities SHOULD support
3117 more recent methods as well. Authorities SHOULD NOT support or
3118 advertise support for any method before 25. Clients MAY assume that
3119 they will never see a current valid signed consensus for any method
3120 before method 25.
3122 (The consensuses generated by new methods must be parsable by
3123 implementations that only understand the old methods, and must not cause
3124 those implementations to compromise their anonymity. This is a means for
3125 making changes in the contents of consensus; not for making
3126 backward-incompatible changes in their format.)
3128 The following methods have incorrect implementations; authorities SHOULD
3129 NOT advertise support for them:
3131 "21" -- Did not correctly enable support for ed25519 key collation.
3133 3.8.2. Encoding port lists
3135 Whether the summary shows the list of accepted ports or the list of
3136 rejected ports depends on which list is shorter (has a shorter string
3137 representation). In case of ties we choose the list of accepted
3138 ports. As an exception to this rule an allow-all policy is
3139 represented as "accept 1-65535" instead of "reject " and a reject-all
3140 policy is similarly given as "reject 1-65535".
3142 Summary items are compressed, that is instead of "80-88,89-100" there
3143 only is a single item of "80-100", similarly instead of "20,21" a
3144 summary will say "20-21".
3146 Port lists are sorted in ascending order.
3148 The maximum allowed length of a policy summary (including the "accept "
3149 or "reject ") is 1000 characters. If a summary exceeds that length we
3150 use an accept-style summary and list as much of the port list as is
3151 possible within these 1000 bytes. [XXXX be more specific.]
3153 3.8.3. Computing Bandwidth Weights
3155 Let weight_scale = 10000, or the value of the "bwweightscale" parameter.
3156 (Before consensus method 31 there was a bug in parsing bwweightscale, so
3157 that if there were any consensus parameters after it alphabetically, it
3158 would always be treated as 10000. A similar bug existed for
3159 "maxunmeasuredbw".)
3161 Starting with consensus method 26, G, M, E, and D are initialized to 1 and
3162 T to 4. Prior consensus methods initialize them all to 0. With this change,
3163 test tor networks that are small or new are much more likely to produce
3164 bandwidth-weights in their consensus. The extra bandwidth has a negligible
3165 impact on the bandwidth weights in the public tor network.
3167 Let G be the total bandwidth for Guard-flagged nodes.
3168 Let M be the total bandwidth for non-flagged nodes.
3169 Let E be the total bandwidth for Exit-flagged nodes.
3170 Let D be the total bandwidth for Guard+Exit-flagged nodes.
3171 Let T = G+M+E+D
3173 Let Wgd be the weight for choosing a Guard+Exit for the guard position.
3174 Let Wmd be the weight for choosing a Guard+Exit for the middle position.
3175 Let Wed be the weight for choosing a Guard+Exit for the exit position.
3177 Let Wme be the weight for choosing an Exit for the middle position.
3178 Let Wmg be the weight for choosing a Guard for the middle position.
3180 Let Wgg be the weight for choosing a Guard for the guard position.
3181 Let Wee be the weight for choosing an Exit for the exit position.
3183 Balanced network conditions then arise from solutions to the following
3184 system of equations:
3186 Wgg*G + Wgd*D == M + Wmd*D + Wme*E + Wmg*G (guard bw = middle bw)
3187 Wgg*G + Wgd*D == Wee*E + Wed*D (guard bw = exit bw)
3188 Wed*D + Wmd*D + Wgd*D == D (aka: Wed+Wmd+Wdg = weight_scale)
3189 Wmg*G + Wgg*G == G (aka: Wgg = weight_scale-Wmg)
3190 Wme*E + Wee*E == E (aka: Wee = weight_scale-Wme)
3192 We are short 2 constraints with the above set. The remaining constraints
3193 come from examining different cases of network load. The following
3194 constraints are used in consensus method 10 and above. There are another
3195 incorrect and obsolete set of constraints used for these same cases in
3196 consensus method 9. For those, see dir-spec.txt in Tor 0.2.2.10-alpha
3197 to 0.2.2.16-alpha.
3199 Case 1: E >= T/3 && G >= T/3 (Neither Exit nor Guard Scarce)
3201 In this case, the additional two constraints are: Wmg == Wmd,
3202 Wed == 1/3.
3204 This leads to the solution:
3205 Wgd = weight_scale/3
3206 Wed = weight_scale/3
3207 Wmd = weight_scale/3
3208 Wee = (weight_scale*(E+G+M))/(3*E)
3209 Wme = weight_scale - Wee
3210 Wmg = (weight_scale*(2*G-E-M))/(3*G)
3211 Wgg = weight_scale - Wmg
3213 Case 2: E < T/3 && G < T/3 (Both are scarce)
3215 Let R denote the more scarce class (Rare) between Guard vs Exit.
3216 Let S denote the less scarce class.
3218 Subcase a: R+D < S
3220 In this subcase, we simply devote all of D bandwidth to the
3221 scarce class.
3223 Wgg = Wee = weight_scale
3224 Wmg = Wme = Wmd = 0;
3225 if E < G:
3226 Wed = weight_scale
3227 Wgd = 0
3228 else:
3229 Wed = 0
3230 Wgd = weight_scale
3232 Subcase b: R+D >= S
3234 In this case, if M <= T/3, we have enough bandwidth to try to achieve
3235 a balancing condition.
3237 Add constraints Wgg = weight_scale, Wmd == Wgd to maximize bandwidth in
3238 the guard position while still allowing exits to be used as middle nodes:
3240 Wee = (weight_scale*(E - G + M))/E
3241 Wed = (weight_scale*(D - 2*E + 4*G - 2*M))/(3*D)
3242 Wme = (weight_scale*(G-M))/E
3243 Wmg = 0
3244 Wgg = weight_scale
3245 Wmd = (weight_scale - Wed)/2
3246 Wgd = (weight_scale - Wed)/2
3248 If this system ends up with any values out of range (ie negative, or
3249 above weight_scale), use the constraints Wgg == weight_scale and Wee ==
3250 weight_scale, since both those positions are scarce:
3252 Wgg = weight_scale
3253 Wee = weight_scale
3254 Wed = (weight_scale*(D - 2*E + G + M))/(3*D)
3255 Wmd = (weight_Scale*(D - 2*M + G + E))/(3*D)
3256 Wme = 0
3257 Wmg = 0
3258 Wgd = weight_scale - Wed - Wmd
3260 If M > T/3, then the Wmd weight above will become negative. Set it to 0
3261 in this case:
3262 Wmd = 0
3263 Wgd = weight_scale - Wed
3265 Case 3: One of E < T/3 or G < T/3
3267 Let S be the scarce class (of E or G).
3269 Subcase a: (S+D) < T/3:
3270 if G=S:
3271 Wgg = Wgd = weight_scale;
3272 Wmd = Wed = Wmg = 0;
3273 // Minor subcase, if E is more scarce than M,
3274 // keep its bandwidth in place.
3275 if (E < M) Wme = 0;
3276 else Wme = (weight_scale*(E-M))/(2*E);
3277 Wee = weight_scale-Wme;
3278 if E=S:
3279 Wee = Wed = weight_scale;
3280 Wmd = Wgd = Wme = 0;
3281 // Minor subcase, if G is more scarce than M,
3282 // keep its bandwidth in place.
3283 if (G < M) Wmg = 0;
3284 else Wmg = (weight_scale*(G-M))/(2*G);
3285 Wgg = weight_scale-Wmg;
3287 Subcase b: (S+D) >= T/3
3288 if G=S:
3289 Add constraints Wgg = weight_scale, Wmd == Wed to maximize bandwidth
3290 in the guard position, while still allowing exits to be
3291 used as middle nodes:
3292 Wgg = weight_scale
3293 Wgd = (weight_scale*(D - 2*G + E + M))/(3*D)
3294 Wmg = 0
3295 Wee = (weight_scale*(E+M))/(2*E)
3296 Wme = weight_scale - Wee
3297 Wmd = (weight_scale - Wgd)/2
3298 Wed = (weight_scale - Wgd)/2
3299 if E=S:
3300 Add constraints Wee == weight_scale, Wmd == Wgd to maximize bandwidth
3301 in the exit position:
3302 Wee = weight_scale;
3303 Wed = (weight_scale*(D - 2*E + G + M))/(3*D);
3304 Wme = 0;
3305 Wgg = (weight_scale*(G+M))/(2*G);
3306 Wmg = weight_scale - Wgg;
3307 Wmd = (weight_scale - Wed)/2;
3308 Wgd = (weight_scale - Wed)/2;
3310 To ensure consensus, all calculations are performed using integer math
3311 with a fixed precision determined by the bwweightscale consensus
3312 parameter (defaults at 10000, Min: 1, Max: INT32_MAX). (See note above
3313 about parsing bug in bwweightscale before consensus method 31.)
3315 For future balancing improvements, Tor clients support 11 additional weights
3316 for directory requests and middle weighting. These weights are currently
3317 set at weight_scale, with the exception of the following groups of
3318 assignments:
3320 Directory requests use middle weights:
3322 Wbd=Wmd, Wbg=Wmg, Wbe=Wme, Wbm=Wmm
3324 Handle bridges and strange exit policies:
3326 Wgm=Wgg, Wem=Wee, Weg=Wed
3328 3.9. Computing consensus flavors
3330 Consensus flavors are variants of the consensus that clients can choose
3331 to download and use instead of the unflavored consensus. The purpose
3332 of a consensus flavor is to remove or replace information in the
3333 unflavored consensus without forcing clients to download information
3334 they would not use anyway.
3336 Directory authorities can produce and serve an arbitrary number of
3337 flavors of the same consensus. A downside of creating too many new
3338 flavors is that clients will be distinguishable based on which flavor
3339 they download. A new flavor should not be created when adding a field
3340 instead wouldn't be too onerous.
3342 Examples for consensus flavors include:
3344 - Publishing hashes of microdescriptors instead of hashes of
3345 full descriptors (see section 3.9.2).
3346 - Including different digests of descriptors, instead of the
3347 perhaps-soon-to-be-totally-broken SHA1.
3349 Consensus flavors are derived from the unflavored consensus once the
3350 voting process is complete. This is to avoid consensus synchronization
3351 problems.
3353 Every consensus flavor has a name consisting of a sequence of one
3354 or more alphanumeric characters and dashes. For compatibility,
3355 the original (unflavored) consensus type is called "ns".
3357 The supported consensus flavors are defined as part of the
3358 authorities' consensus method.
3360 All consensus flavors have in common that their first line is
3361 "network-status-version" where version is 3 or higher, and the flavor
3362 is a string consisting of alphanumeric characters and dashes:
3364 "network-status-version" SP version [SP flavor] NL
3366 3.9.1. ns consensus
3368 The ns consensus flavor is equivalent to the unflavored consensus.
3369 When the flavor is omitted from the "network-status-version" line,
3370 it should be assumed to be "ns". Some implementations may explicitly
3371 state that the flavor is "ns" when generating consensuses, but should
3372 accept consensuses where the flavor is omitted.
3374 3.9.2. Microdescriptor consensus
3376 The microdescriptor consensus is a consensus flavor that contains
3377 microdescriptor hashes instead of descriptor hashes and that omits
3378 exit-policy summaries which are contained in microdescriptors. The
3379 microdescriptor consensus was designed to contain elements that are
3380 small and frequently changing. Clients use the information in the
3381 microdescriptor consensus to decide which servers to fetch information
3382 about and which servers to fetch information from.
3384 The microdescriptor consensus is based on the unflavored consensus with
3385 the exceptions as follows:
3387 "network-status-version" SP version SP "microdesc" NL
3389 [At start, exactly once.]
3391 The flavor name of a microdescriptor consensus is "microdesc".
3393 Changes to router status entries are as follows:
3395 "r" SP nickname SP identity SP publication SP IP SP ORPort
3396 SP DirPort NL
3398 [At start, exactly once.]
3400 Similar to "r" lines in section 3.4.1, but without the digest element.
3402 "a" SP address ":" port NL
3404 [Any number]
3406 Identical to the "a" lines in section 3.4.1.
3408 (Only included when the vote is generated with consensus-method 14
3409 or later, and the consensus is generated with consensus-method 27 or
3410 later.)
3412 "p" ... NL
3414 [At most once]
3416 Not currently generated.
3418 Exit policy summaries are contained in microdescriptors and
3419 therefore omitted in the microdescriptor consensus.
3421 "m" SP digest NL
3423 [Exactly once.*]
3425 "digest" is the base64 of the SHA256 hash of the router's
3426 microdescriptor with trailing =s omitted. For a given router
3427 descriptor digest and consensus method there should only be a
3428 single microdescriptor digest in the "m" lines of all votes.
3429 If different votes have different microdescriptor digests for
3430 the same descriptor digest and consensus method, at least one
3431 of the authorities is broken. If this happens, the microdesc
3432 consensus should contain whichever microdescriptor digest is
3433 most common. If there is no winner, we break ties in the favor
3434 of the lexically earliest.
3436 [*Before consensus method 13, this field was sometimes erroneously
3437 omitted.]
3439 Additionally, a microdescriptor consensus SHOULD use the sha256 digest
3440 algorithm for its signatures.
3442 3.10. Exchanging detached signatures
3444 Once an authority has computed and signed a consensus network status, it
3445 should send its detached signature to each other authority in an HTTP POST
3446 request to the URL:
3448 http://<hostname>/tor/post/consensus-signature
3450 [XXX Note why we support push-and-then-pull.]
3452 All of the detached signatures it knows for consensus status should be
3453 available at:
3455 http://<hostname>/tor/status-vote/next/consensus-signatures.z
3457 Assuming full connectivity, every authority should compute and sign the
3458 same consensus including any flavors in each period. Therefore, it
3459 isn't necessary to download the consensus or any flavors of it computed
3460 by each authority; instead, the authorities only push/fetch each
3461 others' signatures. A "detached signature" document contains items as
3462 follows:
3464 "consensus-digest" SP Digest NL
3466 [At start, at most once.]
3468 The digest of the consensus being signed.
3470 "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
3471 "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
3472 "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
3474 [As in the consensus]
3476 "additional-digest" SP flavor SP algname SP digest NL
3478 [Any number.]
3480 For each supported consensus flavor, every directory authority
3481 adds one or more "additional-digest" lines. "flavor" is the name
3482 of the consensus flavor, "algname" is the name of the hash
3483 algorithm that is used to generate the digest, and "digest" is the
3484 hex-encoded digest.
3486 The hash algorithm for the microdescriptor consensus flavor is
3487 defined as SHA256 with algname "sha256".
3489 "additional-signature" SP flavor SP algname SP identity SP
3490 signing-key-digest NL signature.
3492 [Any number.]
3494 For each supported consensus flavor and defined digest algorithm,
3495 every directory authority adds an "additional-signature" line.
3496 "flavor" is the name of the consensus flavor. "algname" is the
3497 name of the algorithm that was used to hash the identity and
3498 signing keys, and to compute the signature. "identity" is the
3499 hex-encoded digest of the authority identity key of the signing
3500 authority, and "signing-key-digest" is the hex-encoded digest of
3501 the current authority signing key of the signing authority.
3503 The "sha256" signature format is defined as the RSA signature of
3504 the OAEP+-padded SHA256 digest of the item to be signed. When
3505 checking signatures, the signature MUST be treated as valid if the
3506 signature material begins with SHA256(document), so that other
3507 data can get added later.
3508 [To be honest, I didn't fully understand the previous paragraph
3509 and only copied it from the proposals. Review carefully. -KL]
3511 "directory-signature"
3513 [As in the consensus; the signature object is the same as in the
3514 consensus document.]
3516 3.11. Publishing the signed consensus
3518 The voting period ends at the valid-after time. If the consensus has
3519 been signed by a majority of authorities, these documents are made
3520 available at
3522 http://<hostname>/tor/status-vote/current/consensus.z
3524 and
3526 http://<hostname>/tor/status-vote/current/consensus-signatures.z
3528 [XXX current/consensus-signatures is not currently implemented, as it
3529 is not used in the voting protocol.]
3531 [XXX possible future features include support for downloading old
3532 consensuses.]
3534 The other vote documents are analogously made available under
3536 http://<hostname>/tor/status-vote/current/authority.z
3537 http://<hostname>/tor/status-vote/current/<fp>.z
3538 http://<hostname>/tor/status-vote/current/d/<d>.z
3539 http://<hostname>/tor/status-vote/current/bandwidth.z
3541 once the voting period ends, regardless of the number of signatures.
3543 The authorities serve another consensus of each flavor "F" from the
3544 locations
3546 /tor/status-vote/(current|next)/consensus-F.z. and
3547 /tor/status-vote/(current|next)/consensus-F/<FP1>+....z.
3549 The standard URLs for bandwidth list files first-appeared in Tor 0.3.5.
3551 4. Directory cache operation
3553 All directory caches implement this section, except as noted.
3555 4.1. Downloading consensus status documents from directory authorities
3557 All directory caches try to keep a recent
3558 network-status consensus document to serve to clients. A cache ALWAYS
3559 downloads a network-status consensus if any of the following are true:
3561 - The cache has no consensus document.
3562 - The cache's consensus document is no longer valid.
3564 Otherwise, the cache downloads a new consensus document at a randomly
3565 chosen time in the first half-interval after its current consensus
3566 stops being fresh. (This time is chosen at random to avoid swarming
3567 the authorities at the start of each period. The interval size is
3568 inferred from the difference between the valid-after time and the
3569 fresh-until time on the consensus.)
3571 [For example, if a cache has a consensus that became valid at 1:00,
3572 and is fresh until 2:00, that cache will fetch a new consensus at
3573 a random time between 2:00 and 2:30.]
3575 Directory caches also fetch consensus flavors from the authorities.
3576 Caches check the correctness of consensus flavors, but do not check
3577 anything about an unrecognized consensus document beyond its digest and
3578 length. Caches serve all consensus flavors from the same locations as
3579 the directory authorities.
3581 4.2. Downloading server descriptors from directory authorities
3583 Periodically (currently, every 10 seconds), directory caches check
3584 whether there are any specific descriptors that they do not have and that
3585 they are not currently trying to download. Caches identify these
3586 descriptors by hash in the recent network-status consensus documents.
3588 If so, the directory cache launches requests to the authorities for these
3589 descriptors.
3591 If one of these downloads fails, we do not try to download that descriptor
3592 from the authority that failed to serve it again unless we receive a newer
3593 network-status consensus that lists the same descriptor.
3595 Directory caches must potentially cache multiple descriptors for each
3596 router. Caches must not discard any descriptor listed by any recent
3597 consensus. If there is enough space to store additional descriptors,
3598 caches SHOULD try to hold those which clients are likely to download the
3599 most. (Currently, this is judged based on the interval for which each
3600 descriptor seemed newest.)
3602 [XXXX define recent]
3604 4.3. Downloading microdescriptors from directory authorities
3606 Directory mirrors should fetch, cache, and serve each microdescriptor
3607 from the authorities.
3609 The microdescriptors with base64 hashes <D1>,<D2>,<D3> are available
3610 at:
3612 http://<hostname>/tor/micro/d/<D1>-<D2>-<D3>[.z]
3614 <Dn> are base64 encoded with trailing =s omitted for size and for
3615 consistency with the microdescriptor consensus format. -s are used
3616 instead of +s to separate items, since the + character is used in
3617 base64 encoding.
3619 Directory mirrors should check to make sure that the microdescriptors
3620 they're about to serve match the right hashes (either the hashes from
3621 the fetch URL or the hashes from the consensus, respectively).
3623 (NOTE: Due to squid proxy url limitations at most 92 microdescriptor hashes
3624 can be retrieved in a single request.)
3626 4.4. Downloading extra-info documents from directory authorities
3628 Any cache that chooses to cache extra-info documents should implement this
3629 section.
3631 Periodically, the Tor instance checks whether it is missing any extra-info
3632 documents: in other words, if it has any server descriptors with an
3633 extra-info-digest field that does not match any of the extra-info
3634 documents currently held. If so, it downloads whatever extra-info
3635 documents are missing. Caches download from authorities. We follow the
3636 same splitting and back-off rules as in section 4.2.
3638 4.5. Consensus diffs
3640 Instead of downloading an entire consensus, clients may download
3641 a "diff" document containing an ed-style diff from a previous
3642 consensus document. Caches (and authorities) make these diffs as
3643 they learn about new consensuses. To do so, they must store a
3644 record of older consensuses.
3646 (Support for consensus diffs was added in 0.3.1.1-alpha, and is
3647 advertised with the DirCache protocol version "2" or later.)
3649 4.5.1. Consensus diff format
3651 Consensus diffs are formatted as follows:
3653 The first line is "network-status-diff-version 1" NL
3655 The second line is
3657 "hash" SP FromDigest SP ToDigest NL
3659 where FromDigest is the hex-encoded SHA3-256 digest of the _signed
3660 part_ of the consensus that the diff should be applied to, and
3661 ToDigest is the hex-encoded SHA3-256 digest of the _entire_
3662 consensus resulting from applying the diff. (See 3.4.1 for
3663 information on that part of a consensus is signed.)
3665 The third and subsequent lines encode the diff from FromDigest to
3666 ToDigest in a limited subset of the ed diff format, as specified
3667 in appendix E.
3669 4.5.2. Serving and requesting diffs.
3671 When downloading the current consensus, a client may include an
3672 HTTP header of the form
3674 X-Or-Diff-From-Consensus: HASH1, HASH2, ...
3676 where the HASH values are hex-encoded SHA3-256 digests of the
3677 _signed part_ of one or more consensuses that the client knows
3678 about.
3680 If a cache knows a consensus diff from one of those consensuses
3681 to the most recent consensus of the requested flavor, it may
3682 send that diff instead of the specified consensus.
3684 Caches also serve diffs from the URIs:
3686 /tor/status-vote/current/consensus/diff/<HASH>/<FPRLIST>.z
3687 /tor/status-vote/current/consensus-<FLAVOR>/diff/<HASH>/<FPRLIST>.z
3689 where FLAVOR is the consensus flavor, defaulting to "ns", and
3690 FPRLIST is +-separated list of recognized authority identity
3691 fingerprints as in appendix B.
3693 4.6 Retrying failed downloads
3695 See section 5.5 below; it applies to caches as well as clients.
3697 5. Client operation
3699 Every Tor that is not a directory server (that is, those that do
3700 not have a DirPort set) implements this section.
3702 5.1. Downloading network-status documents
3704 Each client maintains a list of directory authorities. Insofar as
3705 possible, clients SHOULD all use the same list.
3707 [Newer versions of Tor (0.2.8.1-alpha and later):
3708 Each client also maintains a list of default fallback directory mirrors
3709 (fallbacks). Each released version of Tor MAY have a different list,
3710 depending on the mirrors that satisfy the fallback directory criteria at
3711 release time.]
3713 Clients try to have a live consensus network-status document at all times.
3714 A network-status document is "live" if the time in its valid-after field
3715 has passed, and the time in its valid-until field has not passed.
3717 When a client has no consensus network-status document, it downloads it
3718 from a randomly chosen fallback directory mirror or authority. Clients
3719 prefer fallbacks to authorities, trying them earlier and more frequently.
3720 In all other cases, the client downloads from caches randomly chosen from
3721 among those believed to be V3 directory servers. (This information comes
3722 from the network-status documents.)
3724 After receiving any response client MUST discard any network-status
3725 documents that it did not request.
3727 On failure, the client waits briefly, then tries that network-status
3728 document again from another cache. The client does not build circuits
3729 until it has a live network-status consensus document, and it has
3730 descriptors for a significant proportion of the routers that it believes
3731 are running (this is configurable using torrc options and consensus
3732 parameters).
3734 [Newer versions of Tor (0.2.6.2-alpha and later):
3735 If the consensus contains Exits (the typical case), Tor will build both
3736 exit and internal circuits. When bootstrap completes, Tor will be ready
3737 to handle an application requesting an exit circuit to services like the
3738 World Wide Web.
3740 If the consensus does not contain Exits, Tor will only build internal
3741 circuits. In this case, earlier statuses will have included "internal"
3742 as indicated above. When bootstrap completes, Tor will be ready to handle
3743 an application requesting an internal circuit to hidden services at
3744 ".onion" addresses.
3746 If a future consensus contains Exits, exit circuits may become available.]
3748 (Note: clients can and should pick caches based on the network-status
3749 information they have: once they have first fetched network-status info
3750 from an authority or fallback, they should not need to go to the authority
3751 directly again, and should only choose the fallback at random, based on its
3752 consensus weight in the current consensus.)
3754 To avoid swarming the caches whenever a consensus expires, the
3755 clients download new consensuses at a randomly chosen time after the
3756 caches are expected to have a fresh consensus, but before their
3757 consensus will expire. (This time is chosen uniformly at random from
3758 the interval between the time 3/4 into the first interval after the
3759 consensus is no longer fresh, and 7/8 of the time remaining after
3760 that before the consensus is invalid.)
3762 [For example, if a client has a consensus that became valid at 1:00,
3763 and is fresh until 2:00, and expires at 4:00, that client will fetch
3764 a new consensus at a random time between 2:45 and 3:50, since 3/4
3765 of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
3766 minutes is 65 minutes.]
3768 Clients may choose to download the microdescriptor consensus instead
3769 of the general network status consensus. In that case they should use
3770 the same update strategy as for the normal consensus. They should not
3771 download more than one consensus flavor.
3773 When a client does not have a live consensus, it will generally use the
3774 most recent consensus it has if that consensus is "reasonably live". A
3775 "reasonably live" consensus is one that expired less than 24 hours ago.
3777 5.2. Downloading server descriptors or microdescriptors
3779 Clients try to have the best descriptor for each router. A descriptor is
3780 "best" if:
3782 * It is listed in the consensus network-status document.
3784 Periodically (currently every 10 seconds) clients check whether there are
3785 any "downloadable" descriptors. A descriptor is downloadable if:
3787 - It is the "best" descriptor for some router.
3788 - The descriptor was published at least 10 minutes in the past.
3789 (This prevents clients from trying to fetch descriptors that the
3790 mirrors have probably not yet retrieved and cached.)
3791 - The client does not currently have it.
3792 - The client is not currently trying to download it.
3793 - The client would not discard it immediately upon receiving it.
3794 - The client thinks it is running and valid (see section 5.4.1 below).
3796 If at least 16 known routers have downloadable descriptors, or if
3797 enough time (currently 10 minutes) has passed since the last time the
3798 client tried to download descriptors, it launches requests for all
3799 downloadable descriptors.
3801 When downloading multiple server descriptors, the client chooses multiple
3802 mirrors so that:
3804 - At least 3 different mirrors are used, except when this would result
3805 in more than one request for under 4 descriptors.
3806 - No more than 128 descriptors are requested from a single mirror.
3807 - Otherwise, as few mirrors as possible are used.
3808 After choosing mirrors, the client divides the descriptors among them
3809 randomly.
3811 After receiving any response the client MUST discard any descriptors that
3812 it did not request.
3814 When a descriptor download fails, the client notes it, and does not
3815 consider the descriptor downloadable again until a certain amount of time
3816 has passed. (Currently 0 seconds for the first failure, 60 seconds for the
3817 second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
3818 thereafter.) Periodically (currently once an hour) clients reset the
3819 failure count.
3821 Clients retain the most recent descriptor they have downloaded for each
3822 router so long as it is listed in the consensus. If it is not listed,
3823 they keep it so long as it is not too old (currently, ROUTER_MAX_AGE=48
3824 hours) and no better router descriptor has been downloaded for the same
3825 relay. Caches retain descriptors until they are at least
3826 OLD_ROUTER_DESC_MAX_AGE=5 days old.
3828 Clients which chose to download the microdescriptor consensus instead
3829 of the general consensus must download the referenced microdescriptors
3830 instead of server descriptors. Clients fetch and cache
3831 microdescriptors preemptively from dir mirrors when starting up, like
3832 they currently fetch descriptors. After bootstrapping, clients only
3833 need to fetch the microdescriptors that have changed.
3835 When a client gets a new microdescriptor consensus, it looks to see if
3836 there are any microdescriptors it needs to learn, and launches a request
3837 for them.
3839 Clients maintain a cache of microdescriptors along with metadata like
3840 when it was last referenced by a consensus, and which identity key
3841 it corresponds to. They keep a microdescriptor until it hasn't been
3842 mentioned in any consensus for a week. Future clients might cache them
3843 for longer or shorter times.
3845 5.3. Downloading extra-info documents
3847 Any client that uses extra-info documents should implement this
3848 section.
3850 Note that generally, clients don't need extra-info documents.
3852 Periodically, the Tor instance checks whether it is missing any extra-info
3853 documents: in other words, if it has any server descriptors with an
3854 extra-info-digest field that does not match any of the extra-info
3855 documents currently held. If so, it downloads whatever extra-info
3856 documents are missing. Clients try to download from caches.
3857 We follow the same splitting and back-off rules as in section 5.2.
3859 5.4. Using directory information
3861 [XXX This subsection really belongs in path-spec.txt, not here. -KL]
3863 Everyone besides directory authorities uses the approaches in this section
3864 to decide which relays to use and what their keys are likely to be.
3865 (Directory authorities just believe their own opinions, as in section 3.4.2
3866 above.)
3868 5.4.1. Choosing routers for circuits.
3870 Circuits SHOULD NOT be built until the client has enough directory
3871 information: a live consensus network status [XXXX fallback?] and
3872 descriptors for at least 1/4 of the relays believed to be running.
3874 A relay is "listed" if it is included by the consensus network-status
3875 document. Clients SHOULD NOT use unlisted relays.
3877 These flags are used as follows:
3879 - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
3880 requested to do so.
3882 - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
3883 very-low-bandwidth circuits (such as introduction circuits).
3885 - Clients SHOULD NOT use non-'Stable' routers for circuits that are
3886 likely to need to be open for a very long time (such as those used for
3887 IRC or SSH connections).
3889 - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
3890 nodes.
3892 See the "path-spec.txt" document for more details.
3894 5.4.2. Managing naming
3896 (This section is removed; authorities no longer assign the 'Named' flag.)
3898 5.4.3. Software versions
3900 An implementation of Tor SHOULD warn when it has fetched a consensus
3901 network-status, and it is running a software version not listed.
3903 5.4.4. Warning about a router's status.
3905 (This section is removed; authorities no longer assign the 'Named' flag.)
3907 5.5. Retrying failed downloads
3909 This section applies to caches as well as to clients.
3911 When a client fails to download a resource (a consensus, a router
3912 descriptor, a microdescriptor, etc) it waits for a certain amount of
3913 time before retrying the download. To determine the amount of time
3914 to wait, clients use a randomized exponential backoff algorithm.
3915 (Specifically, they use a variation of the "decorrelated jitter"
3916 algorithm from
3917 https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ .)
3919 The specific formula used to compute the 'i+1'th delay is:
3921 Delay_{i+1} = MIN(cap, random_between(lower_bound, upper_bound)))
3922 where upper_bound = MAX(lower_bound+1, Delay_i * 3)
3923 lower_bound = MAX(1, base_delay).
3925 The value of 'cap' is set to INT_MAX; the value of 'base_delay'
3926 depends on what is being downloaded, whether the client is fully
3927 bootstrapped, how the client is configured, and where it is
3928 downloading from. Current base_delay values are:
3930 Consensus objects, as a non-bridge cache:
3931 0 (TestingServerConsensusDownloadInitialDelay)
3933 Consensus objects, as a client or bridge that has bootstrapped:
3934 0 (TestingClientConsensusDownloadInitialDelay)
3936 Consensus objects, as a client or bridge that is bootstrapping,
3937 when connecting to an authority because no "fallback" caches are
3938 known:
3939 0 (ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay)
3941 Consensus objects, as a client or bridge that is bootstrapping,
3942 when "fallback" caches are known but connecting to an authority
3943 anyway:
3944 6 (ClientBootstrapConsensusAuthorityDownloadInitialDelay)
3946 Consensus objects, as a client or bridge that is bootstrapping,
3947 when downloading from a "fallback" cache.
3948 0 (ClientBootstrapConsensusFallbackDownloadInitialDelay)
3950 Bridge descriptors, as a bridge-using client when at least one bridge
3951 is usable:
3952 10800 (TestingBridgeDownloadInitialDelay)
3954 Bridge descriptors, otherwise:
3955 0 (TestingBridgeBootstrapDownloadInitialDelay)
3957 Other objects, as cache or authority:
3958 0 (TestingServerDownloadInitialDelay)
3960 Other objects, as client:
3961 0 (TestingClientDownloadInitialDelay)
3964 6. Standards compliance
3966 All clients and servers MUST support HTTP 1.0. Clients and servers MAY
3967 support later versions of HTTP as well.
3969 6.1. HTTP headers
3971 Servers SHOULD set Content-Encoding to the algorithm used to compress the
3972 document(s) being served. Recognized algorithms are:
3974 - "identity" -- RFC2616 section 3.5
3975 - "deflate" -- RFC2616 section 3.5
3976 - "gzip" -- RFC2616 section 3.5
3977 - "x-zstd" -- The zstandard compression algorithm (www.zstd.net)
3978 - "x-tor-lzma" -- The lzma compression algorithm, with a "preset"
3979 value no higher than 6.
3981 Clients SHOULD use Accept-Encoding on most directory requests to indicate
3982 which of the above compression algorithms they support. If they omit it
3983 (as Tor clients did before 0.3.1.1-alpha), then the server should serve
3984 only "deflate" or "identity" encoded documents, based on the presence or
3985 absence of the ".z" suffix on the requested URL.
3987 Note that for anonymous directory requests (that is, requests made over
3988 multi-hop circuits, like those for onion service lookups) implementations
3989 SHOULD NOT advertise any Accept-Encoding values other than deflate. To do
3990 so would be to create a fingerprinting opportunity.
3992 When receiving multiple documents, clients MUST accept compressed
3993 concatenated documents and concatenated compressed documents as
3994 equivalent.
3996 Servers MAY set the Content-Length: header. When they do, it should
3997 match the number of compressed bytes that they are sending.
3999 Servers MAY include an X-Your-Address-Is: header, whose value is the
4000 apparent IP address of the client connecting to them (as a dotted quad).
4001 For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
4002 report the IP from which the circuit carrying the BEGIN_DIR stream reached
4003 them.
4005 Servers SHOULD disable caching of multiple network statuses or multiple
4006 server descriptors. Servers MAY enable caching of single descriptors,
4007 single network statuses, the list of all server descriptors, a v1
4008 directory, or a v1 running routers document. XXX mention times.
4010 6.2. HTTP status codes
4012 Tor delivers the following status codes. Some were chosen without much
4013 thought; other code SHOULD NOT rely on specific status codes yet.
4015 200 -- the operation completed successfully
4016 -- the user requested statuses or serverdescs, and none of the ones we
4017 requested were found (0.2.0.4-alpha and earlier).
4019 304 -- the client specified an if-modified-since time, and none of the
4020 requested resources have changed since that time.
4022 400 -- the request is malformed, or
4023 -- the URL is for a malformed variation of one of the URLs we support,
4024 or
4025 -- the client tried to post to a non-authority, or
4026 -- the authority rejected a malformed posted document, or
4028 404 -- the requested document was not found.
4029 -- the user requested statuses or serverdescs, and none of the ones
4030 requested were found (0.2.0.5-alpha and later).
4032 503 -- we are declining the request in order to save bandwidth
4033 -- user requested some items that we ordinarily generate or store,
4034 but we do not have any available.
4036 A. Consensus-negotiation timeline.
4038 Period begins: this is the Published time.
4039 Everybody sends votes
4040 Reconciliation: everybody tries to fetch missing votes.
4041 consensus may exist at this point.
4042 End of voting period:
4043 everyone swaps signatures.
4044 Now it's okay for caches to download
4045 Now it's okay for clients to download.
4047 Valid-after/valid-until switchover
4049 B. General-use HTTP URLs
4051 "Fingerprints" in these URLs are base16-encoded SHA1 hashes.
4053 The most recent v3 consensus should be available at:
4055 http://<hostname>/tor/status-vote/current/consensus.z
4057 Similarly, the v3 microdescriptor consensus should be available at:
4059 http://<hostname>/tor/status-vote/current/consensus-microdesc.z
4061 Starting with Tor version 0.2.1.1-alpha is also available at:
4063 http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
4065 (NOTE: Due to squid proxy url limitations at most 96 fingerprints can be
4066 retrieved in a single request.)
4068 Where F1, F2, etc. are authority identity fingerprints the client trusts.
4069 Servers will only return a consensus if more than half of the requested
4070 authorities have signed the document, otherwise a 404 error will be sent
4071 back. The fingerprints can be shortened to a length of any multiple of
4072 two, using only the leftmost part of the encoded fingerprint. Tor uses
4073 3 bytes (6 hex characters) of the fingerprint.
4075 Clients SHOULD sort the fingerprints in ascending order. Server MUST
4076 accept any order.
4078 Clients SHOULD use this format when requesting consensus documents from
4079 directory authority servers and from caches running a version of Tor
4080 that is known to support this URL format.
4082 A concatenated set of all the current key certificates should be available
4083 at:
4085 http://<hostname>/tor/keys/all.z
4087 The key certificate for this server should be available at:
4089 http://<hostname>/tor/keys/authority.z
4091 The key certificate for an authority whose authority identity fingerprint
4092 is <F> should be available at:
4094 http://<hostname>/tor/keys/fp/<F>.z
4096 The key certificate whose signing key fingerprint is <F> should be
4097 available at:
4099 http://<hostname>/tor/keys/sk/<F>.z
4101 The key certificate whose identity key fingerprint is <F> and whose signing
4102 key fingerprint is <S> should be available at:
4104 http://<hostname>/tor/keys/fp-sk/<F>-<S>.z
4106 (As usual, clients may request multiple certificates using:
4108 http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z )
4110 [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]
4112 The most recent descriptor for a server whose identity key has a
4113 fingerprint of <F> should be available at:
4115 http://<hostname>/tor/server/fp/<F>.z
4117 The most recent descriptors for servers with identity fingerprints
4118 <F1>,<F2>,<F3> should be available at:
4120 http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
4122 (NOTE: Due to squid proxy url limitations at most 96 fingerprints can be
4123 retrieved in a single request.
4125 Implementations SHOULD NOT download descriptors by identity key
4126 fingerprint. This allows a corrupted server (in collusion with a cache) to
4127 provide a unique descriptor to a client, and thereby partition that client
4128 from the rest of the network.)
4130 The server descriptor with (descriptor) digest <D> (in hex) should be
4131 available at:
4133 http://<hostname>/tor/server/d/<D>.z
4135 The most recent descriptors with digests <D1>,<D2>,<D3> should be
4136 available at:
4138 http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
4140 The most recent descriptor for this server should be at:
4142 http://<hostname>/tor/server/authority.z
4144 This is used for authorities, and also if a server is configured
4145 as a bridge. The official Tor implementations (starting at
4146 0.1.1.x) use this resource to test whether a server's own DirPort
4147 is reachable. It is also useful for debugging purposes.
4149 A concatenated set of the most recent descriptors for all known servers
4150 should be available at:
4152 http://<hostname>/tor/server/all.z
4154 Extra-info documents are available at the URLS
4156 http://<hostname>/tor/extra/d/...
4157 http://<hostname>/tor/extra/fp/...
4158 http://<hostname>/tor/extra/all[.z]
4159 http://<hostname>/tor/extra/authority[.z]
4160 (As for /tor/server/ URLs: supports fetching extra-info
4161 documents by their digest, by the fingerprint of their servers,
4162 or all at once. When serving by fingerprint, we serve the
4163 extra-info that corresponds to the descriptor we would serve by
4164 that fingerprint. Only directory authorities of version
4165 0.2.0.1-alpha or later are guaranteed to support the first
4166 three classes of URLs. Caches may support them, and MUST
4167 support them if they have advertised "caches-extra-info".)
4169 For debugging, directories SHOULD expose non-compressed objects at
4170 URLs like the above, but without the final ".z". If the client uses
4171 Accept-Encodings header, it should override the presence or absence
4172 of the ".z" (see section 6.1).
4174 Clients SHOULD use upper case letters (A-F) when base16-encoding
4175 fingerprints. Servers MUST accept both upper and lower case fingerprints
4176 in requests.
4178 C. Converting a curve25519 public key to an ed25519 public key
4180 Given an X25519 key, that is, an affine point (u,v) on the
4181 Montgomery curve defined by
4183 bv^2 = u(u^2 + au +1)
4185 where
4187 a = 486662
4188 b = 1
4190 and comprised of the compressed form (i.e. consisting of only the
4191 u-coordinate), we can retrieve the y-coordinate of the affine point
4192 (x,y) on the twisted Edwards form of the curve defined by
4194 -x^2 + y^2 = 1 + d x^2 y^2
4196 where
4198 d = - 121665/121666
4200 by computing
4202 y = (u-1)/(u+1).
4204 and then we can apply the usual curve25519 twisted Edwards point
4205 decompression algorithm to find _an_ x-coordinate of an affine
4206 twisted Edwards point to check signatures with. Signing keys for
4207 ed25519 are compressed curve points in twisted Edwards form (so a
4208 y-coordinate and the sign of the x-coordinate), and X25519 keys are
4209 compressed curve points in Montgomery form (i.e. a u-coordinate).
4211 However, note that compressed point in Montgomery form neglects to
4212 encode what the sign of the corresponding twisted Edwards
4213 x-coordinate would be. Thus, we need the sign of the x-coordinate
4214 to do this operation; otherwise, we'll have two possible
4215 x-coordinates that might have correspond to the ed25519 public key.
4217 To get the sign, the easiest way is to take the corresponding
4218 private key, feed it to the ed25519 public key generation
4219 algorithm, and see what the sign is.
4221 [Recomputing the sign bit from the private key every time sounds
4222 rather strange and inefficient to me… —isis]
4224 Note that in addition to its coordinates, an expanded Ed25519 private key
4225 also has a 32-byte random value, "prefix", used to compute internal `r`
4226 values in the signature. For security, this prefix value should be
4227 derived deterministically from the curve25519 key. The Tor
4228 implementation derives it as SHA512(private_key | STR)[0..32], where
4229 STR is the nul-terminated string:
4231 "Derive high part of ed25519 key from curve25519 key\0"
4234 On the client side, where there is no access to the curve25519 private
4235 keys, one may use the curve25519 public key's Montgomery u-coordinate to
4236 recover the Montgomery v-coordinate by computing the right-hand side of
4237 the Montgomery curve equation:
4239 bv^2 = u(u^2 + au +1)
4241 where
4243 a = 486662
4244 b = 1
4246 Then, knowing the intended sign of the Edwards x-coordinate, one
4247 may recover said x-coordinate by computing:
4249 x = (u/v) * sqrt(-a - 2)
4251 D. Inferring missing proto lines.
4253 The directory authorities no longer allow versions of Tor before
4254 0.2.4.18-rc. But right now, there is no version of Tor in the consensus
4255 before 0.2.4.19. Therefore, we should disallow versions of Tor earlier
4256 than 0.2.4.19, so that we can have the protocol list for all current Tor
4257 versions include:
4259 Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1-2 Link=1-4
4260 LinkAuth=1 Microdesc=1-2 Relay=1-2
4262 For Desc, Microdesc and Cons, Tor versions before 0.2.7.stable should be
4263 taken to only support version 1.
4265 E. Limited ed diff format
4267 We support the following format for consensus diffs. It's a
4268 subset of the ed diff format, but clients MUST NOT accept other
4269 ed commands.
4271 We support the following ed commands, each on a line by itself:
4273 - "<n1>d" Delete line n1
4274 - "<n1>,<n2>d" Delete lines n1 through n2, inclusive
4275 - "<n1>,$d" Delete line n1 through the end of the file, inclusive.
4276 - "<n1>c" Replace line n1 with the following block
4277 - "<n1>,<n2>c" Replace lines n1 through n2, inclusive, with the
4278 following block.
4279 - "<n1>a" Append the following block after line n1.
4281 Note that line numbers always apply to the file after all previous
4282 commands have already been applied. Note also that line numbers
4283 are 1-indexed.
4285 The commands MUST apply to the file from back to front, such that
4286 lines are only ever referred to by their position in the original
4287 file.
4289 If there are any directory signatures on the original document, the
4290 first command MUST be a "<n1>,$d" form to remove all of the directory
4291 signatures. Using this format ensures that the client will
4292 successfully apply the diff even if they have an unusual encoding for
4293 the signatures.
4295 The replace and append command take blocks. These blocks are simply
4296 appended to the diff after the line with the command. A line with
4297 just a period (".") ends the block (and is not part of the lines
4298 to add). Note that it is impossible to insert a line with just
4299 a single dot.