from Sebastian: 235-kill-named-flag.txt
[torspec.git] / pt-spec.txt
1
2                            Pluggable Transport Specification
3
4                                      Jacob Appelbaum
5                                      Nick Mathewson
6
7
8
9 Overview
10
11   This proposal describes a way to decouple protocol-level obfuscation
12   from the core Tor protocol in order to better resist client-bridge
13   censorship.  Our approach is to specify a means to add pluggable
14   transport implementations to Tor clients and bridges so that they can
15   negotiate a superencipherment for the Tor protocol.
16
17   It is based on Proposal 180: see that document and its discussion for
18   more background and motivation issue, and a discussion of issues in
19   writing pluggable transpots.
20
21 Specifications: Client behavior
22
23   We extend the bridge line format to allow you to say which method
24   to use to connect to a bridge.
25
26   The new format is:
27      Bridge method address:port [id-fingerprint] [k=v] [k=v] [k=v]
28
29   To connect to such a bridge, the Tor program needs to know which
30   SOCKS proxy will support the transport called "method".  It
31   then connects to this proxy, and asks it to connect to
32   address:port.  If [id-fingerprint] is provided, Tor should expect
33   the public identity key on the TLS connection to match the digest
34   provided in [id-fingerprint].  If any [k=v] items are provided,
35   they are configuration parameters for the proxy: Tor should
36   separate them with semicolons and put them in the user and
37   password fields of the request, splitting them across the fields
38   as necessary.  If a key or value value must contain a semicolon or
39   a backslash, it is escaped with a backslash.
40   Example of SOCKS parameters encoding:
41     shared-secret=rahasia;secrets-file=/tmp/blob
42
43   Method names MUST be C identifiers. That is, method names must begin
44   with a letter or underscore and the rest of the characters can be
45   letters, numbers or underscores. No length limit is imposed. The
46   relevant regular expression is: "[a-zA-Z_][a-zA-Z0-9_]*".
47
48   For reference, the old bridge format was
49     Bridge address[:port] [id-fingerprint]
50   where port defaults to 443 and the id-fingerprint is optional. The
51   new format can be distinguished from the old one by checking if the
52   first argument has any non-C-identifier characters. (Looking for a
53   period should be a simple way.) Also, while the id-fingerprint could
54   optionally include whitespace in the old format, whitespace in the
55   id-fingerprint is not permitted in the new format.
56
57   Example: if the bridge line is "bridge trebuchet www.example.com:3333
58      09F911029D74E35BD84156C5635688C009F909F9 rocks=20 height=5.6m"
59      AND if the Tor client knows that the 'trebuchet' method is supported,
60      the client should connect to the proxy that provides the 'trebuchet'
61      method, ask it to connect to www.example.com, and provide the string
62      "rocks=20;height=5.6m" as the username, the password, or split
63      across the username and password.
64
65   There are two ways to tell Tor clients about protocol proxies:
66   external proxies and managed proxies.  An external proxy is configured
67   with
68      ClientTransportPlugin <method> socks4 <address:port> [auth=X]
69   or
70      ClientTransportPlugin <method> socks5 <address:port> [username=X] [password=Y]
71   as in
72      "ClientTransportPlugin trebuchet socks5 127.0.0.1:9999".
73   This example tells Tor that another program is already running to handle
74   'trubuchet' connections, and Tor doesn't need to worry about it.
75
76   A managed proxy is configured with
77      ClientTransportPlugin <methods> exec <path> [options]
78   as in
79     "ClientTransportPlugin trebuchet exec /usr/libexec/trebuchet --managed".
80   This example tells Tor to launch an external program to provide a
81   socks proxy for 'trebuchet' connections. The Tor client only
82   launches one instance of each external program with a given set of
83   options, even if the same executable and options are listed for
84   more than one method.
85
86   In managed proxies, <methods> can be a comma-separated list of
87   pluggable transport method names, as in:
88     "ClientTransportPlugin pawn,bishop,rook exec /bin/ptproxy --managed".
89
90   If instead of a transport method, the torrc lists "*" for a managed
91   proxy, Tor uses that proxy for all transport methods that the plugin
92   supports. So "ClientTransportPlugin * exec /usr/libexec/tor/foobar"
93   tells Tor that Tor should use the foobar plugin for every method that
94   the proxy supports. See the "Managed proxy interface" section below
95   for details on how Tor learns which methods a plugin supports.
96
97   If two plugins support the same method, Tor should use whichever
98   one is listed first.
99
100   The same program can implement a managed or an external proxy: it just
101   needs to take an argument saying which one to be.
102
103 Server behavior
104
105   Server proxies are configured similarly to client proxies.  When
106   launching a proxy, the server must tell it what ORPort it has
107   configured, and what address (if any) it can listen on.  The
108   server must tell the proxy which (if any) methods it should
109   provide if it can; the proxy needs to tell the server which
110   methods it is actually providing, and on what ports.
111
112   When a client connects to the proxy, the proxy may need a way to
113   tell the server some identifier for the client address.  It does
114   this in-band.
115
116   As before, the server lists proxies in its torrc.  These can be
117   external proxies that run on their own, or managed proxies that Tor
118   launches.
119
120   An external server proxy is configured as
121      ServerTransportPlugin <method> proxy <address:port> <param=val> ...
122   as in
123      "ServerTransportPlugin trebuchet proxy 127.0.0.1:999 rocks=heavy".
124   The param=val pairs and the address are used to make the bridge
125   configuration information that we'll tell users.
126
127   A managed proxy is configured as
128      ServerTransportPlugin <methods> exec </path/to/binary> [options]
129   or
130      ServerTransportPlugin * exec </path/to/binary> [options]
131
132   When possible, Tor should launch only one binary of each binary/option
133   pair configured.  So if the torrc contains
134
135      ClientTransportPlugin foo exec /usr/bin/megaproxy --foo
136      ClientTransportPlugin bar exec /usr/bin/megaproxy --bar
137      ServerTransportPlugin * exec /usr/bin/megaproxy --foo
138
139   then Tor will launch the megaproxy binary twice: once with the option
140   --foo and once with the option --bar.
141
142   Specify bind address
143
144     The address that a managed proxy will use to bind can be configured with:
145         ServerTransportListenAddr <method> <address:port>
146
147     For example, a valid configuration would be:
148         ServerTransportPlugin obfs2,obfs3,stegotorus exec /usr/bin/obfsproxy --managed
149         ServerTransportListenAddr obfs2 0.0.0.0:4200
150         ServerTransportListenAddr stegotorus 98.23.4.45:6559
151
152     If no ServerTransportListenAddr is specified and it's the first time
153     that Tor encounters that transport, Tor will instruct the managed
154     proxy to bind to a random TCP port on 0.0.0.0. If Tor has seen the
155     trasport before, it will instruct the managed proxy to bind to the
156     same TCP port that the transport used last time.
157
158   Specify additional configuration parameters
159
160     Further configuration parameters (like the k=v values passed to
161     client-transports using the Bridge line) can be passed to
162     server-transports using the ServerTransportOptions option.
163
164     The format of the ServerTransportOptions line is:
165        ServerTransportOptions <method> <k=v> ...
166
167     For example, a valid instance of this line would be:
168        ServerTransportOptions trebuchet secret=nou cache=/tmp/cache
169
170 Managed proxy interface
171
172    When the Tor client or relay launches a managed proxy, it communicates
173    via environment variables.  At a minimum, it sets (in addition to the
174    normal environment variables inherited from Tor):
175
176       {Client and server}
177
178       "TOR_PT_STATE_LOCATION" -- A filesystem directory path where the
179        proxy should store state if it wants to.  This directory is not
180        required to exist, but the proxy SHOULD be able to create it if
181        it doesn't.  The proxy MUST NOT store state elsewhere.
182       Example: TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
183
184       "TOR_PT_MANAGED_TRANSPORT_VER" -- To tell the proxy which
185        versions of this configuration protocol Tor supports.  Future
186        versions will give a comma-separated list.  Clients MUST accept
187        comma-separated lists containing any version that they
188        recognize, and MUST work correctly even if some of the versions
189        they don't recognize are non-numeric.  Valid version characters
190        are non-space, non-comma printing ASCII characters.
191       Example: TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2,4B
192
193       {Client only}
194
195       "TOR_PT_CLIENT_TRANSPORTS" -- A comma-separated list of which
196        methods this client should enable, or * if all methods should
197        be enabled.  The proxy SHOULD ignore methods that it doesn't
198        recognize.
199       Example: TOR_PT_CLIENT_TRANSPORTS=trebuchet,battering_ram,ballista
200
201       {Server only}
202
203       "TOR_PT_EXTENDED_SERVER_PORT" -- An <address>:<port> where tor
204        should be listening for connections speaking the extended
205        ORPort protocol (See the "The extended ORPort protocol" section
206        below). If tor does not support the extended ORPort protocol,
207        it MUST use the empty string as the value of this environment
208        variable.
209       Example: TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
210
211       "TOR_PT_ORPORT" -- Our regular ORPort in a form suitable
212        for local connections, i.e. connections from the proxy to
213        the ORPort.
214       Example: TOR_PT_ORPORT=127.0.0.1:9001
215
216       "TOR_PT_SERVER_BINDADDR" -- A comma seperated list of
217        <key>-<value> pairs, where <key> is a transport name and
218        <value> is the adress:port on which it should listen for client
219        proxy connections.
220        The keys holding transport names must appear on the same order
221        as they appear on TOR_PT_SERVER_TRANSPORTS.
222        This might be the advertised address, or might be a local
223        address that Tor will forward ports to.  It MUST be an address
224        that will work with bind().
225       Example:
226         TOR_PT_SERVER_BINDADDR=trebuchet-127.0.0.1:1984,ballista-127.0.0.1:4891
227
228       "TOR_PT_SERVER_TRANSPORTS" -- A comma-separated list of server
229        methods that the proxy should support, or * if all methods
230        should be enabled.  The proxy SHOULD ignore methods that it
231        doesn't recognize.
232       Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista
233
234       "TOR_PT_AUTH_COOKIE_FILE" -- A filesystem path where the proxy
235       should expect to find the authentication cookie to be able to
236       communicate with the Extended ORPort and TransportControlPort.
237       TOR_PT_AUTH_COOKIE_FILE is optional and might not be present in
238       the environment of the proxy.
239
240       "TOR_PT_SERVER_TRANSPORT_OPTIONS" -- A semicolon-separated list
241        of <key>:<value> pairs, where <key> is a transport name and
242        <value> is a k=v string value with options that are to be
243        passed to the transport. Colons, semicolons, equal signs and
244        backslashes must be escaped with a backslash.
245        The TOR_PT_SERVER_TRANSPORT_OPTIONS is optional and might not
246        be present in the environment of the proxy if no options need
247        to be passed to transports.
248        Example:
249          TOR_PT_SERVER_TRANSPORT_OPTIONS=trebuchet:secret=nou;trebuchet:cache=/tmp/cache;ballista:secret=yes
250        will pass to 'trebuchet' the arguments "secret=nou" and
251        "cache=/tmp/cache" and will pass to 'ballista' the argument
252        "secret=yes".
253
254   The transport proxy replies by writing NL-terminated lines to
255   stdout.  The line metaformat is
256
257       <Line> ::= <Keyword> <OptArgs> <NL>
258       <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
259       <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
260       <OptArgs> ::= <Args>*
261       <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
262       <ArgChar> ::= <any US-ASCII character but NUL or NL>
263       <SP> ::= <US-ASCII whitespace symbol (32)>
264       <NL> ::= <US-ASCII newline (line feed) character (10)>
265
266   Tor MUST ignore lines with keywords that it doesn't recognize.
267
268   First, if there's an error parsing the environment variables, the
269   proxy should write:
270     ENV-ERROR <errormessage>
271   and exit.
272
273   If the environment variables were correctly formatted, the proxy
274   should write:
275     VERSION <configuration protocol version>
276   to say that it supports this configuration protocol version (example
277   "VERSION 1"). It must either pick a version that Tor told it about
278   in TOR_PT_MANAGED_TRANSPORT_VER, or pick no version at all, say:
279      VERSION-ERROR no-version
280   and exit.
281
282   The proxy should then open its ports.  If running as a client
283   proxy, it should not use fixed ports; instead it should autoselect
284   ports to avoid conflicts.  A client proxy should by default only
285   listen on localhost for connections.
286
287   A server proxy SHOULD try to listen at a consistent port, though it
288   SHOULD pick a different one if the port it last used is now allocated.
289
290   A client or server proxy then should tell which methods it has
291   made available and how.  It does this by printing zero or more
292   CMETHOD and SMETHOD lines to its stdout.  These lines look like:
293
294    CMETHOD <methodname> socks4/socks5 <address:port> [ARGS=arglist] \
295         [OPT-ARGS=arglist]
296
297   as in
298
299    CMETHOD trebuchet socks5 127.0.0.1:19999 ARGS=rocks,height \
300               OPT-ARGS=tensile-strength
301
302   The ARGS field lists mandatory parameters that must appear in
303   every bridge line for this method. The OPT-ARGS field lists
304   optional parameters.  If no ARGS or OPT-ARGS field is provided,
305   Tor should not check the parameters in bridge lines for this
306   method.
307
308   The proxy should print a single "CMETHODS DONE" line after it is
309   finished telling Tor about the client methods it provides.  If it
310   tries to supply a client method but can't for some reason, it
311   should say:
312     CMETHOD-ERROR <methodname> <errormessage>
313
314   A proxy should also tell Tor about the server methods it is providing
315   by printing zero or more SMETHOD lines.  These lines look like:
316
317     SMETHOD <methodname> <address:port> [options]
318
319   If there's an error setting up a configured server method, the
320   proxy should say:
321     SMETHOD-ERROR <methodname> <errormessage>
322   as in
323     SMETHOD-ERROR trebuchet could not setup 'trebuchet' method
324
325   The 'address:port' part of an SMETHOD line is the address to put
326   in the bridge line.  The Options part is a list of space-separated
327   K:V flags that Tor should know about.  Recognized options are:
328
329       - ARGS:K=V,K=V,K=V
330
331         If this option is set, the K=V arguments are added to Tor's
332         extrainfo document. Equal signs and commas must be escaped
333         with a backslash.
334
335   SMETHOD and CMETHOD lines may be interspersed, to allow the proxies to
336   report methods as they become available, even when some methods may
337   require probing your network, connecting to some kind of peers, etc
338   before they are set up. After the final SMETHOD line, the proxy says
339   "SMETHODS DONE".
340
341   The proxy SHOULD NOT tell Tor about a server or client method
342   unless it is actually open and ready to use.
343
344   Tor clients SHOULD NOT use any method from a client proxy or
345   advertise any method from a server proxy UNLESS it is listed as a
346   possible method for that proxy in torrc, and it is listed by the
347   proxy as a method it supports.
348
349   Proxies should respond to a single INT signal by closing their
350   listener ports and not accepting any new connections, but keeping
351   all connections open, then terminating when connections are all
352   closed.  Proxies should respond to a second INT signal by shutting
353   down cleanly.
354
355   The managed proxy configuration protocol version defined in this
356   section is "1".
357   So, for example, if tor supports this configuration protocol it
358   should set the environment variable:
359     TOR_PT_MANAGED_TRANSPORT_VER=1
360
361 Advertising bridge methods
362
363   Bridges use transport lines in their extra-info documents to
364   advertise their pluggable transports:
365
366      transport SP <transportname> SP <address:port> [SP arglist] NL
367
368   The address:port are as returned from an SMETHOD line (unless they
369   are replaced by the FORWARD: directive).
370
371   The arglist is a K=V,... list as returned in the ARGS: part of the
372   SMETHOD line's Options component (commas and equal signs are escaped
373   with a backslash).
374