1
$Id: control-spec.txt,v 1.9 2004/11/26 04:00:40 arma Exp $
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 a
42
"STAT" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore
47
3.1. ERROR (Type 0x0000)
49
Sent in response to a message that could not be processed as requested.
51
The body of the message begins with a 2-byte error code. The following
54
0x0000 Unspecified error
58
[Something went wrong inside Tor, so that the client's
59
request couldn't be fulfilled.]
61
0x0002 Unrecognized message type
62
[The client sent a message type we don't understand.]
65
[The client sent a message body in a format we can't parse.]
67
0x0004 Unrecognized configuration key
68
[The client tried to get or set a configuration option we don't
71
0x0005 Invalid configuration value
72
[The client tried to set a configuration option to an
73
incorrect, ill-formed, or impossible value.]
75
0x0006 Unrecognized event code
76
[The client tried to set an event code that we don't recognize.]
79
[The client tried to send a command that requires
80
authorization, but it hasn't sent a valid AUTHENTICATE message.]
82
0x0008 Failed authentication attempt
83
[The client sent a well-formed authorization message.]
85
The rest of the body should be a human-readable description of the error.
87
In general, new error codes should only be added when they don't fall under
88
one of the existing error codes.
90
3.2. DONE (Type 0x0001)
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.
95
3.3. SETCONF (Type 0x0002)
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
102
The server responds with a DONE message on success, or an ERROR message on
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.
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.
115
3.4. GETCONF (Type 0x0003)
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.
121
If an option appears multiple times in the configuration, all of its
122
key-value pairs are returned in order.
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.
130
3.5. CONFVALUE (Type 0x0004)
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)
136
3.6. SETEVENTS (Type 0x0005)
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.
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.)
146
3.7. EVENT (Type 0x0006)
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
152
0x0001 -- Circuit status changed
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
162
0x0002 -- Stream status changed
165
(Sent connect=0,sent resolve=1,succeeded=2,failed=3,
168
(Must be unique to Tor process/time)
169
Target (NUL-terminated address-port string]
171
0x0003 -- OR Connection status changed
174
(Launched=0,connected=1,failed=2,closed=3)
175
OR nickname/identity [NUL-terminated]
177
0x0004 -- Bandwidth used in the last second
179
Bytes read [4 octets]
180
Bytes written [4 octets]
182
0x0005 -- Notice/warning/error occurred
184
Message [NUL-terminated]
186
3.8. AUTHENTICATE (Type 0x0007)
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
192
3.9. SAVECONF (Type 0x0008)
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.
198
4. Implementation notes
200
4.1. There are four ways we could authenticate, for now:
202
1) Listen on 127.0.0.1; trust all local users.
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.
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
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.
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.
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.
225
4.2. Don't let the buffer get too big.
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.
added
removed
doc/control-spec.txt
