$Id: control-spec-v0.txt 9411 2007-01-26 01:59:50Z nickm $ TC: A Tor control protocol (Version 0) -1. Deprecation THIS PROTOCOL IS DEPRECATED. It is still documented here because Tor 0.1.1.x happens to support much of it; but the support for v0 is not maintained, so you should expect it to rot in unpredictable ways. Support for v0 will be removed some time after Tor 0.1.2. 0. Scope This document describes an implementation-specific protocol that is used for other programs (such as frontend user-interfaces) to communicate with a locally running Tor process. It is not part of the Tor onion routing protocol. We're trying to be pretty extensible here, but not infinitely forward-compatible. 1. Protocol outline TC is a bidirectional message-based protocol. It assumes an underlying stream for communication between a controlling process (the "client") and a Tor process (the "server"). The stream may be implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on, but it must provide reliable in-order delivery. For security, the stream should not be accessible by untrusted parties. In TC, the client and server send typed variable-length messages to each other over the underlying stream. By default, all messages from the server are in response to messages from the client. Some client requests, however, will cause the server to send messages to the client indefinitely far into the future. Servers respond to messages in the order they're received. 2. Message format The messages take the following format: Length [2 octets; big-endian] Type [2 octets; big-endian] Body [Length octets] Upon encountering a recognized Type, implementations behave as described in section 3 below. If the type is not recognized, servers respond with an "ERROR" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore the message. 2.1. Types and encodings All numbers are given in big-endian (network) order. OR identities are given in hexadecimal, in the same format as identity key fingerprints, but without spaces; see tor-spec.txt for more information. 3. Message types Message types are drawn from the following ranges: 0x0000-0xEFFF : Reserved for use by official versions of this spec. 0xF000-0xFFFF : Unallocated; usable by unofficial extensions. 3.1. ERROR (Type 0x0000) Sent in response to a message that could not be processed as requested. The body of the message begins with a 2-byte error code. The following values are defined: 0x0000 Unspecified error [] 0x0001 Internal error [Something went wrong inside Tor, so that the client's request couldn't be fulfilled.] 0x0002 Unrecognized message type [The client sent a message type we don't understand.] 0x0003 Syntax error [The client sent a message body in a format we can't parse.] 0x0004 Unrecognized configuration key [The client tried to get or set a configuration option we don't recognize.] 0x0005 Invalid configuration value [The client tried to set a configuration option to an incorrect, ill-formed, or impossible value.] 0x0006 Unrecognized byte code [The client tried to set a byte code (in the body) that we don't recognize.] 0x0007 Unauthorized. [The client tried to send a command that requires authorization, but it hasn't sent a valid AUTHENTICATE message.] 0x0008 Failed authentication attempt [The client sent a well-formed authorization message.] 0x0009 Resource exhausted [The server didn't have enough of a given resource to fulfill a given request.] 0x000A No such stream 0x000B No such circuit 0x000C No such OR The rest of the body should be a human-readable description of the error. In general, new error codes should only be added when they don't fall under one of the existing error codes. 3.2. DONE (Type 0x0001) Sent from server to client in response to a request that was successfully completed, with no more information needed. The body is usually empty but may contain a message. 3.3. SETCONF (Type 0x0002) Change the value of a configuration variable. The body contains a list of newline-terminated key-value configuration lines. An individual key-value configuration line consists of the key, followed by a space, followed by the value. The server behaves as though it had just read the key-value pair in its configuration file. The server responds with a DONE message on success, or an ERROR message on failure. When a configuration options takes multiple values, or when multiple configuration keys form a context-sensitive group (see below), then setting _any_ of the options in a SETCONF command is taken to reset all of the others. For example, if two ORBindAddress values are configured, and a SETCONF command arrives containing a single ORBindAddress value, the new command's value replaces the two old values. To _remove_ all settings for a given option entirely (and go back to its default value), send a single line containing the key and no value. 3.4. GETCONF (Type 0x0003) Request the value of a configuration variable. The body contains one or more NL-terminated strings for configuration keys. The server replies with a CONFVALUE message. If an option appears multiple times in the configuration, all of its key-value pairs are returned in order. Some options are context-sensitive, and depend on other options with different keywords. These cannot be fetched directly. Currently there is only one such option: clients should use the "HiddenServiceOptions" virtual keyword to get all HiddenServiceDir, HiddenServicePort, HiddenServiceNodes, and HiddenServiceExcludeNodes option settings. 3.5. CONFVALUE (Type 0x0004) Sent in response to a GETCONF message; contains a list of "Key Value\n" (A non-whitespace keyword, a single space, a non-NL value, a NL) strings. 3.6. SETEVENTS (Type 0x0005) Request the server to inform the client about interesting events. The body contains a list of 2-byte event codes (see "event" below). Any events *not* listed in the SETEVENTS body are turned off; thus, sending SETEVENTS with an empty body turns off all event reporting. The server responds with a DONE message on success, and an ERROR message if one of the event codes isn't recognized. (On error, the list of active event codes isn't changed.) 3.7. EVENT (Type 0x0006) Sent from the server to the client when an event has occurred and the client has requested that kind of event. The body contains a 2-byte event code followed by additional event-dependent information. Event codes are: 0x0001 -- Circuit status changed Status [1 octet] 0x00 Launched - circuit ID assigned to new circuit 0x01 Built - all hops finished, can now accept streams 0x02 Extended - one more hop has been completed 0x03 Failed - circuit closed (was not built) 0x04 Closed - circuit closed (was built) Circuit ID [4 octets] (Must be unique to Tor process/time) Path [NUL-terminated comma-separated string] (For extended/failed, is the portion of the path that is built) 0x0002 -- Stream status changed Status [1 octet] (Sent connect=0,sent resolve=1,succeeded=2,failed=3, closed=4, new connection=5, new resolve request=6, stream detached from circuit and still retriable=7) Stream ID [4 octets] (Must be unique to Tor process/time) Target (NUL-terminated address-port string] 0x0003 -- OR Connection status changed Status [1 octet] (Launched=0,connected=1,failed=2,closed=3) OR nickname/identity [NUL-terminated] 0x0004 -- Bandwidth used in the last second Bytes read [4 octets] Bytes written [4 octets] 0x0005 -- Notice/warning/error occurred Message [NUL-terminated] <obsolete: use 0x0007-0x000B instead.> 0x0006 -- New descriptors available OR List [NUL-terminated, comma-delimited list of OR identity] 0x0007 -- Debug message occurred 0x0008 -- Info message occurred 0x0009 -- Notice message occurred 0x000A -- Warning message occurred 0x000B -- Error message occurred Message [NUL-terminated] 3.8. AUTHENTICATE (Type 0x0007) Sent from the client to the server. Contains a 'magic cookie' to prove that client is really allowed to control this Tor process. The server responds with DONE or ERROR. The format of the 'cookie' is implementation-dependent; see 4.1 below for information on how the standard Tor implementation handles it. 3.9. SAVECONF (Type 0x0008) Sent from the client to the server. Instructs the server to write out its config options into its torrc. Server returns DONE if successful, or ERROR if it can't write the file or some other error occurs. 3.10. SIGNAL (Type 0x0009) S...
techno45