control-spec-v0.txt

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