1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
$Id$
TC: A Tor control protocol
0. Scope
(8 Aug 2004) This document describes an implementation-specific protocol to
be implemented in a future version of Tor. It is not part of the Tor onion
routing protocol.
The protocol described in this document is used for other programs (such as
frontend user-interfaces) to communicate with a locally running Tor 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 pipe, or so on. For security, the stream should not be
observable by untrusted parties.
In TC, the client and server send typed variable-length messages to one
another 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
"STAT" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore
the message.
3. Message types
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 Unrecognized message type
0x0002 Unrecognized configuration key
0x0003 Invalid configuration value
0x0004 Unrecognized event code
0x0005 Unauthorized user
0x0006 Failed authentication attempt
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 empty.
3.3. SETCONF (Type 0x0002)
Change the value of a configuration variable. The body contains
two nul-terminated strings: a configuration key and a configuration 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.
3.4. GETCONF (Type 0x0003)
Request the value of a configuration variable. The body contains a
nul-terminated string for a configuration key. The server replies with a
CONFVALUE message
3.5. CONFVALUE (Type 0x0004)
Sent in response to a GETCONF message; contains a nul-terminated key string
and a nul-terminated value string.
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).
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]
(Launched=0,Built=1,Extended=2,Failed=3,Closed=4)
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)
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 last N seconds. (N=1? 5?)
Bytes read [4 octets]
Bytes written [4 octets]
0x0005 -- Warning/error 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 the admin for this Tor process. The server responds
with DONE or ERROR.
4. Implementation notes
On Unix, we should use a named pipe on the fs and use filesystem privileges
to authenticate. On Win32, a password/magic cookie may be in order.
-----------
(for emacs)
Local Variables:
mode:text
indent-tabs-mode:nil
fill-column:77
End:
|