dir-spec-v2.txt 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897
  1. $Id$
  2. Tor directory protocol, version 2
  3. 0. Scope and preliminaries
  4. This directory protocol is used by Tor version 0.1.1.x and 0.1.2.x. See
  5. dir-spec-v1.txt for information on earlier versions, and dir-spec.txt
  6. for information on later versions.
  7. 0.1. Goals and motivation
  8. There were several problems with the way Tor handles directory information
  9. in version 0.1.0.x and earlier. Here are the problems we try to fix with
  10. this new design, already implemented in 0.1.1.x:
  11. 1. Directories were very large and use up a lot of bandwidth: clients
  12. downloaded descriptors for all router several times an hour.
  13. 2. Every directory authority was a trust bottleneck: if a single
  14. directory authority lied, it could make clients believe for a time an
  15. arbitrarily distorted view of the Tor network.
  16. 3. Our current "verified server" system is kind of nonsensical.
  17. 4. Getting more directory authorities would add more points of failure
  18. and worsen possible partitioning attacks.
  19. There are two problems that remain unaddressed by this design.
  20. 5. Requiring every client to know about every router won't scale.
  21. 6. Requiring every directory cache to know every router won't scale.
  22. We attempt to fix 1-4 here, and to build a solution that will work when we
  23. figure out an answer for 5. We haven't thought at all about what to do
  24. about 6.
  25. 1. Outline
  26. There is a small set (say, around 10) of semi-trusted directory
  27. authorities. A default list of authorities is shipped with the Tor
  28. software. Users can change this list, but are encouraged not to do so, in
  29. order to avoid partitioning attacks.
  30. Routers periodically upload signed "descriptors" to the directory
  31. authorities describing their keys, capabilities, and other information.
  32. Routers may act as directory mirrors (also called "caches"), to reduce
  33. load on the directory authorities. They announce this in their
  34. descriptors.
  35. Each directory authority periodically generates and signs a compact
  36. "network status" document that lists that authority's view of the current
  37. descriptors and status for known routers, but which does not include the
  38. descriptors themselves.
  39. Directory mirrors download, cache, and re-serve network-status documents
  40. to clients.
  41. Clients, directory mirrors, and directory authorities all use
  42. network-status documents to find out when their list of routers is
  43. out-of-date. If it is, they download any missing router descriptors.
  44. Clients download missing descriptors from mirrors; mirrors and authorities
  45. download from authorities. Descriptors are downloaded by the hash of the
  46. descriptor, not by the server's identity key: this prevents servers from
  47. attacking clients by giving them descriptors nobody else uses.
  48. All directory information is uploaded and downloaded with HTTP.
  49. Coordination among directory authorities is done client-side: clients
  50. compute a vote-like algorithm among the network-status documents they
  51. have, and base their decisions on the result.
  52. 1.1. What's different from 0.1.0.x?
  53. Clients used to download a signed concatenated set of router descriptors
  54. (called a "directory") from directory mirrors, regardless of which
  55. descriptors had changed.
  56. Between downloading directories, clients would download "network-status"
  57. documents that would list which servers were supposed to running.
  58. Clients would always believe the most recently published network-status
  59. document they were served.
  60. Routers used to upload fresh descriptors all the time, whether their keys
  61. and other information had changed or not.
  62. 1.2. Document meta-format
  63. Router descriptors, directories, and running-routers documents all obey the
  64. following lightweight extensible information format.
  65. The highest level object is a Document, which consists of one or more
  66. Items. Every Item begins with a KeywordLine, followed by one or more
  67. Objects. A KeywordLine begins with a Keyword, optionally followed by
  68. whitespace and more non-newline characters, and ends with a newline. A
  69. Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  70. An Object is a block of encoded data in pseudo-Open-PGP-style
  71. armor. (cf. RFC 2440)
  72. More formally:
  73. Document ::= (Item | NL)+
  74. Item ::= KeywordLine Object*
  75. KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
  76. Keyword = KeywordChar+
  77. KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  78. ArgumentChar ::= any printing ASCII character except NL.
  79. WS = (SP | TAB)+
  80. Object ::= BeginLine Base-64-encoded-data EndLine
  81. BeginLine ::= "-----BEGIN " Keyword "-----" NL
  82. EndLine ::= "-----END " Keyword "-----" NL
  83. The BeginLine and EndLine of an Object must use the same keyword.
  84. When interpreting a Document, software MUST ignore any KeywordLine that
  85. starts with a keyword it doesn't recognize; future implementations MUST NOT
  86. require current clients to understand any KeywordLine not currently
  87. described.
  88. The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
  89. extensions. All implementations MUST ignore any item of the form "opt
  90. keyword ....." when they would not recognize "keyword ....."; and MUST
  91. treat "opt keyword ....." as synonymous with "keyword ......" when keyword
  92. is recognized.
  93. Implementations before 0.1.2.5-alpha rejected any document with a
  94. KeywordLine that started with a keyword that they didn't recognize.
  95. Implementations MUST prefix items not recognized by older versions of Tor
  96. with an "opt" until those versions of Tor are obsolete.
  97. Other implementations that want to extend Tor's directory format MAY
  98. introduce their own items. The keywords for extension items SHOULD start
  99. with the characters "x-" or "X-", to guarantee that they will not conflict
  100. with keywords used by future versions of Tor.
  101. 2. Router operation
  102. ORs SHOULD generate a new router descriptor whenever any of the
  103. following events have occurred:
  104. - A period of time (18 hrs by default) has passed since the last
  105. time a descriptor was generated.
  106. - A descriptor field other than bandwidth or uptime has changed.
  107. - Bandwidth has changed by at least a factor of 2 from the last time a
  108. descriptor was generated, and at least a given interval of time
  109. (20 mins by default) has passed since then.
  110. - Its uptime has been reset (by restarting).
  111. After generating a descriptor, ORs upload it to every directory
  112. authority they know, by posting it to the URL
  113. http://<hostname:port>/tor/
  114. 2.1. Router descriptor format
  115. Every router descriptor MUST start with a "router" Item; MUST end with a
  116. "router-signature" Item and an extra NL; and MUST contain exactly one
  117. instance of each of the following Items: "published" "onion-key"
  118. "signing-key" "bandwidth".
  119. A router descriptor MAY have zero or one of each of the following Items,
  120. but MUST NOT have more than one: "contact", "uptime", "fingerprint",
  121. "hibernating", "read-history", "write-history", "eventdns", "platform",
  122. "family".
  123. Additionally, a router descriptor MAY contain any number of "accept",
  124. "reject", and "opt" Items. Other than "router" and "router-signature",
  125. the items may appear in any order.
  126. The items' formats are as follows:
  127. "router" nickname address ORPort SocksPort DirPort
  128. Indicates the beginning of a router descriptor. "address" must be an
  129. IPv4 address in dotted-quad format. The last three numbers indicate
  130. the TCP ports at which this OR exposes functionality. ORPort is a port
  131. at which this OR accepts TLS connections for the main OR protocol;
  132. SocksPort is deprecated and should always be 0; and DirPort is the
  133. port at which this OR accepts directory-related HTTP connections. If
  134. any port is not supported, the value 0 is given instead of a port
  135. number.
  136. "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed
  137. Estimated bandwidth for this router, in bytes per second. The
  138. "average" bandwidth is the volume per second that the OR is willing to
  139. sustain over long periods; the "burst" bandwidth is the volume that
  140. the OR is willing to sustain in very short intervals. The "observed"
  141. value is an estimate of the capacity this server can handle. The
  142. server remembers the max bandwidth sustained output over any ten
  143. second period in the past day, and another sustained input. The
  144. "observed" value is the lesser of these two numbers.
  145. "platform" string
  146. A human-readable string describing the system on which this OR is
  147. running. This MAY include the operating system, and SHOULD include
  148. the name and version of the software implementing the Tor protocol.
  149. "published" YYYY-MM-DD HH:MM:SS
  150. The time, in GMT, when this descriptor was generated.
  151. "fingerprint"
  152. A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
  153. hex, with a single space after every 4 characters) for this router's
  154. identity key. A descriptor is considered invalid (and MUST be
  155. rejected) if the fingerprint line does not match the public key.
  156. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  157. be marked with "opt" until earlier versions of Tor are obsolete.]
  158. "hibernating" 0|1
  159. If the value is 1, then the Tor server was hibernating when the
  160. descriptor was published, and shouldn't be used to build circuits.
  161. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
  162. marked with "opt" until earlier versions of Tor are obsolete.]
  163. "uptime"
  164. The number of seconds that this OR process has been running.
  165. "onion-key" NL a public key in PEM format
  166. This key is used to encrypt EXTEND cells for this OR. The key MUST be
  167. accepted for at least 1 week after any new key is published in a
  168. subsequent descriptor.
  169. "signing-key" NL a public key in PEM format
  170. The OR's long-term identity key.
  171. "accept" exitpattern
  172. "reject" exitpattern
  173. These lines describe the rules that an OR follows when
  174. deciding whether to allow a new stream to a given address. The
  175. 'exitpattern' syntax is described below. The rules are considered in
  176. order; if no rule matches, the address will be accepted. For clarity,
  177. the last such entry SHOULD be accept *:* or reject *:*.
  178. "router-signature" NL Signature NL
  179. The "SIGNATURE" object contains a signature of the PKCS1-padded
  180. hash of the entire router descriptor, taken from the beginning of the
  181. "router" line, through the newline after the "router-signature" line.
  182. The router descriptor is invalid unless the signature is performed
  183. with the router's identity key.
  184. "contact" info NL
  185. Describes a way to contact the server's administrator, preferably
  186. including an email address and a PGP key fingerprint.
  187. "family" names NL
  188. 'Names' is a space-separated list of server nicknames or
  189. hexdigests. If two ORs list one another in their "family" entries,
  190. then OPs should treat them as a single OR for the purpose of path
  191. selection.
  192. For example, if node A's descriptor contains "family B", and node B's
  193. descriptor contains "family A", then node A and node B should never
  194. be used on the same circuit.
  195. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  196. "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  197. Declare how much bandwidth the OR has used recently. Usage is divided
  198. into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
  199. defines the end of the most recent interval. The numbers are the
  200. number of bytes used in the most recent intervals, ordered from
  201. oldest to newest.
  202. [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
  203. be marked with "opt" until earlier versions of Tor are obsolete.]
  204. "eventdns" bool NL
  205. Declare whether this version of Tor is using the newer enhanced
  206. dns logic. Versions of Tor without eventdns SHOULD NOT be used for
  207. reverse hostname lookups.
  208. [All versions of Tor before 0.1.2.2-alpha should be assumed to have
  209. this option set to 0 if it is not present. All Tor versions at
  210. 0.1.2.2-alpha or later should be assumed to have this option set to
  211. 1 if it is not present. Until 0.1.2.1-alpha-dev, this option was
  212. not generated, even when eventdns was in use. Versions of Tor
  213. before 0.1.2.1-alpha-dev did not parse this option, so it should be
  214. marked "opt". With 0.2.0.1-alpha, the old 'dnsworker' logic has
  215. been removed, rendering this option of historical interest only.]
  216. 2.2. Nonterminals in router descriptors
  217. nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
  218. hexdigest ::= a '$', followed by 20 hexadecimal characters.
  219. [Represents a server by the digest of its identity key.]
  220. exitpattern ::= addrspec ":" portspec
  221. portspec ::= "*" | port | port "-" port
  222. port ::= an integer between 1 and 65535, inclusive.
  223. [Some implementations incorrectly generate ports with value 0.
  224. Implementations SHOULD accept this, and SHOULD NOT generate it.]
  225. addrspec ::= "*" | ip4spec | ip6spec
  226. ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
  227. ip4 ::= an IPv4 address in dotted-quad format
  228. ip4mask ::= an IPv4 mask in dotted-quad format
  229. num_ip4_bits ::= an integer between 0 and 32
  230. ip6spec ::= ip6 | ip6 "/" num_ip6_bits
  231. ip6 ::= an IPv6 address, surrounded by square brackets.
  232. num_ip6_bits ::= an integer between 0 and 128
  233. bool ::= "0" | "1"
  234. Ports are required; if they are not included in the router
  235. line, they must appear in the "ports" lines.
  236. 3. Network status format
  237. Directory authorities generate, sign, and compress network-status
  238. documents. Directory servers SHOULD generate a fresh network-status
  239. document when the contents of such a document would be different from the
  240. last one generated, and some time (at least one second, possibly longer)
  241. has passed since the last one was generated.
  242. The network status document contains a preamble, a set of router status
  243. entries, and a signature, in that order.
  244. We use the same meta-format as used for directories and router descriptors
  245. in "tor-spec.txt". Implementations MAY insert blank lines
  246. for clarity between sections; these blank lines are ignored.
  247. Implementations MUST NOT depend on blank lines in any particular location.
  248. As used here, "whitespace" is a sequence of 1 or more tab or space
  249. characters.
  250. The preamble contains:
  251. "network-status-version" -- A document format version. For this
  252. specification, the version is "2".
  253. "dir-source" -- The authority's hostname, current IP address, and
  254. directory port, all separated by whitespace.
  255. "fingerprint" -- A base16-encoded hash of the signing key's
  256. fingerprint, with no additional spaces added.
  257. "contact" -- An arbitrary string describing how to contact the
  258. directory server's administrator. Administrators should include at
  259. least an email address and a PGP fingerprint.
  260. "dir-signing-key" -- The directory server's public signing key.
  261. "client-versions" -- A comma-separated list of recommended client
  262. versions.
  263. "server-versions" -- A comma-separated list of recommended server
  264. versions.
  265. "published" -- The publication time for this network-status object.
  266. "dir-options" -- A set of flags, in any order, separated by whitespace:
  267. "Names" if this directory authority performs name bindings.
  268. "Versions" if this directory authority recommends software versions.
  269. "BadExits" if the directory authority flags nodes that it believes
  270. are performing incorrectly as exit nodes.
  271. "BadDirectories" if the directory authority flags nodes that it
  272. believes are performing incorrectly as directory caches.
  273. The dir-options entry is optional. The "-versions" entries are required if
  274. the "Versions" flag is present. The other entries are required and must
  275. appear exactly once. The "network-status-version" entry must appear first;
  276. the others may appear in any order. Implementations MUST ignore
  277. additional arguments to the items above, and MUST ignore unrecognized
  278. flags.
  279. For each router, the router entry contains: (This format is designed for
  280. conciseness.)
  281. "r" -- followed by the following elements, in order, separated by
  282. whitespace:
  283. - The OR's nickname,
  284. - A hash of its identity key, encoded in base64, with trailing =
  285. signs removed.
  286. - A hash of its most recent descriptor, encoded in base64, with
  287. trailing = signs removed. (The hash is calculated as for
  288. computing the signature of a descriptor.)
  289. - The publication time of its most recent descriptor, in the form
  290. YYYY-MM-DD HH:MM:SS, in GMT.
  291. - An IP address
  292. - An OR port
  293. - A directory port (or "0" for none")
  294. "s" -- A series of whitespace-separated status flags, in any order:
  295. "Authority" if the router is a directory authority.
  296. "BadExit" if the router is believed to be useless as an exit node
  297. (because its ISP censors it, because it is behind a restrictive
  298. proxy, or for some similar reason).
  299. "BadDirectory" if the router is believed to be useless as a
  300. directory cache (because its directory port isn't working,
  301. its bandwidth is always throttled, or for some similar
  302. reason).
  303. "Exit" if the router is useful for building general-purpose exit
  304. circuits.
  305. "Fast" if the router is suitable for high-bandwidth circuits.
  306. "Guard" if the router is suitable for use as an entry guard.
  307. "Named" if the router's identity-nickname mapping is canonical,
  308. and this authority binds names.
  309. "Stable" if the router is suitable for long-lived circuits.
  310. "Running" if the router is currently usable.
  311. "Valid" if the router has been 'validated'.
  312. "V2Dir" if the router implements this protocol.
  313. "v" -- The version of the Tor protocol that this server is running. If
  314. the value begins with "Tor" SP, the rest of the string is a Tor
  315. version number, and the protocol is "The Tor protocol as supported
  316. by the given version of Tor." Otherwise, if the value begins with
  317. some other string, Tor has upgraded to a more sophisticated
  318. protocol versioning system, and the protocol is "a version of the
  319. Tor protocol more recent than any we recognize."
  320. The "r" entry for each router must appear first and is required. The
  321. "s" entry is optional (see Section 3.1 below for how the flags are
  322. decided). Unrecognized flags on the "s" line and extra elements
  323. on the "r" line must be ignored. The "v" line is optional; it was not
  324. supported until 0.1.2.5-alpha, and it must be preceded with an "opt"
  325. until all earlier versions of Tor are obsolete.
  326. The signature section contains:
  327. "directory-signature" nickname-of-dirserver NL Signature
  328. Signature is a signature of this network-status document
  329. (the document up until the signature, including the line
  330. "directory-signature <nick>\n"), using the directory authority's
  331. signing key.
  332. We compress the network status list with zlib before transmitting it.
  333. 3.1. Establishing server status
  334. (This section describes how directory authorities choose which status
  335. flags to apply to routers, as of Tor 0.1.1.18-rc. Later directory
  336. authorities MAY do things differently, so long as clients keep working
  337. well. Clients MUST NOT depend on the exact behaviors in this section.)
  338. In the below definitions, a router is considered "active" if it is
  339. running, valid, and not hibernating.
  340. "Valid" -- a router is 'Valid' if it is running a version of Tor not
  341. known to be broken, and the directory authority has not blacklisted
  342. it as suspicious.
  343. "Named" -- Directory authority administrators may decide to support name
  344. binding. If they do, then they must maintain a file of
  345. nickname-to-identity-key mappings, and try to keep this file consistent
  346. with other directory authorities. If they don't, they act as clients, and
  347. report bindings made by other directory authorities (name X is bound to
  348. identity Y if at least one binding directory lists it, and no directory
  349. binds X to some other Y'.) A router is called 'Named' if the router
  350. believes the given name should be bound to the given key.
  351. "Running" -- A router is 'Running' if the authority managed to connect to
  352. it successfully within the last 30 minutes.
  353. "Stable" -- A router is 'Stable' if it is active, and either its
  354. uptime is at least the median uptime for known active routers, or
  355. its uptime is at least 30 days. Routers are never called stable if
  356. they are running a version of Tor known to drop circuits stupidly.
  357. (0.1.1.10-alpha through 0.1.1.16-rc are stupid this way.)
  358. "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
  359. in the top 7/8ths for known active routers.
  360. "Guard" -- A router is a possible 'Guard' if it is 'Stable' and its
  361. bandwidth is above median for known active routers. If the total
  362. bandwidth of active non-BadExit Exit servers is less than one third
  363. of the total bandwidth of all active servers, no Exit is listed as
  364. a Guard.
  365. "Authority" -- A router is called an 'Authority' if the authority
  366. generating the network-status document believes it is an authority.
  367. "V2Dir" -- A router supports the v2 directory protocol if it has an open
  368. directory port, and it is running a version of the directory protocol that
  369. supports the functionality clients need. (Currently, this is
  370. 0.1.1.9-alpha or later.)
  371. Directory server administrators may label some servers or IPs as
  372. blacklisted, and elect not to include them in their network-status lists.
  373. Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
  374. When there are more than 3 to choose from, authorities should first prefer
  375. authorities to non-authorities, then prefer Running to non-Running, and
  376. then prefer high-bandwidth to low-bandwidth. To 'disable' a server, the
  377. authority *should* advertise it without the Running or Valid flag.
  378. Thus, the network-status list includes all non-blacklisted,
  379. non-expired, non-superseded descriptors.
  380. 4. Directory server operation
  381. All directory authorities and directory mirrors ("directory servers")
  382. implement this section, except as noted.
  383. 4.1. Accepting uploads (authorities only)
  384. When a router posts a signed descriptor to a directory authority, the
  385. authority first checks whether it is well-formed and correctly
  386. self-signed. If it is, the authority next verifies that the nickname
  387. in question is not already assigned to a router with a different
  388. public key.
  389. Finally, the authority MAY check that the router is not blacklisted
  390. because of its key, IP, or another reason.
  391. If the descriptor passes these tests, and the authority does not already
  392. have a descriptor for a router with this public key, it accepts the
  393. descriptor and remembers it.
  394. If the authority _does_ have a descriptor with the same public key, the
  395. newly uploaded descriptor is remembered if its publication time is more
  396. recent than the most recent old descriptor for that router, and either:
  397. - There are non-cosmetic differences between the old descriptor and the
  398. new one.
  399. - Enough time has passed between the descriptors' publication times.
  400. (Currently, 12 hours.)
  401. Differences between router descriptors are "non-cosmetic" if they would be
  402. sufficient to force an upload as described in section 2 above.
  403. Note that the "cosmetic difference" test only applies to uploaded
  404. descriptors, not to descriptors that the authority downloads from other
  405. authorities.
  406. 4.2. Downloading network-status documents (authorities and caches)
  407. All directory servers (authorities and mirrors) try to keep a fresh
  408. set of network-status documents from every authority. To do so,
  409. every 5 minutes, each authority asks every other authority for its
  410. most recent network-status document. Every 15 minutes, each mirror
  411. picks a random authority and asks it for the most recent network-status
  412. documents for all the authorities the authority knows about (including
  413. the chosen authority itself).
  414. Directory servers and mirrors remember and serve the most recent
  415. network-status document they have from each authority. Other
  416. network-status documents don't need to be stored. If the most recent
  417. network-status document is over 10 days old, it is discarded anyway.
  418. Mirrors SHOULD store and serve network-status documents from authorities
  419. they don't recognize, but SHOULD NOT use such documents for any other
  420. purpose. Mirrors SHOULD discard network-status documents older than 48
  421. hours.
  422. 4.3. Downloading and storing router descriptors (authorities and caches)
  423. Periodically (currently, every 10 seconds), directory servers check
  424. whether there are any specific descriptors (as identified by descriptor
  425. hash in a network-status document) that they do not have and that they
  426. are not currently trying to download.
  427. If so, the directory server launches requests to the authorities for these
  428. descriptors, such that each authority is only asked for descriptors listed
  429. in its most recent network-status. When more than one authority lists the
  430. descriptor, we choose which to ask at random.
  431. If one of these downloads fails, we do not try to download that descriptor
  432. from the authority that failed to serve it again unless we receive a newer
  433. network-status from that authority that lists the same descriptor.
  434. Directory servers must potentially cache multiple descriptors for each
  435. router. Servers must not discard any descriptor listed by any current
  436. network-status document from any authority. If there is enough space to
  437. store additional descriptors, servers SHOULD try to hold those which
  438. clients are likely to download the most. (Currently, this is judged
  439. based on the interval for which each descriptor seemed newest.)
  440. Authorities SHOULD NOT download descriptors for routers that they would
  441. immediately reject for reasons listed in 3.1.
  442. 4.4. HTTP URLs
  443. "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
  444. The authoritative network-status published by a host should be available at:
  445. http://<hostname>/tor/status/authority.z
  446. The network-status published by a host with fingerprint
  447. <F> should be available at:
  448. http://<hostname>/tor/status/fp/<F>.z
  449. The network-status documents published by hosts with fingerprints
  450. <F1>,<F2>,<F3> should be available at:
  451. http://<hostname>/tor/status/fp/<F1>+<F2>+<F3>.z
  452. The most recent network-status documents from all known authorities,
  453. concatenated, should be available at:
  454. http://<hostname>/tor/status/all.z
  455. The most recent descriptor for a server whose identity key has a
  456. fingerprint of <F> should be available at:
  457. http://<hostname>/tor/server/fp/<F>.z
  458. The most recent descriptors for servers with identity fingerprints
  459. <F1>,<F2>,<F3> should be available at:
  460. http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
  461. (NOTE: Implementations SHOULD NOT download descriptors by identity key
  462. fingerprint. This allows a corrupted server (in collusion with a cache) to
  463. provide a unique descriptor to a client, and thereby partition that client
  464. from the rest of the network.)
  465. The server descriptor with (descriptor) digest <D> (in hex) should be
  466. available at:
  467. http://<hostname>/tor/server/d/<D>.z
  468. The most recent descriptors with digests <D1>,<D2>,<D3> should be
  469. available at:
  470. http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
  471. The most recent descriptor for this server should be at:
  472. http://<hostname>/tor/server/authority.z
  473. [Nothing in the Tor protocol uses this resource yet, but it is useful
  474. for debugging purposes. Also, the official Tor implementations
  475. (starting at 0.1.1.x) use this resource to test whether a server's
  476. own DirPort is reachable.]
  477. A concatenated set of the most recent descriptors for all known servers
  478. should be available at:
  479. http://<hostname>/tor/server/all.z
  480. For debugging, directories SHOULD expose non-compressed objects at URLs like
  481. the above, but without the final ".z".
  482. Clients MUST handle compressed concatenated information in two forms:
  483. - A concatenated list of zlib-compressed objects.
  484. - A zlib-compressed concatenated list of objects.
  485. Directory servers MAY generate either format: the former requires less
  486. CPU, but the latter requires less bandwidth.
  487. Clients SHOULD use upper case letters (A-F) when base16-encoding
  488. fingerprints. Servers MUST accept both upper and lower case fingerprints
  489. in requests.
  490. 5. Client operation: downloading information
  491. Every Tor that is not a directory server (that is, those that do
  492. not have a DirPort set) implements this section.
  493. 5.1. Downloading network-status documents
  494. Each client maintains an ordered list of directory authorities.
  495. Insofar as possible, clients SHOULD all use the same ordered list.
  496. For each network-status document a client has, it keeps track of its
  497. publication time *and* the time when the client retrieved it. Clients
  498. consider a network-status document "live" if it was published within the
  499. last 24 hours.
  500. Clients try to have a live network-status document hours from *every*
  501. authority, and try to periodically get new network-status documents from
  502. each authority in rotation as follows:
  503. If a client is missing a live network-status document for any
  504. authority, it tries to fetch it from a directory cache. On failure,
  505. the client waits briefly, then tries that network-status document
  506. again from another cache. The client does not build circuits until it
  507. has live network-status documents from more than half the authorities
  508. it trusts, and it has descriptors for more than 1/4 of the routers
  509. that it believes are running.
  510. If the most recently _retrieved_ network-status document is over 30
  511. minutes old, the client attempts to download a network-status document.
  512. When choosing which documents to download, clients treat their list of
  513. directory authorities as a circular ring, and begin with the authority
  514. appearing immediately after the authority for their most recently
  515. retrieved network-status document. If this attempt fails (either it
  516. fails to download at all, or the one it gets is not as good as the
  517. one it has), the client retries at other caches several times, before
  518. moving on to the next network-status document in sequence.
  519. Clients discard all network-status documents over 24 hours old.
  520. If enough mirrors (currently 4) claim not to have a given network status,
  521. we stop trying to download that authority's network-status, until we
  522. download a new network-status that makes us believe that the authority in
  523. question is running. Clients should wait a little longer after each
  524. failure.
  525. Clients SHOULD try to batch as many network-status requests as possible
  526. into each HTTP GET.
  527. (Note: clients can and should pick caches based on the network-status
  528. information they have: once they have first fetched network-status info
  529. from an authority, they should not need to go to the authority directly
  530. again.)
  531. 5.2. Downloading and storing router descriptors
  532. Clients try to have the best descriptor for each router. A descriptor is
  533. "best" if:
  534. * It is the most recently published descriptor listed for that router
  535. by at least two network-status documents.
  536. OR,
  537. * No descriptor for that router is listed by two or more
  538. network-status documents, and it is the most recently published
  539. descriptor listed by any network-status document.
  540. Periodically (currently every 10 seconds) clients check whether there are
  541. any "downloadable" descriptors. A descriptor is downloadable if:
  542. - It is the "best" descriptor for some router.
  543. - The descriptor was published at least 10 minutes in the past.
  544. (This prevents clients from trying to fetch descriptors that the
  545. mirrors have probably not yet retrieved and cached.)
  546. - The client does not currently have it.
  547. - The client is not currently trying to download it.
  548. - The client would not discard it immediately upon receiving it.
  549. - The client thinks it is running and valid (see 6.1 below).
  550. If at least 16 known routers have downloadable descriptors, or if
  551. enough time (currently 10 minutes) has passed since the last time the
  552. client tried to download descriptors, it launches requests for all
  553. downloadable descriptors, as described in 5.3 below.
  554. When a descriptor download fails, the client notes it, and does not
  555. consider the descriptor downloadable again until a certain amount of time
  556. has passed. (Currently 0 seconds for the first failure, 60 seconds for the
  557. second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
  558. thereafter.) Periodically (currently once an hour) clients reset the
  559. failure count.
  560. No descriptors are downloaded until the client has downloaded more than
  561. half of the network-status documents.
  562. Clients retain the most recent descriptor they have downloaded for each
  563. router so long as it is not too old (currently, 48 hours), OR so long as
  564. it is recommended by at least one networkstatus AND no "better"
  565. descriptor has been downloaded. [Versions of Tor before 0.1.2.3-alpha
  566. would discard descriptors simply for being published too far in the past.]
  567. [The code seems to discard descriptors in all cases after they're 5
  568. days old. True? -RD]
  569. 5.3. Managing downloads
  570. When a client has no live network-status documents, it downloads
  571. network-status documents from a randomly chosen authority. In all other
  572. cases, the client downloads from mirrors randomly chosen from among those
  573. believed to be V2 directory servers. (This information comes from the
  574. network-status documents; see 6 below.)
  575. When downloading multiple router descriptors, the client chooses multiple
  576. mirrors so that:
  577. - At least 3 different mirrors are used, except when this would result
  578. in more than one request for under 4 descriptors.
  579. - No more than 128 descriptors are requested from a single mirror.
  580. - Otherwise, as few mirrors as possible are used.
  581. After choosing mirrors, the client divides the descriptors among them
  582. randomly.
  583. After receiving any response client MUST discard any network-status
  584. documents and descriptors that it did not request.
  585. 6. Using directory information
  586. Everyone besides directory authorities uses the approaches in this section
  587. to decide which servers to use and what their keys are likely to be.
  588. (Directory authorities just believe their own opinions, as in 3.1 above.)
  589. 6.1. Choosing routers for circuits.
  590. Tor implementations only pay attention to "live" network-status documents.
  591. A network status is "live" if it is the most recently downloaded network
  592. status document for a given directory server, and the server is a
  593. directory server trusted by the client, and the network-status document is
  594. no more than 1 day old.
  595. For time-sensitive information, Tor implementations focus on "recent"
  596. network-status documents. A network status is "recent" if it is live, and
  597. if it was published in the last 60 minutes. If there are fewer
  598. than 3 such documents, the most recently published 3 are "recent." If
  599. there are fewer than 3 in all, all are "recent.")
  600. Circuits SHOULD NOT be built until the client has enough directory
  601. information: network-statuses (or failed attempts to download
  602. network-statuses) for all authorities, network-statuses for at more than
  603. half of the authorities, and descriptors for at least 1/4 of the servers
  604. believed to be running.
  605. A server is "listed" if it is included by more than half of the live
  606. network status documents. Clients SHOULD NOT use unlisted servers.
  607. Clients believe the flags "Valid", "Exit", "Fast", "Guard", "Stable", and
  608. "V2Dir" about a given router when they are asserted by more than half of
  609. the live network-status documents. Clients believe the flag "Running" if
  610. it is listed by more than half of the recent network-status documents.
  611. These flags are used as follows:
  612. - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
  613. requested to do so.
  614. - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
  615. very-low-bandwidth circuits (such as introduction circuits).
  616. - Clients SHOULD NOT use non-'Stable' routers for circuits that are
  617. likely to need to be open for a very long time (such as those used for
  618. IRC or SSH connections).
  619. - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
  620. nodes.
  621. - Clients SHOULD NOT download directory information from non-'V2Dir'
  622. caches.
  623. 6.2. Managing naming
  624. In order to provide human-memorable names for individual server
  625. identities, some directory servers bind names to IDs. Clients handle
  626. names in two ways:
  627. When a client encounters a name it has not mapped before:
  628. If all the live "Naming" network-status documents the client has
  629. claim that the name binds to some identity ID, and the client has at
  630. least three live network-status documents, the client maps the name to
  631. ID.
  632. When a user tries to refer to a router with a name that does not have a
  633. mapping under the above rules, the implementation SHOULD warn the user.
  634. After giving the warning, the implementation MAY use a router that at
  635. least one Naming authority maps the name to, so long as no other naming
  636. authority maps that name to a different router. If no Naming authority
  637. maps the name to a router, the implementation MAY use any router that
  638. advertises the name.
  639. Not every router needs a nickname. When a router doesn't configure a
  640. nickname, it publishes with the default nickname "Unnamed". Authorities
  641. SHOULD NOT ever mark a router with this nickname as Named; client software
  642. SHOULD NOT ever use a router in response to a user request for a router
  643. called "Unnamed".
  644. 6.3. Software versions
  645. An implementation of Tor SHOULD warn when it has fetched (or has
  646. attempted to fetch and failed four consecutive times) a network-status
  647. for each authority, and it is running a software version
  648. not listed on more than half of the live "Versioning" network-status
  649. documents.
  650. 6.4. Warning about a router's status.
  651. If a router tries to publish its descriptor to a Naming authority
  652. that has its nickname mapped to another key, the router SHOULD
  653. warn the operator that it is either using the wrong key or is using
  654. an already claimed nickname.
  655. If a router has fetched (or attempted to fetch and failed four
  656. consecutive times) a network-status for every authority, and at
  657. least one of the authorities is "Naming", and no live "Naming"
  658. authorities publish a binding for the router's nickname, the
  659. router MAY remind the operator that the chosen nickname is not
  660. bound to this key at the authorities, and suggest contacting the
  661. authority operators.
  662. ...
  663. 6.5. Router protocol versions
  664. A client should believe that a router supports a given feature if that
  665. feature is supported by the router or protocol versions in more than half
  666. of the live networkstatus's "v" entries for that router. In other words,
  667. if the "v" entries for some router are:
  668. v Tor 0.0.8pre1 (from authority 1)
  669. v Tor 0.1.2.11 (from authority 2)
  670. v FutureProtocolDescription 99 (from authority 3)
  671. then the client should believe that the router supports any feature
  672. supported by 0.1.2.11.
  673. This is currently equivalent to believing the median declared version for
  674. a router in all live networkstatuses.
  675. 7. Standards compliance
  676. All clients and servers MUST support HTTP 1.0.
  677. 7.1. HTTP headers
  678. Servers MAY set the Content-Length: header. Servers SHOULD set
  679. Content-Encoding to "deflate" or "identity".
  680. Servers MAY include an X-Your-Address-Is: header, whose value is the
  681. apparent IP address of the client connecting to them (as a dotted quad).
  682. For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
  683. report the IP from which the circuit carrying the BEGIN_DIR stream reached
  684. them. [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
  685. BEGIN_DIR-tunneled connections.]
  686. Servers SHOULD disable caching of multiple network statuses or multiple
  687. router descriptors. Servers MAY enable caching of single descriptors,
  688. single network statuses, the list of all router descriptors, a v1
  689. directory, or a v1 running routers document. XXX mention times.
  690. 7.2. HTTP status codes
  691. XXX We should write down what return codes dirservers send in what situations.