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