control-spec.txt 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  1. $Id$
  2. TC: A Tor control protocol
  3. 0. Scope
  4. This document describes an implementation-specific protocol that is used
  5. for other programs (such as frontend user-interfaces) to communicate
  6. with a locally running Tor process. It is not part of the Tor onion
  7. routing protocol.
  8. We're trying to be pretty extensible here, but not infinitely
  9. forward-compatible.
  10. 1. Protocol outline
  11. TC is a bidirectional message-based protocol. It assumes an underlying
  12. stream for communication between a controlling process (the "client") and
  13. a Tor process (the "server"). The stream may be implemented via TCP,
  14. TLS-over-TCP, a Unix-domain socket, or so on, but it must provide
  15. reliable in-order delivery. For security, the stream should not be
  16. accessible by untrusted parties.
  17. In TC, the client and server send typed variable-length messages to each
  18. other over the underlying stream. By default, all messages from the server
  19. are in response to messages from the client. Some client requests, however,
  20. will cause the server to send messages to the client indefinitely far into
  21. the future.
  22. Servers respond to messages in the order they're received.
  23. 2. Message format
  24. The messages take the following format:
  25. Length [2 octets; big-endian]
  26. Type [2 octets; big-endian]
  27. Body [Length octets]
  28. Upon encountering a recognized Type, implementations behave as described in
  29. section 3 below. If the type is not recognized, servers respond with a
  30. "STAT" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore
  31. the message.
  32. 3. Message types
  33. 3.1. ERROR (Type 0x0000)
  34. Sent in response to a message that could not be processed as requested.
  35. The body of the message begins with a 2-byte error code. The following
  36. values are defined:
  37. 0x0000 Unspecified error
  38. []
  39. 0x0001 Internal error
  40. [Something went wrong inside Tor, so that the client's
  41. request couldn't be fulfilled.]
  42. 0x0002 Unrecognized message type
  43. [The client sent a message type we don't understand.]
  44. 0x0003 Syntax error
  45. [The client sent a message body in a format we can't parse.]
  46. 0x0004 Unrecognized configuration key
  47. [The client tried to get or set a configuration option we don't
  48. recognize.]
  49. 0x0005 Invalid configuration value
  50. [The client tried to set a configuration option to an
  51. incorrect, ill-formed, or impossible value.]
  52. 0x0006 Unrecognized byte code
  53. [The client tried to set a byte code (in the body) that
  54. we don't recognize.]
  55. 0x0007 Unauthorized.
  56. [The client tried to send a command that requires
  57. authorization, but it hasn't sent a valid AUTHENTICATE message.]
  58. 0x0008 Failed authentication attempt
  59. [The client sent a well-formed authorization message.]
  60. The rest of the body should be a human-readable description of the error.
  61. In general, new error codes should only be added when they don't fall under
  62. one of the existing error codes.
  63. 3.2. DONE (Type 0x0001)
  64. Sent from server to client in response to a request that was successfully
  65. completed, with no more information needed. The body is empty.
  66. 3.3. SETCONF (Type 0x0002)
  67. Change the value of a configuration variable. The body contains a list of
  68. newline-terminated key-value configuration lines.
  69. The server behaves as though it had just read the key-value pair in its
  70. configuration file.
  71. The server responds with a DONE message on success, or an ERROR message on
  72. failure.
  73. When a configuration options takes multiple values, or when multiple
  74. configuration keys form a context-sensitive group (see below), then
  75. setting _any_ of the options in a SETCONF command is taken to reset all of
  76. the others. For example, if two ORBindAddress values are configured,
  77. and a SETCONF command arrives containing a single ORBindAddress value, the
  78. new command's value replaces the two old values.
  79. To _remove_ all settings for a given option entirely (and go back to its
  80. default value), send a single line containing the key and no value.
  81. 3.4. GETCONF (Type 0x0003)
  82. Request the value of a configuration variable. The body contains one or
  83. more NL-terminated strings for configuration keys. The server replies
  84. with a CONFVALUE message.
  85. If an option appears multiple times in the configuration, all of its
  86. key-value pairs are returned in order.
  87. Some options are context-sensitive, and depend on other options with
  88. different keywords. These cannot be fetched directly. Currently there
  89. is only one such option: clients should use the "HiddenServiceOptions"
  90. virtual keyword to get all HiddenServiceDir, HiddenServicePort,
  91. HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
  92. 3.5. CONFVALUE (Type 0x0004)
  93. Sent in response to a GETCONF message; contains a list of "Key Value\n"
  94. (A non-whitespace keyword, a single space, a non-NL value, a NL)
  95. strings.
  96. 3.6. SETEVENTS (Type 0x0005)
  97. Request the server to inform the client about interesting events.
  98. The body contains a list of 2-byte event codes (see "event" below).
  99. Sending SETEVENTS with an empty body turns off all event reporting.
  100. The server responds with a DONE message on success, and an ERROR message
  101. if one of the event codes isn't recognized. (On error, the list of active
  102. event codes isn't changed.)
  103. 3.7. EVENT (Type 0x0006)
  104. Sent from the server to the client when an event has occurred and the
  105. client has requested that kind of event. The body contains a 2-byte
  106. event code followed by additional event-dependent information. Event
  107. codes are:
  108. 0x0001 -- Circuit status changed
  109. Status [1 octet]
  110. (Launched=0,Built=1,Extended=2,Failed=3,Closed=4)
  111. Circuit ID [4 octets]
  112. (Must be unique to Tor process/time)
  113. Path [NUL-terminated comma-separated string]
  114. (For extended/failed, is the portion of the path that is
  115. built)
  116. 0x0002 -- Stream status changed
  117. Status [1 octet]
  118. (Sent connect=0,sent resolve=1,succeeded=2,failed=3,
  119. closed=4)
  120. Stream ID [4 octets]
  121. (Must be unique to Tor process/time)
  122. Target (NUL-terminated address-port string]
  123. 0x0003 -- OR Connection status changed
  124. Status [1 octet]
  125. (Launched=0,connected=1,failed=2,closed=3)
  126. OR nickname/identity [NUL-terminated]
  127. 0x0004 -- Bandwidth used in the last second
  128. Bytes read [4 octets]
  129. Bytes written [4 octets]
  130. 0x0005 -- Notice/warning/error occurred
  131. Message [NUL-terminated]
  132. 3.8. AUTHENTICATE (Type 0x0007)
  133. Sent from the client to the server. Contains a 'magic cookie' to prove
  134. that client is really the admin for this Tor process. The server responds
  135. with DONE or ERROR.
  136. 3.9. SAVECONF (Type 0x0008)
  137. Sent from the client to the server. Instructs the server to write out
  138. its config options into its torrc. Server returns DONE if successful, or
  139. ERROR if it can't write the file or some other error occurs.
  140. 3.10. SIGNAL (Type 0x0009)
  141. Sent from the client to the server. The body contains one byte that
  142. indicates the action the client wishes the server to take.
  143. 0x01 -- Reload: reload config items, refetch directory.
  144. 0x02 -- Controlled shutdown: if server is an OP, exit immediately.
  145. If it's an OR, close listeners and exit after 30 seconds.
  146. 0x10 -- Dump stats: log information about open connections and
  147. circuits.
  148. 0x12 -- Debug: switch all open logs to loglevel debug.
  149. 0x15 -- Immediate shutdown: clean up and exit now.
  150. The server responds with DONE if the signal is recognized (or simply
  151. closes the socket if it was asked to close immediately), else ERROR.
  152. 4. Implementation notes
  153. 4.1. There are four ways we could authenticate, for now:
  154. 1) Listen on 127.0.0.1; trust all local users.
  155. 2) Write a named socket in tor's data-directory or in some other location;
  156. rely on the OS to ensure that only authorized users can open it. (NOTE:
  157. the Linux unix(7) man page suggests that some BSDs don't enforce
  158. authorization.) If the OS has named sockets, and implements
  159. authentication, trust all users who can read Tor's data directory.
  160. 3) Write a random magic cookie to the FS in Tor's data-directory; use that
  161. magic cookie for authentication. Trust all users who can read Tor's data
  162. directory.
  163. 4) Store a salted-and-hashed passphrase in Tor's configuration. Use the
  164. passphrase for authentication. Trust all users who know the passphrase.
  165. On Win32, our only options are 1, 3, and 4. Since the semantics for 2
  166. and 3 are so similar, we chose to not support 2, and just always bind
  167. on 127.0.0.1. We've implemented 1, 3, and 4.
  168. By default, the Tor client accepts authentication approach #1. If
  169. the controller wants Tor to demand more authentication, it should use
  170. setconf and saveconf to configure Tor to demand more next time.
  171. 4.2. Don't let the buffer get too big.
  172. If you ask for lots of events, and 16MB of them queue up on the buffer,
  173. the Tor process will close the socket.