3 TC: A Tor control protocol
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
12 We're trying to be pretty extensible here, but not infinitely
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.
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
30 Servers respond to messages in the order they're received.
34 The messages take the following format:
36 Length [2 octets; big-endian]
37 Type [2 octets; big-endian]
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
45 2.1. Types and encodings
47 All numbers are given in big-endian (network) order.
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.
54 Message types are drawn from the following ranges:
56 0x0000-0xEFFF : Reserved for use by official versions of this spec.
57 0xF000-0xFFFF : Unallocated; usable by unofficial extensions.
59 3.1. ERROR (Type 0x0000)
61 Sent in response to a message that could not be processed as requested.
63 The body of the message begins with a 2-byte error code. The following
66 0x0000 Unspecified error
70 [Something went wrong inside Tor, so that the client's
71 request couldn't be fulfilled.]
73 0x0002 Unrecognized message type
74 [The client sent a message type we don't understand.]
77 [The client sent a message body in a format we can't parse.]
79 0x0004 Unrecognized configuration key
80 [The client tried to get or set a configuration option we don't
83 0x0005 Invalid configuration value
84 [The client tried to set a configuration option to an
85 incorrect, ill-formed, or impossible value.]
87 0x0006 Unrecognized byte code
88 [The client tried to set a byte code (in the body) that
92 [The client tried to send a command that requires
93 authorization, but it hasn't sent a valid AUTHENTICATE
96 0x0008 Failed authentication attempt
97 [The client sent a well-formed authorization message.]
99 0x0009 Resource exhausted
100 [The server didn't have enough of a given resource to
101 fulfill a given request.]
103 0x000A No such stream
105 0x000B No such circuit
109 The rest of the body should be a human-readable description of the error.
111 In general, new error codes should only be added when they don't fall under
112 one of the existing error codes.
114 3.2. DONE (Type 0x0001)
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.
120 3.3. SETCONF (Type 0x0002)
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.
128 The server responds with a DONE message on success, or an ERROR message on
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.
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.
141 3.4. GETCONF (Type 0x0003)
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.
147 If an option appears multiple times in the configuration, all of its
148 key-value pairs are returned in order.
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.
156 3.5. CONFVALUE (Type 0x0004)
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)
162 3.6. SETEVENTS (Type 0x0005)
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.
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.)
173 3.7. EVENT (Type 0x0006)
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
179 0x0001 -- Circuit status changed
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
193 0x0002 -- Stream status changed
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)
200 (Must be unique to Tor process/time)
201 Target (NUL-terminated address-port string]
203 0x0003 -- OR Connection status changed
206 (Launched=0,connected=1,failed=2,closed=3)
207 OR nickname/identity [NUL-terminated]
209 0x0004 -- Bandwidth used in the last second
211 Bytes read [4 octets]
212 Bytes written [4 octets]
214 0x0005 -- Notice/warning/error occurred
216 Message [NUL-terminated]
218 <obsolete: use 0x0007-0x000B instead.>
220 0x0006 -- New descriptors available
222 OR List [NUL-terminated, comma-delimited list of
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
231 Message [NUL-terminated]
234 3.8. AUTHENTICATE (Type 0x0007)
236 Sent from the client to the server. Contains a 'magic cookie' to prove
237 that client is really the admin for this Tor process. The server responds
240 3.9. SAVECONF (Type 0x0008)
242 Sent from the client to the server. Instructs the server to write out
243 its config options into its torrc. Server returns DONE if successful, or
244 ERROR if it can't write the file or some other error occurs.
246 3.10. SIGNAL (Type 0x0009)
248 Sent from the client to the server. The body contains one byte that
249 indicates the action the client wishes the server to take.
251 1 (0x01) -- Reload: reload config items, refetch directory.
252 2 (0x02) -- Controlled shutdown: if server is an OP, exit immediately.
253 If it's an OR, close listeners and exit after 30 seconds.
254 10 (0x0A) -- Dump stats: log information about open connections and
256 12 (0x0C) -- Debug: switch all open logs to loglevel debug.
257 15 (0x0F) -- Immediate shutdown: clean up and exit now.
259 The server responds with DONE if the signal is recognized (or simply
260 closes the socket if it was asked to close immediately), else ERROR.
262 3.11. MAPADDRESS (Type 0x000A)
264 Sent from the client to the server. The body contains a sequence of
265 address mappings, each consisting of the address to be mapped, a single
266 space, the replacement address, and a NL character.
268 Addresses may be IPv4 addresses, IPv6 addresses, or hostnames.
270 The client sends this message to the server in order to tell it that future
271 SOCKS requests for connections to the original address should be replaced
272 with connections to the specified replacement address. If the addresses
273 are well-formed, and the server is able to fulfill the request, the server
274 replies with a single DONE message containing the source and destination
275 addresses. If request is malformed, the server replies with a syntax error
276 message. The server can't fulfill the request, it replies with an internal
279 The client may decline to provide a body for the original address, and
280 instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
281 "." for hostname), signifying that the server should choose the original
282 address itself, and return that address in the DONE message. The server
283 should ensure that it returns an element of address space that is unlikely
284 to be in actual use. If there is already an address mapped to the
285 destination address, the server may reuse that mapping.
287 If the original address is already mapped to a different address, the old
288 mapping is removed. If the original address and the destination address
289 are the same, the server removes any mapping in place for the original
292 {Note: This feature is designed to be used to help Tor-ify applications
293 that need to use SOCKS4 or hostname-less SOCKS5. There are three
294 approaches to doing this:
295 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
296 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
297 feature) to resolve the hostname remotely. This doesn't work
298 with special addresses like x.onion or x.y.exit.
299 3. Use MAPADDRESS to map an IP address to the desired hostname, and then
300 arrange to fool the application into thinking that the hostname
301 has resolved to that IP.
302 This functionality is designed to help implement the 3rd approach.}
304 [XXXX When, if ever, can mappings expire? Should they expire?]
305 [XXXX What addresses, if any, are safe to use?]
307 3.12 GETINFO (Type 0x000B)
309 Sent from the client to the server. The message body is as for GETCONF:
310 one or more NL-terminated strings. The server replies with an INFOVALUE
313 Unlike GETCONF, this message is used for data that are not stored in the
314 Tor configuration file, but instead.
316 Recognized key and their values include:
318 "version" -- The version of the server's software, including the name
319 of the software. (example: "Tor 0.0.9.4")
321 "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest server
322 descriptor for a given OR, NUL-terminated. If no such OR is known, the
323 corresponding value is an empty string.
325 "network-status" -- a space-separated list of all known OR identities.
326 This is in the same format as the router-status line in directories;
327 see tor-spec.txt for details.
330 "addr-mappings/config"
331 "addr-mappings/cache"
332 "addr-mappings/control" -- a NL-terminated list of address mappings, each
333 in the form of "from-address" SP "to-address". The 'config' key
334 returns those address mappings set in the configuration; the 'cache'
335 key returns the mappings in the client-side DNS cache; the 'control'
336 key returns the mappings set via the control interface; the 'all'
337 target returns the mappings set through any mechanism.
339 3.13 INFOVALUE (Type 0x000C)
341 Sent from the server to the client in response to a GETINFO message.
342 Contains one or more items of the format:
344 Key [(NUL-terminated string)]
345 Value [(NUL-terminated string)]
347 The keys match those given in the GETINFO message.
349 3.14 EXTENDCIRCUIT (Type 0x000D)
351 Sent from the client to the server. The message body contains two fields:
352 Circuit ID [4 octets]
353 Path [NUL-terminated, comma-delimited string of OR nickname/identity]
355 This request takes one of two forms: either the Circuit ID is zero, in
356 which case it is a request for the server to build a new circuit according
357 to the specified path, or the Circuit ID is nonzero, in which case it is a
358 request for the server to extend an existing circuit with that ID according
359 to the specified path.
361 If the request is successful, the server sends a DONE message containing
362 a message body consisting of the four-octet Circuit ID of the newly created
365 3.15 ATTACHSTREAM (Type 0x000E)
367 Sent from the client to the server. The message body contains two fields:
369 Circuit ID [4 octets]
371 This message informs the server that the specified stream should be
372 associated with the specified circuit. Each stream may be associated with
373 at most one circuit, and multiple streams may share the same circuit.
374 Streams can only be attached to completed circuits (that is, circuits that
375 have sent a circuit status 'built' event).
377 If the circuit ID is 0, responsibility for attaching the given stream is
380 {Implementation note: By default, Tor automatically attaches streams to
381 circuits itself, unless the configuration variable
382 "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
383 via TC when "__LeaveStreamsUnattached" is false may cause a race between
384 Tor and the controller, as both attempt to attach streams to circuits.}
386 3.16 POSTDESCRIPTOR (Type 0x000F)
388 Sent from the client to the server. The message body contains one field:
389 Descriptor [NUL-terminated string]
391 This message informs the server about a new descriptor.
393 The descriptor, when parsed, must contain a number of well-specified
394 fields, including fields for its nickname and identity.
396 If there is an error in parsing the descriptor, the server must send an
397 appropriate error message. If the descriptor is well-formed but the server
398 chooses not to add it, it must reply with a DONE message whose body
399 explains why the server was not added.
401 3.17 FRAGMENTHEADER (Type 0x0010)
403 Sent in either direction. Used to encapsulate messages longer than 65535
406 Underlying type [2 bytes]
407 Total Length [4 bytes]
408 Data [Rest of message]
410 A FRAGMENTHEADER message MUST be followed immediately by a number of
411 FRAGMENT messages, such that lengths of the "Data" fields of the
412 FRAGMENTHEADER and FRAGMENT messages add to the "Total Length" field of the
413 FRAGMENTHEADER message.
415 Implementations MUST NOT fragment messages of length less than 65536 bytes.
416 Implementations MUST be able to process fragmented messages that not
419 3.18 FRAGMENT (Type 0x0011)
421 Data [Entire message]
423 See FRAGMENTHEADER for more information
425 3.19 REDIRECTSTREAM (Type 0x0012)
427 Sent from the client to the server. The message body contains two fields:
429 Address [variable-length, NUL-terminated.]
431 Tells the server to change the exit address on the specified stream. No
432 remapping is performed on the new provided address.
434 To be sure that the modified address will be used, this event must be sent
435 after a new stream event is received, and before attaching this stream to
438 3.20 CLOSESTREAM (Type 0x0013)
440 Sent from the client to the server. The message body contains three
446 Tells the server to close the specified stream. The reason should be
447 one of the Tor RELAY_END reasons given in tor-spec.txt. Flags is not
448 used currently. Tor may hold the stream open for a while to flush
449 any data that is pending.
451 3.21 CLOSECIRCUIT (Type 0x0014)
453 Sent from the client to the server. The message body contains two
455 Circuit ID [4 octets]
458 Tells the server to close the specified circuit. If the LSB of the flags
459 field is nonzero, do not close the circuit unless it is unused.
461 4. Implementation notes
463 4.1. There are four ways we could authenticate, for now:
465 1) Listen on 127.0.0.1; trust all local users.
467 2) Write a named socket in tor's data-directory or in some other location;
468 rely on the OS to ensure that only authorized users can open it. (NOTE:
469 the Linux unix(7) man page suggests that some BSDs don't enforce
470 authorization.) If the OS has named sockets, and implements
471 authentication, trust all users who can read Tor's data directory.
473 3) Write a random magic cookie to the FS in Tor's data-directory; use that
474 magic cookie for authentication. Trust all users who can read Tor's data
477 4) Store a salted-and-hashed passphrase in Tor's configuration. Use the
478 passphrase for authentication. Trust all users who know the passphrase.
480 On Win32, our only options are 1, 3, and 4. Since the semantics for 2
481 and 3 are so similar, we chose to not support 2, and just always bind
482 on 127.0.0.1. We've implemented 1, 3, and 4.
484 By default, the Tor client accepts authentication approach #1. If
485 the controller wants Tor to demand more authentication, it should use
486 setconf and saveconf to configure Tor to demand more next time.
488 4.2. Don't let the buffer get too big.
490 If you ask for lots of events, and 16MB of them queue up on the buffer,
491 the Tor process will close the socket.