dir-spec-v1.txt 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. $Id$
  2. Tor Protocol Specification
  3. Roger Dingledine
  4. Nick Mathewson
  5. 0. Prelimaries
  6. THIS SPECIFICATION IS OBSOLETE.
  7. This document specifies the Tor directory protocol as used in version
  8. 0.1.0.x and earlier. See dir-spec.txt for a current version.
  9. 1. Basic operation
  10. There is a small number of directory authorities, and a larger number of
  11. caches. Client and servers know public keys for the directory authorities.
  12. Tor servers periodically upload self-signed "router descriptors" to the
  13. directory authorities. Each authority publishes a self-signed "directory"
  14. (containing all the router descriptors it knows, and a statement on which
  15. are running) and a self-signed "running routers" document containing only
  16. the statement on which routers are running.
  17. All Tors periodically download these documents, downloading the directory
  18. less frequently than they do the "running routers" document. Clients
  19. preferentially download from caches rather than authorities.
  20. 1.1. Document format
  21. Router descriptors, directories, and running-routers documents all obey the
  22. following lightweight extensible information format.
  23. The highest level object is a Document, which consists of one or more
  24. Items. Every Item begins with a KeywordLine, followed by one or more
  25. Objects. A KeywordLine begins with a Keyword, optionally followed by
  26. whitespace and more non-newline characters, and ends with a newline. A
  27. Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  28. An Object is a block of encoded data in pseudo-Open-PGP-style
  29. armor. (cf. RFC 2440)
  30. More formally:
  31. Document ::= (Item | NL)+
  32. Item ::= KeywordLine Object*
  33. KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
  34. Keyword = KeywordChar+
  35. KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  36. ArgumentChar ::= any printing ASCII character except NL.
  37. WS = (SP | TAB)+
  38. Object ::= BeginLine Base-64-encoded-data EndLine
  39. BeginLine ::= "-----BEGIN " Keyword "-----" NL
  40. EndLine ::= "-----END " Keyword "-----" NL
  41. The BeginLine and EndLine of an Object must use the same keyword.
  42. When interpreting a Document, software MUST reject any document containing a
  43. KeywordLine that starts with a keyword it doesn't recognize.
  44. The "opt" keyword is reserved for non-critical future extensions. All
  45. implementations MUST ignore any item of the form "opt keyword ....." when
  46. they would not recognize "keyword ....."; and MUST treat "opt keyword ....."
  47. as synonymous with "keyword ......" when keyword is recognized.
  48. 2. Router descriptor format.
  49. Every router descriptor MUST start with a "router" Item; MUST end with a
  50. "router-signature" Item and an extra NL; and MUST contain exactly one
  51. instance of each of the following Items: "published" "onion-key" "link-key"
  52. "signing-key" "bandwidth". Additionally, a router descriptor MAY contain
  53. any number of "accept", "reject", "fingerprint", "uptime", and "opt" Items.
  54. Other than "router" and "router-signature", the items may appear in any
  55. order.
  56. The items' formats are as follows:
  57. "router" nickname address ORPort SocksPort DirPort
  58. Indicates the beginning of a router descriptor. "address"
  59. must be an IPv4 address in dotted-quad format. The last
  60. three numbers indicate the TCP ports at which this OR exposes
  61. functionality. ORPort is a port at which this OR accepts TLS
  62. connections for the main OR protocol; SocksPort is deprecated and
  63. should always be 0; and DirPort is the port at which this OR accepts
  64. directory-related HTTP connections. If any port is not supported,
  65. the value 0 is given instead of a port number.
  66. "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed
  67. Estimated bandwidth for this router, in bytes per second. The
  68. "average" bandwidth is the volume per second that the OR is willing
  69. to sustain over long periods; the "burst" bandwidth is the volume
  70. that the OR is willing to sustain in very short intervals. The
  71. "observed" value is an estimate of the capacity this server can
  72. handle. The server remembers the max bandwidth sustained output
  73. over any ten second period in the past day, and another sustained
  74. input. The "observed" value is the lesser of these two numbers.
  75. "platform" string
  76. A human-readable string describing the system on which this OR is
  77. running. This MAY include the operating system, and SHOULD include
  78. the name and version of the software implementing the Tor protocol.
  79. "published" YYYY-MM-DD HH:MM:SS
  80. The time, in GMT, when this descriptor was generated.
  81. "fingerprint"
  82. A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded
  83. in hex, with a single space after every 4 characters) for this router's
  84. identity key. A descriptor is considered invalid (and MUST be
  85. rejected) if the fingerprint line does not match the public key.
  86. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  87. be marked with "opt" until earlier versions of Tor are obsolete.]
  88. "hibernating" 0|1
  89. If the value is 1, then the Tor server was hibernating when the
  90. descriptor was published, and shouldn't be used to build circuits.
  91. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  92. be marked with "opt" until earlier versions of Tor are obsolete.]
  93. "uptime"
  94. The number of seconds that this OR process has been running.
  95. "onion-key" NL a public key in PEM format
  96. This key is used to encrypt EXTEND cells for this OR. The key MUST
  97. be accepted for at least XXXX hours after any new key is published in
  98. a subsequent descriptor.
  99. "signing-key" NL a public key in PEM format
  100. The OR's long-term identity key.
  101. "accept" exitpattern
  102. "reject" exitpattern
  103. These lines, in order, describe the rules that an OR follows when
  104. deciding whether to allow a new stream to a given address. The
  105. 'exitpattern' syntax is described below.
  106. "router-signature" NL Signature NL
  107. The "SIGNATURE" object contains a signature of the PKCS1-padded
  108. hash of the entire router descriptor, taken from the beginning of the
  109. "router" line, through the newline after the "router-signature" line.
  110. The router descriptor is invalid unless the signature is performed
  111. with the router's identity key.
  112. "contact" info NL
  113. Describes a way to contact the server's administrator, preferably
  114. including an email address and a PGP key fingerprint.
  115. "family" names NL
  116. 'Names' is a whitespace-separated list of server nicknames. If two ORs
  117. list one another in their "family" entries, then OPs should treat them
  118. as a single OR for the purpose of path selection.
  119. For example, if node A's descriptor contains "family B", and node B's
  120. descriptor contains "family A", then node A and node B should never
  121. be used on the same circuit.
  122. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  123. "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  124. Declare how much bandwidth the OR has used recently. Usage is divided
  125. into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field defines
  126. the end of the most recent interval. The numbers are the number of
  127. bytes used in the most recent intervals, ordered from oldest to newest.
  128. [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
  129. be marked with "opt" until earlier versions of Tor are obsolete.]
  130. 2.1. Nonterminals in routerdescriptors
  131. nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
  132. exitpattern ::= addrspec ":" portspec
  133. portspec ::= "*" | port | port "-" port
  134. port ::= an integer between 1 and 65535, inclusive.
  135. addrspec ::= "*" | ip4spec | ip6spec
  136. ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
  137. ip4 ::= an IPv4 address in dotted-quad format
  138. ip4mask ::= an IPv4 mask in dotted-quad format
  139. num_ip4_bits ::= an integer between 0 and 32
  140. ip6spec ::= ip6 | ip6 "/" num_ip6_bits
  141. ip6 ::= an IPv6 address, surrounded by square brackets.
  142. num_ip6_bits ::= an integer between 0 and 128
  143. Ports are required; if they are not included in the router
  144. line, they must appear in the "ports" lines.
  145. 3. Directory format
  146. A Directory begins with a "signed-directory" item, followed by one each of
  147. the following, in any order: "recommended-software", "published",
  148. "router-status", "dir-signing-key". It may include any number of "opt"
  149. items. After these items, a directory includes any number of router
  150. descriptors, and a single "directory-signature" item.
  151. "signed-directory"
  152. Indicates the start of a directory.
  153. "published" YYYY-MM-DD HH:MM:SS
  154. The time at which this directory was generated and signed, in GMT.
  155. "dir-signing-key"
  156. The key used to sign this directory; see "signing-key" for format.
  157. "recommended-software" comma-separated-version-list
  158. A list of which versions of which implementations are currently
  159. believed to be secure and compatible with the network.
  160. "running-routers" whitespace-separated-list
  161. A description of which routers are currently believed to be up or
  162. down. Every entry consists of an optional "!", followed by either an
  163. OR's nickname, or "$" followed by a hexadecimal encoding of the hash
  164. of an OR's identity key. If the "!" is included, the router is
  165. believed not to be running; otherwise, it is believed to be running.
  166. If a router's nickname is given, exactly one router of that nickname
  167. will appear in the directory, and that router is "approved" by the
  168. directory server. If a hashed identity key is given, that OR is not
  169. "approved". [XXXX The 'running-routers' line is only provided for
  170. backward compatibility. New code should parse 'router-status'
  171. instead.]
  172. "router-status" whitespace-separated-list
  173. A description of which routers are currently believed to be up or
  174. down, and which are verified or unverified. Contains one entry for
  175. every router that the directory server knows. Each entry is of the
  176. format:
  177. !name=$digest [Verified router, currently not live.]
  178. name=$digest [Verified router, currently live.]
  179. !$digest [Unverified router, currently not live.]
  180. or $digest [Unverified router, currently live.]
  181. (where 'name' is the router's nickname and 'digest' is a hexadecimal
  182. encoding of the hash of the routers' identity key).
  183. When parsing this line, clients should only mark a router as
  184. 'verified' if its nickname AND digest match the one provided.
  185. "directory-signature" nickname-of-dirserver NL Signature
  186. The signature is computed by computing the digest of the
  187. directory, from the characters "signed-directory", through the newline
  188. after "directory-signature". This digest is then padded with PKCS.1,
  189. and signed with the directory server's signing key.
  190. If software encounters an unrecognized keyword in a single router descriptor,
  191. it MUST reject only that router descriptor, and continue using the
  192. others. Because this mechanism is used to add 'critical' extensions to
  193. future versions of the router descriptor format, implementation should treat
  194. it as a normal occurrence and not, for example, report it to the user as an
  195. error. [Versions of Tor prior to 0.1.1 did this.]
  196. If software encounters an unrecognized keyword in the directory header,
  197. it SHOULD reject the entire directory.
  198. 4. Network-status descriptor
  199. A "network-status" (a.k.a "running-routers") document is a truncated
  200. directory that contains only the current status of a list of nodes, not
  201. their actual descriptors. It contains exactly one of each of the following
  202. entries.
  203. "network-status"
  204. Must appear first.
  205. "published" YYYY-MM-DD HH:MM:SS
  206. (see section 3 above)
  207. "router-status" list
  208. (see section 3 above)
  209. "directory-signature" NL signature
  210. (see section 3 above)
  211. 5. Behavior of a directory server
  212. lists nodes that are connected currently
  213. speaks HTTP on a socket, spits out directory on request
  214. Directory servers listen on a certain port (the DirPort), and speak a
  215. limited version of HTTP 1.0. Clients send either GET or POST commands.
  216. The basic interactions are:
  217. "%s %s HTTP/1.0\r\nContent-Length: %lu\r\nHost: %s\r\n\r\n",
  218. command, url, content-length, host.
  219. Get "/tor/" to fetch a full directory.
  220. Get "/tor/dir.z" to fetch a compressed full directory.
  221. Get "/tor/running-routers" to fetch a network-status descriptor.
  222. Post "/tor/" to post a server descriptor, with the body of the
  223. request containing the descriptor.
  224. "host" is used to specify the address:port of the dirserver, so
  225. the request can survive going through HTTP proxies.