Clarify that 0 is the only reserved circID value
[torspec.git] / proposals / 196-transport-control-ports.txt
1 Filename: 196-transport-control-ports.txt
2 Title: Extended ORPort and TransportControlPort
3 Author: George Kadianakis, Nick Mathewson
4 Created: 14 Mar 2012
5 Status: Open
6 Target: 0.2.4.x
7
8 1. Overview
9
10   Proposal 180 defined Tor pluggable transports, a way to decouple
11   protocol-level obfuscation from the core Tor protocol in order to
12   better resist client-bridge censorship. This is achieved by
13   introducing pluggable transport proxies, programs that obfuscate Tor
14   traffic to resist DPI detection.
15
16   Proposal 180 defined a way for pluggable transport proxies to
17   communicate with local Tor clients and bridges, so as to exchange
18   traffic. This document extends this communication protocol, so that
19   pluggable transport proxies can exchange arbitrary operational
20   information and metadata with Tor clients and bridges.
21
22 2. Motivation
23
24   The communication protocol specified in Proposal 180 gives a way
25   for transport proxies to announce the IP address of their clients
26   to tor. Still, modern pluggable transports might have more (?)
27   needs than this. For example:
28
29   1. Tor might want to inform pluggable transport proxies on how to
30      rate-limit incoming or outgoing connections.
31
32   2. Server pluggable transport proxies might want to pass client
33      information to an anti-active-probing system controlled by tor.
34
35   3. Tor might want to temporarily stop a transport proxy from
36      obfuscating traffic.
37
38   To satisfy the above use cases, there must be real-time
39   communication between the tor process and the pluggable transport
40   proxy. To achieve this, this proposal refactors the Extended ORPort
41   protocol specified in Proposal 180, and introduces a new port,
42   TransportControlPort, whose sole role is the exchange of control
43   information between transport proxies and tor.
44
45   Specifically, transports proxies deliver each connection to the
46   "Extended ORPort", where they provide metadata and agree on an
47   identifier for each tunneled connection.  Once this handshake
48   occurs, the OR protocol proceeds unchanged.
49
50   Additionally, each transport maintains a single connection to Tor's
51   "TransportControlPort", where it receives instructions from Tor
52   about rate-limiting on individual connections.
53
54 3. The new port protocols
55
56 3.1. The new extended ORPort protocol
57
58 3.1.1. Protocol
59
60   The extended server port protocol is as follows:
61
62      COMMAND [2 bytes, big-endian]
63      BODYLEN [2 bytes, big-endian]
64      BODY [BODYLEN bytes]
65
66      Commands sent from the transport proxy to the bridge are:
67
68      [0x0000] DONE: There is no more information to give. The next
69        bytes sent by the transport will be those tunneled over it.
70        (body ignored)
71
72      [0x0001] USERADDR: an address:port string that represents the
73        client's address.
74
75      [0x0002] TRANSPORT: a string of the name of the pluggable
76        transport currently in effect on the connection.
77
78      Replies sent from tor to the proxy are:
79
80      [0x1000] OKAY: Send the user's traffic. (body ignored)
81
82      [0x1001] DENY: Tor would prefer not to get more traffic from
83        this address for a while. (body ignored)
84
85      [0x1002] CONTROL: a NUL-terminated "identifier" string. The
86        pluggable transport proxy must use the "identifier" to access
87        the TransportControlPort. See the 'Association and identifier
88        creation' section below.
89
90   Parties MUST ignore command codes that they do not understand.
91
92   If the server receives a recognized command that does not parse, it
93   MUST close the connection to the client.
94
95 3.1.2. Command descriptions
96
97 3.1.2.1. USERADDR
98
99   An ASCII string holding the TCP/IP address of the client of the
100   pluggable transport proxy. A Tor bridge SHOULD use that address to
101   collect statistics about its clients.
102
103   The string MUST not be NUL-terminated.
104
105 3.1.2.2. TRANSPORT
106
107   An ASCII string holding the name of the pluggable transport used by
108   the client of the pluggable transport proxy. A Tor bridge that
109   supports multiple transports SHOULD use that information to collect
110   statistics about the popularity of individual pluggable transports.
111
112   The string MUST not be NUL-terminated.
113
114   Pluggable transport names are C-identifiers and Tor MUST check them
115   for correctness.
116
117 3.2. The new TransportControlPort protocol
118
119   The TransportControlPort protocol is as follows:
120
121      CONNECTIONID[16 bytes, big-endian]
122      COMMAND [2 bytes, big-endian]
123      BODYLEN [2 bytes, big-endian]
124      BODY [BODYLEN bytes]
125
126      Commands sent from the transport proxy to the bridge:
127
128      [0x0001] RATE_LIMITED: Message confirming that the rate limiting
129        request of the bridge was carried out successfully (body
130        ignored). See the 'Rate Limiting' section below.
131
132      [0x0002] NOT_RATE_LIMITED: Message notifying that the transport
133        proxy failed to carry out the rate limiting request of the
134        bridge (body ignored). See the 'Rate Limiting' section below.
135
136      Configuration commands sent from the bridge to the transport
137      proxy are:
138
139      [0x1001] NOT_ALLOWED: Message notifying that the CONNECTIONID
140        could not be matched with an authorized connection ID. The
141        bridge SHOULD shutdown the connection.
142
143      [0x1001] RATE_LIMIT: Carries information on how the pluggable
144        transport proxy should rate-limit its traffic. See the 'Rate
145        Limiting' section below.
146
147   CONNECTIONID should carry the connection identifier described in the
148   'Association and identifier creation' section.
149
150   Parties should ignore command codes that they do not understand.
151
152 3.3. Association and identifier creation
153
154   For Tor and a transport proxy to communicate using the
155   TransportControlPort, an identifier must have already been negotiated
156   using the 'CONTROL' command of Extended ORPort.
157
158   The TransportControlPort identifier should not be predictable by a
159   user who hasn't received a 'CONTROL' command from the Extended
160   ORPort. For this reason, the TransportControlPort identifier should
161   not be cryptographically-weak or deterministically created.
162
163   Tor MUST create its identifiers by generating 16 bytes of random
164   data.
165
166 4. Configuration commands
167
168 4.1. Rate Limiting
169
170   A Tor relay should be able to inform a transport proxy in real-time
171   about its rate-limiting needs.
172
173   This can be achieved by using the TransportControlPort and sending a
174   'RATE_LIMIT' command to the transport proxy.
175
176   The body of the 'RATE_LIMIT' command should contain two integers,
177   4 bytes each, in big-endian format. The two numbers should represent
178   the bandwidth rate and bandwidth burst respectively in 'bytes per
179   second' which the transport proxy must set as its overall
180   rate-limiting setting.
181
182   When the transport proxy sets the appropriate rate limiting, it
183   should send back a 'RATE_LIMITED' command. If it fails while setting
184   up rate limiting, it should send back a 'NOT_RATE_LIMITED' command.
185
186   After sending a 'RATE_LIMIT' command. the tor bridge MAY want to
187   stop pushing data to the transport proxy, till it receives a
188   'RATE_LIMITED' command. If, instead, it receives a 'NOT_RATE_LIMITED'
189   command it MAY want to shutdown its connections to the transport
190   proxy.
191
192 5. Authentication
193
194   To defend against cross-protocol attacks on the Extended ORPOrt,
195   proposal 213 defines an authentication scheme that should be used to
196   protect it.
197
198   If the Extended ORPort is enabled, Tor should regenerate the cookie
199   file of proposal 213 on startup and store it in
200   $DataDirectory/extended_orport_auth_cookie.
201
202   The location of the cookie can be overriden by using the
203   configuration file parameter ExtORPortCookieAuthFile, which is
204   defined as:
205
206     ExtORPortCookieAuthFile <path>
207
208   where <path> is a filesystem path.
209
210   XXX should we also add an ExtORPortCookieFileGroupReadable torrc option?
211
212 6. Security Considerations
213
214   Extended ORPort or TransportControlPort do _not_ provide link
215   confidentiality, authentication or integrity. Sensitive data, like
216   cryptographic material, should not be transferred through them.
217
218   An attacker with superuser access, is able to sniff network traffic,
219   and capture TransportControlPort identifiers and any data passed
220   through those ports.
221
222   Tor SHOULD issue a warning if the bridge operator tries to bind
223   Extended ORPort or TransportControlPort to a non-localhost address.
224
225   Pluggable transport proxies SHOULD issue a warning if they are
226   instructed to connect to a non-localhost Extended ORPort or
227   TransportControlPort.
228
229 7. Future
230
231   In the future, we might have pluggable transports which require the
232   _client_ transport proxy to use the TransportControlPort and exchange
233   control information with the Tor client. The current proposal doesn't
234   yet support this, but we should not add functionality that will
235   prevent it from being possible.