control-spec-v0.txt 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498
  1. $Id$
  2. TC: A Tor control protocol (Version 0)
  3. -1. Deprecation
  4. THIS PROTOCOL IS DEPRECATED. It is still documented here because Tor
  5. 0.1.1.x happens to support much of it; but the support for v0 is not
  6. maintained, so you should expect it to rot in unpredictable ways.
  7. 0. Scope
  8. This document describes an implementation-specific protocol that is used
  9. for other programs (such as frontend user-interfaces) to communicate
  10. with a locally running Tor process. It is not part of the Tor onion
  11. routing protocol.
  12. We're trying to be pretty extensible here, but not infinitely
  13. forward-compatible.
  14. 1. Protocol outline
  15. TC is a bidirectional message-based protocol. It assumes an underlying
  16. stream for communication between a controlling process (the "client") and
  17. a Tor process (the "server"). The stream may be implemented via TCP,
  18. TLS-over-TCP, a Unix-domain socket, or so on, but it must provide
  19. reliable in-order delivery. For security, the stream should not be
  20. accessible by untrusted parties.
  21. In TC, the client and server send typed variable-length messages to each
  22. other over the underlying stream. By default, all messages from the server
  23. are in response to messages from the client. Some client requests, however,
  24. will cause the server to send messages to the client indefinitely far into
  25. the future.
  26. Servers respond to messages in the order they're received.
  27. 2. Message format
  28. The messages take the following format:
  29. Length [2 octets; big-endian]
  30. Type [2 octets; big-endian]
  31. Body [Length octets]
  32. Upon encountering a recognized Type, implementations behave as described in
  33. section 3 below. If the type is not recognized, servers respond with an
  34. "ERROR" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore
  35. the message.
  36. 2.1. Types and encodings
  37. All numbers are given in big-endian (network) order.
  38. OR identities are given in hexadecimal, in the same format as identity key
  39. fingerprints, but without spaces; see tor-spec.txt for more information.
  40. 3. Message types
  41. Message types are drawn from the following ranges:
  42. 0x0000-0xEFFF : Reserved for use by official versions of this spec.
  43. 0xF000-0xFFFF : Unallocated; usable by unofficial extensions.
  44. 3.1. ERROR (Type 0x0000)
  45. Sent in response to a message that could not be processed as requested.
  46. The body of the message begins with a 2-byte error code. The following
  47. values are defined:
  48. 0x0000 Unspecified error
  49. []
  50. 0x0001 Internal error
  51. [Something went wrong inside Tor, so that the client's
  52. request couldn't be fulfilled.]
  53. 0x0002 Unrecognized message type
  54. [The client sent a message type we don't understand.]
  55. 0x0003 Syntax error
  56. [The client sent a message body in a format we can't parse.]
  57. 0x0004 Unrecognized configuration key
  58. [The client tried to get or set a configuration option we don't
  59. recognize.]
  60. 0x0005 Invalid configuration value
  61. [The client tried to set a configuration option to an
  62. incorrect, ill-formed, or impossible value.]
  63. 0x0006 Unrecognized byte code
  64. [The client tried to set a byte code (in the body) that
  65. we don't recognize.]
  66. 0x0007 Unauthorized.
  67. [The client tried to send a command that requires
  68. authorization, but it hasn't sent a valid AUTHENTICATE
  69. message.]
  70. 0x0008 Failed authentication attempt
  71. [The client sent a well-formed authorization message.]
  72. 0x0009 Resource exhausted
  73. [The server didn't have enough of a given resource to
  74. fulfill a given request.]
  75. 0x000A No such stream
  76. 0x000B No such circuit
  77. 0x000C No such OR
  78. The rest of the body should be a human-readable description of the error.
  79. In general, new error codes should only be added when they don't fall under
  80. one of the existing error codes.
  81. 3.2. DONE (Type 0x0001)
  82. Sent from server to client in response to a request that was successfully
  83. completed, with no more information needed. The body is usually empty but
  84. may contain a message.
  85. 3.3. SETCONF (Type 0x0002)
  86. Change the value of a configuration variable. The body contains a list of
  87. newline-terminated key-value configuration lines. An individual key-value
  88. configuration line consists of the key, followed by a space, followed by
  89. the value. The server behaves as though it had just read the key-value pair
  90. in its configuration file.
  91. The server responds with a DONE message on success, or an ERROR message on
  92. failure.
  93. When a configuration options takes multiple values, or when multiple
  94. configuration keys form a context-sensitive group (see below), then
  95. setting _any_ of the options in a SETCONF command is taken to reset all of
  96. the others. For example, if two ORBindAddress values are configured,
  97. and a SETCONF command arrives containing a single ORBindAddress value, the
  98. new command's value replaces the two old values.
  99. To _remove_ all settings for a given option entirely (and go back to its
  100. default value), send a single line containing the key and no value.
  101. 3.4. GETCONF (Type 0x0003)
  102. Request the value of a configuration variable. The body contains one or
  103. more NL-terminated strings for configuration keys. The server replies
  104. with a CONFVALUE message.
  105. If an option appears multiple times in the configuration, all of its
  106. key-value pairs are returned in order.
  107. Some options are context-sensitive, and depend on other options with
  108. different keywords. These cannot be fetched directly. Currently there
  109. is only one such option: clients should use the "HiddenServiceOptions"
  110. virtual keyword to get all HiddenServiceDir, HiddenServicePort,
  111. HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
  112. 3.5. CONFVALUE (Type 0x0004)
  113. Sent in response to a GETCONF message; contains a list of "Key Value\n"
  114. (A non-whitespace keyword, a single space, a non-NL value, a NL)
  115. strings.
  116. 3.6. SETEVENTS (Type 0x0005)
  117. Request the server to inform the client about interesting events.
  118. The body contains a list of 2-byte event codes (see "event" below).
  119. Any events *not* listed in the SETEVENTS body are turned off; thus, sending
  120. SETEVENTS with an empty body turns off all event reporting.
  121. The server responds with a DONE message on success, and an ERROR message
  122. if one of the event codes isn't recognized. (On error, the list of active
  123. event codes isn't changed.)
  124. 3.7. EVENT (Type 0x0006)
  125. Sent from the server to the client when an event has occurred and the
  126. client has requested that kind of event. The body contains a 2-byte
  127. event code followed by additional event-dependent information. Event
  128. codes are:
  129. 0x0001 -- Circuit status changed
  130. Status [1 octet]
  131. 0x00 Launched - circuit ID assigned to new circuit
  132. 0x01 Built - all hops finished, can now accept streams
  133. 0x02 Extended - one more hop has been completed
  134. 0x03 Failed - circuit closed (was not built)
  135. 0x04 Closed - circuit closed (was built)
  136. Circuit ID [4 octets]
  137. (Must be unique to Tor process/time)
  138. Path [NUL-terminated comma-separated string]
  139. (For extended/failed, is the portion of the path that is
  140. built)
  141. 0x0002 -- Stream status changed
  142. Status [1 octet]
  143. (Sent connect=0,sent resolve=1,succeeded=2,failed=3,
  144. closed=4, new connection=5, new resolve request=6,
  145. stream detached from circuit and still retriable=7)
  146. Stream ID [4 octets]
  147. (Must be unique to Tor process/time)
  148. Target (NUL-terminated address-port string]
  149. 0x0003 -- OR Connection status changed
  150. Status [1 octet]
  151. (Launched=0,connected=1,failed=2,closed=3)
  152. OR nickname/identity [NUL-terminated]
  153. 0x0004 -- Bandwidth used in the last second
  154. Bytes read [4 octets]
  155. Bytes written [4 octets]
  156. 0x0005 -- Notice/warning/error occurred
  157. Message [NUL-terminated]
  158. <obsolete: use 0x0007-0x000B instead.>
  159. 0x0006 -- New descriptors available
  160. OR List [NUL-terminated, comma-delimited list of
  161. OR identity]
  162. 0x0007 -- Debug message occurred
  163. 0x0008 -- Info message occurred
  164. 0x0009 -- Notice message occurred
  165. 0x000A -- Warning message occurred
  166. 0x000B -- Error message occurred
  167. Message [NUL-terminated]
  168. 3.8. AUTHENTICATE (Type 0x0007)
  169. Sent from the client to the server. Contains a 'magic cookie' to prove
  170. that client is really allowed to control this Tor process. The server
  171. responds with DONE or ERROR.
  172. The format of the 'cookie' is implementation-dependent; see 4.1 below for
  173. information on how the standard Tor implementation handles it.
  174. 3.9. SAVECONF (Type 0x0008)
  175. Sent from the client to the server. Instructs the server to write out
  176. its config options into its torrc. Server returns DONE if successful, or
  177. ERROR if it can't write the file or some other error occurs.
  178. 3.10. SIGNAL (Type 0x0009)
  179. Sent from the client to the server. The body contains one byte that
  180. indicates the action the client wishes the server to take.
  181. 1 (0x01) -- Reload: reload config items, refetch directory.
  182. 2 (0x02) -- Controlled shutdown: if server is an OP, exit immediately.
  183. If it's an OR, close listeners and exit after 30 seconds.
  184. 10 (0x0A) -- Dump stats: log information about open connections and
  185. circuits.
  186. 12 (0x0C) -- Debug: switch all open logs to loglevel debug.
  187. 15 (0x0F) -- Immediate shutdown: clean up and exit now.
  188. The server responds with DONE if the signal is recognized (or simply
  189. closes the socket if it was asked to close immediately), else ERROR.
  190. 3.11. MAPADDRESS (Type 0x000A)
  191. Sent from the client to the server. The body contains a sequence of
  192. address mappings, each consisting of the address to be mapped, a single
  193. space, the replacement address, and a NL character.
  194. Addresses may be IPv4 addresses, IPv6 addresses, or hostnames.
  195. The client sends this message to the server in order to tell it that future
  196. SOCKS requests for connections to the original address should be replaced
  197. with connections to the specified replacement address. If the addresses
  198. are well-formed, and the server is able to fulfill the request, the server
  199. replies with a single DONE message containing the source and destination
  200. addresses. If request is malformed, the server replies with a syntax error
  201. message. The server can't fulfill the request, it replies with an internal
  202. ERROR message.
  203. The client may decline to provide a body for the original address, and
  204. instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
  205. "." for hostname), signifying that the server should choose the original
  206. address itself, and return that address in the DONE message. The server
  207. should ensure that it returns an element of address space that is unlikely
  208. to be in actual use. If there is already an address mapped to the
  209. destination address, the server may reuse that mapping.
  210. If the original address is already mapped to a different address, the old
  211. mapping is removed. If the original address and the destination address
  212. are the same, the server removes any mapping in place for the original
  213. address.
  214. {Note: This feature is designed to be used to help Tor-ify applications
  215. that need to use SOCKS4 or hostname-less SOCKS5. There are three
  216. approaches to doing this:
  217. 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
  218. 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
  219. feature) to resolve the hostname remotely. This doesn't work
  220. with special addresses like x.onion or x.y.exit.
  221. 3. Use MAPADDRESS to map an IP address to the desired hostname, and then
  222. arrange to fool the application into thinking that the hostname
  223. has resolved to that IP.
  224. This functionality is designed to help implement the 3rd approach.}
  225. [XXXX When, if ever, can mappings expire? Should they expire?]
  226. [XXXX What addresses, if any, are safe to use?]
  227. 3.12 GETINFO (Type 0x000B)
  228. Sent from the client to the server. The message body is as for GETCONF:
  229. one or more NL-terminated strings. The server replies with an INFOVALUE
  230. message.
  231. Unlike GETCONF, this message is used for data that are not stored in the
  232. Tor configuration file, but instead.
  233. Recognized key and their values include:
  234. "version" -- The version of the server's software, including the name
  235. of the software. (example: "Tor 0.0.9.4")
  236. "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest server
  237. descriptor for a given OR, NUL-terminated. If no such OR is known, the
  238. corresponding value is an empty string.
  239. "network-status" -- a space-separated list of all known OR identities.
  240. This is in the same format as the router-status line in directories;
  241. see tor-spec.txt for details.
  242. "addr-mappings/all"
  243. "addr-mappings/config"
  244. "addr-mappings/cache"
  245. "addr-mappings/control" -- a NL-terminated list of address mappings, each
  246. in the form of "from-address" SP "to-address". The 'config' key
  247. returns those address mappings set in the configuration; the 'cache'
  248. key returns the mappings in the client-side DNS cache; the 'control'
  249. key returns the mappings set via the control interface; the 'all'
  250. target returns the mappings set through any mechanism.
  251. 3.13 INFOVALUE (Type 0x000C)
  252. Sent from the server to the client in response to a GETINFO message.
  253. Contains one or more items of the format:
  254. Key [(NUL-terminated string)]
  255. Value [(NUL-terminated string)]
  256. The keys match those given in the GETINFO message.
  257. 3.14 EXTENDCIRCUIT (Type 0x000D)
  258. Sent from the client to the server. The message body contains two fields:
  259. Circuit ID [4 octets]
  260. Path [NUL-terminated, comma-delimited string of OR nickname/identity]
  261. This request takes one of two forms: either the Circuit ID is zero, in
  262. which case it is a request for the server to build a new circuit according
  263. to the specified path, or the Circuit ID is nonzero, in which case it is a
  264. request for the server to extend an existing circuit with that ID according
  265. to the specified path.
  266. If the request is successful, the server sends a DONE message containing
  267. a message body consisting of the four-octet Circuit ID of the newly created
  268. circuit.
  269. 3.15 ATTACHSTREAM (Type 0x000E)
  270. Sent from the client to the server. The message body contains two fields:
  271. Stream ID [4 octets]
  272. Circuit ID [4 octets]
  273. This message informs the server that the specified stream should be
  274. associated with the specified circuit. Each stream may be associated with
  275. at most one circuit, and multiple streams may share the same circuit.
  276. Streams can only be attached to completed circuits (that is, circuits that
  277. have sent a circuit status 'built' event).
  278. If the circuit ID is 0, responsibility for attaching the given stream is
  279. returned to Tor.
  280. {Implementation note: By default, Tor automatically attaches streams to
  281. circuits itself, unless the configuration variable
  282. "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
  283. via TC when "__LeaveStreamsUnattached" is false may cause a race between
  284. Tor and the controller, as both attempt to attach streams to circuits.}
  285. 3.16 POSTDESCRIPTOR (Type 0x000F)
  286. Sent from the client to the server. The message body contains one field:
  287. Descriptor [NUL-terminated string]
  288. This message informs the server about a new descriptor.
  289. The descriptor, when parsed, must contain a number of well-specified
  290. fields, including fields for its nickname and identity.
  291. If there is an error in parsing the descriptor, the server must send an
  292. appropriate error message. If the descriptor is well-formed but the server
  293. chooses not to add it, it must reply with a DONE message whose body
  294. explains why the server was not added.
  295. 3.17 FRAGMENTHEADER (Type 0x0010)
  296. Sent in either direction. Used to encapsulate messages longer than 65535
  297. bytes in length.
  298. Underlying type [2 bytes]
  299. Total Length [4 bytes]
  300. Data [Rest of message]
  301. A FRAGMENTHEADER message MUST be followed immediately by a number of
  302. FRAGMENT messages, such that lengths of the "Data" fields of the
  303. FRAGMENTHEADER and FRAGMENT messages add to the "Total Length" field of the
  304. FRAGMENTHEADER message.
  305. Implementations MUST NOT fragment messages of length less than 65536 bytes.
  306. Implementations MUST be able to process fragmented messages that not
  307. optimally packed.
  308. 3.18 FRAGMENT (Type 0x0011)
  309. Data [Entire message]
  310. See FRAGMENTHEADER for more information
  311. 3.19 REDIRECTSTREAM (Type 0x0012)
  312. Sent from the client to the server. The message body contains two fields:
  313. Stream ID [4 octets]
  314. Address [variable-length, NUL-terminated.]
  315. Tells the server to change the exit address on the specified stream. No
  316. remapping is performed on the new provided address.
  317. To be sure that the modified address will be used, this event must be sent
  318. after a new stream event is received, and before attaching this stream to
  319. a circuit.
  320. 3.20 CLOSESTREAM (Type 0x0013)
  321. Sent from the client to the server. The message body contains three
  322. fields:
  323. Stream ID [4 octets]
  324. Reason [1 octet]
  325. Flags [1 octet]
  326. Tells the server to close the specified stream. The reason should be
  327. one of the Tor RELAY_END reasons given in tor-spec.txt. Flags is not
  328. used currently. Tor may hold the stream open for a while to flush
  329. any data that is pending.
  330. 3.21 CLOSECIRCUIT (Type 0x0014)
  331. Sent from the client to the server. The message body contains two
  332. fields:
  333. Circuit ID [4 octets]
  334. Flags [1 octet]
  335. Tells the server to close the specified circuit. If the LSB of the flags
  336. field is nonzero, do not close the circuit unless it is unused.
  337. 4. Implementation notes
  338. 4.1. Authentication
  339. By default, the current Tor implementation trusts all local users.
  340. If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
  341. file named "control_auth_cookie" into its data directory. To authenticate,
  342. the controller must send the contents of this file.
  343. If the 'HashedControlPassword' option is set, it must contain the salted
  344. hash of a secret password. The salted hash is computed according to the
  345. S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
  346. This is then encoded in hexadecimal, prefixed by the indicator sequence
  347. "16:". Thus, for example, the password 'foo' could encode to:
  348. 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
  349. ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  350. salt hashed value
  351. indicator
  352. You can generate the salt of a password by calling
  353. 'tor --hash-password <password>'
  354. or by using the example code in the Python and Java controller libraries.
  355. To authenticate under this scheme, the controller sends Tor the original
  356. secret that was used to generate the password.
  357. 4.2. Don't let the buffer get too big.
  358. If you ask for lots of events, and 16MB of them queue up on the buffer,
  359. the Tor process will close the socket.