doc/control-spec.txt

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