dir-spec.txt 150 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644
  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. This document merges and supersedes the following proposals:
  8. 101 Voting on the Tor Directory System
  9. 103 Splitting identity key from regularly used signing key
  10. 104 Long and Short Router Descriptors
  11. XXX timeline
  12. XXX fill in XXXXs
  13. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  14. NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
  15. "OPTIONAL" in this document are to be interpreted as described in
  16. RFC 2119.
  17. 0.1. History
  18. The earliest versions of Onion Routing shipped with a list of known
  19. routers and their keys. When the set of routers changed, users needed to
  20. fetch a new list.
  21. The Version 1 Directory protocol
  22. --------------------------------
  23. Early versions of Tor (0.0.2) introduced "Directory authorities": servers
  24. that served signed "directory" documents containing a list of signed
  25. "server descriptors", along with short summary of the status of each
  26. router. Thus, clients could get up-to-date information on the state of
  27. the network automatically, and be certain that the list they were getting
  28. was attested by a trusted directory authority.
  29. Later versions (0.0.8) added directory caches, which download
  30. directories from the authorities and serve them to clients. Non-caches
  31. fetch from the caches in preference to fetching from the authorities, thus
  32. distributing bandwidth requirements.
  33. Also added during the version 1 directory protocol were "router status"
  34. documents: short documents that listed only the up/down status of the
  35. routers on the network, rather than a complete list of all the
  36. descriptors. Clients and caches would fetch these documents far more
  37. frequently than they would fetch full directories.
  38. The Version 2 Directory Protocol
  39. --------------------------------
  40. During the Tor 0.1.1.x series, Tor revised its handling of directory
  41. documents in order to address two major problems:
  42. * Directories had grown quite large (over 1MB), and most directory
  43. downloads consisted mainly of server descriptors that clients
  44. already had.
  45. * Every directory authority was a trust bottleneck: if a single
  46. directory authority lied, it could make clients believe for a time
  47. an arbitrarily distorted view of the Tor network. (Clients
  48. trusted the most recent signed document they downloaded.) Thus,
  49. adding more authorities would make the system less secure, not
  50. more.
  51. To address these, we extended the directory protocol so that
  52. authorities now published signed "network status" documents. Each
  53. network status listed, for every router in the network: a hash of its
  54. identity key, a hash of its most recent descriptor, and a summary of
  55. what the authority believed about its status. Clients would download
  56. the authorities' network status documents in turn, and believe
  57. statements about routers iff they were attested to by more than half of
  58. the authorities.
  59. Instead of downloading all server descriptors at once, clients
  60. downloaded only the descriptors that they did not have. Descriptors
  61. were indexed by their digests, in order to prevent malicious caches
  62. from giving different versions of a server descriptor to different
  63. clients.
  64. Routers began working harder to upload new descriptors only when their
  65. contents were substantially changed.
  66. 0.2. Goals of the version 3 protocol
  67. Version 3 of the Tor directory protocol tries to solve the following
  68. issues:
  69. * A great deal of bandwidth used to transmit server descriptors was
  70. used by two fields that are not actually used by Tor routers
  71. (namely read-history and write-history). We save about 60% by
  72. moving them into a separate document that most clients do not
  73. fetch or use.
  74. * It was possible under certain perverse circumstances for clients
  75. to download an unusual set of network status documents, thus
  76. partitioning themselves from clients who have a more recent and/or
  77. typical set of documents. Even under the best of circumstances,
  78. clients were sensitive to the ages of the network status documents
  79. they downloaded. Therefore, instead of having the clients
  80. correlate multiple network status documents, we have the
  81. authorities collectively vote on a single consensus network status
  82. document.
  83. * The most sensitive data in the entire network (the identity keys
  84. of the directory authorities) needed to be stored unencrypted so
  85. that the authorities can sign network-status documents on the fly.
  86. Now, the authorities' identity keys are stored offline, and used
  87. to certify medium-term signing keys that can be rotated.
  88. 0.3. Some Remaining questions
  89. Things we could solve on a v3 timeframe:
  90. The SHA-1 hash is showing its age. We should do something about our
  91. dependency on it. We could probably future-proof ourselves here in
  92. this revision, at least so far as documents from the authorities are
  93. concerned.
  94. Too many things about the authorities are hardcoded by IP.
  95. Perhaps we should start accepting longer identity keys for routers
  96. too.
  97. Things to solve eventually:
  98. Requiring every client to know about every router won't scale forever.
  99. Requiring every directory cache to know every router won't scale
  100. forever.
  101. 1. Outline
  102. There is a small set (say, around 5-10) of semi-trusted directory
  103. authorities. A default list of authorities is shipped with the Tor
  104. software. Users can change this list, but are encouraged not to do so,
  105. in order to avoid partitioning attacks.
  106. Every authority has a very-secret, long-term "Authority Identity Key".
  107. This is stored encrypted and/or offline, and is used to sign "key
  108. certificate" documents. Every key certificate contains a medium-term
  109. (3-12 months) "authority signing key", that is used by the authority to
  110. sign other directory information. (Note that the authority identity
  111. key is distinct from the router identity key that the authority uses
  112. in its role as an ordinary router.)
  113. Routers periodically upload signed "routers descriptors" to the
  114. directory authorities describing their keys, capabilities, and other
  115. information. Routers may also upload signed "extra info documents"
  116. containing information that is not required for the Tor protocol.
  117. Directory authorities serve server descriptors indexed by router
  118. identity, or by hash of the descriptor.
  119. Routers may act as directory caches to reduce load on the directory
  120. authorities. They announce this in their descriptors.
  121. Periodically, each directory authority generates a view of
  122. the current descriptors and status for known routers. They send a
  123. signed summary of this view (a "status vote") to the other
  124. authorities. The authorities compute the result of this vote, and sign
  125. a "consensus status" document containing the result of the vote.
  126. Directory caches download, cache, and re-serve consensus documents.
  127. Clients, directory caches, and directory authorities all use consensus
  128. documents to find out when their list of routers is out-of-date.
  129. (Directory authorities also use vote statuses.) If it is, they download
  130. any missing server descriptors. Clients download missing descriptors
  131. from caches; caches and authorities download from authorities.
  132. Descriptors are downloaded by the hash of the descriptor, not by the
  133. relay's identity key: this prevents directory servers from attacking
  134. clients by giving them descriptors nobody else uses.
  135. All directory information is uploaded and downloaded with HTTP.
  136. 1.1. What's different from version 2?
  137. Clients used to download multiple network status documents,
  138. corresponding roughly to "status votes" above. They would compute the
  139. result of the vote on the client side.
  140. Authorities used to sign documents using the same private keys they used
  141. for their roles as routers. This forced them to keep these extremely
  142. sensitive keys in memory unencrypted.
  143. All of the information in extra-info documents used to be kept in the
  144. main descriptors.
  145. 1.2. Document meta-format
  146. Server descriptors, directories, and running-routers documents all obey the
  147. following lightweight extensible information format.
  148. The highest level object is a Document, which consists of one or more
  149. Items. Every Item begins with a KeywordLine, followed by zero or more
  150. Objects. A KeywordLine begins with a Keyword, optionally followed by
  151. whitespace and more non-newline characters, and ends with a newline. A
  152. Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  153. An Object is a block of encoded data in pseudo-Open-PGP-style
  154. armor. (cf. RFC 2440)
  155. More formally:
  156. NL = The ascii LF character (hex value 0x0a).
  157. Document ::= (Item | NL)+
  158. Item ::= KeywordLine Object*
  159. KeywordLine ::= Keyword NL | Keyword WS ArgumentChar+ NL
  160. Keyword = KeywordChar+
  161. KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  162. ArgumentChar ::= any printing ASCII character except NL.
  163. WS = (SP | TAB)+
  164. Object ::= BeginLine Base64-encoded-data EndLine
  165. BeginLine ::= "-----BEGIN " Keyword "-----" NL
  166. EndLine ::= "-----END " Keyword "-----" NL
  167. The BeginLine and EndLine of an Object must use the same keyword.
  168. When interpreting a Document, software MUST ignore any KeywordLine that
  169. starts with a keyword it doesn't recognize; future implementations MUST NOT
  170. require current clients to understand any KeywordLine not currently
  171. described.
  172. Other implementations that want to extend Tor's directory format MAY
  173. introduce their own items. The keywords for extension items SHOULD start
  174. with the characters "x-" or "X-", to guarantee that they will not conflict
  175. with keywords used by future versions of Tor.
  176. In our document descriptions below, we tag Items with a multiplicity in
  177. brackets. Possible tags are:
  178. "At start, exactly once": These items MUST occur in every instance of
  179. the document type, and MUST appear exactly once, and MUST be the
  180. first item in their documents.
  181. "Exactly once": These items MUST occur exactly one time in every
  182. instance of the document type.
  183. "At end, exactly once": These items MUST occur in every instance of
  184. the document type, and MUST appear exactly once, and MUST be the
  185. last item in their documents.
  186. "At most once": These items MAY occur zero or one times in any
  187. instance of the document type, but MUST NOT occur more than once.
  188. "Any number": These items MAY occur zero, one, or more times in any
  189. instance of the document type.
  190. "Once or more": These items MUST occur at least once in any instance
  191. of the document type, and MAY occur more.
  192. For forward compatibility, each item MUST allow extra arguments at the
  193. end of the line unless otherwise noted. So if an item's description below
  194. is given as:
  195. "thing" int int int NL
  196. then implementations SHOULD accept this string as well:
  197. "thing 5 9 11 13 16 12" NL
  198. but not this string:
  199. "thing 5" NL
  200. and not this string:
  201. "thing 5 10 thing" NL
  202. .
  203. Whenever an item DOES NOT allow extra arguments, we will tag it with
  204. "no extra arguments".
  205. 1.3. Signing documents
  206. Every signable document below is signed in a similar manner, using a
  207. given "Initial Item", a final "Signature Item", a digest algorithm, and
  208. a signing key.
  209. The Initial Item must be the first item in the document.
  210. The Signature Item has the following format:
  211. <signature item keyword> [arguments] NL SIGNATURE NL
  212. The "SIGNATURE" Object contains a signature (using the signing key) of
  213. the PKCS1-padded digest of the entire document, taken from the
  214. beginning of the Initial item, through the newline after the Signature
  215. Item's keyword and its arguments.
  216. Unless otherwise, the digest algorithm is SHA-1.
  217. All documents are invalid unless signed with the correct signing key.
  218. The "Digest" of a document, unless stated otherwise, is its digest *as
  219. signed by this signature scheme*.
  220. 1.4. Voting timeline
  221. Every consensus document has a "valid-after" (VA) time, a "fresh-until"
  222. (FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
  223. in turn precede VU. Times are chosen so that every consensus will be
  224. "fresh" until the next consensus becomes valid, and "valid" for a while
  225. after. At least 3 consensuses should be valid at any given time.
  226. The timeline for a given consensus is as follows:
  227. VA-DistSeconds-VoteSeconds: The authorities exchange votes.
  228. VA-DistSeconds-VoteSeconds/2: The authorities try to download any
  229. votes they don't have.
  230. VA-DistSeconds: The authorities calculate the consensus and exchange
  231. signatures.
  232. VA-DistSeconds/2: The authorities try to download any signatures
  233. they don't have.
  234. VA: All authorities have a multiply signed consensus.
  235. VA ... FU: Caches download the consensus. (Note that since caches have
  236. no way of telling what VA and FU are until they have downloaded
  237. the consensus, they assume that the present consensus's VA is
  238. equal to the previous one's FU, and that its FU is one interval after
  239. that.)
  240. FU: The consensus is no longer the freshest consensus.
  241. FU ... (the current consensus's VU): Clients download the consensus.
  242. (See note above: clients guess that the next consensus's FU will be
  243. two intervals after the current VA.)
  244. VU: The consensus is no longer valid.
  245. VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
  246. VU-FU MUST each be at least 5 minutes.
  247. 2. Router operation and formats
  248. 2.1. Uploading server descriptors and extra-info documents
  249. ORs SHOULD generate a new server descriptor and a new extra-info
  250. document whenever any of the following events have occurred:
  251. - A period of time (18 hrs by default) has passed since the last
  252. time a descriptor was generated.
  253. - A descriptor field other than bandwidth or uptime has changed.
  254. - Bandwidth has changed by a factor of 2 from the last time a
  255. descriptor was generated, and at least a given interval of time
  256. (20 mins by default) has passed since then.
  257. - Its uptime has been reset (by restarting).
  258. [XXX this list is incomplete; see router_differences_are_cosmetic()
  259. in routerlist.c for others]
  260. ORs SHOULD NOT publish a new server descriptor or extra-info document
  261. if none of the above events have occurred and not much time has passed
  262. (12 hours by default).
  263. After generating a descriptor, ORs upload them to every directory
  264. authority they know, by posting them (in order) to the URL
  265. http://<hostname:port>/tor/
  266. Server descriptors may not exceed 20,000 bytes in length; extra-info
  267. documents may not exceed 50,000 bytes in length. If they do, the
  268. authorities SHOULD reject them.
  269. 2.1.1. Server descriptor format
  270. Server descriptors consist of the following items. For backward
  271. compatibility, there should be an extra NL at the end of each router
  272. descriptor.
  273. In lines that take multiple arguments, extra arguments SHOULD be
  274. accepted and ignored. Many of the nonterminals below are defined in
  275. section 2.1.3.
  276. "router" nickname address ORPort SOCKSPort DirPort NL
  277. [At start, exactly once.]
  278. Indicates the beginning of a server descriptor. "nickname" must be a
  279. valid router nickname as specified in section 2.1.3. "address" must
  280. be an IPv4
  281. address in dotted-quad format. The last three numbers indicate the
  282. TCP ports at which this OR exposes functionality. ORPort is a port at
  283. which this OR accepts TLS connections for the main OR protocol;
  284. SOCKSPort is deprecated and should always be 0; and DirPort is the
  285. port at which this OR accepts directory-related HTTP connections. If
  286. any port is not supported, the value 0 is given instead of a port
  287. number. (At least one of DirPort and ORPort SHOULD be set;
  288. authorities MAY reject any descriptor with both DirPort and ORPort of
  289. 0.)
  290. "identity-ed25519" NL "-----BEGIN ED25519 CERT-----" NL certificate
  291. "-----END ED25519 CERT-----" NL
  292. [At most once, in second position in document.]
  293. [No extra arguments]
  294. The certificate is a base64-encoded Ed25519 certificate (see
  295. cert-spec.txt) with terminating =s removed. When this element
  296. is present, it MUST appear as the first or second element in
  297. the router descriptor.
  298. The certificate has CERT_TYPE of [04]. It must include a
  299. signed-with-ed25519-key extension (see cert-spec.txt,
  300. section 2.2.1), so that we can extract the master identity key.
  301. "master-key-ed25519" SP MasterKey NL
  302. [At most once]
  303. Contains the base-64 encoded ed25519 master key as a single
  304. argument. If it is present, it MUST match the identity key
  305. in the identity-ed25519 entry.
  306. "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
  307. [Exactly once]
  308. Estimated bandwidth for this router, in bytes per second. The
  309. "average" bandwidth is the volume per second that the OR is willing to
  310. sustain over long periods; the "burst" bandwidth is the volume that
  311. the OR is willing to sustain in very short intervals. The "observed"
  312. value is an estimate of the capacity this relay can handle. The
  313. relay remembers the max bandwidth sustained output over any ten
  314. second period in the past day, and another sustained input. The
  315. "observed" value is the lesser of these two numbers.
  316. "platform" string NL
  317. [At most once]
  318. A human-readable string describing the system on which this OR is
  319. running. This MAY include the operating system, and SHOULD include
  320. the name and version of the software implementing the Tor protocol.
  321. "published" YYYY-MM-DD HH:MM:SS NL
  322. [Exactly once]
  323. The time, in UTC, when this descriptor (and its corresponding
  324. extra-info document if any) was generated.
  325. "fingerprint" fingerprint NL
  326. [At most once]
  327. A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
  328. hex, with a single space after every 4 characters) for this router's
  329. identity key. A descriptor is considered invalid (and MUST be
  330. rejected) if the fingerprint line does not match the public key.
  331. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  332. be marked with "opt" until earlier versions of Tor are obsolete.]
  333. "hibernating" bool NL
  334. [At most once]
  335. If the value is 1, then the Tor relay was hibernating when the
  336. descriptor was published, and shouldn't be used to build circuits.
  337. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
  338. marked with "opt" until earlier versions of Tor are obsolete.]
  339. "uptime" number NL
  340. [At most once]
  341. The number of seconds that this OR process has been running.
  342. "onion-key" NL a public key in PEM format
  343. [Exactly once]
  344. [No extra arguments]
  345. This key is used to encrypt CREATE cells for this OR. The key MUST be
  346. accepted for at least 1 week after any new key is published in a
  347. subsequent descriptor. It MUST be 1024 bits.
  348. The key encoding is the encoding of the key as a PKCS#1 RSAPublicKey
  349. structure, encoded in base64, and wrapped in "-----BEGIN RSA PUBLIC
  350. KEY-----" and "-----END RSA PUBLIC KEY-----".
  351. "onion-key-crosscert" NL a RSA signature in PEM format.
  352. [At most once, required when identity-ed25519 is present]
  353. [No extra arguments]
  354. This element contains an RSA signature, generated using the
  355. onion-key, of the following:
  356. A SHA1 hash of the RSA identity key,
  357. i.e. RSA key from "signing-key" (see below) [20 bytes]
  358. The Ed25519 identity key,
  359. i.e. Ed25519 key from "master-key-ed25519" [32 bytes]
  360. If there is no Ed25519 identity key, or if in some future version
  361. there is no RSA identity key, the corresponding field must be
  362. zero-filled.
  363. Parties verifying this signature MUST allow additional data
  364. beyond the 52 bytes listed above.
  365. This signature proves that the party creating the descriptor
  366. had control over the secret key corresponding to the
  367. onion-key.
  368. "ntor-onion-key" base-64-encoded-key
  369. [At most once]
  370. A curve25519 public key used for the ntor circuit extended
  371. handshake. It's the standard encoding of the OR's curve25519
  372. public key, encoded in base 64. The trailing '=' sign MAY be
  373. omitted from the base64 encoding. The key MUST be accepted
  374. for at least 1 week after any new key is published in a
  375. subsequent descriptor.
  376. "ntor-onion-key-crosscert" SP Bit NL
  377. "-----BEGIN ED25519 CERT-----" NL certificate
  378. "-----END ED25519 CERT-----" NL
  379. [At most once, required when identity-ed25519 is present]
  380. [No extra arguments]
  381. A signature created with the ntor-onion-key, using the
  382. certificate format documented in cert-spec.txt, with type
  383. [0a]. The signed key here is the master identity key.
  384. Bit must be "0" or "1". It indicates the sign of the ed25519
  385. public key corresponding to the ntor onion key.
  386. To compute the ed25519 public key corresponding to a
  387. curve25519 key, see appendix C.
  388. This signature proves that the party creating the descriptor
  389. had control over the secret key corresponding to the
  390. ntor-onion-key.
  391. "signing-key" NL a public key in PEM format
  392. [Exactly once]
  393. [No extra arguments]
  394. The OR's long-term RSA identity key. It MUST be 1024 bits.
  395. The encoding is as for "onion-key" above.
  396. "accept" exitpattern NL
  397. "reject" exitpattern NL
  398. [Any number]
  399. These lines describe an "exit policy": the rules that an OR follows
  400. when deciding whether to allow a new stream to a given address. The
  401. 'exitpattern' syntax is described below. There MUST be at least one
  402. such entry. The rules are considered in order; if no rule matches,
  403. the address will be accepted. For clarity, the last such entry SHOULD
  404. be accept *:* or reject *:*.
  405. "ipv6-policy" SP ("accept" / "reject") SP PortList NL
  406. [At most once.]
  407. An exit-policy summary as specified in sections 3.4.1 and 3.8.2,
  408. summarizing
  409. the router's rules for connecting to IPv6 addresses. A missing
  410. "ipv6-policy" line is equivalent to "ipv6-policy reject
  411. 1-65535".
  412. "router-sig-ed25519" SP Signature NL
  413. [At most once.]
  414. [Required when identity-ed25519 is present; forbidden otherwise.]
  415. It MUST be the next-to-last element in the descriptor, appearing
  416. immediately before the RSA signature. It MUST contain an Ed25519
  417. signature of a SHA256 digest of the entire document, from the
  418. first character up to and including the first space after the
  419. "router-sig-ed25519" string, prefixed with the string "Tor
  420. router descriptor signature v1". Its format is:
  421. The signature is encoded in Base64 with terminating =s removed.
  422. The signing key in the identity-ed25519 certificate MUST
  423. be the one used to sign the document.
  424. "router-signature" NL Signature NL
  425. [At end, exactly once]
  426. [No extra arguments]
  427. The "SIGNATURE" object contains a signature of the PKCS1-padded
  428. hash of the entire server descriptor, taken from the beginning of the
  429. "router" line, through the newline after the "router-signature" line.
  430. The server descriptor is invalid unless the signature is performed
  431. with the router's identity key.
  432. "contact" info NL
  433. [At most once]
  434. Describes a way to contact the relay's administrator, preferably
  435. including an email address and a PGP key fingerprint.
  436. "family" names NL
  437. [At most once]
  438. 'Names' is a space-separated list of relay nicknames or
  439. hexdigests. If two ORs list one another in their "family" entries,
  440. then OPs should treat them as a single OR for the purpose of path
  441. selection.
  442. For example, if node A's descriptor contains "family B", and node B's
  443. descriptor contains "family A", then node A and node B should never
  444. be used on the same circuit.
  445. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  446. [At most once]
  447. "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  448. [At most once]
  449. Declare how much bandwidth the OR has used recently. Usage is divided
  450. into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field
  451. defines the end of the most recent interval. The numbers are the
  452. number of bytes used in the most recent intervals, ordered from
  453. oldest to newest.
  454. [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
  455. be marked with "opt" until earlier versions of Tor are obsolete.]
  456. [See also migration notes in section 2.1.2.1.]
  457. "eventdns" bool NL
  458. [At most once]
  459. Declare whether this version of Tor is using the newer enhanced
  460. dns logic. Versions of Tor with this field set to false SHOULD NOT
  461. be used for reverse hostname lookups.
  462. [This option is obsolete. All Tor current relays should be presumed
  463. to have the evdns backend.]
  464. "caches-extra-info" NL
  465. [At most once.]
  466. [No extra arguments]
  467. Present only if this router is a directory cache that provides
  468. extra-info documents.
  469. [Versions before 0.2.0.1-alpha don't recognize this]
  470. "extra-info-digest" SP sha1digest [SP sha256-digest] NL
  471. [At most once]
  472. "sha1-digest" is a hex-encoded digest (using upper-case characters) of
  473. the router's extra-info document, as signed in the router's extra-info
  474. (that is, not including the signature). (If this field is absent, the
  475. router is not uploading a corresponding extra-info document.)
  476. "sha256-digest" is a base64-encoded SHA256 digest of the extra-info
  477. document, computed over the same data.
  478. [Versions before 0.2.7.2-alpha did not include a SHA256 digest.]
  479. [Versions before 0.2.0.1-alpha don't recognize this field at all.]
  480. "hidden-service-dir" *(SP VersionNum) NL
  481. [At most once.]
  482. Present only if this router stores and serves hidden service
  483. descriptors. If any VersionNum(s) are specified, this router
  484. supports those descriptor versions. If none are specified, it
  485. defaults to version 2 descriptors.
  486. "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
  487. CIRCUIT-VERSION-LIST NL
  488. [At most once.]
  489. Both lists are space-separated sequences of numbers, to indicate which
  490. protocols the server supports. As of 30 Mar 2008, specified
  491. protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt
  492. for more information about link protocol versions.
  493. [NOTE: No version of Tor uses this protocol list. It will be removed
  494. in a future version of Tor.]
  495. "allow-single-hop-exits" NL
  496. [At most once.]
  497. [No extra arguments]
  498. Present only if the router allows single-hop circuits to make exit
  499. connections. Most Tor relays do not support this: this is
  500. included for specialized controllers designed to support perspective
  501. access and such. This is obsolete in tor version >= 0.3.1.0-alpha.
  502. "or-address" SP ADDRESS ":" PORT NL
  503. [Any number]
  504. ADDRESS = IP6ADDR | IP4ADDR
  505. IPV6ADDR = an ipv6 address, surrounded by square brackets.
  506. IPV4ADDR = an ipv4 address, represented as a dotted quad.
  507. PORT = a number between 1 and 65535 inclusive.
  508. An alternative for the address and ORPort of the "router" line, but with
  509. two added capabilities:
  510. * or-address can be either an IPv4 or IPv6 address
  511. * or-address allows for multiple ORPorts and addresses
  512. A descriptor SHOULD NOT include an or-address line that does nothing but
  513. duplicate the address:port pair from its "router" line.
  514. The ordering of or-address lines and their PORT entries matter because
  515. Tor MAY accept a limited number of addresses or ports. As of Tor 0.2.3.x
  516. only the first address and the first port are used.
  517. "tunnelled-dir-server" NL
  518. [At most once.]
  519. [No extra arguments]
  520. Present if the router accepts "tunneled" directory requests using a
  521. BEGIN_DIR cell over the router's OR port.
  522. (Added in 0.2.8.1-alpha. Before this, Tor relays accepted
  523. tunneled directory requests only if they had a DirPort open,
  524. or if they were bridges.)
  525. "proto" SP Entries NL
  526. [At most one.]
  527. Entries =
  528. Entries = Entry
  529. Entries = Entry SP Entries
  530. Entry = Keyword "=" Values
  531. Values = Value
  532. Values = Value "," Values
  533. Value = Int
  534. Value = Int "-" Int
  535. Int = NON_ZERO_DIGIT
  536. Int = Int DIGIT
  537. Each 'Entry' in the "proto" line indicates that the Tor relay supports
  538. one or more versions of the protocol in question. Entries should be
  539. sorted by keyword. Values should be numerically ascending within each
  540. entry. (This implies that there should be no overlapping ranges.)
  541. Ranges should be represented as compactly as possible. Ints must be no
  542. more than 2^32 - 1.
  543. 2.1.2. Extra-info document format
  544. Extra-info documents consist of the following items:
  545. "extra-info" Nickname Fingerprint NL
  546. [At start, exactly once.]
  547. Identifies what router this is an extra info descriptor for.
  548. Fingerprint is encoded in hex (using upper-case letters), with
  549. no spaces.
  550. "identity-ed25519"
  551. [As in router descriptors]
  552. "published" YYYY-MM-DD HH:MM:SS NL
  553. [Exactly once.]
  554. The time, in UTC, when this document (and its corresponding router
  555. descriptor if any) was generated. It MUST match the published time
  556. in the corresponding server descriptor.
  557. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  558. [At most once.]
  559. "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  560. [At most once.]
  561. As documented in section 2.1.1 above. See migration notes in
  562. section 2.1.2.1.
  563. "geoip-db-digest" Digest NL
  564. [At most once.]
  565. SHA1 digest of the IPv4 GeoIP database file that is used to
  566. resolve IPv4 addresses to country codes.
  567. "geoip6-db-digest" Digest NL
  568. [At most once.]
  569. SHA1 digest of the IPv6 GeoIP database file that is used to
  570. resolve IPv6 addresses to country codes.
  571. ("geoip-start-time" YYYY-MM-DD HH:MM:SS NL)
  572. ("geoip-client-origins" CC=N,CC=N,... NL)
  573. Only generated by bridge routers (see blocking.pdf), and only
  574. when they have been configured with a geoip database.
  575. Non-bridges SHOULD NOT generate these fields. Contains a list
  576. of mappings from two-letter country codes (CC) to the number
  577. of clients that have connected to that bridge from that
  578. country (approximate, and rounded up to the nearest multiple of 8
  579. in order to hamper traffic analysis). A country is included
  580. only if it has at least one address. The time in
  581. "geoip-start-time" is the time at which we began collecting geoip
  582. statistics.
  583. "geoip-start-time" and "geoip-client-origins" have been replaced by
  584. "bridge-stats-end" and "bridge-stats-ips" in 0.2.2.4-alpha. The
  585. reason is that the measurement interval with "geoip-stats" as
  586. determined by subtracting "geoip-start-time" from "published" could
  587. have had a variable length, whereas the measurement interval in
  588. 0.2.2.4-alpha and later is set to be exactly 24 hours long. In
  589. order to clearly distinguish the new measurement intervals from
  590. the old ones, the new keywords have been introduced.
  591. "bridge-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  592. [At most once.]
  593. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  594. interval of length NSEC seconds (86400 seconds by default).
  595. A "bridge-stats-end" line, as well as any other "bridge-*" line,
  596. is only added when the relay has been running as a bridge for at
  597. least 24 hours.
  598. "bridge-ips" CC=N,CC=N,... NL
  599. [At most once.]
  600. List of mappings from two-letter country codes to the number of
  601. unique IP addresses that have connected from that country to the
  602. bridge and which are no known relays, rounded up to the nearest
  603. multiple of 8.
  604. "bridge-ip-versions" FAM=N,FAM=N,... NL
  605. [At most once.]
  606. List of unique IP addresses that have connected to the bridge
  607. per protocol family.
  608. "bridge-ip-transports" PT=N,PT=N,... NL
  609. [At most once.]
  610. List of mappings from pluggable transport names to the number
  611. of unique IP addresses that have connected using that
  612. pluggable transport. Unobfuscated connections are counted
  613. using the reserved pluggable transport name "<OR>" (without
  614. quotes). If we received a connection from a transport proxy
  615. but we couldn't figure out the name of the pluggable
  616. transport, we use the reserved pluggable transport name
  617. "<??>".
  618. ("<OR>" and "<??>" are reserved because normal pluggable
  619. transport names MUST match the following regular expression:
  620. "[a-zA-Z_][a-zA-Z0-9_]*" )
  621. The pluggable transport name list is sorted into lexically
  622. ascending order.
  623. If no clients have connected to the bridge yet, we only write
  624. "bridge-ip-transports" to the stats file.
  625. "dirreq-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  626. [At most once.]
  627. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  628. interval of length NSEC seconds (86400 seconds by default).
  629. A "dirreq-stats-end" line, as well as any other "dirreq-*" line,
  630. is only added when the relay has opened its Dir port and after 24
  631. hours of measuring directory requests.
  632. "dirreq-v2-ips" CC=N,CC=N,... NL
  633. [At most once.]
  634. "dirreq-v3-ips" CC=N,CC=N,... NL
  635. [At most once.]
  636. List of mappings from two-letter country codes to the number of
  637. unique IP addresses that have connected from that country to
  638. request a v2/v3 network status, rounded up to the nearest multiple
  639. of 8. Only those IP addresses are counted that the directory can
  640. answer with a 200 OK status code. (Note here and below: current Tor
  641. versions, as of 0.2.5.2-alpha, no longer cache or serve v2
  642. networkstatus documents.)
  643. "dirreq-v2-reqs" CC=N,CC=N,... NL
  644. [At most once.]
  645. "dirreq-v3-reqs" CC=N,CC=N,... NL
  646. [At most once.]
  647. List of mappings from two-letter country codes to the number of
  648. requests for v2/v3 network statuses from that country, rounded up
  649. to the nearest multiple of 8. Only those requests are counted that
  650. the directory can answer with a 200 OK status code.
  651. "dirreq-v2-share" num% NL
  652. [At most once.]
  653. "dirreq-v3-share" num% NL
  654. [At most once.]
  655. The share of v2/v3 network status requests that the directory
  656. expects to receive from clients based on its advertised bandwidth
  657. compared to the overall network bandwidth capacity. Shares are
  658. formatted in percent with two decimal places. Shares are
  659. calculated as means over the whole 24-hour interval.
  660. "dirreq-v2-resp" status=num,... NL
  661. [At most once.]
  662. "dirreq-v3-resp" status=nul,... NL
  663. [At most once.]
  664. List of mappings from response statuses to the number of requests
  665. for v2/v3 network statuses that were answered with that response
  666. status, rounded up to the nearest multiple of 4. Only response
  667. statuses with at least 1 response are reported. New response
  668. statuses can be added at any time. The current list of response
  669. statuses is as follows:
  670. "ok": a network status request is answered; this number
  671. corresponds to the sum of all requests as reported in
  672. "dirreq-v2-reqs" or "dirreq-v3-reqs", respectively, before
  673. rounding up.
  674. "not-enough-sigs: a version 3 network status is not signed by a
  675. sufficient number of requested authorities.
  676. "unavailable": a requested network status object is unavailable.
  677. "not-found": a requested network status is not found.
  678. "not-modified": a network status has not been modified since the
  679. If-Modified-Since time that is included in the request.
  680. "busy": the directory is busy.
  681. "dirreq-v2-direct-dl" key=val,... NL
  682. [At most once.]
  683. "dirreq-v3-direct-dl" key=val,... NL
  684. [At most once.]
  685. "dirreq-v2-tunneled-dl" key=val,... NL
  686. [At most once.]
  687. "dirreq-v3-tunneled-dl" key=val,... NL
  688. [At most once.]
  689. List of statistics about possible failures in the download process
  690. of v2/v3 network statuses. Requests are either "direct"
  691. HTTP-encoded requests over the relay's directory port, or
  692. "tunneled" requests using a BEGIN_DIR cell over the relay's OR
  693. port. The list of possible statistics can change, and statistics
  694. can be left out from reporting. The current list of statistics is
  695. as follows:
  696. Successful downloads and failures:
  697. "complete": a client has finished the download successfully.
  698. "timeout": a download did not finish within 10 minutes after
  699. starting to send the response.
  700. "running": a download is still running at the end of the
  701. measurement period for less than 10 minutes after starting to
  702. send the response.
  703. Download times:
  704. "min", "max": smallest and largest measured bandwidth in B/s.
  705. "d[1-4,6-9]": 1st to 4th and 6th to 9th decile of measured
  706. bandwidth in B/s. For a given decile i, i/10 of all downloads
  707. had a smaller bandwidth than di, and (10-i)/10 of all downloads
  708. had a larger bandwidth than di.
  709. "q[1,3]": 1st and 3rd quartile of measured bandwidth in B/s. One
  710. fourth of all downloads had a smaller bandwidth than q1, one
  711. fourth of all downloads had a larger bandwidth than q3, and the
  712. remaining half of all downloads had a bandwidth between q1 and
  713. q3.
  714. "md": median of measured bandwidth in B/s. Half of the downloads
  715. had a smaller bandwidth than md, the other half had a larger
  716. bandwidth than md.
  717. "dirreq-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
  718. [At most once]
  719. "dirreq-write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL
  720. [At most once]
  721. Declare how much bandwidth the OR has spent on answering directory
  722. requests. Usage is divided into intervals of NSEC seconds. The
  723. YYYY-MM-DD HH:MM:SS field defines the end of the most recent
  724. interval. The numbers are the number of bytes used in the most
  725. recent intervals, ordered from oldest to newest.
  726. "entry-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  727. [At most once.]
  728. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  729. interval of length NSEC seconds (86400 seconds by default).
  730. An "entry-stats-end" line, as well as any other "entry-*"
  731. line, is first added after the relay has been running for at least
  732. 24 hours.
  733. "entry-ips" CC=N,CC=N,... NL
  734. [At most once.]
  735. List of mappings from two-letter country codes to the number of
  736. unique IP addresses that have connected from that country to the
  737. relay and which are no known other relays, rounded up to the
  738. nearest multiple of 8.
  739. "cell-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  740. [At most once.]
  741. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  742. interval of length NSEC seconds (86400 seconds by default).
  743. A "cell-stats-end" line, as well as any other "cell-*" line,
  744. is first added after the relay has been running for at least 24
  745. hours.
  746. "cell-processed-cells" num,...,num NL
  747. [At most once.]
  748. Mean number of processed cells per circuit, subdivided into
  749. deciles of circuits by the number of cells they have processed in
  750. descending order from loudest to quietest circuits.
  751. "cell-queued-cells" num,...,num NL
  752. [At most once.]
  753. Mean number of cells contained in queues by circuit decile. These
  754. means are calculated by 1) determining the mean number of cells in
  755. a single circuit between its creation and its termination and 2)
  756. calculating the mean for all circuits in a given decile as
  757. determined in "cell-processed-cells". Numbers have a precision of
  758. two decimal places.
  759. Note that this statistic can be inaccurate for circuits that had
  760. queued cells at the start or end of the measurement interval.
  761. "cell-time-in-queue" num,...,num NL
  762. [At most once.]
  763. Mean time cells spend in circuit queues in milliseconds. Times are
  764. calculated by 1) determining the mean time cells spend in the
  765. queue of a single circuit and 2) calculating the mean for all
  766. circuits in a given decile as determined in
  767. "cell-processed-cells".
  768. Note that this statistic can be inaccurate for circuits that had
  769. queued cells at the start or end of the measurement interval.
  770. "cell-circuits-per-decile" num NL
  771. [At most once.]
  772. Mean number of circuits that are included in any of the deciles,
  773. rounded up to the next integer.
  774. "conn-bi-direct" YYYY-MM-DD HH:MM:SS (NSEC s) BELOW,READ,WRITE,BOTH NL
  775. [At most once]
  776. Number of connections, split into 10-second intervals, that are
  777. used uni-directionally or bi-directionally as observed in the NSEC
  778. seconds (usually 86400 seconds) before YYYY-MM-DD HH:MM:SS. Every
  779. 10 seconds, we determine for every connection whether we read and
  780. wrote less than a threshold of 20 KiB (BELOW), read at least 10
  781. times more than we wrote (READ), wrote at least 10 times more than
  782. we read (WRITE), or read and wrote more than the threshold, but
  783. not 10 times more in either direction (BOTH). After classifying a
  784. connection, read and write counters are reset for the next
  785. 10-second interval.
  786. "exit-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  787. [At most once.]
  788. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  789. interval of length NSEC seconds (86400 seconds by default).
  790. An "exit-stats-end" line, as well as any other "exit-*" line, is
  791. first added after the relay has been running for at least 24 hours
  792. and only if the relay permits exiting (where exiting to a single
  793. port and IP address is sufficient).
  794. "exit-kibibytes-written" port=N,port=N,... NL
  795. [At most once.]
  796. "exit-kibibytes-read" port=N,port=N,... NL
  797. [At most once.]
  798. List of mappings from ports to the number of kibibytes that the
  799. relay has written to or read from exit connections to that port,
  800. rounded up to the next full kibibyte. Relays may limit the
  801. number of listed ports and subsume any remaining kibibytes under
  802. port "other".
  803. "exit-streams-opened" port=N,port=N,... NL
  804. [At most once.]
  805. List of mappings from ports to the number of opened exit streams
  806. to that port, rounded up to the nearest multiple of 4. Relays may
  807. limit the number of listed ports and subsume any remaining opened
  808. streams under port "other".
  809. "hidserv-stats-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
  810. [At most once.]
  811. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  812. interval of length NSEC seconds (86400 seconds by default).
  813. A "hidserv-stats-end" line, as well as any other "hidserv-*" line,
  814. is first added after the relay has been running for at least 24
  815. hours.
  816. "hidserv-rend-relayed-cells" SP num SP key=val SP key=val ... NL
  817. [At most once.]
  818. Approximate number of RELAY cells seen in either direction on a
  819. circuit after receiving and successfully processing a RENDEZVOUS1
  820. cell.
  821. The original measurement value is obfuscated in several steps:
  822. first, it is rounded up to the nearest multiple of 'bin_size'
  823. which is reported in the key=val part of this line; second, a
  824. (possibly negative) noise value is added to the result of the
  825. first step by randomly sampling from a Laplace distribution with
  826. mu = 0 and b = (delta_f / epsilon) with 'delta_f' and 'epsilon'
  827. being reported in the key=val part, too; third, the result of the
  828. previous obfuscation steps is truncated to the next smaller
  829. integer and included as 'num'. Note that the overall reported
  830. value can be negative.
  831. "hidserv-dir-onions-seen" SP num SP key=val SP key=val ... NL
  832. [At most once.]
  833. Approximate number of unique hidden-service identities seen in
  834. descriptors published to and accepted by this hidden-service
  835. directory.
  836. The original measurement value is obfuscated in the same way as
  837. the 'num' value reported in "hidserv-rend-relayed-cells", but
  838. possibly with different parameters as reported in the key=val part
  839. of this line. Note that the overall reported value can be
  840. negative.
  841. "transport" transportname address:port [arglist] NL
  842. [Any number.]
  843. Signals that the router supports the 'transportname' pluggable
  844. transport in IP address 'address' and TCP port 'port'. A single
  845. descriptor MUST not have more than one transport line with the
  846. same 'transportname'.
  847. Pluggable transports are only relevant to bridges, but these entries
  848. can appear in non-bridge relays as well.
  849. "padding-counts" YYYY-MM-DD HH:MM:SS (NSEC s) key=val key=val ... NL
  850. [At most once.]
  851. YYYY-MM-DD HH:MM:SS defines the end of the included measurement
  852. interval of length NSEC seconds (86400 seconds by default). Counts
  853. are reset to 0 at the end of this interval.
  854. The keyword list is currently as follows:
  855. bin-size
  856. - The current rounding value for cell count fields (10000 by
  857. default)
  858. write-drop
  859. - The number of RELAY_DROP cells this relay sent
  860. write-pad
  861. - The number of CELL_PADDING cells this relay sent
  862. write-total
  863. - The total number of cells this relay cent
  864. read-drop
  865. - The number of RELAY_DROP cells this relay received
  866. read-pad
  867. - The number of CELL_PADDING cells this relay received
  868. read-total
  869. - The total number of cells this relay received
  870. enabled-read-pad
  871. - The number of CELL_PADDING cells this relay received on
  872. connections that support padding
  873. enabled-read-total
  874. - The total number of cells this relay received on connections
  875. that support padding
  876. enabled-write-pad
  877. - The total number of cells this relay received on connections
  878. that support padding
  879. enabled-write-total
  880. - The total number of cells sent by this relay on connections
  881. that support padding
  882. max-chanpad-timers
  883. - The maximum number of timers that this relay scheduled for
  884. padding in the previous NSEC interval
  885. "router-sig-ed25519"
  886. [As in router descriptors]
  887. "router-signature" NL Signature NL
  888. [At end, exactly once.]
  889. [No extra arguments]
  890. A document signature as documented in section 1.3, using the
  891. initial item "extra-info" and the final item "router-signature",
  892. signed with the router's identity key.
  893. 2.1.2.1. Moving history fields to extra-info documents
  894. Tools that want to use the read-history and write-history values SHOULD
  895. download extra-info documents as well as server descriptors. Such
  896. tools SHOULD accept history values from both sources; if they appear in
  897. both documents, the values in the extra-info documents are authoritative.
  898. New versions of Tor no longer generate server descriptors
  899. containing read-history or write-history. Tools should continue to
  900. accept read-history and write-history values in server descriptors
  901. produced by older versions of Tor until all Tor versions earlier
  902. than 0.2.0.x are obsolete.
  903. 2.1.3. Nonterminals in server descriptors
  904. nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
  905. case-insensitive.
  906. hexdigest ::= a '$', followed by 40 hexadecimal characters
  907. ([A-Fa-f0-9]). [Represents a relay by the digest of its identity
  908. key.]
  909. exitpattern ::= addrspec ":" portspec
  910. portspec ::= "*" | port | port "-" port
  911. port ::= an integer between 1 and 65535, inclusive.
  912. [Some implementations incorrectly generate ports with value 0.
  913. Implementations SHOULD accept this, and SHOULD NOT generate it.
  914. Connections to port 0 are never permitted.]
  915. addrspec ::= "*" | ip4spec | ip6spec
  916. ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
  917. ip4 ::= an IPv4 address in dotted-quad format
  918. ip4mask ::= an IPv4 mask in dotted-quad format
  919. num_ip4_bits ::= an integer between 0 and 32
  920. ip6spec ::= ip6 | ip6 "/" num_ip6_bits
  921. ip6 ::= an IPv6 address, surrounded by square brackets.
  922. num_ip6_bits ::= an integer between 0 and 128
  923. bool ::= "0" | "1"
  924. 3. Directory authority operation and formats
  925. Every authority has two keys used in this protocol: a signing key, and
  926. an authority identity key. (Authorities also have a router identity
  927. key used in their role as a router and by earlier versions of the
  928. directory protocol.) The identity key is used from time to time to
  929. sign new key certificates using new signing keys; it is very sensitive.
  930. The signing key is used to sign key certificates and status documents.
  931. 3.1. Creating key certificates
  932. Key certificates consist of the following items:
  933. "dir-key-certificate-version" version NL
  934. [At start, exactly once.]
  935. Determines the version of the key certificate. MUST be "3" for
  936. the protocol described in this document. Implementations MUST
  937. reject formats they don't understand.
  938. "dir-address" IPPort NL
  939. [At most once]
  940. An IP:Port for this authority's directory port.
  941. "fingerprint" fingerprint NL
  942. [Exactly once.]
  943. Hexadecimal encoding without spaces based on the authority's
  944. identity key.
  945. "dir-identity-key" NL a public key in PEM format
  946. [Exactly once.]
  947. [No extra arguments]
  948. The long-term authority identity key for this authority. This key
  949. SHOULD be at least 2048 bits long; it MUST NOT be shorter than
  950. 1024 bits.
  951. "dir-key-published" YYYY-MM-DD HH:MM:SS NL
  952. [Exactly once.]
  953. The time (in UTC) when this document and corresponding key were
  954. last generated.
  955. "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
  956. [Exactly once.]
  957. A time (in UTC) after which this key is no longer valid.
  958. "dir-signing-key" NL a key in PEM format
  959. [Exactly once.]
  960. [No extra arguments]
  961. The directory server's public signing key. This key MUST be at
  962. least 1024 bits, and MAY be longer.
  963. "dir-key-crosscert" NL CrossSignature NL
  964. [Exactly once.]
  965. [No extra arguments]
  966. CrossSignature is a signature, made using the certificate's signing
  967. key, of the digest of the PKCS1-padded hash of the certificate's
  968. identity key. For backward compatibility with broken versions of the
  969. parser, we wrap the base64-encoded signature in -----BEGIN ID
  970. SIGNATURE---- and -----END ID SIGNATURE----- tags. Implementations
  971. MUST allow the "ID " portion to be omitted, however.
  972. Implementations MUST verify that the signature is a correct signature
  973. of the hash of the identity key using the signing key.
  974. "dir-key-certification" NL Signature NL
  975. [At end, exactly once.]
  976. [No extra arguments]
  977. A document signature as documented in section 1.3, using the
  978. initial item "dir-key-certificate-version" and the final item
  979. "dir-key-certification", signed with the authority identity key.
  980. Authorities MUST generate a new signing key and corresponding
  981. certificate before the key expires.
  982. 3.2. Accepting server descriptor and extra-info document uploads
  983. When a router posts a signed descriptor to a directory authority, the
  984. authority first checks whether it is well-formed and correctly
  985. self-signed. If it is, the authority next verifies that the nickname
  986. in question is not already assigned to a router with a different
  987. public key.
  988. Finally, the authority MAY check that the router is not blacklisted
  989. because of its key, IP, or another reason.
  990. An authority also keeps a record of all the Ed25519/RSA1024
  991. identity key pairs that it has seen before. It rejects any
  992. descriptor that has a known Ed/RSA identity key that it has
  993. already seen accompanied by a different RSA/Ed identity key
  994. in an older descriptor.
  995. At a future date, authorities will begin rejecting all
  996. descriptors whose RSA key was previously accompanied by an
  997. Ed25519 key, if the descriptor does not list an Ed25519 key.
  998. At a future date, authorities will begin rejecting all descriptors
  999. that do not list an Ed25519 key.
  1000. If the descriptor passes these tests, and the authority does not already
  1001. have a descriptor for a router with this public key, it accepts the
  1002. descriptor and remembers it.
  1003. If the authority _does_ have a descriptor with the same public key, the
  1004. newly uploaded descriptor is remembered if its publication time is more
  1005. recent than the most recent old descriptor for that router, and either:
  1006. - There are non-cosmetic differences between the old descriptor and the
  1007. new one.
  1008. - Enough time has passed between the descriptors' publication times.
  1009. (Currently, 12 hours.)
  1010. Differences between server descriptors are "non-cosmetic" if they would be
  1011. sufficient to force an upload as described in section 2.1 above.
  1012. Note that the "cosmetic difference" test only applies to uploaded
  1013. descriptors, not to descriptors that the authority downloads from other
  1014. authorities.
  1015. When a router posts a signed extra-info document to a directory authority,
  1016. the authority again checks it for well-formedness and correct signature,
  1017. and checks that its matches the extra-info-digest in some router
  1018. descriptor that it believes is currently useful. If so, it accepts it and
  1019. stores it and serves it as requested. If not, it drops it.
  1020. 3.3. Computing microdescriptors
  1021. Microdescriptors are a stripped-down version of server descriptors
  1022. generated by the directory authorities which may additionally contain
  1023. authority-generated information. Microdescriptors contain only the
  1024. most relevant parts that clients care about. Microdescriptors are
  1025. expected to be relatively static and only change about once per week.
  1026. Microdescriptors do not contain any information that clients need to
  1027. use to decide which servers to fetch information about, or which
  1028. servers to fetch information from.
  1029. Microdescriptors are a straight transform from the server descriptor
  1030. and the consensus method. Microdescriptors have no header or footer.
  1031. Microdescriptors are identified by the hash of its concatenated
  1032. elements without a signature by the router. Microdescriptors do not
  1033. contain any version information, because their version is determined
  1034. by the consensus method.
  1035. Starting with consensus method 8, microdescriptors contain the
  1036. following elements taken from or based on the server descriptor. Order
  1037. matters here, because different directory authorities must be able to
  1038. transform a given server descriptor and consensus method into the exact
  1039. same microdescriptor.
  1040. "onion-key" NL a public key in PEM format
  1041. [Exactly once, at start]
  1042. [No extra arguments]
  1043. The "onion-key" element as specified in section 2.1.1.
  1044. "ntor-onion-key" SP base-64-encoded-key NL
  1045. [At most once]
  1046. The "ntor-onion-key" element as specified in section 2.1.1.
  1047. (Only included when generating microdescriptors for
  1048. consensus-method 16 or later.)
  1049. "a" SP address ":" port NL
  1050. [Any number]
  1051. The "or-address" element as specified in section 2.1.1.
  1052. "family" names NL
  1053. [At most once]
  1054. The "family" element as specified in section 2.1.1.
  1055. "p" SP ("accept" / "reject") SP PortList NL
  1056. [Exactly once.]
  1057. The exit-policy summary as specified in sections 3.4.1 and 3.8.2.
  1058. [With microdescriptors, clients don't learn exact exit policies:
  1059. clients can only guess whether a relay accepts their request, try the
  1060. BEGIN request, and might get end-reason-exit-policy if they guessed
  1061. wrong, in which case they'll have to try elsewhere.]
  1062. [In consensus methods before 5, this line was omitted.]
  1063. "p6" SP ("accept" / "reject") SP PortList NL
  1064. [At most once]
  1065. The IPv6 exit policy summary as specified in sections 3.4.1 and 3.8.2. A
  1066. missing "p6" line is equivalent to "p6 reject 1-65535".
  1067. (Only included when generating microdescriptors for
  1068. consensus-method 15 or later.)
  1069. "id" SP "rsa1024" SP base64-encoded-identity-digest NL
  1070. [At most once]
  1071. The node identity digest (as described in tor-spec.txt), base64
  1072. encoded, without trailing =s. This line is included to prevent
  1073. collisions between microdescriptors.
  1074. Implementations SHOULD ignore these lines: they are
  1075. added to microdescriptors only to prevent collisions.
  1076. (Only included when generating microdescriptors for
  1077. consensus-method 18 or later.)
  1078. "id" SP "ed25519" SP base64-encoded-ed25519-identity NL
  1079. [At most once]
  1080. The node's master Ed25519 identity key, base64 encoded,
  1081. without trailing =s.
  1082. All implementations MUST ignore this key for any microdescriptor
  1083. whose corresponding entry in the consensus includes the
  1084. 'NoEdConsensus' flag.
  1085. (Only included when generating microdescriptors for
  1086. consensus-method 21 or later.)
  1087. "id" SP keytype ... NL
  1088. [At most once per distinct keytype.]
  1089. Implementations MUST ignore "id" lines with unrecognized
  1090. key-types in place of "rsa1024" or "ed25519"
  1091. "pr" SP Entries NL
  1092. [At most once.]
  1093. The "proto" element as specified in section 2.1.1.
  1094. (Note that with microdescriptors, clients do not learn the RSA identity of
  1095. their routers: they only learn a hash of the RSA identity key. This is
  1096. all they need to confirm the actual identity key when doing a TLS
  1097. handshake, and all they need to put the identity key digest in their
  1098. CREATE cells.)
  1099. 3.4. Exchanging votes
  1100. Authorities divide time into Intervals. Authority administrators SHOULD
  1101. try to all pick the same interval length, and SHOULD pick intervals that
  1102. are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
  1103. minutes, 60 minutes, 90 minutes). Voting intervals SHOULD be chosen to
  1104. divide evenly into a 24-hour day.
  1105. Authorities SHOULD act according to interval and delays in the
  1106. latest consensus. Lacking a latest consensus, they SHOULD default to a
  1107. 30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
  1108. Authorities MUST take pains to ensure that their clocks remain accurate
  1109. within a few seconds. (Running NTP is usually sufficient.)
  1110. The first voting period of each day begins at 00:00 (midnight) UTC. If
  1111. the last period of the day would be truncated by one-half or more, it is
  1112. merged with the second-to-last period.
  1113. An authority SHOULD publish its vote immediately at the start of each voting
  1114. period (minus VoteSeconds+DistSeconds). It does this by making it
  1115. available at
  1116. http://<hostname>/tor/status-vote/next/authority.z
  1117. and sending it in an HTTP POST request to each other authority at the URL
  1118. http://<hostname>/tor/post/vote
  1119. If, at the start of the voting period, minus DistSeconds, an authority
  1120. does not have a current statement from another authority, the first
  1121. authority downloads the other's statement.
  1122. Once an authority has a vote from another authority, it makes it available
  1123. at
  1124. http://<hostname>/tor/status-vote/next/<fp>.z
  1125. where <fp> is the fingerprint of the other authority's identity key.
  1126. And at
  1127. http://<hostname>/tor/status-vote/next/d/<d>.z
  1128. where <d> is the digest of the vote document.
  1129. Also, once an authority receives a vote from another authority, it
  1130. examines it for new descriptors and fetches them from that authority.
  1131. This may be the only way for an authority to hear about relays that didn't
  1132. publish their descriptor to all authorities, and, while it's too late
  1133. for the authority to include relays in its current vote, it can include
  1134. them in its next vote. See section 3.6 below for details.
  1135. 3.4.1. Vote and consensus status document formats
  1136. Votes and consensuses are more strictly formatted than other documents
  1137. in this specification, since different authorities must be able to
  1138. generate exactly the same consensus given the same set of votes.
  1139. The procedure for deciding when to generate vote and consensus status
  1140. documents are described in section 1.4 on the voting timeline.
  1141. Status documents contain a preamble, an authority section, a list of
  1142. router status entries, and one or more footer signature, in that order.
  1143. Unlike other formats described above, a SP in these documents must be a
  1144. single space character (hex 20).
  1145. Some items appear only in votes, and some items appear only in
  1146. consensuses. Unless specified, items occur in both.
  1147. The preamble contains the following items. They SHOULD occur in the
  1148. order given here:
  1149. "network-status-version" SP version NL
  1150. [At start, exactly once.]
  1151. A document format version. For this specification, the version is
  1152. "3".
  1153. "vote-status" SP type NL
  1154. [Exactly once.]
  1155. The status MUST be "vote" or "consensus", depending on the type of
  1156. the document.
  1157. "consensus-methods" SP IntegerList NL
  1158. [At most once for votes; does not occur in consensuses.]
  1159. A space-separated list of supported methods for generating
  1160. consensuses from votes. See section 3.8.1 for details. Absence of
  1161. the line means that only method "1" is supported.
  1162. "consensus-method" SP Integer NL
  1163. [At most once for consensuses; does not occur in votes.]
  1164. [No extra arguments]
  1165. See section 3.8.1 for details.
  1166. (Only included when the vote is generated with consensus-method 2 or
  1167. later.)
  1168. "published" SP YYYY-MM-DD SP HH:MM:SS NL
  1169. [Exactly once for votes; does not occur in consensuses.]
  1170. The publication time for this status document (if a vote).
  1171. "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
  1172. [Exactly once.]
  1173. The start of the Interval for this vote. Before this time, the
  1174. consensus document produced from this vote should not be used.
  1175. See section 1.4 for voting timeline information.
  1176. "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
  1177. [Exactly once.]
  1178. The time at which the next consensus should be produced; before this
  1179. time, there is no point in downloading another consensus, since there
  1180. won't be a new one. See section 1.4 for voting timeline information.
  1181. "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
  1182. [Exactly once.]
  1183. The end of the Interval for this vote. After this time, the
  1184. consensus produced by this vote should not be used. See section 1.4
  1185. for voting timeline information.
  1186. "voting-delay" SP VoteSeconds SP DistSeconds NL
  1187. [Exactly once.]
  1188. VoteSeconds is the number of seconds that we will allow to collect
  1189. votes from all authorities; DistSeconds is the number of seconds
  1190. we'll allow to collect signatures from all authorities. See
  1191. section 1.4 for voting timeline information.
  1192. "client-versions" SP VersionList NL
  1193. [At most once.]
  1194. A comma-separated list of recommended Tor versions for client
  1195. usage, in ascending order. The versions are given as defined by
  1196. version-spec.txt. If absent, no opinion is held about client
  1197. versions.
  1198. "server-versions" SP VersionList NL
  1199. [At most once.]
  1200. A comma-separated list of recommended Tor versions for relay
  1201. usage, in ascending order. The versions are given as defined by
  1202. version-spec.txt. If absent, no opinion is held about server
  1203. versions.
  1204. "package" SP PackageName SP Version SP URL SP DIGESTS NL
  1205. [Any number of times.]
  1206. For this element:
  1207. PACKAGENAME = NONSPACE
  1208. VERSION = NONSPACE
  1209. URL = NONSPACE
  1210. DIGESTS = DIGEST | DIGESTS SP DIGEST
  1211. DIGEST = DIGESTTYPE "=" DIGESTVAL
  1212. NONSPACE = one or more non-space printing characters
  1213. DIGESTVAL = DIGESTTYPE = one or more non-=, non-" " characters.
  1214. Indicates that a package called "package" of version VERSION may be
  1215. found at URL, and its digest as computed with DIGESTTYPE is equal to
  1216. DIGESTVAL. In consensuses, these lines are sorted lexically by
  1217. "PACKAGENAME VERSION" pairs, and DIGESTTYPES must appear in ascending
  1218. order. A consensus must not contain the same "PACKAGENAME VERSION"
  1219. more than once. If a vote contains the same "PACKAGENAME VERSION"
  1220. more than once, all but the last is ignored.
  1221. Included in consensuses only for method 19 and later.
  1222. "known-flags" SP FlagList NL
  1223. [Exactly once.]
  1224. A space-separated list of all of the flags that this document
  1225. might contain. A flag is "known" either because the authority
  1226. knows about them and might set them (if in a vote), or because
  1227. enough votes were counted for the consensus for an authoritative
  1228. opinion to have been formed about their status.
  1229. "flag-thresholds" SP Thresholds NL
  1230. [At most once for votes; does not occur in consensuses.]
  1231. A space-separated list of the internal performance thresholds
  1232. that the directory authority had at the moment it was forming
  1233. a vote.
  1234. The metaformat is:
  1235. Thresholds = Threshold | Threshold SP Thresholds
  1236. Threshold = ThresholdKey '=' ThresholdVal
  1237. ThresholdKey = (KeywordChar | "_") +
  1238. ThresholdVal = [0-9]+("."[0-9]+)? "%"?
  1239. Commonly used Thresholds at this point include:
  1240. "stable-uptime" -- Uptime (in seconds) required for a relay
  1241. to be marked as stable.
  1242. "stable-mtbf" -- MTBF (in seconds) required for a relay to be
  1243. marked as stable.
  1244. "enough-mtbf" -- Whether we have measured enough MTBF to look
  1245. at stable-mtbf instead of stable-uptime.
  1246. "fast-speed" -- Bandwidth (in bytes per second) required for
  1247. a relay to be marked as fast.
  1248. "guard-wfu" -- WFU (in seconds) required for a relay to be
  1249. marked as guard.
  1250. "guard-tk" -- Weighted Time Known (in seconds) required for a
  1251. relay to be marked as guard.
  1252. "guard-bw-inc-exits" -- If exits can be guards, then all guards
  1253. must have a bandwidth this high.
  1254. "guard-bw-exc-exits" -- If exits can't be guards, then all guards
  1255. must have a bandwidth this high.
  1256. "ignoring-advertised-bws" -- 1 if we have enough measured bandwidths
  1257. that we'll ignore the advertised bandwidth
  1258. claims of routers without measured bandwidth.
  1259. "recommended-client-protocols" SP Entries NL
  1260. "recommended-relay-protocols" SP Entries NL
  1261. "required-client-protocols" SP Entries NL
  1262. "required-relay-protocols" SP Entries NL
  1263. [At most once for each.]
  1264. The "proto" element as specified in section 2.1.1.
  1265. To vote on these entries, a protocol/version combination is included
  1266. only if it is listed by a majority of the voters.
  1267. These lines should be voted on. A majority of votes is sufficient to
  1268. make a protocol un-supported. and should require a supermajority of
  1269. authorities (2/3) to make a protocol required. The required protocols
  1270. should not be torrc-configurable, but rather should be hardwired in
  1271. the Tor code.
  1272. The tor-spec.txt section 9 details how a relay and a client should
  1273. behave when they encounter these lines in the consensus.
  1274. "params" SP [Parameters] NL
  1275. [At most once]
  1276. Parameter ::= Keyword '=' Int32
  1277. Int32 ::= A decimal integer between -2147483648 and 2147483647.
  1278. Parameters ::= Parameter | Parameters SP Parameter
  1279. The parameters list, if present, contains a space-separated list of
  1280. case-sensitive key-value pairs, sorted in lexical order by their
  1281. keyword (as ASCII byte strings). Each parameter has its own meaning.
  1282. (Only included when the vote is generated with consensus-method 7 or
  1283. later.)
  1284. Commonly used "param" arguments at this point include:
  1285. "circwindow" -- the default package window that circuits should
  1286. be established with. It started out at 1000 cells, but some
  1287. research indicates that a lower value would mean fewer cells in
  1288. transit in the network at any given time.
  1289. Min: 100, Max: 1000
  1290. First-appeared: Tor 0.2.1.20
  1291. "CircuitPriorityHalflifeMsec" -- the halflife parameter used when
  1292. weighting which circuit will send the next cell. Obeyed by Tor
  1293. 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha
  1294. and 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter,
  1295. but mishandled it badly.)
  1296. Min: -1, Max: 2147483647 (INT32_MAX)
  1297. First-appeared: Tor 0.2.2.11-alpha
  1298. "perconnbwrate" and "perconnbwburst" -- if set, each relay sets
  1299. up a separate token bucket for every client OR connection,
  1300. and rate limits that connection indepedently. Typically left
  1301. unset, except when used for performance experiments around trac
  1302. entry 1750. Only honored by relays running Tor 0.2.2.16-alpha
  1303. and later. (Note that relays running 0.2.2.7-alpha through
  1304. 0.2.2.14-alpha looked for bwconnrate and bwconnburst, but then
  1305. did the wrong thing with them; see bug 1830 for details.)
  1306. Min: 1, Max: 2147483647 (INT32_MAX)
  1307. First-appeared: 0.2.2.7-alpha
  1308. Removed-in: 0.2.2.16-alpha
  1309. "refuseunknownexits" -- if set to one, exit relays look at
  1310. the previous hop of circuits that ask to open an exit stream,
  1311. and refuse to exit if they don't recognize it as a relay. The
  1312. goal is to make it harder for people to use them as one-hop
  1313. proxies. See trac entry 1751 for details.
  1314. Min: 0, Max: 1
  1315. First-appeared: 0.2.2.17-alpha
  1316. "bwweightscale" -- Value that bandwidth-weights are divided by. If not
  1317. present then this defaults to 10000.
  1318. Min: 1
  1319. First-appeared: 0.2.2.10-alpha
  1320. "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts",
  1321. "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq",
  1322. "cbtmintimeout", and "cbtinitialtimeout" -- see "2.4.5. Consensus
  1323. parameters governing behavior" in path-spec.txt for a series of
  1324. circuit build time related consensus params.
  1325. "UseOptimisticData" -- If set to zero, clients by default
  1326. shouldn't try to send optimistic data to servers until they have
  1327. received a RELAY_CONNECTED cell.
  1328. Min: 0, Max: 1, Default: 1
  1329. First-appeared: 0.2.3.3-alpha
  1330. Default was 0 before: 0.2.9.1-alpha
  1331. "maxunmeasuredbw" -- Used by authorities during voting with
  1332. method 17 or later. The maximum value to give for any Bandwidth=
  1333. entry for a router that isn't based on at least three
  1334. measurements.
  1335. First-appeared: 0.2.4.11-alpha
  1336. "Support022HiddenServices" -- Used to implement a mass switch-over
  1337. from sending timestamps to hidden services by default to sending
  1338. no timestamps at all. If this option is absent, or is set to 1,
  1339. clients with the default configuration send timestamps; otherwise,
  1340. they do not.
  1341. Min: 0, Max: 1. Default: 1.
  1342. First-appeared: 0.2.4.18-rc
  1343. "usecreatefast" -- Used to control whether clients use the
  1344. CREATE_FAST handshake on the first hop of their circuits.
  1345. Min: 0, Max: 1. Default: 1.
  1346. First-appeared: 0.2.4.23, 0.2.5.2-alpha
  1347. "pb_mincircs", "pb_noticepct", "pb_warnpct", "pb_extremepct",
  1348. "pb_dropguards", "pb_scalecircs", "pb_scalefactor",
  1349. "pb_multfactor", "pb_minuse", "pb_noticeusepct",
  1350. "pb_extremeusepct", "pb_scaleuse" -- DOCDOC
  1351. "UseNTorHandshake" -- If true, then versions of Tor that support
  1352. NTor will prefer to use it by default.
  1353. Min: 0, Max: 1. Default: 1.
  1354. First-appeared: 0.2.4.8-alpha
  1355. "FastFlagMinThreshold", "FastFlagMaxThreshold" -- lowest and
  1356. highest allowable values for the cutoff for routers that should get
  1357. the Fast flag. This is used during voting to prevent the threshold
  1358. for getting the Fast flag from being too low or too high.
  1359. FastFlagMinThreshold: Min: 4. Max: INT32_MAX: Default: 4.
  1360. FastFlagMaxThreshold: Min: -. Max: INT32_MAX: Default: INT32_MAX
  1361. First-appeared: 0.2.3.11-alpha
  1362. "NumDirectoryGuards", "NumEntryGuards" -- Number of guard nodes
  1363. clients should use by default. If NumDirectoryGuards is 0,
  1364. we default to NumEntryGuards.
  1365. NumDirectoryGuards: Min: 0. Max: 10. Default: 0
  1366. NumEntryGuards: Min: 1. Max: 10. Default: 3
  1367. First-appeared: 0.2.4.23, 0.2.5.6-alpha
  1368. "GuardLifetime" -- Duration for which clients should choose guard
  1369. nodes, in seconds.
  1370. Min: 30 days. Max: 1826 days. Default: 60 days.
  1371. First-appeared: 0.2.4.12-alpha
  1372. "min_paths_for_circs_pct" -- DOCDOC
  1373. "NumNTorsPerTAP" -- When balancing ntor and TAP cells at relays,
  1374. how many ntor handshakes should we perform for each TAP handshake?
  1375. Min: 1. Max: 100000. Default: 10.
  1376. First-appeared: 0.2.4.17-rc
  1377. "AllowNonearlyExtend" -- If true, permit EXTEND cells that are not
  1378. inside RELAY_EARLY cells.
  1379. Min: 0. Max: 1. Default: 0.
  1380. First-appeared: 0.2.3.11-alpha
  1381. "AuthDirNumSRVAgreements" -- Minimum number of agreeing directory
  1382. authority votes required for a fresh shared random value to be written
  1383. in the consensus (this rule only applies on the first commit round of
  1384. the shared randomness protocol).
  1385. Min: 1. Max: INT32_MAX. Default: 2/3 of the total number of dirauth.
  1386. "shared-rand-previous-value" SP NumReveals SP Value NL
  1387. [At most once]
  1388. NumReveals ::= An integer greater or equal to 0.
  1389. Value ::= Base64-encoded-data
  1390. The shared random value that was generated during the second-to-last
  1391. shared randomness protocol run. For example, if this document was
  1392. created on the 5th of November, this field carries the shared random
  1393. value generated during the protocol run of the 3rd of November.
  1394. See section [SRCALC] of srv-spec.txt for instructions on how to compute
  1395. this value, and see section [CONS] for why we include old shared random
  1396. values in votes and consensus.
  1397. Value is the actual shared random value encoded in base64. NumReveals
  1398. is the number of commits used to generate this SRV.
  1399. "shared-rand-current-value" SP NumReveals SP Value NL
  1400. [At most once]
  1401. NumReveals ::= An integer greater or equal to 0.
  1402. Value ::= Base64-encoded-data
  1403. The shared random value that was generated during the latest shared
  1404. randomness protocol run. For example, if this document was created on
  1405. the 5th of November, this field carries the shared random value
  1406. generated during the protocol run of the 4th of November
  1407. See section [SRCALC] of srv-spec.txt for instructions on how to compute
  1408. this value given the active commits.
  1409. Value is the actual shared random value encoded in base64. NumReveals
  1410. is the number of commits used to generate this SRV.
  1411. The authority section of a vote contains the following items, followed
  1412. in turn by the authority's current key certificate:
  1413. "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
  1414. orport NL
  1415. [Exactly once, at start]
  1416. Describes this authority. The nickname is a convenient identifier
  1417. for the authority. The identity is an uppercase hex fingerprint of
  1418. the authority's current (v3 authority) identity key. The address is
  1419. the server's hostname. The IP is the server's current IP address,
  1420. and dirport is its current directory port. The orport is the
  1421. port at that address where the authority listens for OR
  1422. connections.
  1423. "contact" SP string NL
  1424. [Exactly once]
  1425. An arbitrary string describing how to contact the directory
  1426. server's administrator. Administrators should include at least an
  1427. email address and a PGP fingerprint.
  1428. "legacy-dir-key" SP FINGERPRINT NL
  1429. [At most once]
  1430. Lists a fingerprint for an obsolete _identity_ key still used
  1431. by this authority to keep older clients working. This option
  1432. is used to keep key around for a little while in case the
  1433. authorities need to migrate many identity keys at once.
  1434. (Generally, this would only happen because of a security
  1435. vulnerability that affected multiple authorities, like the
  1436. Debian OpenSSL RNG bug of May 2008.)
  1437. "shared-rand-participate" NL
  1438. [At most once]
  1439. Denotes that the directory authority supports and can participate in the
  1440. shared random protocol.
  1441. "shared-rand-commit" SP Version SP AlgName SP Identity SP Commit [SP Reveal] NL
  1442. [Any number of times]
  1443. Version ::= An integer greater or equal to 0.
  1444. AlgName ::= 1*(ALPHA / DIGIT / "_" / "-")
  1445. Identity ::= 40 * HEXDIG
  1446. Commit ::= Base64-encoded-data
  1447. Reveal ::= Base64-encoded-data
  1448. Denotes a directory authority commit for the shared randomness
  1449. protocol, containing the commitment value and potentially also the
  1450. reveal value. See sections [COMMITREVEAL] and [VALIDATEVALUES] of
  1451. srv-spec.txt on how to generate and validate these values.
  1452. Version is the current shared randomness protocol version. AlgName is
  1453. the hash algorithm that is used (e.g. "sha3-256") and Identity is the
  1454. authority's SHA1 v3 identity fingerprint. Commit is the encoded
  1455. commitment value in base64. Reveal is optional and if it's set, it
  1456. contains the reveal value in base64.
  1457. If a vote contains multiple commits from the same authority, the
  1458. receiver MUST only consider the first commit listed.
  1459. "shared-rand-previous-value" SP NumReveals SP Value NL
  1460. [At most once]
  1461. See shared-rand-previous-value description above.
  1462. "shared-rand-current-value" SP NumReveals SP Value NL
  1463. [At most once]
  1464. See shared-rand-current-value decription above.
  1465. The authority section of a consensus contains groups the following items,
  1466. in the order given, with one group for each authority that contributed to
  1467. the consensus, with groups sorted by authority identity digest:
  1468. "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
  1469. orport NL
  1470. [Exactly once, at start]
  1471. As in the authority section of a vote.
  1472. "contact" SP string NL
  1473. [Exactly once.]
  1474. As in the authority section of a vote.
  1475. "vote-digest" SP digest NL
  1476. [Exactly once.]
  1477. A digest of the vote from the authority that contributed to this
  1478. consensus, as signed (that is, not including the signature).
  1479. (Hex, upper-case.)
  1480. For each "legacy-dir-key" in the vote, there is an additional "dir-source"
  1481. line containing that legacy key's fingerprint, the authority's nickname
  1482. with "-legacy" appended, and all other fields as in the main "dir-source"
  1483. line for that authority. These "dir-source" lines do not have
  1484. corresponding "contact" or "vote-digest" entries.
  1485. Each router status entry contains the following items. Router status
  1486. entries are sorted in ascending order by identity digest.
  1487. "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
  1488. SP DirPort NL
  1489. [At start, exactly once.]
  1490. "Nickname" is the OR's nickname. "Identity" is a hash of its
  1491. identity key, encoded in base64, with trailing equals sign(s)
  1492. removed. "Digest" is a hash of its most recent descriptor as
  1493. signed (that is, not including the signature), encoded in base64.
  1494. "Publication" is the
  1495. publication time of its most recent descriptor, in the form
  1496. YYYY-MM-DD HH:MM:SS, in UTC. "IP" is its current IP address;
  1497. ORPort is its current OR port, "DirPort" is its current directory
  1498. port, or "0" for "none".
  1499. "a" SP address ":" port NL
  1500. [Any number.]
  1501. Present only if the OR has at least one IPv6 address.
  1502. Address and portlist are as for "or-address" as specified in
  1503. section 2.1.1.
  1504. (Only included when the vote or consensus is generated with
  1505. consensus-method 14 or later.)
  1506. "s" SP Flags NL
  1507. [Exactly once.]
  1508. A series of space-separated status flags, in lexical order (as ASCII
  1509. byte strings). Currently documented flags are:
  1510. "Authority" if the router is a directory authority.
  1511. "BadExit" if the router is believed to be useless as an exit node
  1512. (because its ISP censors it, because it is behind a restrictive
  1513. proxy, or for some similar reason).
  1514. "Exit" if the router is more useful for building
  1515. general-purpose exit circuits than for relay circuits. The
  1516. path building algorithm uses this flag; see path-spec.txt.
  1517. "Fast" if the router is suitable for high-bandwidth circuits.
  1518. "Guard" if the router is suitable for use as an entry guard.
  1519. "HSDir" if the router is considered a v2 hidden service directory.
  1520. "NoEdConsensus" if any Ed25519 key in the router's descriptor or
  1521. microdesriptor does not reflect authority consensus.
  1522. "Stable" if the router is suitable for long-lived circuits.
  1523. "Running" if the router is currently usable. Relays without this
  1524. flag are omitted from the consensus, and current clients
  1525. (since 0.2.9.4-alpha) assume that every listed relay has
  1526. this flag.
  1527. "Valid" if the router has been 'validated'. Clients before
  1528. 0.2.9.4-alpha would not use routers without this flag by
  1529. default. Currently, relays without this flag are omitted
  1530. fromthe consensus, and current (post-0.2.9.4-alpha) clients
  1531. assume that every listed relay has this flag.
  1532. "V2Dir" if the router implements the v2 directory protocol or
  1533. higher.
  1534. "v" SP version NL
  1535. [At most once.]
  1536. The version of the Tor protocol that this relay is running. If
  1537. the value begins with "Tor" SP, the rest of the string is a Tor
  1538. version number, and the protocol is "The Tor protocol as supported
  1539. by the given version of Tor." Otherwise, if the value begins with
  1540. some other string, Tor has upgraded to a more sophisticated
  1541. protocol versioning system, and the protocol is "a version of the
  1542. Tor protocol more recent than any we recognize."
  1543. Directory authorities SHOULD omit version strings they receive from
  1544. descriptors if they would cause "v" lines to be over 128 characters
  1545. long.
  1546. "pr" SP Entries NL
  1547. [At most once.]
  1548. The "proto" family element as specified in section 2.1.1.
  1549. During voting, authorities copy these lines immediately below the "v"
  1550. lines. When a descriptor does not contain a "proto" entry, the
  1551. authorities should reconstruct it using the approach described below
  1552. in section D. They are included in the consensus using the same rules
  1553. as currently used for "v" lines, if a sufficiently late consensus
  1554. method is in use.
  1555. "w" SP "Bandwidth=" INT [SP "Measured=" INT] [SP "Unmeasured=1"] NL
  1556. [At most once.]
  1557. An estimate of the bandwidth of this relay, in an arbitrary
  1558. unit (currently kilobytes per second). Used to weight router
  1559. selection. See section 3.4.2 for details on how the value of
  1560. Bandwidth is determined in a consensus.
  1561. Additionally, the Measured= keyword is present in votes by
  1562. participating bandwidth measurement authorities to indicate
  1563. a measured bandwidth currently produced by measuring stream
  1564. capacities. It does not occur in consensuses.
  1565. The "Unmeasured=1" value is included in consensuses generated
  1566. with method 17 or later when the 'Bandwidth=' value is not
  1567. based on a threshold of 3 or more measurements for this relay.
  1568. Other weighting keywords may be added later.
  1569. Clients MUST ignore keywords they do not recognize.
  1570. "p" SP ("accept" / "reject") SP PortList NL
  1571. [At most once.]
  1572. PortList = PortOrRange
  1573. PortList = PortList "," PortOrRange
  1574. PortOrRange = INT "-" INT / INT
  1575. A list of those ports that this router supports (if 'accept')
  1576. or does not support (if 'reject') for exit to "most
  1577. addresses".
  1578. "m" SP methods 1*(SP algorithm "=" digest) NL
  1579. [Any number, only in votes.]
  1580. Microdescriptor hashes for all consensus methods that an authority
  1581. supports and that use the same microdescriptor format. "methods"
  1582. is a comma-separated list of the consensus methods that the
  1583. authority believes will produce "digest". "algorithm" is the name
  1584. of the hash algorithm producing "digest", which can be "sha256" or
  1585. something else, depending on the consensus "methods" supporting
  1586. this algorithm. "digest" is the base64 encoding of the hash of
  1587. the router's microdescriptor with trailing =s omitted.
  1588. "id" SP "ed25519" SP ed25519-identity NL
  1589. "id" SP "ed25519" SP "none" NL
  1590. [vote only, at most once]
  1591. The footer section is delineated in all votes and consensuses supporting
  1592. consensus method 9 and above with the following:
  1593. "directory-footer" NL
  1594. [No extra arguments]
  1595. It contains two subsections, a bandwidths-weights line and a
  1596. directory-signature. (Prior to conensus method 9, footers only contained
  1597. directory-signatures without a 'directory-footer' line or
  1598. bandwidth-weights.)
  1599. The bandwidths-weights line appears At Most Once for a consensus. It does
  1600. not appear in votes.
  1601. "bandwidth-weights" [SP Weights] NL
  1602. Weight ::= Keyword '=' Int32
  1603. Int32 ::= A decimal integer between -2147483648 and 2147483647.
  1604. Weights ::= Weight | Weights SP Weight
  1605. List of optional weights to apply to router bandwidths during path
  1606. selection. They are sorted in lexical order (as ASCII byte strings) and
  1607. values are divided by the consensus' "bwweightscale" param. Definition
  1608. of our known entries are...
  1609. Wgg - Weight for Guard-flagged nodes in the guard position
  1610. Wgm - Weight for non-flagged nodes in the guard Position
  1611. Wgd - Weight for Guard+Exit-flagged nodes in the guard Position
  1612. Wmg - Weight for Guard-flagged nodes in the middle Position
  1613. Wmm - Weight for non-flagged nodes in the middle Position
  1614. Wme - Weight for Exit-flagged nodes in the middle Position
  1615. Wmd - Weight for Guard+Exit flagged nodes in the middle Position
  1616. Weg - Weight for Guard flagged nodes in the exit Position
  1617. Wem - Weight for non-flagged nodes in the exit Position
  1618. Wee - Weight for Exit-flagged nodes in the exit Position
  1619. Wed - Weight for Guard+Exit-flagged nodes in the exit Position
  1620. Wgb - Weight for BEGIN_DIR-supporting Guard-flagged nodes
  1621. Wmb - Weight for BEGIN_DIR-supporting non-flagged nodes
  1622. Web - Weight for BEGIN_DIR-supporting Exit-flagged nodes
  1623. Wdb - Weight for BEGIN_DIR-supporting Guard+Exit-flagged nodes
  1624. Wbg - Weight for Guard flagged nodes for BEGIN_DIR requests
  1625. Wbm - Weight for non-flagged nodes for BEGIN_DIR requests
  1626. Wbe - Weight for Exit-flagged nodes for BEGIN_DIR requests
  1627. Wbd - Weight for Guard+Exit-flagged nodes for BEGIN_DIR requests
  1628. These values are calculated as specified in section 3.8.3.
  1629. The signature contains the following item, which appears Exactly Once
  1630. for a vote, and At Least Once for a consensus.
  1631. "directory-signature" [SP Algorithm] SP identity SP signing-key-digest
  1632. NL Signature
  1633. This is a signature of the status document, with the initial item
  1634. "network-status-version", and the signature item
  1635. "directory-signature", using the signing key. (In this case, we take
  1636. the hash through the _space_ after directory-signature, not the
  1637. newline: this ensures that all authorities sign the same thing.)
  1638. "identity" is the hex-encoded digest of the authority identity key of
  1639. the signing authority, and "signing-key-digest" is the hex-encoded
  1640. digest of the current authority signing key of the signing authority.
  1641. The Algorithm is one of "sha1" or "sha256" if it is present;
  1642. implementations MUST ignore directory-signature entries with an
  1643. unrecognized Algorithm. "sha1" is the default, if no Algorithm is
  1644. given. The algorithm describes how to compute the hash of the
  1645. document before signing it.
  1646. "ns"-flavored consensus documents must contain only sha1 signatures.
  1647. Votes and microdescriptor documents may contain other signature
  1648. types. Note that only one signature from each authority should be
  1649. "counted" as meaning that the authority has signed the consensus.
  1650. (Tor clients before 0.2.3.x did not understand the 'algorithm'
  1651. field.)
  1652. 3.4.2. Assigning flags in a vote
  1653. (This section describes how directory authorities choose which status
  1654. flags to apply to routers. Later directory authorities MAY do things
  1655. differently, so long as clients keep working well. Clients MUST NOT
  1656. depend on the exact behaviors in this section.)
  1657. In the below definitions, a router is considered "active" if it is
  1658. running, valid, and not hibernating.
  1659. When we speak of a router's bandwidth in this section, we mean either
  1660. its measured bandwidth, or its advertised bandwidth. If a sufficient
  1661. threshold (configurable with MinMeasuredBWsForAuthToIgnoreAdvertised,
  1662. 500 by default) of routers have measured bandwidth values, then the
  1663. authority bases flags on _measured_ bandwidths, and treats nodes with
  1664. non-measured bandwidths as if their bandwidths were zero. Otherwise,
  1665. it uses measured bandwidths for nodes that have them, and advertised
  1666. bandwidths for other nodes.
  1667. When computing thresholds based on percentiles of nodes, an authority
  1668. only considers nodes that are active, that have not been
  1669. omitted as a sybil (see below), and whose bandwidth is at least
  1670. 4 KB. Nodes that don't meet these criteria do not influence any
  1671. threshold calculations (including calculation of stability and uptime
  1672. and bandwidth thresholds) and also do not have their Exit status
  1673. change.
  1674. "Valid" -- a router is 'Valid' if it is running a version of Tor not
  1675. known to be broken, and the directory authority has not blacklisted
  1676. it as suspicious.
  1677. "Named" --
  1678. "Unnamed" -- Directory authorities no longer assign these flags.
  1679. They were once used to determine whether a relay's nickname was
  1680. canonically linked to its public key.
  1681. "Running" -- A router is 'Running' if the authority managed to connect to
  1682. it successfully within the last 45 minutes.
  1683. "Stable" -- A router is 'Stable' if it is active, and either its Weighted
  1684. MTBF is at least the median for known active routers or its Weighted MTBF
  1685. corresponds to at least 7 days. Routers are never called Stable if they are
  1686. running a version of Tor known to drop circuits stupidly. (0.1.1.10-alpha
  1687. through 0.1.1.16-rc are stupid this way.)
  1688. To calculate weighted MTBF, compute the weighted mean of the lengths
  1689. of all intervals when the router was observed to be up, weighting
  1690. intervals by $\alpha^n$, where $n$ is the amount of time that has
  1691. passed since the interval ended, and $\alpha$ is chosen so that
  1692. measurements over approximately one month old no longer influence the
  1693. weighted MTBF much.
  1694. [XXXX what happens when we have less than 4 days of MTBF info.]
  1695. "Exit" -- A router is called an 'Exit' iff it allows exits to at
  1696. least two of the ports 80, 443, and 6667 and allows exits to at
  1697. least one /8 address space.
  1698. "Fast" -- A router is 'Fast' if it is active, and its bandwidth is either in
  1699. the top 7/8ths for known active routers or at least 100KB/s.
  1700. "Guard" -- A router is a possible Guard if all of the following apply:
  1701. - It is Fast.
  1702. - It is Stable.
  1703. - Its Weighted Fractional Uptime is at least the median for "familiar"
  1704. active routers,
  1705. - It is "familiar",
  1706. - Its bandwidth is at least AuthDirGuardBWGuarantee (if set, 2 MB by
  1707. default), OR its bandwidth is among the 25% fastest relays.
  1708. To calculate weighted fractional uptime, compute the fraction
  1709. of time that the router is up in any given day, weighting so that
  1710. downtime and uptime in the past counts less.
  1711. A node is 'familiar' if 1/8 of all active nodes have appeared more
  1712. recently than it, OR it has been around for a few weeks.
  1713. "Authority" -- A router is called an 'Authority' if the authority
  1714. generating the network-status document believes it is an authority.
  1715. "V2Dir" -- A router supports the v2 directory protocol or higher if it has
  1716. an open directory port OR a tunnelled-dir-server line in its router
  1717. descriptor, and it is running a version of the directory
  1718. protocol that supports the functionality clients need. (Currently, this
  1719. is every supported version of Tor.)
  1720. "HSDir" -- A router is a v2 hidden service directory if it stores and
  1721. serves v2 hidden service descriptors, has the Stable and Fast flag, and the
  1722. authority believes that it's been up for at least 96 hours (or the current
  1723. value of MinUptimeHidServDirectoryV2).
  1724. "NoEdConsensus" -- authorities should not vote on this flag; it is
  1725. produced as part of the consensus for consensus method 22 or later.
  1726. Directory server administrators may label some relays or IPs as
  1727. blacklisted, and elect not to include them in their network-status lists.
  1728. Authorities SHOULD 'disable' any relays in excess of 2 on any single
  1729. IP. When there are more than 2 (or AuthDirMaxServersPerAddr) to
  1730. choose from, authorities should first prefer authorities to
  1731. non-authorities, then prefer Running to non-Running, and then prefer
  1732. high-bandwidth to low-bandwidth[*]. To 'disable' a relay, the
  1733. authority *should* advertise it without the Running or Valid flag.
  1734. [*] In this comparison, measured bandwidth is used unless it is not
  1735. present for a router, in which case advertised bandwidth is used.
  1736. Bug 8710 has a patch to change this behavior.
  1737. Thus, the network-status vote includes all non-blacklisted,
  1738. non-expired, non-superseded descriptors.
  1739. The bandwidth in a "w" line should be taken as the best estimate
  1740. of the router's actual capacity that the authority has. For now,
  1741. this should be the lesser of the observed bandwidth and bandwidth
  1742. rate limit from the server descriptor. It is given in kilobytes
  1743. per second, and capped at some arbitrary value (currently 10 MB/s).
  1744. The Measured= keyword on a "w" line vote is currently computed
  1745. by multiplying the previous published consensus bandwidth by the
  1746. ratio of the measured average node stream capacity to the network
  1747. average. If 3 or more authorities provide a Measured= keyword for
  1748. a router, the authorities produce a consensus containing a "w"
  1749. Bandwidth= keyword equal to the median of the Measured= votes.
  1750. The ports listed in a "p" line should be taken as those ports for
  1751. which the router's exit policy permits 'most' addresses, ignoring any
  1752. accept not for all addresses, ignoring all rejects for private
  1753. netblocks. "Most" addresses are permitted if no more than 2^25
  1754. IPv4 addresses (two /8 networks) were blocked. The list is encoded
  1755. as described in section 3.8.2.
  1756. 3.5. Downloading missing certificates from other directory authorities
  1757. XXX when to download certificates.
  1758. 3.6. Downloading server descriptors from other directory authorities
  1759. Periodically (currently, every 10 seconds), directory authorities check
  1760. whether there are any specific descriptors that they do not have and that
  1761. they are not currently trying to download.
  1762. Authorities identify them by hash in vote (if publication date is more
  1763. recent than the descriptor we currently have).
  1764. [XXXX need a way to fetch descriptors ahead of the vote? v2 status docs can
  1765. do that for now.]
  1766. If so, the directory authority launches requests to the authorities for these
  1767. descriptors, such that each authority is only asked for descriptors listed
  1768. in its most recent vote. If more
  1769. than one authority lists the descriptor, we choose which to ask at random.
  1770. If one of these downloads fails, we do not try to download that descriptor
  1771. from the authority that failed to serve it again unless we receive a newer
  1772. network-status (consensus or vote) from that authority that lists the same
  1773. descriptor.
  1774. Directory authorities must potentially cache multiple descriptors for each
  1775. router. Authorities must not discard any descriptor listed by any recent
  1776. consensus. If there is enough space to store additional descriptors,
  1777. authorities SHOULD try to hold those which clients are likely to download the
  1778. most. (Currently, this is judged based on the interval for which each
  1779. descriptor seemed newest.)
  1780. [XXXX define recent]
  1781. Authorities SHOULD NOT download descriptors for routers that they would
  1782. immediately reject for reasons listed in section 3.2.
  1783. 3.7. Downloading extra-info documents from other directory authorities
  1784. Periodically, an authority checks whether it is missing any extra-info
  1785. documents: in other words, if it has any server descriptors with an
  1786. extra-info-digest field that does not match any of the extra-info
  1787. documents currently held. If so, it downloads whatever extra-info
  1788. documents are missing. We follow the same splitting and back-off rules
  1789. as in section 3.6.
  1790. 3.8. Computing a consensus from a set of votes
  1791. Given a set of votes, authorities compute the contents of the consensus.
  1792. The consensus status, along with as many signatures as the server
  1793. currently knows (see section 3.10 below), should be available at
  1794. http://<hostname>/tor/status-vote/next/consensus.z
  1795. The contents of the consensus document are as follows:
  1796. The "valid-after", "valid-until", and "fresh-until" times are taken as
  1797. the median of the respective values from all the votes.
  1798. The times in the "voting-delay" line are taken as the median of the
  1799. VoteSeconds and DistSeconds times in the votes.
  1800. Known-flags is the union of all flags known by any voter.
  1801. Entries are given on the "params" line for every keyword on which a
  1802. majority of authorities (total authorities, not just those
  1803. participating in this vote) voted on, or if at least three
  1804. authorities voted for that parameter. The values given are the
  1805. low-median of all votes on that keyword.
  1806. Consensus methods 11 and before, entries are given on the "params"
  1807. line for every keyword on which any authority voted, the value given
  1808. being the low-median of all votes on that keyword.
  1809. "client-versions" and "server-versions" are sorted in ascending
  1810. order; A version is recommended in the consensus if it is recommended
  1811. by more than half of the voting authorities that included a
  1812. client-versions or server-versions lines in their votes.
  1813. With consensus method 19 or later, a package line is generated for a
  1814. given PACKAGENAME/VERSION pair if at least three authorities list such a
  1815. package in their votes. (Call these lines the "input" lines for
  1816. PACKAGENAME.) The consensus will contain every "package" line that is
  1817. listed verbatim by more than half of the authorities listing a line for
  1818. the PACKAGENAME/VERSION pair, and no others.
  1819. The authority item groups (dir-source, contact, fingerprint,
  1820. vote-digest) are taken from the votes of the voting
  1821. authorities. These groups are sorted by the digests of the
  1822. authorities identity keys, in ascending order. If the consensus
  1823. method is 3 or later, a dir-source line must be included for
  1824. every vote with legacy-key entry, using the legacy-key's
  1825. fingerprint, the voter's ordinary nickname with the string
  1826. "-legacy" appended, and all other fields as from the original
  1827. vote's dir-source line.
  1828. A router status entry:
  1829. * is included in the result if some router status entry with the same
  1830. identity is included by more than half of the authorities (total
  1831. authorities, not just those whose votes we have).
  1832. (Consensus method earlier than 21)
  1833. * is included according to the rules in section 3.8.0.1 and
  1834. 3.8.0.2 below. (Consensus method 22 or later)
  1835. * For any given RSA identity digest, we include at most
  1836. one router status entry.
  1837. * For any given Ed25519 identity, we include at most one router
  1838. status entry.
  1839. * A router entry has a flag set if that is included by more than half
  1840. of the authorities who care about that flag.
  1841. * Two router entries are "the same" if they have the same
  1842. <descriptor digest, published time, nickname, IP, ports> tuple.
  1843. We choose the tuple for a given router as whichever tuple appears
  1844. for that router in the most votes. We break ties first in favor of
  1845. the more recently published, then in favor of smaller server
  1846. descriptor digest.
  1847. [
  1848. * The Named flag appears if it is included for this routerstatus by
  1849. _any_ authority, and if all authorities that list it list the same
  1850. nickname. However, if consensus-method 2 or later is in use, and
  1851. any authority calls this identity/nickname pair Unnamed, then
  1852. this routerstatus does not get the Named flag.
  1853. * If consensus-method 2 or later is in use, the Unnamed flag is
  1854. set for a routerstatus if any authorities have voted for a different
  1855. identities to be Named with that nickname, or if any authority
  1856. lists that nickname/ID pair as Unnamed.
  1857. (With consensus-method 1, Unnamed is set like any other flag.)
  1858. [But note that authorities no longer vote for the Named flag,
  1859. and the above two bulletpoints are now irrelevant.]
  1860. ]
  1861. * The version is given as whichever version is listed by the most
  1862. voters, with ties decided in favor of more recent versions.
  1863. * If consensus-method 4 or later is in use, then routers that
  1864. do not have the Running flag are not listed at all.
  1865. * If consensus-method 5 or later is in use, then the "w" line
  1866. is generated using a low-median of the bandwidth values from
  1867. the votes that included "w" lines for this router.
  1868. * If consensus-method 5 or later is in use, then the "p" line
  1869. is taken from the votes that have the same policy summary
  1870. for the descriptor we are listing. (They should all be the
  1871. same. If they are not, we pick the most commonly listed
  1872. one, breaking ties in favor of the lexicographically larger
  1873. vote.) The port list is encoded as specified in section 3.8.2.
  1874. * If consensus-method 6 or later is in use and if 3 or more
  1875. authorities provide a Measured= keyword in their votes for
  1876. a router, the authorities produce a consensus containing a
  1877. Bandwidth= keyword equal to the median of the Measured= votes.
  1878. * If consensus-method 7 or later is in use, the params line is
  1879. included in the output.
  1880. * If the consensus method is under 11, bad exits are considered as
  1881. possible exits when computing bandwidth weights. Otherwise, if
  1882. method 11 or later is in use, any router that is determined to get
  1883. the BadExit flag doesn't count when we're calculating weights.
  1884. * If consensus method 12 or later is used, only consensus
  1885. parameters that more than half of the total number of
  1886. authorities voted for are included in the consensus.
  1887. * If consensus method 13 or later is used, microdesc consensuses
  1888. omit any router for which no microdesc was agreed upon.
  1889. * If consensus method 14 or later is used, votes and
  1890. consensuses may include "a" lines listing additional OR
  1891. ports.
  1892. * If consensus method 15 or later is used, microdescriptors
  1893. include "p6" lines including IPv6 exit policies.
  1894. * If consensus method 16 or later is used, ntor-onion-key
  1895. are included in microdescriptors
  1896. * If consensus method 17 or later is used, authorities impose a
  1897. maximum on the Bandwidth= values that they'll put on a 'w'
  1898. line for any router that doesn't have at least 3 measured
  1899. bandwidth values in votes. They also add an "Unmeasured=1"
  1900. flag to such 'w' lines.
  1901. * If consensus method 18 or later is used, authorities include
  1902. "id" lines in microdescriptors.
  1903. * If consensus method 22 or later is used, and the votes do not
  1904. produce a majority consensus about a relay's Ed25519 key (see
  1905. 3.8.0.1 below), the consensus must include a NoEdConsensus flag on
  1906. the "s" line for every relay whose listed Ed key does not reflect
  1907. consensus.
  1908. * If consensus method 23 or later is used, authorities include
  1909. shared randomness protocol data on their votes and consensus.
  1910. * If consensus-method 24 or later is in use, then routers that
  1911. do not have the Valid flag are not listed at all.
  1912. * If consensus-method 25 or later is in use, then we vote
  1913. on recommended-protocols and required-protocols lines in the
  1914. consensus. We also include protocols lines in routerstatus
  1915. entries.
  1916. * If consensus-method 26 or later is in use, then we initialize
  1917. bandwith weights to 1 in our calculations, to avoid
  1918. division-by-zero errors on unusual networks.
  1919. The signatures at the end of a consensus document are sorted in
  1920. ascending order by identity digest.
  1921. All ties in computing medians are broken in favor of the smaller or
  1922. earlier item.
  1923. 3.8.0.1. Deciding which Ids to include.
  1924. This sorting algorithm is used for consensus-method 22 and later.
  1925. First, consider each listing by tuple of <Ed,Rsa> identities, where 'Ed'
  1926. may be "None" if the voter included "id ed25519 none" to indicate that
  1927. the authority knows what ed25519 identities are, and thinks that the RSA
  1928. key doesn't have one.
  1929. For each such <Ed, RSA> tuple that is listed by more than half of the
  1930. total authorities (not just total votes), include it. (It is not
  1931. possible for any other <id-Ed, id-RSA'> to have as many votes.) If more
  1932. than half of the authorities list a single <Ed,Rsa> pair of this type, we
  1933. consider that Ed key to be "consensus"; see description of the
  1934. NoEdConsensus flag.
  1935. Log any other id-RSA values corresponding to an id-Ed we included, and any
  1936. other id-Ed values corresponding to an id-RSA we included.
  1937. For each <id-RSA> that is not yet included, if it is listed by more than
  1938. half of the total authorities, and we do not already have it listed with
  1939. some <id-Ed>, include it, but do not consider its Ed identity canonical.
  1940. 3.8.0.2 Deciding which descriptors to include
  1941. Deciding which descriptors to include.
  1942. A tuple belongs to an <id-RSA, id-Ed> identity if it is a new tuple that
  1943. matches both ID parts, or if it is an old tuple (one with no Ed opinion)
  1944. that matches the RSA part. A tuple belongs to an <id-RSA> identity if its
  1945. RSA identity matches.
  1946. A tuple matches another tuple if all the fields that are present in both
  1947. tuples are the same.
  1948. For every included identity, consider the tuples belonging to that
  1949. identity. Group them into sets of matching tuples. Include the tuple
  1950. that matches the largest set, breaking ties in favor of the most recently
  1951. published, and then in favor of the smaller server descriptor digest.
  1952. 3.8.1. Forward compatibility
  1953. Future versions of Tor will need to include new information in the
  1954. consensus documents, but it is important that all authorities (or at least
  1955. half) generate and sign the same signed consensus.
  1956. To achieve this, authorities list in their votes their supported methods
  1957. for generating consensuses from votes. Later methods will be assigned
  1958. higher numbers. Currently specified methods:
  1959. "1" -- The first implemented version.
  1960. "2" -- Added support for the Unnamed flag.
  1961. "3" -- Added legacy ID key support to aid in authority ID key rollovers
  1962. "4" -- No longer list routers that are not running in the consensus
  1963. "5" -- adds support for "w" and "p" lines.
  1964. "6" -- Prefers measured bandwidth values rather than advertised
  1965. "7" -- Provides keyword=integer pairs of consensus parameters
  1966. "8" -- Provides microdescriptor summaries
  1967. "9" -- Provides weights for selecting flagged routers in paths
  1968. "10" -- Fixes edge case bugs in router flag selection weights
  1969. "11" -- Don't consider BadExits when calculating bandwidth weights
  1970. "12" -- Params are only included if enough auths voted for them
  1971. "13" -- Omit router entries with missing microdescriptors.
  1972. "14" -- Adds support for "a" lines.
  1973. "15" -- Adds support for "p6" lines.
  1974. "16" -- Adds ntor keys to microdescriptors
  1975. "17" -- Adds "Unmeasured=1" flags to "w" lines
  1976. "18" -- Adds 'id' to microdescriptors.
  1977. "19" -- Adds "package" lines to consensuses
  1978. "20" -- Adds GuardFraction information to microdescriptors.
  1979. "21" -- Adds Ed25519 keys to microdescriptors.
  1980. "22" -- Instantiates Ed25519 voting algorithm correctly.
  1981. "23" -- Adds shared randomness protocol data.
  1982. "24" -- No longer lists routers that are not Valid in the consensus.
  1983. "25" -- Vote on recommended-protocols and required-protocols.
  1984. "26" -- Initialize bandwidth weights to 1 to avoid division-by-zero.
  1985. Before generating a consensus, an authority must decide which consensus
  1986. method to use. To do this, it looks for the highest version number
  1987. supported by more than 2/3 of the authorities voting. If it supports this
  1988. method, then it uses it. Otherwise, it falls back to the newest consensus
  1989. method that it supports (which will probably not result in a sufficiently
  1990. signed consensus).
  1991. All authorities MUST support method 13; authorities SHOULD support
  1992. more recent methods as well. Authorities SHOULD NOT support or
  1993. advertise support for any method before 13. Clients MAY assume that
  1994. they will never see a current valid signed consensus for any method
  1995. before method 13.
  1996. (The consensuses generated by new methods must be parsable by
  1997. implementations that only understand the old methods, and must not cause
  1998. those implementations to compromise their anonymity. This is a means for
  1999. making changes in the contents of consensus; not for making
  2000. backward-incompatible changes in their format.)
  2001. The following methods have incorrect implementations; authorities SHOULD
  2002. NOT advertise support for them:
  2003. "21" -- Did not correctly enable support for ed25519 key collation.
  2004. 3.8.2. Encoding port lists
  2005. Whether the summary shows the list of accepted ports or the list of
  2006. rejected ports depends on which list is shorter (has a shorter string
  2007. representation). In case of ties we choose the list of accepted
  2008. ports. As an exception to this rule an allow-all policy is
  2009. represented as "accept 1-65535" instead of "reject " and a reject-all
  2010. policy is similarly given as "reject 1-65535".
  2011. Summary items are compressed, that is instead of "80-88,89-100" there
  2012. only is a single item of "80-100", similarly instead of "20,21" a
  2013. summary will say "20-21".
  2014. Port lists are sorted in ascending order.
  2015. The maximum allowed length of a policy summary (including the "accept "
  2016. or "reject ") is 1000 characters. If a summary exceeds that length we
  2017. use an accept-style summary and list as much of the port list as is
  2018. possible within these 1000 bytes. [XXXX be more specific.]
  2019. 3.8.3. Computing Bandwidth Weights
  2020. Let weight_scale = 10000
  2021. Starting with consensus method 26, G, M, E, and D are initialized to 1 and
  2022. T to 4. Prior consensus methods initialize them all to 0. With this change,
  2023. test tor networks that are small or new are much more likely to produce
  2024. bandwidth-weights in their consensus. The extra bandwidth has a negligible
  2025. impact on the bandwidth weights in the public tor network.
  2026. Let G be the total bandwidth for Guard-flagged nodes.
  2027. Let M be the total bandwidth for non-flagged nodes.
  2028. Let E be the total bandwidth for Exit-flagged nodes.
  2029. Let D be the total bandwidth for Guard+Exit-flagged nodes.
  2030. Let T = G+M+E+D
  2031. Let Wgd be the weight for choosing a Guard+Exit for the guard position.
  2032. Let Wmd be the weight for choosing a Guard+Exit for the middle position.
  2033. Let Wed be the weight for choosing a Guard+Exit for the exit position.
  2034. Let Wme be the weight for choosing an Exit for the middle position.
  2035. Let Wmg be the weight for choosing a Guard for the middle position.
  2036. Let Wgg be the weight for choosing a Guard for the guard position.
  2037. Let Wee be the weight for choosing an Exit for the exit position.
  2038. Balanced network conditions then arise from solutions to the following
  2039. system of equations:
  2040. Wgg*G + Wgd*D == M + Wmd*D + Wme*E + Wmg*G (guard bw = middle bw)
  2041. Wgg*G + Wgd*D == Wee*E + Wed*D (guard bw = exit bw)
  2042. Wed*D + Wmd*D + Wgd*D == D (aka: Wed+Wmd+Wdg = weight_scale)
  2043. Wmg*G + Wgg*G == G (aka: Wgg = weight_scale-Wmg)
  2044. Wme*E + Wee*E == E (aka: Wee = weight_scale-Wme)
  2045. We are short 2 constraints with the above set. The remaining constraints
  2046. come from examining different cases of network load. The following
  2047. constraints are used in consensus method 10 and above. There are another
  2048. incorrect and obsolete set of constraints used for these same cases in
  2049. consensus method 9. For those, see dir-spec.txt in Tor 0.2.2.10-alpha
  2050. to 0.2.2.16-alpha.
  2051. Case 1: E >= T/3 && G >= T/3 (Neither Exit nor Guard Scarce)
  2052. In this case, the additional two constraints are: Wmg == Wmd,
  2053. Wed == 1/3.
  2054. This leads to the solution:
  2055. Wgd = weight_scale/3
  2056. Wed = weight_scale/3
  2057. Wmd = weight_scale/3
  2058. Wee = (weight_scale*(E+G+M))/(3*E)
  2059. Wme = weight_scale - Wee
  2060. Wmg = (weight_scale*(2*G-E-M))/(3*G)
  2061. Wgg = weight_scale - Wmg
  2062. Case 2: E < T/3 && G < T/3 (Both are scarce)
  2063. Let R denote the more scarce class (Rare) between Guard vs Exit.
  2064. Let S denote the less scarce class.
  2065. Subcase a: R+D < S
  2066. In this subcase, we simply devote all of D bandwidth to the
  2067. scarce class.
  2068. Wgg = Wee = weight_scale
  2069. Wmg = Wme = Wmd = 0;
  2070. if E < G:
  2071. Wed = weight_scale
  2072. Wgd = 0
  2073. else:
  2074. Wed = 0
  2075. Wgd = weight_scale
  2076. Subcase b: R+D >= S
  2077. In this case, if M <= T/3, we have enough bandwidth to try to achieve
  2078. a balancing condition.
  2079. Add constraints Wgg = weight_scale, Wmd == Wgd to maximize bandwidth in
  2080. the guard position while still allowing exits to be used as middle nodes:
  2081. Wee = (weight_scale*(E - G + M))/E
  2082. Wed = (weight_scale*(D - 2*E + 4*G - 2*M))/(3*D)
  2083. Wme = (weight_scale*(G-M))/E
  2084. Wmg = 0
  2085. Wgg = weight_scale
  2086. Wmd = (weight_scale - Wed)/2
  2087. Wgd = (weight_scale - Wed)/2
  2088. If this system ends up with any values out of range (ie negative, or
  2089. above weight_scale), use the constraints Wgg == weight_scale and Wee ==
  2090. weight_scale, since both those positions are scarce:
  2091. Wgg = weight_scale
  2092. Wee = weight_scale
  2093. Wed = (weight_scale*(D - 2*E + G + M))/(3*D)
  2094. Wmd = (weight_Scale*(D - 2*M + G + E))/(3*D)
  2095. Wme = 0
  2096. Wmg = 0
  2097. Wgd = weight_scale - Wed - Wmd
  2098. If M > T/3, then the Wmd weight above will become negative. Set it to 0
  2099. in this case:
  2100. Wmd = 0
  2101. Wgd = weight_scale - Wed
  2102. Case 3: One of E < T/3 or G < T/3
  2103. Let S be the scarce class (of E or G).
  2104. Subcase a: (S+D) < T/3:
  2105. if G=S:
  2106. Wgg = Wgd = weight_scale;
  2107. Wmd = Wed = Wmg = 0;
  2108. // Minor subcase, if E is more scarce than M,
  2109. // keep its bandwidth in place.
  2110. if (E < M) Wme = 0;
  2111. else Wme = (weight_scale*(E-M))/(2*E);
  2112. Wee = weight_scale-Wme;
  2113. if E=S:
  2114. Wee = Wed = weight_scale;
  2115. Wmd = Wgd = Wme = 0;
  2116. // Minor subcase, if G is more scarce than M,
  2117. // keep its bandwidth in place.
  2118. if (G < M) Wmg = 0;
  2119. else Wmg = (weight_scale*(G-M))/(2*G);
  2120. Wgg = weight_scale-Wmg;
  2121. Subcase b: (S+D) >= T/3
  2122. if G=S:
  2123. Add constraints Wgg = weight_scale, Wmd == Wed to maximize bandwidth
  2124. in the guard position, while still allowing exits to be
  2125. used as middle nodes:
  2126. Wgg = weight_scale
  2127. Wgd = (weight_scale*(D - 2*G + E + M))/(3*D)
  2128. Wmg = 0
  2129. Wee = (weight_scale*(E+M))/(2*E)
  2130. Wme = weight_scale - Wee
  2131. Wmd = (weight_scale - Wgd)/2
  2132. Wed = (weight_scale - Wgd)/2
  2133. if E=S:
  2134. Add constraints Wee == weight_scale, Wmd == Wgd to maximize bandwidth
  2135. in the exit position:
  2136. Wee = weight_scale;
  2137. Wed = (weight_scale*(D - 2*E + G + M))/(3*D);
  2138. Wme = 0;
  2139. Wgg = (weight_scale*(G+M))/(2*G);
  2140. Wmg = weight_scale - Wgg;
  2141. Wmd = (weight_scale - Wed)/2;
  2142. Wgd = (weight_scale - Wed)/2;
  2143. To ensure consensus, all calculations are performed using integer math
  2144. with a fixed precision determined by the bwweightscale consensus
  2145. parameter (defaults at 10000, Min: 1, Max: INT32_MAX).
  2146. For future balancing improvements, Tor clients support 11 additional weights
  2147. for directory requests and middle weighting. These weights are currently
  2148. set at weight_scale, with the exception of the following groups of
  2149. assignments:
  2150. Directory requests use middle weights:
  2151. Wbd=Wmd, Wbg=Wmg, Wbe=Wme, Wbm=Wmm
  2152. Handle bridges and strange exit policies:
  2153. Wgm=Wgg, Wem=Wee, Weg=Wed
  2154. 3.9. Computing consensus flavors
  2155. Consensus flavors are variants of the consensus that clients can choose
  2156. to download and use instead of the unflavored consensus. The purpose
  2157. of a consensus flavor is to remove or replace information in the
  2158. unflavored consensus without forcing clients to download information
  2159. they would not use anyway.
  2160. Directory authorities can produce and serve an arbitrary number of
  2161. flavors of the same consensus. A downside of creating too many new
  2162. flavors is that clients will be distinguishable based on which flavor
  2163. they download. A new flavor should not be created when adding a field
  2164. instead wouldn't be too onerous.
  2165. Examples for consensus flavors include:
  2166. - Publishing hashes of microdescriptors instead of hashes of
  2167. full descriptors (see section 3.9.2).
  2168. - Including different digests of descriptors, instead of the
  2169. perhaps-soon-to-be-totally-broken SHA1.
  2170. Consensus flavors are derived from the unflavored consensus once the
  2171. voting process is complete. This is to avoid consensus synchronization
  2172. problems.
  2173. Every consensus flavor has a name consisting of a sequence of one
  2174. or more alphanumeric characters and dashes. For compatibility,
  2175. current descriptor flavor is called "ns".
  2176. The supported consensus flavors are defined as part of the
  2177. authorities' consensus method.
  2178. All consensus flavors have in common that their first line is
  2179. "network-status-version" where version is 3 or higher, and the flavor
  2180. is a string consisting of alphanumeric characters and dashes:
  2181. "network-status-version" SP version SP flavor NL
  2182. 3.9.1. ns consensus
  2183. The ns consensus flavor is equivalent to the unflavored consensus
  2184. except for its first line which states its consensus flavor name:
  2185. "network-status-version" SP version SP "ns" NL
  2186. [At start, exactly once.]
  2187. 3.9.2. Microdescriptor consensus
  2188. The microdescriptor consensus is a consensus flavor that contains
  2189. microdescriptor hashes instead of descriptor hashes and that omits
  2190. exit-policy summaries which are contained in microdescriptors. The
  2191. microdescriptor consensus was designed to contain elements that are
  2192. small and frequently changing. Clients use the information in the
  2193. microdescriptor consensus to decide which servers to fetch information
  2194. about and which servers to fetch information from.
  2195. The microdescriptor consensus is based on the unflavored consensus with
  2196. the exceptions as follows:
  2197. "network-status-version" SP version SP "microdesc" NL
  2198. [At start, exactly once.]
  2199. The flavor name of a microdescriptor consensus is "microdesc".
  2200. Changes to router status entries are as follows:
  2201. "r" SP nickname SP identity SP publication SP IP SP ORPort
  2202. SP DirPort NL
  2203. [At start, exactly once.]
  2204. Similar to "r" lines in section 3.4.1, but without the digest element.
  2205. "p" ... NL
  2206. [Zero times.]
  2207. Exit policy summaries are contained in microdescriptors and
  2208. therefore omitted in the microdescriptor consensus.
  2209. "m" SP digest NL
  2210. [Exactly once.*]
  2211. "digest" is the base64 of the SHA256 hash of the router's
  2212. microdescriptor with trailing =s omitted. For a given router
  2213. descriptor digest and consensus method there should only be a
  2214. single microdescriptor digest in the "m" lines of all votes.
  2215. If different votes have different microdescriptor digests for
  2216. the same descriptor digest and consensus method, at least one
  2217. of the authorities is broken. If this happens, the microdesc
  2218. consensus should contain whichever microdescriptor digest is
  2219. most common. If there is no winner, we break ties in the favor
  2220. of the lexically earliest.
  2221. [*Before consensus method 13, this field was sometimes erroneously
  2222. omitted.]
  2223. Additionally, a microdescriptor consensus MAY use the sha256 digest
  2224. algorithm for its signatures.
  2225. 3.10. Exchanging detached signatures
  2226. Once an authority has computed and signed a consensus network status, it
  2227. should send its detached signature to each other authority in an HTTP POST
  2228. request to the URL:
  2229. http://<hostname>/tor/post/consensus-signature
  2230. [XXX Note why we support push-and-then-pull.]
  2231. All of the detached signatures it knows for consensus status should be
  2232. available at:
  2233. http://<hostname>/tor/status-vote/next/consensus-signatures.z
  2234. Assuming full connectivity, every authority should compute and sign the
  2235. same consensus including any flavors in each period. Therefore, it
  2236. isn't necessary to download the consensus or any flavors of it computed
  2237. by each authority; instead, the authorities only push/fetch each
  2238. others' signatures. A "detached signature" document contains items as
  2239. follows:
  2240. "consensus-digest" SP Digest NL
  2241. [At start, at most once.]
  2242. The digest of the consensus being signed.
  2243. "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
  2244. "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
  2245. "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
  2246. [As in the consensus]
  2247. "additional-digest" SP flavor SP algname SP digest NL
  2248. [Any number.]
  2249. For each supported consensus flavor, every directory authority
  2250. adds one or more "additional-digest" lines. "flavor" is the name
  2251. of the consensus flavor, "algname" is the name of the hash
  2252. algorithm that is used to generate the digest, and "digest" is the
  2253. hex-encoded digest.
  2254. The hash algorithm for the microdescriptor consensus flavor is
  2255. defined as SHA256 with algname "sha256".
  2256. "additional-signature" SP flavor SP algname SP identity SP
  2257. signing-key-digest NL signature.
  2258. [Any number.]
  2259. For each supported consensus flavor and defined digest algorithm,
  2260. every directory authority adds an "additional-signature" line.
  2261. "flavor" is the name of the consensus flavor. "algname" is the
  2262. name of the algorithm that was used to hash the identity and
  2263. signing keys, and to compute the signature. "identity" is the
  2264. hex-encoded digest of the authority identity key of the signing
  2265. authority, and "signing-key-digest" is the hex-encoded digest of
  2266. the current authority signing key of the signing authority.
  2267. The "sha256" signature format is defined as the RSA signature of
  2268. the OAEP+-padded SHA256 digest of the item to be signed. When
  2269. checking signatures, the signature MUST be treated as valid if the
  2270. signature material begins with SHA256(document), so that other
  2271. data can get added later.
  2272. [To be honest, I didn't fully understand the previous paragraph
  2273. and only copied it from the proposals. Review carefully. -KL]
  2274. "directory-signature"
  2275. [As in the consensus; the signature object is the same as in the
  2276. consensus document.]
  2277. 3.11. Publishing the signed consensus
  2278. Once there are enough signatures, or once the voting period starts,
  2279. these documents are available at
  2280. http://<hostname>/tor/status-vote/current/consensus.z
  2281. and
  2282. http://<hostname>/tor/status-vote/current/consensus-signatures.z
  2283. [XXX current/consensus-signatures is not currently implemented, as it
  2284. is not used in the voting protocol.]
  2285. [XXX It's actually false that the first document is available as soon
  2286. as there are enough signatures. It's only available as soon as the
  2287. voting period starts. -KL]
  2288. [XXX possible future features include support for downloading old
  2289. consensuses.]
  2290. The other vote documents are analogously made available under
  2291. http://<hostname>/tor/status-vote/current/authority.z
  2292. http://<hostname>/tor/status-vote/current/<fp>.z
  2293. http://<hostname>/tor/status-vote/current/d/<d>.z
  2294. once the consensus is complete.
  2295. The authorities serve another consensus of each flavor "F" from the
  2296. locations
  2297. /tor/status-vote/(current|next)/consensus-F.z. and
  2298. /tor/status-vote/(current|next)/consensus-F/<FP1>+....z.
  2299. 4. Directory cache operation
  2300. All directory caches implement this section, except as noted.
  2301. 4.1. Downloading consensus status documents from directory authorities
  2302. All directory caches try to keep a recent
  2303. network-status consensus document to serve to clients. A cache ALWAYS
  2304. downloads a network-status consensus if any of the following are true:
  2305. - The cache has no consensus document.
  2306. - The cache's consensus document is no longer valid.
  2307. Otherwise, the cache downloads a new consensus document at a randomly
  2308. chosen time in the first half-interval after its current consensus
  2309. stops being fresh. (This time is chosen at random to avoid swarming
  2310. the authorities at the start of each period. The interval size is
  2311. inferred from the difference between the valid-after time and the
  2312. fresh-until time on the consensus.)
  2313. [For example, if a cache has a consensus that became valid at 1:00,
  2314. and is fresh until 2:00, that cache will fetch a new consensus at
  2315. a random time between 2:00 and 2:30.]
  2316. Directory caches also fetch consensus flavors from the authorities.
  2317. Caches check the correctness of consensus flavors, but do not check
  2318. anything about an unrecognized consensus document beyond its digest and
  2319. length. Caches serve all consensus flavors from the same locations as
  2320. the directory authorities.
  2321. 4.2. Downloading server descriptors from directory authorities
  2322. Periodically (currently, every 10 seconds), directory caches check
  2323. whether there are any specific descriptors that they do not have and that
  2324. they are not currently trying to download. Caches identify these
  2325. descriptors by hash in the recent network-status consensus documents.
  2326. If so, the directory cache launches requests to the authorities for these
  2327. descriptors.
  2328. If one of these downloads fails, we do not try to download that descriptor
  2329. from the authority that failed to serve it again unless we receive a newer
  2330. network-status consensus that lists the same descriptor.
  2331. Directory caches must potentially cache multiple descriptors for each
  2332. router. Caches must not discard any descriptor listed by any recent
  2333. consensus. If there is enough space to store additional descriptors,
  2334. caches SHOULD try to hold those which clients are likely to download the
  2335. most. (Currently, this is judged based on the interval for which each
  2336. descriptor seemed newest.)
  2337. [XXXX define recent]
  2338. 4.3. Downloading microdescriptors from directory authorities
  2339. Directory mirrors should fetch, cache, and serve each microdescriptor
  2340. from the authorities.
  2341. The microdescriptors with base64 hashes <D1>,<D2>,<D3> are available
  2342. at:
  2343. http://<hostname>/tor/micro/d/<D1>-<D2>-<D3>[.z]
  2344. <Dn> are base64 encoded with trailing =s omitted for size and for
  2345. consistency with the microdescriptor consensus format. -s are used
  2346. instead of +s to separate items, since the + character is used in
  2347. base64 encoding.
  2348. Directory mirrors should check to make sure that the microdescriptors
  2349. they're about to serve match the right hashes (either the hashes from
  2350. the fetch URL or the hashes from the consensus, respectively).
  2351. (NOTE: Due to squid proxy url limitations at most 92 microdescrriptor hashes
  2352. can be retrieved in a single request.)
  2353. 4.4. Downloading extra-info documents from directory authorities
  2354. Any cache that chooses to cache extra-info documents should implement this
  2355. section.
  2356. Periodically, the Tor instance checks whether it is missing any extra-info
  2357. documents: in other words, if it has any server descriptors with an
  2358. extra-info-digest field that does not match any of the extra-info
  2359. documents currently held. If so, it downloads whatever extra-info
  2360. documents are missing. Caches download from authorities. We follow the
  2361. same splitting and back-off rules as in section 4.2.
  2362. 5. Client operation
  2363. Every Tor that is not a directory server (that is, those that do
  2364. not have a DirPort set) implements this section.
  2365. 5.1. Downloading network-status documents
  2366. Each client maintains a list of directory authorities. Insofar as
  2367. possible, clients SHOULD all use the same list.
  2368. [Newer versions of Tor (0.2.8.1-alpha and later):
  2369. Each client also maintains a list of default fallback directory mirrors
  2370. (fallbacks). Each released version of Tor MAY have a different list,
  2371. depending on the mirrors that satisfy the fallback directory criteria at
  2372. release time.]
  2373. Clients try to have a live consensus network-status document at all times.
  2374. A network-status document is "live" if the time in its valid-until field
  2375. has not passed.
  2376. When a client has no consensus network-status document, it downloads it
  2377. from a randomly chosen fallback directory mirror or authority. Clients
  2378. prefer fallbacks to authorities, trying them earlier and more frequently.
  2379. In all other cases, the client downloads from caches randomly chosen from
  2380. among those believed to be V3 directory servers. (This information comes
  2381. from the network-status documents; see 6 below.)
  2382. After receiving any response client MUST discard any network-status
  2383. documents that it did not request.
  2384. On failure, the client waits briefly, then tries that network-status
  2385. document again from another cache. The client does not build circuits
  2386. until it has a live network-status consensus document, and it has
  2387. descriptors for a significant proportion of the routers that it believes
  2388. are running (this is configurable using torrc options and consensus
  2389. parameters).
  2390. [Newer versions of Tor (0.2.6.2-alpha and later):
  2391. If the consensus contains Exits (the typical case), Tor will build both
  2392. exit and internal circuits. When bootstrap completes, Tor will be ready
  2393. to handle an application requesting an exit circuit to services like the
  2394. World Wide Web.
  2395. If the consensus does not contain Exits, Tor will only build internal
  2396. circuits. In this case, earlier statuses will have included "internal"
  2397. as indicated above. When bootstrap completes, Tor will be ready to handle
  2398. an application requesting an internal circuit to hidden services at
  2399. ".onion" addresses.
  2400. If a future consensus contains Exits, exit circuits may become available.]
  2401. (Note: clients can and should pick caches based on the network-status
  2402. information they have: once they have first fetched network-status info
  2403. from an authority or fallback, they should not need to go to the authority
  2404. directly again, and should only choose the fallback at random, based on its
  2405. consensus weight in the current consensus.)
  2406. To avoid swarming the caches whenever a consensus expires, the
  2407. clients download new consensuses at a randomly chosen time after the
  2408. caches are expected to have a fresh consensus, but before their
  2409. consensus will expire. (This time is chosen uniformly at random from
  2410. the interval between the time 3/4 into the first interval after the
  2411. consensus is no longer fresh, and 7/8 of the time remaining after
  2412. that before the consensus is invalid.)
  2413. [For example, if a client has a consensus that became valid at 1:00,
  2414. and is fresh until 2:00, and expires at 4:00, that client will fetch
  2415. a new consensus at a random time between 2:45 and 3:50, since 3/4
  2416. of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
  2417. minutes is 65 minutes.]
  2418. Clients may choose to download the microdescriptor consensus instead
  2419. of the general network status consensus. In that case they should use
  2420. the same update strategy as for the normal consensus. They should not
  2421. download more than one consensus flavor.
  2422. 5.2. Downloading server descriptors or microdescriptors
  2423. Clients try to have the best descriptor for each router. A descriptor is
  2424. "best" if:
  2425. * It is listed in the consensus network-status document.
  2426. Periodically (currently every 10 seconds) clients check whether there are
  2427. any "downloadable" descriptors. A descriptor is downloadable if:
  2428. - It is the "best" descriptor for some router.
  2429. - The descriptor was published at least 10 minutes in the past.
  2430. (This prevents clients from trying to fetch descriptors that the
  2431. mirrors have probably not yet retrieved and cached.)
  2432. - The client does not currently have it.
  2433. - The client is not currently trying to download it.
  2434. - The client would not discard it immediately upon receiving it.
  2435. - The client thinks it is running and valid (see section 5.4.1 below).
  2436. If at least 16 known routers have downloadable descriptors, or if
  2437. enough time (currently 10 minutes) has passed since the last time the
  2438. client tried to download descriptors, it launches requests for all
  2439. downloadable descriptors.
  2440. When downloading multiple server descriptors, the client chooses multiple
  2441. mirrors so that:
  2442. - At least 3 different mirrors are used, except when this would result
  2443. in more than one request for under 4 descriptors.
  2444. - No more than 128 descriptors are requested from a single mirror.
  2445. - Otherwise, as few mirrors as possible are used.
  2446. After choosing mirrors, the client divides the descriptors among them
  2447. randomly.
  2448. After receiving any response client MUST discard any descriptors that it
  2449. did not request.
  2450. When a descriptor download fails, the client notes it, and does not
  2451. consider the descriptor downloadable again until a certain amount of time
  2452. has passed. (Currently 0 seconds for the first failure, 60 seconds for the
  2453. second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
  2454. thereafter.) Periodically (currently once an hour) clients reset the
  2455. failure count.
  2456. Clients retain the most recent descriptor they have downloaded for each
  2457. router so long as it is not too old (currently, 48 hours), OR so long as
  2458. no better descriptor has been downloaded for the same router.
  2459. [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
  2460. being published too far in the past.] [The code seems to discard
  2461. descriptors in all cases after they're 5 days old. True? -RD]
  2462. Clients which chose to download the microdescriptor consensus instead
  2463. of the general consensus must download the referenced microdescriptors
  2464. instead of server descriptors. Clients fetch and cache
  2465. microdescriptors preemptively from dir mirrors when starting up, like
  2466. they currently fetch descriptors. After bootstrapping, clients only
  2467. need to fetch the microdescriptors that have changed.
  2468. When a client gets a new microdescriptor consensus, it looks to see if
  2469. there are any microdescriptors it needs to learn. If it needs to learn
  2470. more than half of the microdescriptors, it requests 'all', else it
  2471. requests only the missing ones. Clients MAY try to determine whether
  2472. the upload bandwidth for listing the microdescriptors they want is more
  2473. or less than the download bandwidth for the microdescriptors they do
  2474. not want.
  2475. [XXX The 'all' URL is not implemented yet. -KL]
  2476. Clients maintain a cache of microdescriptors along with metadata like
  2477. when it was last referenced by a consensus, and which identity key
  2478. it corresponds to. They keep a microdescriptor until it hasn't been
  2479. mentioned in any consensus for a week. Future clients might cache them
  2480. for longer or shorter times.
  2481. 5.3. Downloading extra-info documents
  2482. Any client that uses extra-info documents should implement this
  2483. section.
  2484. Note that generally, clients don't need extra-info documents.
  2485. Periodically, the Tor instance checks whether it is missing any extra-info
  2486. documents: in other words, if it has any server descriptors with an
  2487. extra-info-digest field that does not match any of the extra-info
  2488. documents currently held. If so, it downloads whatever extra-info
  2489. documents are missing. Clients try to download from caches.
  2490. We follow the same splitting and back-off rules as in section 5.2.
  2491. 5.4. Using directory information
  2492. [XXX This subsection really belongs in path-spec.txt, not here. -KL]
  2493. Everyone besides directory authorities uses the approaches in this section
  2494. to decide which relays to use and what their keys are likely to be.
  2495. (Directory authorities just believe their own opinions, as in section 3.4.2
  2496. above.)
  2497. 5.4.1. Choosing routers for circuits.
  2498. Circuits SHOULD NOT be built until the client has enough directory
  2499. information: a live consensus network status [XXXX fallback?] and
  2500. descriptors for at least 1/4 of the relays believed to be running.
  2501. A relay is "listed" if it is included by the consensus network-status
  2502. document. Clients SHOULD NOT use unlisted relays.
  2503. These flags are used as follows:
  2504. - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
  2505. requested to do so.
  2506. - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
  2507. very-low-bandwidth circuits (such as introduction circuits).
  2508. - Clients SHOULD NOT use non-'Stable' routers for circuits that are
  2509. likely to need to be open for a very long time (such as those used for
  2510. IRC or SSH connections).
  2511. - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
  2512. nodes.
  2513. See the "path-spec.txt" document for more details.
  2514. 5.4.2. Managing naming
  2515. (This section is removed; authorities no longer assign the 'Named' flag.)
  2516. 5.4.3. Software versions
  2517. An implementation of Tor SHOULD warn when it has fetched a consensus
  2518. network-status, and it is running a software version not listed.
  2519. 5.4.4. Warning about a router's status.
  2520. If a router tries to publish its descriptor to a Naming authority
  2521. that has its nickname mapped to another key, the router SHOULD
  2522. warn the operator that it is either using the wrong key or is using
  2523. an already claimed nickname.
  2524. If a router has fetched a consensus document,, and the
  2525. authorities do not publish a binding for the router's nickname, the
  2526. router MAY remind the operator that the chosen nickname is not
  2527. bound to this key at the authorities, and suggest contacting the
  2528. authority operators.
  2529. ...
  2530. 5.4.5. Router protocol versions
  2531. A client should believe that a router supports a given feature if that
  2532. feature is supported by the router or protocol versions in more than half
  2533. of the live networkstatuses' "v" entries for that router. In other words,
  2534. if the "v" entries for some router are:
  2535. v Tor 0.0.8pre1 (from authority 1)
  2536. v Tor 0.1.2.11 (from authority 2)
  2537. v FutureProtocolDescription 99 (from authority 3)
  2538. then the client should believe that the router supports any feature
  2539. supported by 0.1.2.11.
  2540. This is currently equivalent to believing the median declared version for
  2541. a router in all live networkstatuses.
  2542. 6. Standards compliance
  2543. All clients and servers MUST support HTTP 1.0. Clients and servers MAY
  2544. support later versions of HTTP as well.
  2545. 6.1. HTTP headers
  2546. Servers MAY set the Content-Length: header. Servers SHOULD set
  2547. Content-Encoding to "deflate" or "identity".
  2548. Servers MAY include an X-Your-Address-Is: header, whose value is the
  2549. apparent IP address of the client connecting to them (as a dotted quad).
  2550. For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
  2551. report the IP from which the circuit carrying the BEGIN_DIR stream reached
  2552. them.
  2553. Servers SHOULD disable caching of multiple network statuses or multiple
  2554. server descriptors. Servers MAY enable caching of single descriptors,
  2555. single network statuses, the list of all server descriptors, a v1
  2556. directory, or a v1 running routers document. XXX mention times.
  2557. 6.2. HTTP status codes
  2558. Tor delivers the following status codes. Some were chosen without much
  2559. thought; other code SHOULD NOT rely on specific status codes yet.
  2560. 200 -- the operation completed successfully
  2561. -- the user requested statuses or serverdescs, and none of the ones we
  2562. requested were found (0.2.0.4-alpha and earlier).
  2563. 304 -- the client specified an if-modified-since time, and none of the
  2564. requested resources have changed since that time.
  2565. 400 -- the request is malformed, or
  2566. -- the URL is for a malformed variation of one of the URLs we support,
  2567. or
  2568. -- the client tried to post to a non-authority, or
  2569. -- the authority rejected a malformed posted document, or
  2570. 404 -- the requested document was not found.
  2571. -- the user requested statuses or serverdescs, and none of the ones
  2572. requested were found (0.2.0.5-alpha and later).
  2573. 503 -- we are declining the request in order to save bandwidth
  2574. -- user requested some items that we ordinarily generate or store,
  2575. but we do not have any available.
  2576. A. Consensus-negotiation timeline.
  2577. Period begins: this is the Published time.
  2578. Everybody sends votes
  2579. Reconciliation: everybody tries to fetch missing votes.
  2580. consensus may exist at this point.
  2581. End of voting period:
  2582. everyone swaps signatures.
  2583. Now it's okay for caches to download
  2584. Now it's okay for clients to download.
  2585. Valid-after/valid-until switchover
  2586. B. General-use HTTP URLs
  2587. "Fingerprints" in these URLs are base16-encoded SHA1 hashes.
  2588. The most recent v3 consensus should be available at:
  2589. http://<hostname>/tor/status-vote/current/consensus.z
  2590. Similarly, the v3 microdescriptor consensus should be available at:
  2591. http://<hostname>/tor/status-vote/current/consensus-microdesc.z
  2592. Starting with Tor version 0.2.1.1-alpha is also available at:
  2593. http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z
  2594. (NOTE: Due to squid proxy url limitations at most 96 fingerprints can be
  2595. retrieved in a single request.)
  2596. Where F1, F2, etc. are authority identity fingerprints the client trusts.
  2597. Servers will only return a consensus if more than half of the requested
  2598. authorities have signed the document, otherwise a 404 error will be sent
  2599. back. The fingerprints can be shortened to a length of any multiple of
  2600. two, using only the leftmost part of the encoded fingerprint. Tor uses
  2601. 3 bytes (6 hex characters) of the fingerprint.
  2602. Clients SHOULD sort the fingerprints in ascending order. Server MUST
  2603. accept any order.
  2604. Clients SHOULD use this format when requesting consensus documents from
  2605. directory authority servers and from caches running a version of Tor
  2606. that is known to support this URL format.
  2607. A concatenated set of all the current key certificates should be available
  2608. at:
  2609. http://<hostname>/tor/keys/all.z
  2610. The key certificate for this server (if it is an authority) should be
  2611. available at:
  2612. http://<hostname>/tor/keys/authority.z
  2613. The key certificate for an authority whose authority identity fingerprint
  2614. is <F> should be available at:
  2615. http://<hostname>/tor/keys/fp/<F>.z
  2616. The key certificate whose signing key fingerprint is <F> should be
  2617. available at:
  2618. http://<hostname>/tor/keys/sk/<F>.z
  2619. The key certificate whose identity key fingerprint is <F> and whose signing
  2620. key fingerprint is <S> should be available at:
  2621. http://<hostname>/tor/keys/fp-sk/<F>-<S>.z
  2622. (As usual, clients may request multiple certificates using:
  2623. http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z )
  2624. [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]
  2625. The most recent descriptor for a server whose identity key has a
  2626. fingerprint of <F> should be available at:
  2627. http://<hostname>/tor/server/fp/<F>.z
  2628. The most recent descriptors for servers with identity fingerprints
  2629. <F1>,<F2>,<F3> should be available at:
  2630. http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
  2631. (NOTE: Due to squid proxy url limitations at most 96 fingerprints can be
  2632. retrieved in a single request.
  2633. Implementations SHOULD NOT download descriptors by identity key
  2634. fingerprint. This allows a corrupted server (in collusion with a cache) to
  2635. provide a unique descriptor to a client, and thereby partition that client
  2636. from the rest of the network.)
  2637. The server descriptor with (descriptor) digest <D> (in hex) should be
  2638. available at:
  2639. http://<hostname>/tor/server/d/<D>.z
  2640. The most recent descriptors with digests <D1>,<D2>,<D3> should be
  2641. available at:
  2642. http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
  2643. The most recent descriptor for this server should be at:
  2644. http://<hostname>/tor/server/authority.z
  2645. [Nothing in the Tor protocol uses this resource yet, but it is useful
  2646. for debugging purposes. Also, the official Tor implementations
  2647. (starting at 0.1.1.x) use this resource to test whether a server's
  2648. own DirPort is reachable.]
  2649. A concatenated set of the most recent descriptors for all known servers
  2650. should be available at:
  2651. http://<hostname>/tor/server/all.z
  2652. Extra-info documents are available at the URLS
  2653. http://<hostname>/tor/extra/d/...
  2654. http://<hostname>/tor/extra/fp/...
  2655. http://<hostname>/tor/extra/all[.z]
  2656. http://<hostname>/tor/extra/authority[.z]
  2657. (As for /tor/server/ URLs: supports fetching extra-info
  2658. documents by their digest, by the fingerprint of their servers,
  2659. or all at once. When serving by fingerprint, we serve the
  2660. extra-info that corresponds to the descriptor we would serve by
  2661. that fingerprint. Only directory authorities of version
  2662. 0.2.0.1-alpha or later are guaranteed to support the first
  2663. three classes of URLs. Caches may support them, and MUST
  2664. support them if they have advertised "caches-extra-info".)
  2665. For debugging, directories SHOULD expose non-compressed objects at URLs like
  2666. the above, but without the final ".z".
  2667. Clients MUST handle compressed concatenated information in two forms:
  2668. - A concatenated list of zlib-compressed objects.
  2669. - A zlib-compressed concatenated list of objects.
  2670. Directory servers MAY generate either format: the former requires less
  2671. CPU, but the latter requires less bandwidth.
  2672. Clients SHOULD use upper case letters (A-F) when base16-encoding
  2673. fingerprints. Servers MUST accept both upper and lower case fingerprints
  2674. in requests.
  2675. C. Converting a curve25519 public key to an ed25519 public key
  2676. Given a curve25519 x-coordinate (u), we can get the y coordinate
  2677. of the ed25519 key using
  2678. y = (u-1)/(u+1)
  2679. and then we can apply the usual ed25519 point decompression
  2680. algorithm to find the x coordinate of the ed25519 point to check
  2681. signatures with.
  2682. Note that we need the sign of the X coordinate to do this
  2683. operation; otherwise, we'll have two possible X coordinates that
  2684. might have correspond to the key. Therefore, we need the 'sign'
  2685. of the X coordinate, as used by the ed25519 key expansion
  2686. algorithm.
  2687. To get the sign, the easiest way is to take the same private key,
  2688. feed it to the ed25519 public key generation algorithm, and see
  2689. what the sign is.
  2690. D. Inferring missing proto lines.
  2691. The directory authorities no longer allow versions of Tor before
  2692. 0.2.4.18-rc. But right now, there is no version of Tor in the consensus
  2693. before 0.2.4.19. Therefore, we should disallow versions of Tor earlier
  2694. than 0.2.4.19, so that we can have the protocol list for all current Tor
  2695. versions include:
  2696. Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1-2 Link=1-4
  2697. LinkAuth=1 Microdesc=1-2 Relay=1-2
  2698. For Desc, Tor versions before 0.2.7.stable should be taken to have Desc=1
  2699. and versions 0.2.7.stable or later should have Desc=1-2.
  2700. For Microdesc and Cons, Tor versions before 0.2.7.stable should be taken to
  2701. support version 1; 0.2.7.stable and later should have 1-2.