dir-spec.txt 101 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429
  1. Tor directory protocol, version 3
  2. 0. Scope and preliminaries
  3. This directory protocol is used by Tor version 0.2.0.x-alpha and later.
  4. See dir-spec-v1.txt for information on the protocol used up to the
  5. 0.1.0.x series, and dir-spec-v2.txt for information on the protocol
  6. used by the 0.1.1.x and 0.1.2.x series.
  7. Caches and authorities must still support older versions of the
  8. directory protocols, until the versions of Tor that require them are
  9. finally out of commission.
  10. This document merges and supersedes the following proposals:
  11. 101 Voting on the Tor Directory System
  12. 103 Splitting identity key from regularly used signing key
  13. 104 Long and Short Router Descriptors
  14. XXX when to download certificates.
  15. XXX timeline
  16. XXX fill in XXXXs
  17. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  18. NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
  19. "OPTIONAL" in this document are to be interpreted as described in
  20. RFC 2119.
  21. 0.1. History
  22. The earliest versions of Onion Routing shipped with a list of known
  23. routers and their keys. When the set of routers changed, users needed to
  24. fetch a new list.
  25. The Version 1 Directory protocol
  26. --------------------------------
  27. Early versions of Tor (0.0.2) introduced "Directory authorities": servers
  28. that served signed "directory" documents containing a list of signed
  29. "router descriptors", along with short summary of the status of each
  30. router. Thus, clients could get up-to-date information on the state of
  31. the network automatically, and be certain that the list they were getting
  32. was attested by a trusted directory authority.
  33. Later versions (0.0.8) added directory caches, which download
  34. directories from the authorities and serve them to clients. Non-caches
  35. fetch from the caches in preference to fetching from the authorities, thus
  36. distributing bandwidth requirements.
  37. Also added during the version 1 directory protocol were "router status"
  38. documents: short documents that listed only the up/down status of the
  39. routers on the network, rather than a complete list of all the
  40. descriptors. Clients and caches would fetch these documents far more
  41. frequently than they would fetch full directories.
  42. The Version 2 Directory Protocol
  43. --------------------------------
  44. During the Tor 0.1.1.x series, Tor revised its handling of directory
  45. documents in order to address two major problems:
  46. * Directories had grown quite large (over 1MB), and most directory
  47. downloads consisted mainly of router descriptors that clients
  48. already had.
  49. * Every directory authority was a trust bottleneck: if a single
  50. directory authority lied, it could make clients believe for a time
  51. an arbitrarily distorted view of the Tor network. (Clients
  52. trusted the most recent signed document they downloaded.) Thus,
  53. adding more authorities would make the system less secure, not
  54. more.
  55. To address these, we extended the directory protocol so that
  56. authorities now published signed "network status" documents. Each
  57. network status listed, for every router in the network: a hash of its
  58. identity key, a hash of its most recent descriptor, and a summary of
  59. what the authority believed about its status. Clients would download
  60. the authorities' network status documents in turn, and believe
  61. statements about routers iff they were attested to by more than half of
  62. the authorities.
  63. Instead of downloading all router descriptors at once, clients
  64. downloaded only the descriptors that they did not have. Descriptors
  65. were indexed by their digests, in order to prevent malicious caches
  66. from giving different versions of a router descriptor to different
  67. clients.
  68. Routers began working harder to upload new descriptors only when their
  69. contents were substantially changed.
  70. 0.2. Goals of the version 3 protocol
  71. Version 3 of the Tor directory protocol tries to solve the following
  72. issues:
  73. * A great deal of bandwidth used to transmit router descriptors was
  74. used by two fields that are not actually used by Tor routers
  75. (namely read-history and write-history). We save about 60% by
  76. moving them into a separate document that most clients do not
  77. fetch or use.
  78. * It was possible under certain perverse circumstances for clients
  79. to download an unusual set of network status documents, thus
  80. partitioning themselves from clients who have a more recent and/or
  81. typical set of documents. Even under the best of circumstances,
  82. clients were sensitive to the ages of the network status documents
  83. they downloaded. Therefore, instead of having the clients
  84. correlate multiple network status documents, we have the
  85. authorities collectively vote on a single consensus network status
  86. document.
  87. * The most sensitive data in the entire network (the identity keys
  88. of the directory authorities) needed to be stored unencrypted so
  89. that the authorities can sign network-status documents on the fly.
  90. Now, the authorities' identity keys are stored offline, and used
  91. to certify medium-term signing keys that can be rotated.
  92. 0.3. Some Remaining questions
  93. Things we could solve on a v3 timeframe:
  94. The SHA-1 hash is showing its age. We should do something about our
  95. dependency on it. We could probably future-proof ourselves here in
  96. this revision, at least so far as documents from the authorities are
  97. concerned.
  98. Too many things about the authorities are hardcoded by IP.
  99. Perhaps we should start accepting longer identity keys for routers
  100. too.
  101. Things to solve eventually:
  102. Requiring every client to know about every router won't scale forever.
  103. Requiring every directory cache to know every router won't scale
  104. forever.
  105. 1. Outline
  106. There is a small set (say, around 5-10) of semi-trusted directory
  107. authorities. A default list of authorities is shipped with the Tor
  108. software. Users can change this list, but are encouraged not to do so,
  109. in order to avoid partitioning attacks.
  110. Every authority has a very-secret, long-term "Authority Identity Key".
  111. This is stored encrypted and/or offline, and is used to sign "key
  112. certificate" documents. Every key certificate contains a medium-term
  113. (3-12 months) "authority signing key", that is used by the authority to
  114. sign other directory information. (Note that the authority identity
  115. key is distinct from the router identity key that the authority uses
  116. in its role as an ordinary router.)
  117. Routers periodically upload signed "routers descriptors" to the
  118. directory authorities describing their keys, capabilities, and other
  119. information. Routers may also upload signed "extra info documents"
  120. containing information that is not required for the Tor protocol.
  121. Directory authorities serve router descriptors indexed by router
  122. identity, or by hash of the descriptor.
  123. Routers may act as directory caches to reduce load on the directory
  124. authorities. They announce this in their descriptors.
  125. Periodically, each directory authority generates a view of
  126. the current descriptors and status for known routers. They send a
  127. signed summary of this view (a "status vote") to the other
  128. authorities. The authorities compute the result of this vote, and sign
  129. a "consensus status" document containing the result of the vote.
  130. Directory caches download, cache, and re-serve consensus documents.
  131. Clients, directory caches, and directory authorities all use consensus
  132. documents to find out when their list of routers is out-of-date.
  133. (Directory authorities also use vote statuses.) If it is, they download
  134. any missing router descriptors. Clients download missing descriptors
  135. from caches; caches and authorities download from authorities.
  136. Descriptors are downloaded by the hash of the descriptor, not by the
  137. server's identity key: this prevents servers from attacking clients by
  138. giving them descriptors nobody else uses.
  139. All directory information is uploaded and downloaded with HTTP.
  140. [Authorities also generate and caches also cache documents produced and
  141. used by earlier versions of this protocol; see dir-spec-v1.txt and
  142. dir-spec-v2.txt for notes on those versions.]
  143. 1.1. What's different from version 2?
  144. Clients used to download multiple network status documents,
  145. corresponding roughly to "status votes" above. They would compute the
  146. result of the vote on the client side.
  147. Authorities used to sign documents using the same private keys they used
  148. for their roles as routers. This forced them to keep these extremely
  149. sensitive keys in memory unencrypted.
  150. All of the information in extra-info documents used to be kept in the
  151. main descriptors.
  152. 1.2. Document meta-format
  153. Router descriptors, directories, and running-routers documents all obey the
  154. following lightweight extensible information format.
  155. The highest level object is a Document, which consists of one or more
  156. Items. Every Item begins with a KeywordLine, followed by zero or more
  157. Objects. A KeywordLine begins with a Keyword, optionally followed by
  158. whitespace and more non-newline characters, and ends with a newline. A
  159. Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  160. An Object is a block of encoded data in pseudo-Open-PGP-style
  161. armor. (cf. RFC 2440)
  162. More formally:
  163. NL = The ascii LF character (hex value 0x0a).
  164. Document ::= (Item | NL)+
  165. Item ::= KeywordLine Object*
  166. KeywordLine ::= Keyword NL | Keyword WS ArgumentChar+ NL
  167. Keyword = KeywordChar+
  168. KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  169. ArgumentChar ::= any printing ASCII character except NL.
  170. WS = (SP | TAB)+
  171. Object ::= BeginLine Base-64-encoded-data EndLine
  172. BeginLine ::= "-----BEGIN " Keyword "-----" NL
  173. EndLine ::= "-----END " Keyword "-----" NL
  174. The BeginLine and EndLine of an Object must use the same keyword.
  175. When interpreting a Document, software MUST ignore any KeywordLine that
  176. starts with a keyword it doesn't recognize; future implementations MUST NOT
  177. require current clients to understand any KeywordLine not currently
  178. described.
  179. The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
  180. extensions. All implementations MUST ignore any item of the form "opt
  181. keyword ....." when they would not recognize "keyword ....."; and MUST
  182. treat "opt keyword ....." as synonymous with "keyword ......" when keyword
  183. is recognized.
  184. Implementations before 0.1.2.5-alpha rejected any document with a
  185. KeywordLine that started with a keyword that they didn't recognize.
  186. When generating documents that need to be read by older versions of Tor,
  187. implementations MUST prefix items not recognized by older versions of
  188. Tor with an "opt" until those versions of Tor are obsolete. [Note that
  189. key certificates, status vote documents, extra info documents, and
  190. status consensus documents will never be read by older versions of Tor.]
  191. Other implementations that want to extend Tor's directory format MAY
  192. introduce their own items. The keywords for extension items SHOULD start
  193. with the characters "x-" or "X-", to guarantee that they will not conflict
  194. with keywords used by future versions of Tor.
  195. In our document descriptions below, we tag Items with a multiplicity in
  196. brackets. Possible tags are:
  197. "At start, exactly once": These items MUST occur in every instance of
  198. the document type, and MUST appear exactly once, and MUST be the
  199. first item in their documents.
  200. "Exactly once": These items MUST occur exactly one time in every
  201. instance of the document type.
  202. "At end, exactly once": These items MUST occur in every instance of
  203. the document type, and MUST appear exactly once, and MUST be the
  204. last item in their documents.
  205. "At most once": These items MAY occur zero or one times in any
  206. instance of the document type, but MUST NOT occur more than once.
  207. "Any number": These items MAY occur zero, one, or more times in any
  208. instance of the document type.
  209. "Once or more": These items MUST occur at least once in any instance
  210. of the document type, and MAY occur more.
  211. 1.3. Signing documents
  212. Every signable document below is signed in a similar manner, using a
  213. given "Initial Item", a final "Signature Item", a digest algorithm, and
  214. a signing key.
  215. The Initial Item must be the first item in the document.
  216. The Signature Item has the following format:
  217. <signature item keyword> [arguments] NL SIGNATURE NL
  218. The "SIGNATURE" Object contains a signature (using the signing key) of
  219. the PKCS1-padded digest of the entire document, taken from the
  220. beginning of the Initial item, through the newline after the Signature
  221. Item's keyword and its arguments.
  222. Unless otherwise, the digest algorithm is SHA-1.
  223. All documents are invalid unless signed with the correct signing key.
  224. The "Digest" of a document, unless stated otherwise, is its digest *as
  225. signed by this signature scheme*.
  226. 1.4. Voting timeline
  227. Every consensus document has a "valid-after" (VA) time, a "fresh-until"
  228. (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
  229. in turn precede VU. Times are chosen so that every consensus will be
  230. "fresh" until the next consensus becomes valid, and "valid" for a while
  231. after. At least 3 consensuses should be valid at any given time.
  232. The timeline for a given consensus is as follows:
  233. VA-DistSeconds-VoteSeconds: The authorities exchange votes.
  234. VA-DistSeconds-VoteSeconds/2: The authorities try to download any
  235. votes they don't have.
  236. VA-DistSeconds: The authorities calculate the consensus and exchange
  237. signatures.
  238. VA-DistSeconds/2: The authorities try to download any signatures
  239. they don't have.
  240. VA: All authorities have a multiply signed consensus.
  241. VA ... FU: Caches download the consensus. (Note that since caches have
  242. no way of telling what VA and FU are until they have downloaded
  243. the consensus, they assume that the present consensus's VA is
  244. equal to the previous one's FU, and that its FU is one interval after
  245. that.)
  246. FU: The consensus is no longer the freshest consensus.
  247. FU ... (the current consensus's VU): Clients download the consensus.
  248. (See note above: clients guess that the next consensus's FU will be
  249. two intervals after the current VA.)
  250. VU: The consensus is no longer valid.
  251. VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
  252. VU-FU MUST each be at least 5 minutes.
  253. 2. Router operation and formats
  254. ORs SHOULD generate a new router descriptor and a new extra-info
  255. document whenever any of the following events have occurred:
  256. - A period of time (18 hrs by default) has passed since the last
  257. time a descriptor was generated.
  258. - A descriptor field other than bandwidth or uptime has changed.
  259. - Bandwidth has changed by a factor of 2 from the last time a
  260. descriptor was generated, and at least a given interval of time
  261. (20 mins by default) has passed since then.
  262. - Its uptime has been reset (by restarting).
  263. [XXX this list is incomplete; see router_differences_are_cosmetic()
  264. in routerlist.c for others]
  265. ORs SHOULD NOT publish a new router descriptor or extra-info document
  266. if none of the above events have occurred and not much time has passed
  267. (12 hours by default).
  268. After generating a descriptor, ORs upload them to every directory
  269. authority they know, by posting them (in order) to the URL
  270. http://<hostname:port>/tor/
  271. 2.1. Router descriptor format
  272. Router descriptors consist of the following items. For backward
  273. compatibility, there should be an extra NL at the end of each router
  274. descriptor.
  275. In lines that take multiple arguments, extra arguments SHOULD be
  276. accepted and ignored. Many of the nonterminals below are defined in
  277. section 2.3.
  278. "router" nickname address ORPort SOCKSPort DirPort NL
  279. [At start, exactly once.]
  280. Indicates the beginning of a router descriptor. "nickname" must be a
  281. valid router nickname as specified in 2.3. "address" must be an IPv4
  282. address in dotted-quad format. The last three numbers indicate the
  283. TCP ports at which this OR exposes functionality. ORPort is a port at
  284. which this OR accepts TLS connections for the main OR protocol;
  285. SOCKSPort is deprecated and should always be 0; and DirPort is the
  286. port at which this OR accepts directory-related HTTP connections. If
  287. any port is not supported, the value 0 is given instead of a port
  288. number. (At least one of DirPort and ORPort SHOULD be set;
  289. authorities MAY reject any descriptor with both DirPort and ORPort of
  290. 0.)
  291. "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
  292. [Exactly once]
  293. Estimated bandwidth for this router, in bytes per second. The
  294. "average" bandwidth is the volume per second that the OR is willing to
  295. sustain over long periods; the "burst" bandwidth is the volume that
  296. the OR is willing to sustain in very short intervals. The "observed"
  297. value is an estimate of the capacity this server can handle. The
  298. server remembers the max bandwidth sustained output over any ten
  299. second period in the past day, and another sustained input. The
  300. "observed" value is the lesser of these two numbers.
  301. "platform" string NL
  302. [At most once]
  303. A human-readable string describing the system on which this OR is
  304. running. This MAY include the operating system, and SHOULD include
  305. the name and version of the software implementing the Tor protocol.
  306. "published" YYYY-MM-DD HH:MM:SS NL
  307. [Exactly once]
  308. The time, in GMT, when this descriptor (and its corresponding
  309. extra-info document if any) was generated.
  310. "fingerprint" fingerprint NL
  311. [At most once]
  312. A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
  313. hex, with a single space after every 4 characters) for this router's
  314. identity key. A descriptor is considered invalid (and MUST be
  315. rejected) if the fingerprint line does not match the public key.
  316. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  317. be marked with "opt" until earlier versions of Tor are obsolete.]
  318. "hibernating" bool NL
  319. [At most once]
  320. If the value is 1, then the Tor server was hibernating when the
  321. descriptor was published, and shouldn't be used to build circuits.
  322. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
  323. marked with "opt" until earlier versions of Tor are obsolete.]
  324. "uptime" number NL
  325. [At most once]
  326. The number of seconds that this OR process has been running.
  327. "onion-key" NL a public key in PEM format
  328. [Exactly once]
  329. This key is used to encrypt EXTEND cells for this OR. The key MUST be
  330. accepted for at least 1 week after any new key is published in a
  331. subsequent descriptor. It MUST be 1024 bits.
  332. "signing-key" NL a public key in PEM format
  333. [Exactly once]
  334. The OR's long-term identity key. It MUST be 1024 bits.
  335. "accept" exitpattern NL
  336. "reject" exitpattern NL
  337. [Any number]
  338. These lines describe an "exit policy": the rules that an OR follows
  339. when deciding whether to allow a new stream to a given address. The
  340. 'exitpattern' syntax is described below. There MUST be at least one
  341. such entry. The rules are considered in order; if no rule matches,
  342. the address will be accepted. For clarity, the last such entry SHOULD
  343. be accept *:* or reject *:*.
  344. "router-signature" NL Signature NL
  345. [At end, exactly once]
  346. The "SIGNATURE" object contains a signature of the PKCS1-padded
  347. hash of the entire router descriptor, taken from the beginning of the
  348. "router" line, through the newline after the "router-signature" line.
  349. The router descriptor is invalid unless the signature is performed
  350. with the router's identity key.
  351. "contact" info NL
  352. [At most once]
  353. Describes a way to contact the server's administrator, preferably
  354. including an email address and a PGP key fingerprint.
  355. "family" names NL
  356. [At most once]
  357. 'Names' is a space-separated list of server nicknames or
  358. hexdigests. If two ORs list one another in their "family" entries,
  359. then OPs should treat them as a single OR for the purpose of path
  360. selection.
  361. For example, if node A's descriptor contains "family B", and node B's
  362. descriptor contains "family A", then node A and node B should never
  363. be used on the same circuit.
  364. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  365. [At most once]
  366. "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  367. [At most once]
  368. Declare how much bandwidth the OR has used recently. Usage is divided
  369. into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
  370. defines the end of the most recent interval. The numbers are the
  371. number of bytes used in the most recent intervals, ordered from
  372. oldest to newest.
  373. [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
  374. be marked with "opt" until earlier versions of Tor are obsolete.]
  375. [See also migration notes in section 2.2.1.]
  376. "eventdns" bool NL
  377. [At most once]
  378. Declare whether this version of Tor is using the newer enhanced
  379. dns logic. Versions of Tor with this field set to false SHOULD NOT
  380. be used for reverse hostname lookups.
  381. [This option is obsolete. All Tor current servers should be presumed
  382. to have the evdns backend.]
  383. "caches-extra-info" NL
  384. [At most once.]
  385. Present only if this router is a directory cache that provides
  386. extra-info documents.
  387. [Versions before 0.2.0.1-alpha don't recognize this, and versions
  388. before 0.1.2.5-alpha will reject descriptors containing it unless
  389. it is prefixed with "opt"; it should be so prefixed until these
  390. versions are obsolete.]
  391. "extra-info-digest" digest NL
  392. [At most once]
  393. "Digest" is a hex-encoded digest (using upper-case characters) of the
  394. router's extra-info document, as signed in the router's extra-info
  395. (that is, not including the signature). (If this field is absent, the
  396. router is not uploading a corresponding extra-info document.)
  397. [Versions before 0.2.0.1-alpha don't recognize this, and versions
  398. before 0.1.2.5-alpha will reject descriptors containing it unless
  399. it is prefixed with "opt"; it should be so prefixed until these
  400. versions are obsolete.]
  401. "hidden-service-dir" *(SP VersionNum) NL
  402. [At most once.]
  403. Present only if this router stores and serves hidden service
  404. descriptors. If any VersionNum(s) are specified, this router
  405. supports those descriptor versions. If none are specified, it
  406. defaults to version 2 descriptors.
  407. [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
  408. with unrecognized items; the protocols line should be preceded with
  409. an "opt" until these Tors are obsolete.]
  410. "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
  411. CIRCUIT-VERSION-LIST NL
  412. [At most once.]
  413. Both lists are space-separated sequences of numbers, to indicate which
  414. protocols the server supports. As of 30 Mar 2008, specified
  415. protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt
  416. for more information about link protocol versions.
  417. [Versions of Tor before 0.1.2.5-alpha rejected router descriptors
  418. with unrecognized items; the protocols line should be preceded with
  419. an "opt" until these Tors are obsolete.]
  420. "allow-single-hop-exits" NL
  421. [At most once.]
  422. Present only if the router allows single-hop circuits to make exit
  423. connections. Most Tor servers do not support this: this is
  424. included for specialized controllers designed to support perspective
  425. access and such.
  426. 2.2. Extra-info documents
  427. Extra-info documents consist of the following items:
  428. "extra-info" Nickname Fingerprint NL
  429. [At start, exactly once.]
  430. Identifies what router this is an extra info descriptor for.
  431. Fingerprint is encoded in hex (using upper-case letters), with
  432. no spaces.
  433. "published" YYYY-MM-DD HH:MM:SS NL
  434. [Exactly once.]
  435. The time, in GMT, when this document (and its corresponding router
  436. descriptor if any) was generated. It MUST match the published time
  437. in the corresponding router descriptor.
  438. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  439. [At most once.]
  440. "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  441. [At most once.]
  442. As documented in 2.1 above. See migration notes in section 2.2.1.
  443. "geoip-db-digest" Digest NL
  444. [At most once.]
  445. SHA1 digest of the GeoIP database file that is used to resolve IP
  446. addresses to country codes.
  447. ("geoip-start" YYYY-MM-DD HH:MM:SS NL)
  448. ("geoip-client-origins" CC=N,CC=N,... NL)
  449. Only generated by bridge routers (see blocking.pdf), and only
  450. when they have been configured with a geoip database.
  451. Non-bridges SHOULD NOT generate these fields. Contains a list
  452. of mappings from two-letter country codes (CC) to the number
  453. of clients that have connected to that bridge from that
  454. country (approximate, and rounded up to the nearest multiple of 8
  455. in order to hamper traffic analysis). A country is included
  456. only if it has at least one address. The time in
  457. "geoip-start" is the time at which we began collecting geoip
  458. statistics.
  459. "geoip-start" and "geoip-client-origins" have been replaced by
  460. "bridge-stats-end" and "bridge-stats-ips" in 0.2.2.4-alpha. The
  461. reason is that the measurement interval with "geoip-stats" as
  462. determined by subtracting "geoip-start" from "published" could
  463. have had a variable length, whereas the measurement interval in
  464. 0.2.2.4-alpha and later is set to be exactly 24 hours long. In
  465. order to clearly distinguish the new measurement intervals from
  466. the old ones, the new keywords have been introduced.
  467. "bridge-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  468. [At most once.]
  469. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  470. interval of length NSEC seconds (86400 seconds by default).
  471. A "bridge-stats-end" line, as well as any other "bridge-*" line,
  472. is only added when the relay has been running as a bridge for at
  473. least 24 hours.
  474. "bridge-ips" CC=N,CC=N,... NL
  475. [At most once.]
  476. List of mappings from two-letter country codes to the number of
  477. unique IP addresses that have connected from that country to the
  478. bridge and which are no known relays, rounded up to the nearest
  479. multiple of 8.
  480. "dirreq-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  481. [At most once.]
  482. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  483. interval of length NSEC seconds (86400 seconds by default).
  484. A "dirreq-stats-end" line, as well as any other "dirreq-*" line,
  485. is only added when the relay has opened its Dir port and after 24
  486. hours of measuring directory requests.
  487. "dirreq-v2-ips" CC=N,CC=N,... NL
  488. [At most once.]
  489. "dirreq-v3-ips" CC=N,CC=N,... NL
  490. [At most once.]
  491. List of mappings from two-letter country codes to the number of
  492. unique IP addresses that have connected from that country to
  493. request a v2/v3 network status, rounded up to the nearest multiple
  494. of 8. Only those IP addresses are counted that the directory can
  495. answer with a 200 OK status code.
  496. "dirreq-v2-reqs" CC=N,CC=N,... NL
  497. [At most once.]
  498. "dirreq-v3-reqs" CC=N,CC=N,... NL
  499. [At most once.]
  500. List of mappings from two-letter country codes to the number of
  501. requests for v2/v3 network statuses from that country, rounded up
  502. to the nearest multiple of 8. Only those requests are counted that
  503. the directory can answer with a 200 OK status code.
  504. "dirreq-v2-share" num% NL
  505. [At most once.]
  506. "dirreq-v3-share" num% NL
  507. [At most once.]
  508. The share of v2/v3 network status requests that the directory
  509. expects to receive from clients based on its advertised bandwidth
  510. compared to the overall network bandwidth capacity. Shares are
  511. formatted in percent with two decimal places. Shares are
  512. calculated as means over the whole 24-hour interval.
  513. "dirreq-v2-resp" status=num,... NL
  514. [At most once.]
  515. "dirreq-v3-resp" status=nul,... NL
  516. [At most once.]
  517. List of mappings from response statuses to the number of requests
  518. for v2/v3 network statuses that were answered with that response
  519. status, rounded up to the nearest multiple of 4. Only response
  520. statuses with at least 1 response are reported. New response
  521. statuses can be added at any time. The current list of response
  522. statuses is as follows:
  523. "ok": a network status request is answered; this number
  524. corresponds to the sum of all requests as reported in
  525. "dirreq-v2-reqs" or "dirreq-v3-reqs", respectively, before
  526. rounding up.
  527. "not-enough-sigs: a version 3 network status is not signed by a
  528. sufficient number of requested authorities.
  529. "unavailable": a requested network status object is unavailable.
  530. "not-found": a requested network status is not found.
  531. "not-modified": a network status has not been modified since the
  532. If-Modified-Since time that is included in the request.
  533. "busy": the directory is busy.
  534. "dirreq-v2-direct-dl" key=val,... NL
  535. [At most once.]
  536. "dirreq-v3-direct-dl" key=val,... NL
  537. [At most once.]
  538. "dirreq-v2-tunneled-dl" key=val,... NL
  539. [At most once.]
  540. "dirreq-v3-tunneled-dl" key=val,... NL
  541. [At most once.]
  542. List of statistics about possible failures in the download process
  543. of v2/v3 network statuses. Requests are either "direct"
  544. HTTP-encoded requests over the relay's directory port, or
  545. "tunneled" requests using a BEGIN_DIR cell over the relay's OR
  546. port. The list of possible statistics can change, and statistics
  547. can be left out from reporting. The current list of statistics is
  548. as follows:
  549. Successful downloads and failures:
  550. "complete": a client has finished the download successfully.
  551. "timeout": a download did not finish within 10 minutes after
  552. starting to send the response.
  553. "running": a download is still running at the end of the
  554. measurement period for less than 10 minutes after starting to
  555. send the response.
  556. Download times:
  557. "min", "max": smallest and largest measured bandwidth in B/s.
  558. "d[1-4,6-9]": 1st to 4th and 6th to 9th decile of measured
  559. bandwidth in B/s. For a given decile i, i/10 of all downloads
  560. had a smaller bandwidth than di, and (10-i)/10 of all downloads
  561. had a larger bandwidth than di.
  562. "q[1,3]": 1st and 3rd quartile of measured bandwidth in B/s. One
  563. fourth of all downloads had a smaller bandwidth than q1, one
  564. fourth of all downloads had a larger bandwidth than q3, and the
  565. remaining half of all downloads had a bandwidth between q1 and
  566. q3.
  567. "md": median of measured bandwidth in B/s. Half of the downloads
  568. had a smaller bandwidth than md, the other half had a larger
  569. bandwidth than md.
  570. "dirreq-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
  571. [At most once]
  572. "dirreq-write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
  573. [At most once]
  574. Declare how much bandwidth the OR has spent on answering directory
  575. requests. Usage is divided into intervals of NSEC seconds. The
  576. YYYY-MM-DD HH:MM:SS field defines the end of the most recent
  577. interval. The numbers are the number of bytes used in the most
  578. recent intervals, ordered from oldest to newest.
  579. "entry-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  580. [At most once.]
  581. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  582. interval of length NSEC seconds (86400 seconds by default).
  583. An "entry-stats-end" line, as well as any other "entry-*"
  584. line, is first added after the relay has been running for at least
  585. 24 hours.
  586. "entry-ips" CC=N,CC=N,... NL
  587. [At most once.]
  588. List of mappings from two-letter country codes to the number of
  589. unique IP addresses that have connected from that country to the
  590. relay and which are no known other relays, rounded up to the
  591. nearest multiple of 8.
  592. "cell-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  593. [At most once.]
  594. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  595. interval of length NSEC seconds (86400 seconds by default).
  596. A "cell-stats-end" line, as well as any other "cell-*" line,
  597. is first added after the relay has been running for at least 24
  598. hours.
  599. "cell-processed-cells" num,...,num NL
  600. [At most once.]
  601. Mean number of processed cells per circuit, subdivided into
  602. deciles of circuits by the number of cells they have processed in
  603. descending order from loudest to quietest circuits.
  604. "cell-queued-cells" num,...,num NL
  605. [At most once.]
  606. Mean number of cells contained in queues by circuit decile. These
  607. means are calculated by 1) determining the mean number of cells in
  608. a single circuit between its creation and its termination and 2)
  609. calculating the mean for all circuits in a given decile as
  610. determined in "cell-processed-cells". Numbers have a precision of
  611. two decimal places.
  612. "cell-time-in-queue" num,...,num NL
  613. [At most once.]
  614. Mean time cells spend in circuit queues in milliseconds. Times are
  615. calculated by 1) determining the mean time cells spend in the
  616. queue of a single circuit and 2) calculating the mean for all
  617. circuits in a given decile as determined in
  618. "cell-processed-cells".
  619. "cell-circuits-per-decile" num NL
  620. [At most once.]
  621. Mean number of circuits that are included in any of the deciles,
  622. rounded up to the next integer.
  623. "conn-bi-direct" YYYY-MM-DD HH:MM:SS (NSEC s) BELOW,READ,WRITE,BOTH NL
  624. [At most once]
  625. Number of connections, split into 10-second intervals, that are
  626. used uni-directionally or bi-directionally as observed in the NSEC
  627. seconds (usually 86400 seconds) before YYYY-MM-DD HH:MM:SS. Every
  628. 10 seconds, we determine for every connection whether we read and
  629. wrote less than a threshold of 20 KiB (BELOW), read at least 10
  630. times more than we wrote (READ), wrote at least 10 times more than
  631. we read (WRITE), or read and wrote more than the threshold, but
  632. not 10 times more in either direction (BOTH). After classifying a
  633. connection, read and write counters are reset for the next
  634. 10-second interval.
  635. "exit-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  636. [At most once.]
  637. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  638. interval of length NSEC seconds (86400 seconds by default).
  639. An "exit-stats-end" line, as well as any other "exit-*" line, is
  640. first added after the relay has been running for at least 24 hours
  641. and only if the relay permits exiting (where exiting to a single
  642. port and IP address is sufficient).
  643. "exit-kibibytes-written" port=N,port=N,... NL
  644. [At most once.]
  645. "exit-kibibytes-read" port=N,port=N,... NL
  646. [At most once.]
  647. List of mappings from ports to the number of kibibytes that the
  648. relay has written to or read from exit connections to that port,
  649. rounded up to the next full kibibyte.
  650. "exit-streams-opened" port=N,port=N,... NL
  651. [At most once.]
  652. List of mappings from ports to the number of opened exit streams
  653. to that port, rounded up to the nearest multiple of 4.
  654. "router-signature" NL Signature NL
  655. [At end, exactly once.]
  656. A document signature as documented in section 1.3, using the
  657. initial item "extra-info" and the final item "router-signature",
  658. signed with the router's identity key.
  659. 2.2.1. Moving history fields to extra-info documents.
  660. Tools that want to use the read-history and write-history values SHOULD
  661. download extra-info documents as well as router descriptors. Such
  662. tools SHOULD accept history values from both sources; if they appear in
  663. both documents, the values in the extra-info documents are authoritative.
  664. New versions of Tor no longer generate router descriptors
  665. containing read-history or write-history. Tools should continue to
  666. accept read-history and write-history values in router descriptors
  667. produced by older versions of Tor until all Tor versions earlier
  668. than 0.2.0.x are obsolete.
  669. 2.3. Nonterminals in router descriptors
  670. nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
  671. case-insensitive.
  672. hexdigest ::= a '$', followed by 40 hexadecimal characters
  673. ([A-Fa-f0-9]). [Represents a server by the digest of its identity
  674. key.]
  675. exitpattern ::= addrspec ":" portspec
  676. portspec ::= "*" | port | port "-" port
  677. port ::= an integer between 1 and 65535, inclusive.
  678. [Some implementations incorrectly generate ports with value 0.
  679. Implementations SHOULD accept this, and SHOULD NOT generate it.
  680. Connections to port 0 are never permitted.]
  681. addrspec ::= "*" | ip4spec | ip6spec
  682. ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
  683. ip4 ::= an IPv4 address in dotted-quad format
  684. ip4mask ::= an IPv4 mask in dotted-quad format
  685. num_ip4_bits ::= an integer between 0 and 32
  686. ip6spec ::= ip6 | ip6 "/" num_ip6_bits
  687. ip6 ::= an IPv6 address, surrounded by square brackets.
  688. num_ip6_bits ::= an integer between 0 and 128
  689. bool ::= "0" | "1"
  690. 3. Formats produced by directory authorities.
  691. Every authority has two keys used in this protocol: a signing key, and
  692. an authority identity key. (Authorities also have a router identity
  693. key used in their role as a router and by earlier versions of the
  694. directory protocol.) The identity key is used from time to time to
  695. sign new key certificates using new signing keys; it is very sensitive.
  696. The signing key is used to sign key certificates and status documents.
  697. There are three kinds of documents generated by directory authorities:
  698. Key certificates
  699. Status votes
  700. Status consensuses
  701. Each is discussed below.
  702. 3.1. Key certificates
  703. Key certificates consist of the following items:
  704. "dir-key-certificate-version" version NL
  705. [At start, exactly once.]
  706. Determines the version of the key certificate. MUST be "3" for
  707. the protocol described in this document. Implementations MUST
  708. reject formats they don't understand.
  709. "dir-address" IPPort NL
  710. [At most once]
  711. An IP:Port for this authority's directory port.
  712. "fingerprint" fingerprint NL
  713. [Exactly once.]
  714. Hexadecimal encoding without spaces based on the authority's
  715. identity key.
  716. "dir-identity-key" NL a public key in PEM format
  717. [Exactly once.]
  718. The long-term authority identity key for this authority. This key
  719. SHOULD be at least 2048 bits long; it MUST NOT be shorter than
  720. 1024 bits.
  721. "dir-key-published" YYYY-MM-DD HH:MM:SS NL
  722. [Exactly once.]
  723. The time (in GMT) when this document and corresponding key were
  724. last generated.
  725. "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
  726. [Exactly once.]
  727. A time (in GMT) after which this key is no longer valid.
  728. "dir-signing-key" NL a key in PEM format
  729. [Exactly once.]
  730. The directory server's public signing key. This key MUST be at
  731. least 1024 bits, and MAY be longer.
  732. "dir-key-crosscert" NL CrossSignature NL
  733. [At most once.]
  734. NOTE: Authorities MUST include this field in all newly generated
  735. certificates. A future version of this specification will make
  736. the field required.
  737. CrossSignature is a signature, made using the certificate's signing
  738. key, of the digest of the PKCS1-padded hash of the certificate's
  739. identity key. For backward compatibility with broken versions of the
  740. parser, we wrap the base64-encoded signature in -----BEGIN ID
  741. SIGNATURE---- and -----END ID SIGNATURE----- tags. Implementations
  742. MUST allow the "ID " portion to be omitted, however.
  743. When encountering a certificate with a dir-key-crosscert entry,
  744. implementations MUST verify that the signature is a correct signature
  745. of the hash of the identity key using the signing key.
  746. "dir-key-certification" NL Signature NL
  747. [At end, exactly once.]
  748. A document signature as documented in section 1.3, using the
  749. initial item "dir-key-certificate-version" and the final item
  750. "dir-key-certification", signed with the authority identity key.
  751. Authorities MUST generate a new signing key and corresponding
  752. certificate before the key expires.
  753. 3.2. Vote and consensus status documents
  754. Votes and consensuses are more strictly formatted then other documents
  755. in this specification, since different authorities must be able to
  756. generate exactly the same consensus given the same set of votes.
  757. The procedure for deciding when to generate vote and consensus status
  758. documents are described in section 1.4 on the voting timeline.
  759. Status documents contain a preamble, an authority section, a list of
  760. router status entries, and one or more footer signature, in that order.
  761. Unlike other formats described above, a SP in these documents must be a
  762. single space character (hex 20).
  763. Some items appear only in votes, and some items appear only in
  764. consensuses. Unless specified, items occur in both.
  765. The preamble contains the following items. They MUST occur in the
  766. order given here:
  767. "network-status-version" SP version NL.
  768. [At start, exactly once.]
  769. A document format version. For this specification, the version is
  770. "3".
  771. "vote-status" SP type NL
  772. [Exactly once.]
  773. The status MUST be "vote" or "consensus", depending on the type of
  774. the document.
  775. "consensus-methods" SP IntegerList NL
  776. [Exactly once for votes; does not occur in consensuses.]
  777. A space-separated list of supported methods for generating
  778. consensuses from votes. See section 3.4.1 for details. Method "1"
  779. MUST be included.
  780. "consensus-method" SP Integer NL
  781. [Exactly once for consensuses; does not occur in votes.]
  782. See section 3.4.1 for details.
  783. (Only included when the vote is generated with consensus-method 2 or
  784. later.)
  785. "published" SP YYYY-MM-DD SP HH:MM:SS NL
  786. [Exactly once for votes; does not occur in consensuses.]
  787. The publication time for this status document (if a vote).
  788. "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
  789. [Exactly once.]
  790. The start of the Interval for this vote. Before this time, the
  791. consensus document produced from this vote should not be used.
  792. See 1.4 for voting timeline information.
  793. "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
  794. [Exactly once.]
  795. The time at which the next consensus should be produced; before this
  796. time, there is no point in downloading another consensus, since there
  797. won't be a new one. See 1.4 for voting timeline information.
  798. "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
  799. [Exactly once.]
  800. The end of the Interval for this vote. After this time, the
  801. consensus produced by this vote should not be used. See 1.4 for
  802. voting timeline information.
  803. "voting-delay" SP VoteSeconds SP DistSeconds NL
  804. [Exactly once.]
  805. VoteSeconds is the number of seconds that we will allow to collect
  806. votes from all authorities; DistSeconds is the number of seconds
  807. we'll allow to collect signatures from all authorities. See 1.4 for
  808. voting timeline information.
  809. "client-versions" SP VersionList NL
  810. [At most once.]
  811. A comma-separated list of recommended client versions, in
  812. ascending order. If absent, no opinion is held about client
  813. versions.
  814. "server-versions" SP VersionList NL
  815. [At most once.]
  816. A comma-separated list of recommended server versions, in
  817. ascending order. If absent, no opinion is held about server
  818. versions.
  819. "known-flags" SP FlagList NL
  820. [Exactly once.]
  821. A space-separated list of all of the flags that this document
  822. might contain. A flag is "known" either because the authority
  823. knows about them and might set them (if in a vote), or because
  824. enough votes were counted for the consensus for an authoritative
  825. opinion to have been formed about their status.
  826. "params" SP [Parameters] NL
  827. [At most once]
  828. Parameter ::= Keyword '=' Int32
  829. Int32 ::= A decimal integer between -2147483648 and 2147483647.
  830. Parameters ::= Parameter | Parameters SP Parameter
  831. The parameters list, if present, contains a space-separated list of
  832. case-sensitive key-value pairs, sorted in lexical order by
  833. their keyword. Each parameter has its own meaning.
  834. (Only included when the vote is generated with consensus-method 7 or
  835. later.)
  836. Commonly used "param" arguments at this point include:
  837. "circwindow" -- the default package window that circuits should
  838. be established with. It started out at 1000 cells, but some
  839. research indicates that a lower value would mean fewer cells in
  840. transit in the network at any given time. Obeyed by Tor 0.2.1.20
  841. and later.
  842. "CircuitPriorityHalflifeMsec" -- the halflife parameter used when
  843. weighting which circuit will send the next cell. Obeyed by Tor
  844. 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha
  845. and 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter,
  846. but mishandled it badly.)
  847. "perconnbwrate" and "perconnbwburst" -- if set, each relay sets
  848. up a separate token bucket for every client OR connection,
  849. and rate limits that connection indepedently. Typically left
  850. unset, except when used for performance experiments around trac
  851. entry 1750. Only honored by relays running Tor 0.2.2.16-alpha
  852. and later. (Note that relays running 0.2.2.7-alpha through
  853. 0.2.2.14-alpha looked for bwconnrate and bwconnburst, but then
  854. did the wrong thing with them; see bug 1830 for details.)
  855. "refuseunknownexits" -- if set and non-zero, exit relays look at
  856. the previous hop of circuits that ask to open an exit stream,
  857. and refuse to exit if they don't recognize it as a relay. The
  858. goal is to make it harder for people to use them as one-hop
  859. proxies. See trac entry 1751 for details.
  860. See also "2.4.5. Consensus parameters governing behavior"
  861. in path-spec.txt for a series of circuit build time related
  862. consensus params.
  863. The authority section of a vote contains the following items, followed
  864. in turn by the authority's current key certificate:
  865. "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
  866. orport NL
  867. [Exactly once, at start]
  868. Describes this authority. The nickname is a convenient identifier
  869. for the authority. The identity is an uppercase hex fingerprint of
  870. the authority's current (v3 authority) identity key. The address is
  871. the server's hostname. The IP is the server's current IP address,
  872. and dirport is its current directory port. XXXXorport
  873. "contact" SP string NL
  874. [At most once.]
  875. An arbitrary string describing how to contact the directory
  876. server's administrator. Administrators should include at least an
  877. email address and a PGP fingerprint.
  878. "legacy-key" SP FINGERPRINT NL
  879. [At most once]
  880. Lists a fingerprint for an obsolete _identity_ key still used
  881. by this authority to keep older clients working. This option
  882. is used to keep key around for a little while in case the
  883. authorities need to migrate many identity keys at once.
  884. (Generally, this would only happen because of a security
  885. vulnerability that affected multiple authorities, like the
  886. Debian OpenSSL RNG bug of May 2008.)
  887. The authority section of a consensus contains groups the following items,
  888. in the order given, with one group for each authority that contributed to
  889. the consensus, with groups sorted by authority identity digest:
  890. "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
  891. orport NL
  892. [Exactly once, at start]
  893. As in the authority section of a vote.
  894. "contact" SP string NL
  895. [At most once.]
  896. As in the authority section of a vote.
  897. "vote-digest" SP digest NL
  898. [Exactly once.]
  899. A digest of the vote from the authority that contributed to this
  900. consensus, as signed (that is, not including the signature).
  901. (Hex, upper-case.)
  902. Each router status entry contains the following items. Router status
  903. entries are sorted in ascending order by identity digest.
  904. "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
  905. SP DirPort NL
  906. [At start, exactly once.]
  907. "Nickname" is the OR's nickname. "Identity" is a hash of its
  908. identity key, encoded in base64, with trailing equals sign(s)
  909. removed. "Digest" is a hash of its most recent descriptor as
  910. signed (that is, not including the signature), encoded in base64.
  911. "Publication" is the
  912. publication time of its most recent descriptor, in the form
  913. YYYY-MM-DD HH:MM:SS, in GMT. "IP" is its current IP address;
  914. ORPort is its current OR port, "DirPort" is it's current directory
  915. port, or "0" for "none".
  916. "s" SP Flags NL
  917. [At most once.]
  918. A series of space-separated status flags, in alphabetical order.
  919. Currently documented flags are:
  920. "Authority" if the router is a directory authority.
  921. "BadExit" if the router is believed to be useless as an exit node
  922. (because its ISP censors it, because it is behind a restrictive
  923. proxy, or for some similar reason).
  924. "BadDirectory" if the router is believed to be useless as a
  925. directory cache (because its directory port isn't working,
  926. its bandwidth is always throttled, or for some similar
  927. reason).
  928. "Exit" if the router is more useful for building
  929. general-purpose exit circuits than for relay circuits. The
  930. path building algorithm uses this flag; see path-spec.txt.
  931. "Fast" if the router is suitable for high-bandwidth circuits.
  932. "Guard" if the router is suitable for use as an entry guard.
  933. "HSDir" if the router is considered a v2 hidden service directory.
  934. "Named" if the router's identity-nickname mapping is canonical,
  935. and this authority binds names.
  936. "Stable" if the router is suitable for long-lived circuits.
  937. "Running" if the router is currently usable.
  938. "Unnamed" if another router has bound the name used by this
  939. router, and this authority binds names.
  940. "Valid" if the router has been 'validated'.
  941. "V2Dir" if the router implements the v2 directory protocol.
  942. "V3Dir" if the router implements this protocol.
  943. "v" SP version NL
  944. [At most once.]
  945. The version of the Tor protocol that this server is running. If
  946. the value begins with "Tor" SP, the rest of the string is a Tor
  947. version number, and the protocol is "The Tor protocol as supported
  948. by the given version of Tor." Otherwise, if the value begins with
  949. some other string, Tor has upgraded to a more sophisticated
  950. protocol versioning system, and the protocol is "a version of the
  951. Tor protocol more recent than any we recognize."
  952. Directory authorities SHOULD omit version strings they receive from
  953. descriptors if they would cause "v" lines to be over 128 characters
  954. long.
  955. "w" SP "Bandwidth=" INT [SP "Measured=" INT] NL
  956. [At most once.]
  957. An estimate of the bandwidth of this server, in an arbitrary
  958. unit (currently kilobytes per second). Used to weight router
  959. selection.
  960. Additionally, the Measured= keyword is present in votes by
  961. participating bandwidth measurement authorities to indicate
  962. a measured bandwidth currently produced by measuring stream
  963. capacities.
  964. Other weighting keywords may be added later.
  965. Clients MUST ignore keywords they do not recognize.
  966. "p" SP ("accept" / "reject") SP PortList NL
  967. [At most once.]
  968. PortList = PortOrRange
  969. PortList = PortList "," PortOrRange
  970. PortOrRange = INT "-" INT / INT
  971. A list of those ports that this router supports (if 'accept')
  972. or does not support (if 'reject') for exit to "most
  973. addresses".
  974. The footer section is delineated in all votes and consensuses supporting
  975. consensus method 9 and above with the following:
  976. "directory-footer" NL
  977. It contains two subsections, a bandwidths-weights line and a
  978. directory-signature.
  979. The bandwidths-weights line appears At Most Once for a consensus. It does
  980. not appear in votes.
  981. "bandwidth-weights" SP
  982. "Wbd=" INT SP "Wbe=" INT SP "Wbg=" INT SP "Wbm=" INT SP
  983. "Wdb=" INT SP
  984. "Web=" INT SP "Wed=" INT SP "Wee=" INT SP "Weg=" INT SP "Wem=" INT SP
  985. "Wgb=" INT SP "Wgd=" INT SP "Wgg=" INT SP "Wgm=" INT SP
  986. "Wmb=" INT SP "Wmd=" INT SP "Wme=" INT SP "Wmg=" INT SP "Wmm=" INT NL
  987. These values represent the weights to apply to router bandwidths during
  988. path selection. They are sorted in alphabetical order in the list. The
  989. integer values are divided by BW_WEIGHT_SCALE=10000 or the consensus
  990. param "bwweightscale". They are:
  991. Wgg - Weight for Guard-flagged nodes in the guard position
  992. Wgm - Weight for non-flagged nodes in the guard Position
  993. Wgd - Weight for Guard+Exit-flagged nodes in the guard Position
  994. Wmg - Weight for Guard-flagged nodes in the middle Position
  995. Wmm - Weight for non-flagged nodes in the middle Position
  996. Wme - Weight for Exit-flagged nodes in the middle Position
  997. Wmd - Weight for Guard+Exit flagged nodes in the middle Position
  998. Weg - Weight for Guard flagged nodes in the exit Position
  999. Wem - Weight for non-flagged nodes in the exit Position
  1000. Wee - Weight for Exit-flagged nodes in the exit Position
  1001. Wed - Weight for Guard+Exit-flagged nodes in the exit Position
  1002. Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
  1003. Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
  1004. Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
  1005. Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes
  1006. Wbg - Weight for Guard flagged nodes for BEGIN_DIR requests
  1007. Wbm - Weight for non-flagged nodes for BEGIN_DIR requests
  1008. Wbe - Weight for Exit-flagged nodes for BEGIN_DIR requests
  1009. Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
  1010. These values are calculated as specified in Section 3.4.3.
  1011. The signature contains the following item, which appears Exactly Once
  1012. for a vote, and At Least Once for a consensus.
  1013. "directory-signature" SP identity SP signing-key-digest NL Signature
  1014. This is a signature of the status document, with the initial item
  1015. "network-status-version", and the signature item
  1016. "directory-signature", using the signing key. (In this case, we take
  1017. the hash through the _space_ after directory-signature, not the
  1018. newline: this ensures that all authorities sign the same thing.)
  1019. "identity" is the hex-encoded digest of the authority identity key of
  1020. the signing authority, and "signing-key-digest" is the hex-encoded
  1021. digest of the current authority signing key of the signing authority.
  1022. 3.3. Assigning flags in a vote
  1023. (This section describes how directory authorities choose which status
  1024. flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
  1025. authorities MAY do things differently, so long as clients keep working
  1026. well. Clients MUST NOT depend on the exact behaviors in this section.)
  1027. In the below definitions, a router is considered "active" if it is
  1028. running, valid, and not hibernating.
  1029. "Valid" -- a router is 'Valid' if it is running a version of Tor not
  1030. known to be broken, and the directory authority has not blacklisted
  1031. it as suspicious.
  1032. "Named" -- Directory authority administrators may decide to support name
  1033. binding. If they do, then they must maintain a file of
  1034. nickname-to-identity-key mappings, and try to keep this file consistent
  1035. with other directory authorities. If they don't, they act as clients, and
  1036. report bindings made by other directory authorities (name X is bound to
  1037. identity Y if at least one binding directory lists it, and no directory
  1038. binds X to some other Y'.) A router is called 'Named' if the router
  1039. believes the given name should be bound to the given key.
  1040. Two strategies exist on the current network for deciding on
  1041. values for the Named flag. In the original version, server
  1042. operators were asked to send nickname-identity pairs to a
  1043. mailing list of Naming directory authorities operators. The
  1044. operators were then supposed to add the pairs to their
  1045. mapping files; in practice, they didn't get to this often.
  1046. Newer Naming authorities run a script that registers routers
  1047. in their mapping files once the routers have been online at
  1048. least two weeks, no other router has that nickname, and no
  1049. other router has wanted the nickname for a month. If a router
  1050. has not been online for six months, the router is removed.
  1051. "Unnamed" -- Directory authorities that support naming should vote for a
  1052. router to be 'Unnamed' if its given nickname is mapped to a different
  1053. identity.
  1054. "Running" -- A router is 'Running' if the authority managed to connect to
  1055. it successfully within the last 30 minutes.
  1056. "Stable" -- A router is 'Stable' if it is active, and either its Weighted
  1057. MTBF is at least the median for known active routers or its Weighted MTBF
  1058. corresponds to at least 7 days. Routers are never called Stable if they are
  1059. running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
  1060. through 0.1.1.16-rc are stupid this way.)
  1061. To calculate weighted MTBF, compute the weighted mean of the lengths
  1062. of all intervals when the router was observed to be up, weighting
  1063. intervals by $\alpha^n$, where $n$ is the amount of time that has
  1064. passed since the interval ended, and $\alpha$ is chosen so that
  1065. measurements over approximately one month old no longer influence the
  1066. weighted MTBF much.
  1067. [XXXX what happens when we have less than 4 days of MTBF info.]
  1068. "Exit" -- A router is called an 'Exit' iff it allows exits to at
  1069. least two of the ports 80, 443, and 6667 and allows exits to at
  1070. least one /8 address space.
  1071. "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
  1072. either in the top 7/8ths for known active routers or at least 20KB/s.
  1073. "Guard" -- A router is a possible 'Guard' if its Weighted Fractional
  1074. Uptime is at least the median for "familiar" active routers, and if
  1075. its bandwidth is at least median or at least 250KB/s.
  1076. To calculate weighted fractional uptime, compute the fraction
  1077. of time that the router is up in any given day, weighting so that
  1078. downtime and uptime in the past counts less.
  1079. A node is 'familiar' if 1/8 of all active nodes have appeared more
  1080. recently than it, OR it has been around for a few weeks.
  1081. "Authority" -- A router is called an 'Authority' if the authority
  1082. generating the network-status document believes it is an authority.
  1083. "V2Dir" -- A router supports the v2 directory protocol if it has an open
  1084. directory port, and it is running a version of the directory protocol that
  1085. supports the functionality clients need. (Currently, this is
  1086. 0.1.1.9-alpha or later.)
  1087. "V3Dir" -- A router supports the v3 directory protocol if it has an open
  1088. directory port, and it is running a version of the directory protocol that
  1089. supports the functionality clients need. (Currently, this is
  1090. 0.2.0.?????-alpha or later.)
  1091. "HSDir" -- A router is a v2 hidden service directory if it stores and
  1092. serves v2 hidden service descriptors and the authority managed to connect
  1093. to it successfully within the last 24 hours.
  1094. Directory server administrators may label some servers or IPs as
  1095. blacklisted, and elect not to include them in their network-status lists.
  1096. Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
  1097. When there are more than 3 to choose from, authorities should first prefer
  1098. authorities to non-authorities, then prefer Running to non-Running, and
  1099. then prefer high-bandwidth to low-bandwidth. To 'disable' a server, the
  1100. authority *should* advertise it without the Running or Valid flag.
  1101. Thus, the network-status vote includes all non-blacklisted,
  1102. non-expired, non-superseded descriptors.
  1103. The bandwidth in a "w" line should be taken as the best estimate
  1104. of the router's actual capacity that the authority has. For now,
  1105. this should be the lesser of the observed bandwidth and bandwidth
  1106. rate limit from the router descriptor. It is given in kilobytes
  1107. per second, and capped at some arbitrary value (currently 10 MB/s).
  1108. The Measured= keyword on a "w" line vote is currently computed
  1109. by multiplying the previous published consensus bandwidth by the
  1110. ratio of the measured average node stream capacity to the network
  1111. average. If 3 or more authorities provide a Measured= keyword for
  1112. a router, the authorities produce a consensus containing a "w"
  1113. Bandwidth= keyword equal to the median of the Measured= votes.
  1114. The ports listed in a "p" line should be taken as those ports for
  1115. which the router's exit policy permits 'most' addresses, ignoring any
  1116. accept not for all addresses, ignoring all rejects for private
  1117. netblocks. "Most" addresses are permitted if no more than 2^25
  1118. IPv4 addresses (two /8 networks) were blocked. The list is encoded
  1119. as described in 3.4.2.
  1120. 3.4. Computing a consensus from a set of votes
  1121. Given a set of votes, authorities compute the contents of the consensus
  1122. document as follows:
  1123. The "valid-after", "valid-until", and "fresh-until" times are taken as
  1124. the median of the respective values from all the votes.
  1125. The times in the "voting-delay" line are taken as the median of the
  1126. VoteSeconds and DistSeconds times in the votes.
  1127. Known-flags is the union of all flags known by any voter.
  1128. Entries are given on the "params" line for every keyword on which any
  1129. authority voted. The values given are the low-median of all votes on
  1130. that keyword.
  1131. "client-versions" and "server-versions" are sorted in ascending
  1132. order; A version is recommended in the consensus if it is recommended
  1133. by more than half of the voting authorities that included a
  1134. client-versions or server-versions lines in their votes.
  1135. The authority item groups (dir-source, contact, fingerprint,
  1136. vote-digest) are taken from the votes of the voting
  1137. authorities. These groups are sorted by the digests of the
  1138. authorities identity keys, in ascending order. If the consensus
  1139. method is 3 or later, a dir-source line must be included for
  1140. every vote with legacy-key entry, using the legacy-key's
  1141. fingerprint, the voter's ordinary nickname with the string
  1142. "-legacy" appended, and all other fields as from the original
  1143. vote's dir-source line.
  1144. A router status entry:
  1145. * is included in the result if some router status entry with the same
  1146. identity is included by more than half of the authorities (total
  1147. authorities, not just those whose votes we have).
  1148. * For any given identity, we include at most one router status entry.
  1149. * A router entry has a flag set if that is included by more than half
  1150. of the authorities who care about that flag.
  1151. * Two router entries are "the same" if they have the same
  1152. <descriptor digest, published time, nickname, IP, ports> tuple.
  1153. We choose the tuple for a given router as whichever tuple appears
  1154. for that router in the most votes. We break ties first in favor of
  1155. the more recently published, then in favor of smaller server
  1156. descriptor digest.
  1157. * The Named flag appears if it is included for this routerstatus by
  1158. _any_ authority, and if all authorities that list it list the same
  1159. nickname. However, if consensus-method 2 or later is in use, and
  1160. any authority calls this identity/nickname pair Unnamed, then
  1161. this routerstatus does not get the Named flag.
  1162. * If consensus-method 2 or later is in use, the Unnamed flag is
  1163. set for a routerstatus if any authorities have voted for a different
  1164. identities to be Named with that nickname, or if any authority
  1165. lists that nickname/ID pair as Unnamed.
  1166. (With consensus-method 1, Unnamed is set like any other flag.)
  1167. * The version is given as whichever version is listed by the most
  1168. voters, with ties decided in favor of more recent versions.
  1169. * If consensus-method 4 or later is in use, then routers that
  1170. do not have the Running flag are not listed at all.
  1171. * If consensus-method 5 or later is in use, then the "w" line
  1172. is generated using a low-median of the bandwidth values from
  1173. the votes that included "w" lines for this router.
  1174. * If consensus-method 5 or later is in use, then the "p" line
  1175. is taken from the votes that have the same policy summary
  1176. for the descriptor we are listing. (They should all be the
  1177. same. If they are not, we pick the most commonly listed
  1178. one, breaking ties in favor of the lexicographically larger
  1179. vote.) The port list is encoded as specified in 3.4.2.
  1180. * If consensus-method 6 or later is in use and if 3 or more
  1181. authorities provide a Measured= keyword in their votes for
  1182. a router, the authorities produce a consensus containing a
  1183. Bandwidth= keyword equal to the median of the Measured= votes.
  1184. * If consensus-method 7 or later is in use, the params line is
  1185. included in the output.
  1186. The signatures at the end of a consensus document are sorted in
  1187. ascending order by identity digest.
  1188. All ties in computing medians are broken in favor of the smaller or
  1189. earlier item.
  1190. 3.4.1. Forward compatibility
  1191. Future versions of Tor will need to include new information in the
  1192. consensus documents, but it is important that all authorities (or at least
  1193. half) generate and sign the same signed consensus.
  1194. To achieve this, authorities list in their votes their supported methods
  1195. for generating consensuses from votes. Later methods will be assigned
  1196. higher numbers. Currently recognized methods:
  1197. "1" -- The first implemented version.
  1198. "2" -- Added support for the Unnamed flag.
  1199. "3" -- Added legacy ID key support to aid in authority ID key rollovers
  1200. "4" -- No longer list routers that are not running in the consensus
  1201. "5" -- adds support for "w" and "p" lines.
  1202. "6" -- Prefers measured bandwidth values rather than advertised
  1203. "7" -- Provides keyword=integer pairs of consensus parameters
  1204. "8" -- Provides microdescriptor summaries
  1205. "9" -- Provides weights for selecting flagged routers in paths
  1206. "10" -- Fixes edge case bugs in router flag selection weights
  1207. Before generating a consensus, an authority must decide which consensus
  1208. method to use. To do this, it looks for the highest version number
  1209. supported by more than 2/3 of the authorities voting. If it supports this
  1210. method, then it uses it. Otherwise, it falls back to method 1.
  1211. (The consensuses generated by new methods must be parsable by
  1212. implementations that only understand the old methods, and must not cause
  1213. those implementations to compromise their anonymity. This is a means for
  1214. making changes in the contents of consensus; not for making
  1215. backward-incompatible changes in their format.)
  1216. 3.4.2. Encoding port lists
  1217. Whether the summary shows the list of accepted ports or the list of
  1218. rejected ports depends on which list is shorter (has a shorter string
  1219. representation). In case of ties we choose the list of accepted
  1220. ports. As an exception to this rule an allow-all policy is
  1221. represented as "accept 1-65535" instead of "reject " and a reject-all
  1222. policy is similarly given as "reject 1-65535".
  1223. Summary items are compressed, that is instead of "80-88,89-100" there
  1224. only is a single item of "80-100", similarly instead of "20,21" a
  1225. summary will say "20-21".
  1226. Port lists are sorted in ascending order.
  1227. The maximum allowed length of a policy summary (including the "accept "
  1228. or "reject ") is 1000 characters. If a summary exceeds that length we
  1229. use an accept-style summary and list as much of the port list as is
  1230. possible within these 1000 bytes. [XXXX be more specific.]
  1231. 3.4.3. Computing Bandwidth Weights
  1232. Let weight_scale = 10000
  1233. Let G be the total bandwidth for Guard-flagged nodes.
  1234. Let M be the total bandwidth for non-flagged nodes.
  1235. Let E be the total bandwidth for Exit-flagged nodes.
  1236. Let D be the total bandwidth for Guard+Exit-flagged nodes.
  1237. Let T = G+M+E+D
  1238. Let Wgd be the weight for choosing a Guard+Exit for the guard position.
  1239. Let Wmd be the weight for choosing a Guard+Exit for the middle position.
  1240. Let Wed be the weight for choosing a Guard+Exit for the exit position.
  1241. Let Wme be the weight for choosing an Exit for the middle position.
  1242. Let Wmg be the weight for choosing a Guard for the middle position.
  1243. Let Wgg be the weight for choosing a Guard for the guard position.
  1244. Let Wee be the weight for choosing an Exit for the exit position.
  1245. Balanced network conditions then arise from solutions to the following
  1246. system of equations:
  1247. Wgg*G + Wgd*D == M + Wmd*D + Wme*E + Wmg*G (guard bw = middle bw)
  1248. Wgg*G + Wgd*D == Wee*E + Wed*D (guard bw = exit bw)
  1249. Wed*D + Wmd*D + Wgd*D == D (aka: Wed+Wmd+Wdg = 1)
  1250. Wmg*G + Wgg*G == G (aka: Wgg = 1-Wmg)
  1251. Wme*E + Wee*E == E (aka: Wee = 1-Wme)
  1252. We are short 2 constraints with the above set. The remaining constraints
  1253. come from examining different cases of network load. The following
  1254. constraints are used in consensus method 10 and above. There are another
  1255. incorrect and obsolete set of constraints used for these same cases in
  1256. consensus method 9. For those, see dir-spec.txt in Tor 0.2.2.10-alpha
  1257. to 0.2.2.16-alpha.
  1258. Case 1: E >= T/3 && G >= T/3 (Neither Exit nor Guard Scarce)
  1259. In this case, the additional two constraints are: Wmg == Wmd,
  1260. Wed == 1/3.
  1261. This leads to the solution:
  1262. Wgd = weight_scale/3
  1263. Wed = weight_scale/3
  1264. Wmd = weight_scale/3
  1265. Wee = (weight_scale*(E+G+M))/(3*E)
  1266. Wme = weight_scale - Wee
  1267. Wmg = (weight_scale*(2*G-E-M))/(3*G)
  1268. Wgg = weight_scale - Wmg
  1269. Case 2: E < T/3 && G < T/3 (Both are scarce)
  1270. Let R denote the more scarce class (Rare) between Guard vs Exit.
  1271. Let S denote the less scarce class.
  1272. Subcase a: R+D < S
  1273. In this subcase, we simply devote all of D bandwidth to the
  1274. scarce class.
  1275. Wgg = Wee = weight_scale
  1276. Wmg = Wme = Wmd = 0;
  1277. if E < G:
  1278. Wed = weight_scale
  1279. Wgd = 0
  1280. else:
  1281. Wed = 0
  1282. Wgd = weight_scale
  1283. Subcase b: R+D >= S
  1284. In this case, if M <= T/3, we have enough bandwidth to try to achieve
  1285. a balancing condition.
  1286. Add constraints Wgg = 1, Wmd == Wgd to maximize bandwidth in the guard
  1287. position while still allowing exits to be used as middle nodes:
  1288. Wee = (weight_scale*(E - G + M))/E
  1289. Wed = (weight_scale*(D - 2*E + 4*G - 2*M))/(3*D)
  1290. Wme = (weight_scale*(G-M))/E
  1291. Wmg = 0
  1292. Wgg = weight_scale
  1293. Wmd = (weight_scale - Wed)/2
  1294. Wgd = (weight_scale - Wed)/2
  1295. If this system ends up with any values out of range (ie negative, or
  1296. above weight_scale), use the constraints Wgg == 1 and Wee == 1, since
  1297. both those positions are scarce:
  1298. Wgg = weight_scale
  1299. Wee = weight_scale
  1300. Wed = (weight_scale*(D - 2*E + G + M))/(3*D)
  1301. Wmd = (weight_Scale*(D - 2*M + G + E))/(3*D)
  1302. Wme = 0
  1303. Wmg = 0
  1304. Wgd = weight_scale - Wed - Wmd
  1305. If M > T/3, then the Wmd weight above will become negative. Set it to 0
  1306. in this case:
  1307. Wmd = 0
  1308. Wgd = weight_scale - Wed
  1309. Case 3: One of E < T/3 or G < T/3
  1310. Let S be the scarce class (of E or G).
  1311. Subcase a: (S+D) < T/3:
  1312. if G=S:
  1313. Wgg = Wgd = weight_scale;
  1314. Wmd = Wed = Wmg = 0;
  1315. // Minor subcase, if E is more scarce than M,
  1316. // keep its bandwidth in place.
  1317. if (E < M) Wme = 0;
  1318. else Wme = (weight_scale*(E-M))/(2*E);
  1319. Wee = weight_scale-Wme;
  1320. if E=S:
  1321. Wee = Wed = weight_scale;
  1322. Wmd = Wgd = Wme = 0;
  1323. // Minor subcase, if G is more scarce than M,
  1324. // keep its bandwidth in place.
  1325. if (G < M) Wmg = 0;
  1326. else Wmg = (weight_scale*(G-M))/(2*G);
  1327. Wgg = weight_scale-Wmg;
  1328. Subcase b: (S+D) >= T/3
  1329. if G=S:
  1330. Add constraints Wgg = 1, Wmd == Wed to maximize bandwidth
  1331. in the guard position, while still allowing exits to be
  1332. used as middle nodes:
  1333. Wgg = weight_scale
  1334. Wgd = (weight_scale*(D - 2*G + E + M))/(3*D)
  1335. Wmg = 0
  1336. Wee = (weight_scale*(E+M))/(2*E)
  1337. Wme = weight_scale - Wee
  1338. Wmd = (weight_scale - Wgd)/2
  1339. Wed = (weight_scale - Wgd)/2
  1340. if E=S:
  1341. Add constraints Wee == 1, Wmd == Wgd to maximize bandwidth
  1342. in the exit position:
  1343. Wee = weight_scale;
  1344. Wed = (weight_scale*(D - 2*E + G + M))/(3*D);
  1345. Wme = 0;
  1346. Wgg = (weight_scale*(G+M))/(2*G);
  1347. Wmg = weight_scale - Wgg;
  1348. Wmd = (weight_scale - Wed)/2;
  1349. Wgd = (weight_scale - Wed)/2;
  1350. To ensure consensus, all calculations are performed using integer math
  1351. with a fixed precision determined by the bwweightscale consensus
  1352. parameter (defaults at 10000).
  1353. For future balancing improvements, Tor clients support 11 additional weights
  1354. for directory requests and middle weighting. These weights are currently
  1355. set at weight_scale, with the exception of the following groups of
  1356. assignments:
  1357. Directory requests use middle weights:
  1358. Wbd=Wmd, Wbg=Wmg, Wbe=Wme, Wbm=Wmm
  1359. Handle bridges and strange exit policies:
  1360. Wgm=Wgg, Wem=Wee, Weg=Wed
  1361. 3.5. Detached signatures
  1362. Assuming full connectivity, every authority should compute and sign the
  1363. same consensus directory in each period. Therefore, it isn't necessary to
  1364. download the consensus computed by each authority; instead, the
  1365. authorities only push/fetch each others' signatures. A "detached
  1366. signature" document contains items as follows:
  1367. "consensus-digest" SP Digest NL
  1368. [At start, at most once.]
  1369. The digest of the consensus being signed.
  1370. "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
  1371. "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
  1372. "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
  1373. [As in the consensus]
  1374. "directory-signature"
  1375. [As in the consensus; the signature object is the same as in the
  1376. consensus document.]
  1377. 4. Directory server operation
  1378. All directory authorities and directory caches ("directory servers")
  1379. implement this section, except as noted.
  1380. 4.1. Accepting uploads (authorities only)
  1381. When a router posts a signed descriptor to a directory authority, the
  1382. authority first checks whether it is well-formed and correctly
  1383. self-signed. If it is, the authority next verifies that the nickname
  1384. in question is not already assigned to a router with a different
  1385. public key.
  1386. Finally, the authority MAY check that the router is not blacklisted
  1387. because of its key, IP, or another reason.
  1388. If the descriptor passes these tests, and the authority does not already
  1389. have a descriptor for a router with this public key, it accepts the
  1390. descriptor and remembers it.
  1391. If the authority _does_ have a descriptor with the same public key, the
  1392. newly uploaded descriptor is remembered if its publication time is more
  1393. recent than the most recent old descriptor for that router, and either:
  1394. - There are non-cosmetic differences between the old descriptor and the
  1395. new one.
  1396. - Enough time has passed between the descriptors' publication times.
  1397. (Currently, 12 hours.)
  1398. Differences between router descriptors are "non-cosmetic" if they would be
  1399. sufficient to force an upload as described in section 2 above.
  1400. Note that the "cosmetic difference" test only applies to uploaded
  1401. descriptors, not to descriptors that the authority downloads from other
  1402. authorities.
  1403. When a router posts a signed extra-info document to a directory authority,
  1404. the authority again checks it for well-formedness and correct signature,
  1405. and checks that its matches the extra-info-digest in some router
  1406. descriptor that it believes is currently useful. If so, it accepts it and
  1407. stores it and serves it as requested. If not, it drops it.
  1408. 4.2. Voting (authorities only)
  1409. Authorities divide time into Intervals. Authority administrators SHOULD
  1410. try to all pick the same interval length, and SHOULD pick intervals that
  1411. are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
  1412. minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
  1413. divide evenly into a 24-hour day.
  1414. Authorities SHOULD act according to interval and delays in the
  1415. latest consensus. Lacking a latest consensus, they SHOULD default to a
  1416. 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
  1417. Authorities MUST take pains to ensure that their clocks remain accurate
  1418. within a few seconds. (Running NTP is usually sufficient.)
  1419. The first voting period of each day begins at 00:00 (midnight) GMT. If
  1420. the last period of the day would be truncated by one-half or more, it is
  1421. merged with the second-to-last period.
  1422. An authority SHOULD publish its vote immediately at the start of each voting
  1423. period (minus VoteSeconds+DistSeconds). It does this by making it
  1424. available at
  1425. http://<hostname>/tor/status-vote/next/authority.z
  1426. and sending it in an HTTP POST request to each other authority at the URL
  1427. http://<hostname>/tor/post/vote
  1428. If, at the start of the voting period, minus DistSeconds, an authority
  1429. does not have a current statement from another authority, the first
  1430. authority downloads the other's statement.
  1431. Once an authority has a vote from another authority, it makes it available
  1432. at
  1433. http://<hostname>/tor/status-vote/next/<fp>.z
  1434. where <fp> is the fingerprint of the other authority's identity key.
  1435. And at
  1436. http://<hostname>/tor/status-vote/next/d/<d>.z
  1437. where <d> is the digest of the vote document.
  1438. The consensus status, along with as many signatures as the server
  1439. currently knows, should be available at
  1440. http://<hostname>/tor/status-vote/next/consensus.z
  1441. All of the detached signatures it knows for consensus status should be
  1442. available at:
  1443. http://<hostname>/tor/status-vote/next/consensus-signatures.z
  1444. Once there are enough signatures, or once the voting period starts,
  1445. these documents are available at
  1446. http://<hostname>/tor/status-vote/current/consensus.z
  1447. and
  1448. http://<hostname>/tor/status-vote/current/consensus-signatures.z
  1449. [XXX current/consensus-signatures is not currently implemented, as it
  1450. is not used in the voting protocol.]
  1451. The other vote documents are analogously made available under
  1452. http://<hostname>/tor/status-vote/current/authority.z
  1453. http://<hostname>/tor/status-vote/current/<fp>.z
  1454. http://<hostname>/tor/status-vote/current/d/<d>.z
  1455. once the consensus is complete.
  1456. Once an authority has computed and signed a consensus network status, it
  1457. should send its detached signature to each other authority in an HTTP POST
  1458. request to the URL:
  1459. http://<hostname>/tor/post/consensus-signature
  1460. [XXX Note why we support push-and-then-pull.]
  1461. [XXX possible future features include support for downloading old
  1462. consensuses.]
  1463. 4.3. Downloading consensus status documents (caches only)
  1464. All directory servers (authorities and caches) try to keep a recent
  1465. network-status consensus document to serve to clients. A cache ALWAYS
  1466. downloads a network-status consensus if any of the following are true:
  1467. - The cache has no consensus document.
  1468. - The cache's consensus document is no longer valid.
  1469. Otherwise, the cache downloads a new consensus document at a randomly
  1470. chosen time in the first half-interval after its current consensus
  1471. stops being fresh. (This time is chosen at random to avoid swarming
  1472. the authorities at the start of each period. The interval size is
  1473. inferred from the difference between the valid-after time and the
  1474. fresh-until time on the consensus.)
  1475. [For example, if a cache has a consensus that became valid at 1:00,
  1476. and is fresh until 2:00, that cache will fetch a new consensus at
  1477. a random time between 2:00 and 2:30.]
  1478. 4.4. Downloading and storing router descriptors (authorities and caches)
  1479. Periodically (currently, every 10 seconds), directory servers check
  1480. whether there are any specific descriptors that they do not have and that
  1481. they are not currently trying to download. Caches identify these
  1482. descriptors by hash in the recent network-status consensus documents;
  1483. authorities identify them by hash in vote (if publication date is more
  1484. recent than the descriptor we currently have).
  1485. [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
  1486. do that for now.]
  1487. If so, the directory server launches requests to the authorities for these
  1488. descriptors, such that each authority is only asked for descriptors listed
  1489. in its most recent vote (if the requester is an authority) or in the
  1490. consensus (if the requester is a cache). If we're an authority, and more
  1491. than one authority lists the descriptor, we choose which to ask at random.
  1492. If one of these downloads fails, we do not try to download that descriptor
  1493. from the authority that failed to serve it again unless we receive a newer
  1494. network-status (consensus or vote) from that authority that lists the same
  1495. descriptor.
  1496. Directory servers must potentially cache multiple descriptors for each
  1497. router. Servers must not discard any descriptor listed by any recent
  1498. consensus. If there is enough space to store additional descriptors,
  1499. servers SHOULD try to hold those which clients are likely to download the
  1500. most. (Currently, this is judged based on the interval for which each
  1501. descriptor seemed newest.)
  1502. [XXXX define recent]
  1503. Authorities SHOULD NOT download descriptors for routers that they would
  1504. immediately reject for reasons listed in 3.1.
  1505. 4.5. Downloading and storing extra-info documents
  1506. All authorities, and any cache that chooses to cache extra-info documents,
  1507. and any client that uses extra-info documents, should implement this
  1508. section.
  1509. Note that generally, clients don't need extra-info documents.
  1510. Periodically, the Tor instance checks whether it is missing any extra-info
  1511. documents: in other words, if it has any router descriptors with an
  1512. extra-info-digest field that does not match any of the extra-info
  1513. documents currently held. If so, it downloads whatever extra-info
  1514. documents are missing. Caches download from authorities; non-caches try
  1515. to download from caches. We follow the same splitting and back-off rules
  1516. as in 4.4 (if a cache) or 5.3 (if a client).
  1517. 4.6. General-use HTTP URLs
  1518. "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
  1519. The most recent v3 consensus should be available at:
  1520. http://<hostname>/tor/status-vote/current/consensus.z
  1521. Starting with Tor version 0.2.1.1-alpha is also available at:
  1522. http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
  1523. Where F1, F2, etc. are authority identity fingerprints the client trusts.
  1524. Servers will only return a consensus if more than half of the requested
  1525. authorities have signed the document, otherwise a 404 error will be sent
  1526. back. The fingerprints can be shortened to a length of any multiple of
  1527. two, using only the leftmost part of the encoded fingerprint. Tor uses
  1528. 3 bytes (6 hex characters) of the fingerprint.
  1529. Clients SHOULD sort the fingerprints in ascending order. Server MUST
  1530. accept any order.
  1531. Clients SHOULD use this format when requesting consensus documents from
  1532. directory authority servers and from caches running a version of Tor
  1533. that is known to support this URL format.
  1534. A concatenated set of all the current key certificates should be available
  1535. at:
  1536. http://<hostname>/tor/keys/all.z
  1537. The key certificate for this server (if it is an authority) should be
  1538. available at:
  1539. http://<hostname>/tor/keys/authority.z
  1540. The key certificate for an authority whose authority identity fingerprint
  1541. is <F> should be available at:
  1542. http://<hostname>/tor/keys/fp/<F>.z
  1543. The key certificate whose signing key fingerprint is <F> should be
  1544. available at:
  1545. http://<hostname>/tor/keys/sk/<F>.z
  1546. The key certificate whose identity key fingerprint is <F> and whose signing
  1547. key fingerprint is <S> should be available at:
  1548. http://<hostname>/tor/keys/fp-sk/<F>-<S>.z
  1549. (As usual, clients may request multiple certificates using:
  1550. http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z )
  1551. [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]
  1552. The most recent descriptor for a server whose identity key has a
  1553. fingerprint of <F> should be available at:
  1554. http://<hostname>/tor/server/fp/<F>.z
  1555. The most recent descriptors for servers with identity fingerprints
  1556. <F1>,<F2>,<F3> should be available at:
  1557. http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
  1558. (NOTE: Implementations SHOULD NOT download descriptors by identity key
  1559. fingerprint. This allows a corrupted server (in collusion with a cache) to
  1560. provide a unique descriptor to a client, and thereby partition that client
  1561. from the rest of the network.)
  1562. The server descriptor with (descriptor) digest <D> (in hex) should be
  1563. available at:
  1564. http://<hostname>/tor/server/d/<D>.z
  1565. The most recent descriptors with digests <D1>,<D2>,<D3> should be
  1566. available at:
  1567. http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
  1568. The most recent descriptor for this server should be at:
  1569. http://<hostname>/tor/server/authority.z
  1570. [Nothing in the Tor protocol uses this resource yet, but it is useful
  1571. for debugging purposes. Also, the official Tor implementations
  1572. (starting at 0.1.1.x) use this resource to test whether a server's
  1573. own DirPort is reachable.]
  1574. A concatenated set of the most recent descriptors for all known servers
  1575. should be available at:
  1576. http://<hostname>/tor/server/all.z
  1577. Extra-info documents are available at the URLS
  1578. http://<hostname>/tor/extra/d/...
  1579. http://<hostname>/tor/extra/fp/...
  1580. http://<hostname>/tor/extra/all[.z]
  1581. http://<hostname>/tor/extra/authority[.z]
  1582. (As for /tor/server/ URLs: supports fetching extra-info
  1583. documents by their digest, by the fingerprint of their servers,
  1584. or all at once. When serving by fingerprint, we serve the
  1585. extra-info that corresponds to the descriptor we would serve by
  1586. that fingerprint. Only directory authorities of version
  1587. 0.2.0.1-alpha or later are guaranteed to support the first
  1588. three classes of URLs. Caches may support them, and MUST
  1589. support them if they have advertised "caches-extra-info".)
  1590. For debugging, directories SHOULD expose non-compressed objects at URLs like
  1591. the above, but without the final ".z".
  1592. Clients MUST handle compressed concatenated information in two forms:
  1593. - A concatenated list of zlib-compressed objects.
  1594. - A zlib-compressed concatenated list of objects.
  1595. Directory servers MAY generate either format: the former requires less
  1596. CPU, but the latter requires less bandwidth.
  1597. Clients SHOULD use upper case letters (A-F) when base16-encoding
  1598. fingerprints. Servers MUST accept both upper and lower case fingerprints
  1599. in requests.
  1600. 5. Client operation: downloading information
  1601. Every Tor that is not a directory server (that is, those that do
  1602. not have a DirPort set) implements this section.
  1603. 5.1. Downloading network-status documents
  1604. Each client maintains a list of directory authorities. Insofar as
  1605. possible, clients SHOULD all use the same list.
  1606. Clients try to have a live consensus network-status document at all times.
  1607. A network-status document is "live" if the time in its valid-until field
  1608. has not passed.
  1609. If a client is missing a live network-status document, it tries to fetch
  1610. it from a directory cache (or from an authority if it knows no caches).
  1611. On failure, the client waits briefly, then tries that network-status
  1612. document again from another cache. The client does not build circuits
  1613. until it has a live network-status consensus document, and it has
  1614. descriptors for more than 1/4 of the routers that it believes are running.
  1615. (Note: clients can and should pick caches based on the network-status
  1616. information they have: once they have first fetched network-status info
  1617. from an authority, they should not need to go to the authority directly
  1618. again.)
  1619. To avoid swarming the caches whenever a consensus expires, the
  1620. clients download new consensuses at a randomly chosen time after the
  1621. caches are expected to have a fresh consensus, but before their
  1622. consensus will expire. (This time is chosen uniformly at random from
  1623. the interval between the time 3/4 into the first interval after the
  1624. consensus is no longer fresh, and 7/8 of the time remaining after
  1625. that before the consensus is invalid.)
  1626. [For example, if a cache has a consensus that became valid at 1:00,
  1627. and is fresh until 2:00, and expires at 4:00, that cache will fetch
  1628. a new consensus at a random time between 2:45 and 3:50, since 3/4
  1629. of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
  1630. minutes is 65 minutes.]
  1631. 5.2. Downloading and storing router descriptors
  1632. Clients try to have the best descriptor for each router. A descriptor is
  1633. "best" if:
  1634. * It is listed in the consensus network-status document.
  1635. Periodically (currently every 10 seconds) clients check whether there are
  1636. any "downloadable" descriptors. A descriptor is downloadable if:
  1637. - It is the "best" descriptor for some router.
  1638. - The descriptor was published at least 10 minutes in the past.
  1639. (This prevents clients from trying to fetch descriptors that the
  1640. mirrors have probably not yet retrieved and cached.)
  1641. - The client does not currently have it.
  1642. - The client is not currently trying to download it.
  1643. - The client would not discard it immediately upon receiving it.
  1644. - The client thinks it is running and valid (see 6.1 below).
  1645. If at least 16 known routers have downloadable descriptors, or if
  1646. enough time (currently 10 minutes) has passed since the last time the
  1647. client tried to download descriptors, it launches requests for all
  1648. downloadable descriptors, as described in 5.3 below.
  1649. When a descriptor download fails, the client notes it, and does not
  1650. consider the descriptor downloadable again until a certain amount of time
  1651. has passed. (Currently 0 seconds for the first failure, 60 seconds for the
  1652. second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
  1653. thereafter.) Periodically (currently once an hour) clients reset the
  1654. failure count.
  1655. Clients retain the most recent descriptor they have downloaded for each
  1656. router so long as it is not too old (currently, 48 hours), OR so long as
  1657. no better descriptor has been downloaded for the same router.
  1658. [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
  1659. being published too far in the past.] [The code seems to discard
  1660. descriptors in all cases after they're 5 days old. True? -RD]
  1661. 5.3. Managing downloads
  1662. When a client has no consensus network-status document, it downloads it
  1663. from a randomly chosen authority. In all other cases, the client
  1664. downloads from caches randomly chosen from among those believed to be V2
  1665. directory servers. (This information comes from the network-status
  1666. documents; see 6 below.)
  1667. When downloading multiple router descriptors, the client chooses multiple
  1668. mirrors so that:
  1669. - At least 3 different mirrors are used, except when this would result
  1670. in more than one request for under 4 descriptors.
  1671. - No more than 128 descriptors are requested from a single mirror.
  1672. - Otherwise, as few mirrors as possible are used.
  1673. After choosing mirrors, the client divides the descriptors among them
  1674. randomly.
  1675. After receiving any response client MUST discard any network-status
  1676. documents and descriptors that it did not request.
  1677. 6. Using directory information
  1678. Everyone besides directory authorities uses the approaches in this section
  1679. to decide which servers to use and what their keys are likely to be.
  1680. (Directory authorities just believe their own opinions, as in 3.1 above.)
  1681. 6.1. Choosing routers for circuits.
  1682. Circuits SHOULD NOT be built until the client has enough directory
  1683. information: a live consensus network status [XXXX fallback?] and
  1684. descriptors for at least 1/4 of the servers believed to be running.
  1685. A server is "listed" if it is included by the consensus network-status
  1686. document. Clients SHOULD NOT use unlisted servers.
  1687. These flags are used as follows:
  1688. - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
  1689. requested to do so.
  1690. - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
  1691. very-low-bandwidth circuits (such as introduction circuits).
  1692. - Clients SHOULD NOT use non-'Stable' routers for circuits that are
  1693. likely to need to be open for a very long time (such as those used for
  1694. IRC or SSH connections).
  1695. - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
  1696. nodes.
  1697. - Clients SHOULD NOT download directory information from non-'V2Dir'
  1698. caches.
  1699. See the "path-spec.txt" document for more details.
  1700. 6.2. Managing naming
  1701. In order to provide human-memorable names for individual server
  1702. identities, some directory servers bind names to IDs. Clients handle
  1703. names in two ways:
  1704. When a client encounters a name it has not mapped before:
  1705. If the consensus lists any router with that name as "Named", or if
  1706. consensus-method 2 or later is in use and the consensus lists any
  1707. router with that name as having the "Unnamed" flag, then the name is
  1708. bound. (It's bound to the ID listed in the entry with the Named,
  1709. or to an unknown ID if no name is found.)
  1710. When the user refers to a bound name, the implementation SHOULD provide
  1711. only the router with ID bound to that name, and no other router, even
  1712. if the router with the right ID can't be found.
  1713. When a user tries to refer to a non-bound name, the implementation SHOULD
  1714. warn the user. After warning the user, the implementation MAY use any
  1715. router that advertises the name.
  1716. Not every router needs a nickname. When a router doesn't configure a
  1717. nickname, it publishes with the default nickname "Unnamed". Authorities
  1718. SHOULD NOT ever mark a router with this nickname as Named; client software
  1719. SHOULD NOT ever use a router in response to a user request for a router
  1720. called "Unnamed".
  1721. 6.3. Software versions
  1722. An implementation of Tor SHOULD warn when it has fetched a consensus
  1723. network-status, and it is running a software version not listed.
  1724. 6.4. Warning about a router's status.
  1725. If a router tries to publish its descriptor to a Naming authority
  1726. that has its nickname mapped to another key, the router SHOULD
  1727. warn the operator that it is either using the wrong key or is using
  1728. an already claimed nickname.
  1729. If a router has fetched a consensus document,, and the
  1730. authorities do not publish a binding for the router's nickname, the
  1731. router MAY remind the operator that the chosen nickname is not
  1732. bound to this key at the authorities, and suggest contacting the
  1733. authority operators.
  1734. ...
  1735. 6.5. Router protocol versions
  1736. A client should believe that a router supports a given feature if that
  1737. feature is supported by the router or protocol versions in more than half
  1738. of the live networkstatuses' "v" entries for that router. In other words,
  1739. if the "v" entries for some router are:
  1740. v Tor 0.0.8pre1 (from authority 1)
  1741. v Tor 0.1.2.11 (from authority 2)
  1742. v FutureProtocolDescription 99 (from authority 3)
  1743. then the client should believe that the router supports any feature
  1744. supported by 0.1.2.11.
  1745. This is currently equivalent to believing the median declared version for
  1746. a router in all live networkstatuses.
  1747. 7. Standards compliance
  1748. All clients and servers MUST support HTTP 1.0. Clients and servers MAY
  1749. support later versions of HTTP as well.
  1750. 7.1. HTTP headers
  1751. Servers MAY set the Content-Length: header. Servers SHOULD set
  1752. Content-Encoding to "deflate" or "identity".
  1753. Servers MAY include an X-Your-Address-Is: header, whose value is the
  1754. apparent IP address of the client connecting to them (as a dotted quad).
  1755. For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
  1756. report the IP from which the circuit carrying the BEGIN_DIR stream reached
  1757. them. [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
  1758. BEGIN_DIR-tunneled connections.]
  1759. Servers SHOULD disable caching of multiple network statuses or multiple
  1760. router descriptors. Servers MAY enable caching of single descriptors,
  1761. single network statuses, the list of all router descriptors, a v1
  1762. directory, or a v1 running routers document. XXX mention times.
  1763. 7.2. HTTP status codes
  1764. Tor delivers the following status codes. Some were chosen without much
  1765. thought; other code SHOULD NOT rely on specific status codes yet.
  1766. 200 -- the operation completed successfully
  1767. -- the user requested statuses or serverdescs, and none of the ones we
  1768. requested were found (0.2.0.4-alpha and earlier).
  1769. 304 -- the client specified an if-modified-since time, and none of the
  1770. requested resources have changed since that time.
  1771. 400 -- the request is malformed, or
  1772. -- the URL is for a malformed variation of one of the URLs we support,
  1773. or
  1774. -- the client tried to post to a non-authority, or
  1775. -- the authority rejected a malformed posted document, or
  1776. 404 -- the requested document was not found.
  1777. -- the user requested statuses or serverdescs, and none of the ones
  1778. requested were found (0.2.0.5-alpha and later).
  1779. 503 -- we are declining the request in order to save bandwidth
  1780. -- user requested some items that we ordinarily generate or store,
  1781. but we do not have any available.
  1782. 9. Backward compatibility and migration plans
  1783. Until Tor versions before 0.1.1.x are completely obsolete, directory
  1784. authorities should generate, and mirrors should download and cache, v1
  1785. directories and running-routers lists, and allow old clients to download
  1786. them. These documents and the rules for retrieving, serving, and caching
  1787. them are described in dir-spec-v1.txt.
  1788. Until Tor versions before 0.2.0.x are completely obsolete, directory
  1789. authorities should generate, mirrors should download and cache, v2
  1790. network-status documents, and allow old clients to download them.
  1791. Additionally, all directory servers and caches should download, store, and
  1792. serve any router descriptor that is required because of v2 network-status
  1793. documents. These documents and the rules for retrieving, serving, and
  1794. caching them are described in dir-spec-v1.txt.
  1795. A. Consensus-negotiation timeline.
  1796. Period begins: this is the Published time.
  1797. Everybody sends votes
  1798. Reconciliation: everybody tries to fetch missing votes.
  1799. consensus may exist at this point.
  1800. End of voting period:
  1801. everyone swaps signatures.
  1802. Now it's okay for caches to download
  1803. Now it's okay for clients to download.
  1804. Valid-after/valid-until switchover