Add xxx-single-guard-node as proposal 236.
[torspec.git] / proposals / 180-pluggable-transport.txt
1 Filename: 180-pluggable-transport.txt
2 Title: Pluggable transports for circumvention
3 Author: Jacob Appelbaum, Nick Mathewson
4 Created: 15-Oct-2010
5 Status: Closed
6 Implemented-In: 0.2.3.x
7
8 Overview
9
10   This proposal describes a way to decouple protocol-level obfuscation
11   from the core Tor protocol in order to better resist client-bridge
12   censorship.  Our approach is to specify a means to add pluggable
13   transport implementations to Tor clients and bridges so that they can
14   negotiate a superencipherment for the Tor protocol.
15
16 Scope
17
18   This is a document about transport plugins; it does not cover
19   discovery improvements, or bridgedb improvements.  While these
20   requirements might be solved by a program that also functions as a
21   transport plugin, this proposal only covers the requirements and
22   operation of transport plugins.
23
24 Motivation
25
26   Frequently, people want to try a novel circumvention method to help
27   users connect to Tor bridges.  Some of these methods are already
28   pretty easy to deploy: if the user knows an unblocked VPN or open
29   SOCKS proxy, they can just use that with the Tor client today.
30
31   Less easy to deploy are methods that require participation by both the
32   client and the bridge.  In order of increasing sophistication, we
33   might want to support:
34
35   1. A protocol obfuscation tool that transforms the output of a TLS
36      connection into something that looks like HTTP as it leaves the
37      client, and back to TLS as it arrives at the bridge.
38   2. An additional authentication step that a client would need to
39      perform for a given bridge before being allowed to connect.
40   3. An information passing system that uses a side-channel in some
41      existing protocol to convey traffic between a client and a bridge
42      without the two of them ever communicating directly.
43   4. A set of clients to tunnel client->bridge traffic over an existing
44      large p2p network, such that the bridge is known by an identifier
45      in that network rather than by an IP address.
46
47   We could in theory support these almost fine with Tor as it stands
48   today: every Tor client can take a SOCKS proxy to use for its outgoing
49   traffic, so a suitable client proxy could handle the client's traffic
50   and connections on its behalf, while a corresponding program on the
51   bridge side could handle the bridge's side of the protocol
52   transformation.  Nevertheless, there are some reasons to add support
53   for transportation plugins to Tor itself:
54
55   1. It would be good for bridges to have a standard way to advertise
56      which transports they support, so that clients can have multiple
57      local transport proxies, and automatically use the right one for
58      the right bridge.
59
60   2. There are some changes to our architecture that we'll need for a
61      system like this to work.  For testing purposes, if a bridge blocks
62      off its regular ORPort and instead has an obfuscated ORPort, the
63      bridge authority has no way to test it.  Also, unless the bridge
64      has some way to tell that the bridge-side proxy at 127.0.0.1 is not
65      the origin of all the connections it is relaying, it might decide
66      that there are too many connections from 127.0.0.1, and start
67      paring them down to avoid a DoS.
68
69   3. Censorship and anticensorship techniques often evolve faster than
70      the typical Tor release cycle.  As such, it's a good idea to
71      provide ways to test out new anticensorship mechanisms on a more
72      rapid basis.
73
74   4. Transport obfuscation is a relatively distinct problem
75      from the other privacy problems that Tor tries to solve, and it
76      requires a fairly distinct skill-set from hacking the rest of Tor.
77      By decoupling transport obfuscation from the Tor core, we hope to
78      encourage people working on transport obfuscation who would
79      otherwise not be interested in hacking Tor.
80
81   5. Finally, we hope that defining a generic transport obfuscation plugin
82      mechanism will be useful to other anticensorship projects.
83
84 Non-Goals
85
86   We're not going to talk about automatic verification of plugin
87   correctness and safety via sandboxing, proof-carrying code, or
88   whatever.
89
90   We need to do more with discovery and distribution, but that's not
91   what this proposal is about.  We're pretty convinced that the problems
92   are sufficiently orthogonal that we should be fine so long as we don't
93   preclude a single program from implementing both transport and
94   discovery extensions.
95
96   This proposal is not about what transport plugins are the best ones
97   for people to write.  We do, however, make some general
98   recommendations for plugin authors in an appendix.
99
100   We've considered issues involved with completely replacing Tor's TLS
101   with another encryption layer, rather than layering it inside the
102   obfuscation layer.  We describe how to do this in an appendix to the
103   current proposal, though we are not currently sure whether it's a good
104   idea to implement.
105
106   We deliberately reject any design that would involve linking the
107   transport plugins into Tor's process space.
108
109 Design overview
110
111   To write a new transport protocol, an implementer must provide two
112   pieces: a "Client Proxy" to run at the initiator side, and a "Server
113   Proxy" to run at the server side.  These two pieces may or may not be
114   implemented by the same program.
115
116   Each client may run any number of Client Proxies.  Each one acts like
117   a SOCKS proxy that accepts connections on localhost.  Each one
118   runs on a different port, and implements one or more transport
119   methods.  If the protocol has any parameters, they are passed from Tor
120   inside the regular username/password parts of the SOCKS protocol.
121
122   Bridges (and maybe relays) may run any number of Server Proxies: these
123   programs provide an interface like stunnel: they get connections from the
124   network (typically by listening for connections on the network) and relay
125   them to the Bridge's real ORPort.
126
127   To configure one of these programs, it should be sufficient simply to
128   list it in your torrc.  The program tells Tor which transports it
129   provides.  The Tor consensus should carry a new approved version number that
130   is specific for pluggable transport; this will allow Tor to know when a
131   particular transport is known to be unsafe, safe, or non-functional.
132
133   Bridges (and maybe relays) report in their descriptors which transport
134   protocols they support.  This information can be copied into bridge
135   lines.  Bridges using a transport protocol may have multiple bridge
136   lines.
137
138   Any methods that are wildly successful, we can bake into Tor.
139
140 Specifications: Client behavior
141
142   We extend the bridge line format to allow you to say which method
143   to use to connect to a bridge.
144
145   The new format is:
146      Bridge method address:port [[keyid=]id-fingerprint] [k=v] [k=v] [k=v]
147
148   To connect to such a bridge, the Tor program needs to know which
149   SOCKS proxy will support the transport called "method".  It
150   then connects to this proxy, and asks it to connect to
151   address:port.  If [id-fingerprint] is provided, Tor should expect
152   the public identity key on the TLS connection to match the digest
153   provided in [id-fingerprint].  If any [k=v] items are provided,
154   they are configuration parameters for the proxy: Tor should
155   separate them with semicolons and put them in the user and
156   password fields of the request, splitting them across the fields
157   as necessary.  If a key or value value must contain a semicolon or
158   a backslash, it is escaped with a backslash.
159
160   Method names must be C identifiers.
161
162   For reference, the old bridge format was
163     Bridge address[:port] [id-fingerprint]
164   where port defaults to 443 and the id-fingerprint is optional. The
165   new format can be distinguished from the old one by checking if the
166   first argument has any non-C-identifier characters. (Looking for a
167   period should be a simple way.) Also, while the id-fingerprint could
168   optionally include whitespace in the old format, whitespace in the
169   id-fingerprint is not permitted in the new format.
170
171   Example: if the bridge line is "bridge trebuchet www.example.com:3333
172      keyid=09F911029D74E35BD84156C5635688C009F909F9 rocks=20 height=5.6m"
173      AND if the Tor client knows that the 'trebuchet' method is supported,
174      the client should connect to the proxy that provides the 'trebuchet'
175      method, ask it to connect to www.example.com, and provide the string
176      "rocks=20;height=5.6m" as the username, the password, or split
177      across the username and password.
178
179   There are two ways to tell Tor clients about protocol proxies:
180   external proxies and managed proxies.  An external proxy is configured
181   with
182      ClientTransportPlugin <method> socks4 <address:port> [auth=X]
183   or
184      ClientTransportPlugin <method> socks5 <address:port> [username=X] [password=Y]
185   as in
186      "ClientTransportPlugin trebuchet socks5 127.0.0.1:9999".
187   This example tells Tor that another program is already running to handle
188   'trubuchet' connections, and Tor doesn't need to worry about it.
189
190   A managed proxy is configured with
191      ClientTransportPlugin <methods> exec <path> [options]
192   as in
193     "ClientTransportPlugin trebuchet exec /usr/libexec/trebuchet --managed".
194   This example tells Tor to launch an external program to provide a
195   socks proxy for 'trebuchet' connections. The Tor client only
196   launches one instance of each external program with a given set of
197   options, even if the same executable and options are listed for
198   more than one method.
199
200   In managed proxies, <methods> can be a comma-separated list of
201   pluggable transport method names, as in:
202     "ClientTransportPlugin pawn,bishop,rook exec /bin/ptproxy --managed".
203
204   If instead of a transport method, the torrc lists "*" for a managed
205   proxy, Tor uses that proxy for all transport methods that the plugin
206   supports. So "ClientTransportPlugin * exec /usr/libexec/tor/foobar"
207   tells Tor that Tor should use the foobar plugin for every method that
208   the proxy supports. See the "Managed proxy interface" section below
209   for details on how Tor learns which methods a plugin supports.
210
211   If two plugins support the same method, Tor should use whichever
212   one is listed first.
213
214   The same program can implement a managed or an external proxy: it just
215   needs to take an argument saying which one to be.
216
217 Server behavior
218
219   Server proxies are configured similarly to client proxies.  When
220   launching a proxy, the server must tell it what ORPort it has
221   configured, and what address (if any) it can listen on.  The
222   server must tell the proxy which (if any) methods it should
223   provide if it can; the proxy needs to tell the server which
224   methods it is actually providing, and on what ports.
225
226   When a client connects to the proxy, the proxy may need a way to
227   tell the server some identifier for the client address.  It does
228   this in-band.
229
230   As before, the server lists proxies in its torrc.  These can be
231   external proxies that run on their own, or managed proxies that Tor
232   launches.
233
234   An external server proxy is configured as
235      ServerTransportPlugin <method> proxy <address:port> <param=val> ...
236   as in
237      "ServerTransportPlugin trebuchet proxy 127.0.0.1:999 rocks=heavy".
238   The param=val pairs and the address are used to make the bridge
239   configuration information that we'll tell users.
240
241   A managed proxy is configured as
242      ServerTransportPlugin <methods> exec </path/to/binary> [options]
243   or
244      ServerTransportPlugin * exec </path/to/binary> [options]
245
246   When possible, Tor should launch only one binary of each binary/option
247   pair configured.  So if the torrc contains
248
249      ClientTransportPlugin foo exec /usr/bin/megaproxy --foo
250      ClientTransportPlugin bar exec /usr/bin/megaproxy --bar
251      ServerTransportPlugin * exec /usr/bin/megaproxy --foo
252
253   then Tor will launch the megaproxy binary twice: once with the option
254   --foo and once with the option --bar.
255
256 Managed proxy interface
257
258    When the Tor client or relay launches a managed proxy, it communicates
259    via environment variables.  At a minimum, it sets (in addition to the
260    normal environment variables inherited from Tor):
261
262       {Client and server}
263
264       "TOR_PT_STATE_LOCATION" -- A filesystem directory path where the
265        proxy should store state if it wants to.  This directory is not
266        required to exist, but the proxy SHOULD be able to create it if
267        it doesn't.  The proxy MUST NOT store state elsewhere.
268       Example: TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
269
270       "TOR_PT_MANAGED_TRANSPORT_VER" -- To tell the proxy which
271        versions of this configuration protocol Tor supports.  Future
272        versions will give a comma-separated list.  Clients MUST accept
273        comma-separated lists containing any version that they
274        recognize, and MUST work correctly even if some of the versions
275        they don't recognize are non-numeric.  Valid version characters
276        are non-space, non-comma printing ASCII characters.
277       Example: TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2,4B
278
279       {Client only}
280
281       "TOR_PT_CLIENT_TRANSPORTS" -- A comma-separated list of which
282        methods this client should enable, or * if all methods should
283        be enabled.  The proxy SHOULD ignore methods that it doesn't
284        recognize.
285       Example: TOR_PT_CLIENT_TRANSPORTS=trebuchet,battering_ram,ballista
286
287       {Server only}
288
289       "TOR_PT_EXTENDED_SERVER_PORT" -- An <address>:<port> where tor
290        should be listening for connections speaking the extended
291        ORPort protocol (See the "The extended ORPort protocol" section
292        below). If tor does not support the extended ORPort protocol,
293        it MUST use the empty string as the value of this environment
294        variable.
295       Example: TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
296
297       "TOR_PT_ORPORT" -- Our regular ORPort in a form suitable
298        for local connections, i.e. connections from the proxy to
299        the ORPort.
300       Example: TOR_PT_ORPORT=127.0.0.1:9001
301
302       "TOR_PT_SERVER_BINDADDR" -- A comma seperated list of
303        <key>-<value> pairs, where <key> is a transport name and
304        <value> is the adress:port on which it should listen for client
305        proxy connections.
306        The keys holding transport names must appear on the same order
307        as they appear on TOR_PT_SERVER_TRANSPORTS.
308        This might be the advertised address, or might be a local
309        address that Tor will forward ports to.  It MUST be an address
310        that will work with bind().
311       Example:
312         TOR_PT_SERVER_BINDADDR=trebuchet-127.0.0.1:1984,ballista-127.0.0.1:4891
313
314       "TOR_PT_SERVER_TRANSPORTS" -- A comma-separated list of server
315        methods that the proxy should support, or * if all methods
316        should be enabled.  The proxy SHOULD ignore methods that it
317        doesn't recognize.
318       Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista
319
320   The transport proxy replies by writing NL-terminated lines to
321   stdout.  The line metaformat is
322
323       <Line> ::= <Keyword> <OptArgs> <NL>
324       <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
325       <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
326       <OptArgs> ::= <Args>*
327       <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
328       <ArgChar> ::= <any US-ASCII character but NUL or NL>
329       <SP> ::= <US-ASCII whitespace symbol (32)>
330       <NL> ::= <US-ASCII newline (line feed) character (10)>
331
332   Tor MUST ignore lines with keywords that it doesn't recognize.
333
334   First, if there's an error parsing the environment variables, the
335   proxy should write:
336     ENV-ERROR <errormessage>
337   and exit.
338
339   If the environment variables were correctly formatted, the proxy
340   should write:
341     VERSION <configuration protocol version>
342   to say that it supports this configuration protocol version (example
343   "VERSION 1"). It must either pick a version that Tor told it about
344   in TOR_PT_MANAGED_TRANSPORT_VER, or pick no version at all, say:
345      VERSION-ERROR no-version
346   and exit.
347
348   The proxy should then open its ports.  If running as a client
349   proxy, it should not use fixed ports; instead it should autoselect
350   ports to avoid conflicts.  A client proxy should by default only
351   listen on localhost for connections.
352
353   A server proxy SHOULD try to listen at a consistent port, though it
354   SHOULD pick a different one if the port it last used is now allocated.
355
356   A client or server proxy then should tell which methods it has
357   made available and how.  It does this by printing zero or more
358   CMETHOD and SMETHOD lines to its stdout.  These lines look like:
359
360    CMETHOD <methodname> socks4/socks5 <address:port> [ARGS=arglist] \
361         [OPT-ARGS=arglist]
362
363   as in
364
365    CMETHOD trebuchet socks5 127.0.0.1:19999 ARGS=rocks,height \
366               OPT-ARGS=tensile-strength
367
368   The ARGS field lists mandatory parameters that must appear in
369   every bridge line for this method. The OPT-ARGS field lists
370   optional parameters.  If no ARGS or OPT-ARGS field is provided,
371   Tor should not check the parameters in bridge lines for this
372   method.
373
374   The proxy should print a single "CMETHODS DONE" line after it is
375   finished telling Tor about the client methods it provides.  If it
376   tries to supply a client method but can't for some reason, it
377   should say:
378     CMETHOD-ERROR <methodname> <errormessage>
379
380   A proxy should also tell Tor about the server methods it is providing
381   by printing zero or more SMETHOD lines.  These lines look like:
382
383     SMETHOD <methodname> <address:port> [options]
384
385   If there's an error setting up a configured server method, the
386   proxy should say:
387     SMETHOD-ERROR <methodname> <errormessage>
388   as in
389     SMETHOD-ERROR trebuchet could not setup 'trebuchet' method
390
391   The 'address:port' part of an SMETHOD line is the address to put
392   in the bridge line.  The Options part is a list of space-separated
393   K:V flags that Tor should know about.  Recognized options are:
394
395       - FORWARD:1
396
397         If this option is set (for example, because address:port is not
398         a publicly accessible address), then Tor needs to forward some
399         other address:port to address:port via upnp-helper. Tor would
400         then advertise that other address:port in the bridge line instead.
401
402       - ARGS:K=V,K=V,K=V
403
404         If this option is set, the K=V arguments are added to Tor's
405         extrainfo document.
406
407       - DECLARE:K=V,...
408
409         If this option is set, the K=V options should be added as
410         extension entries to the router descriptor, so clients and other
411         relays can make use of it. See ideas/xxx-triangleboy-transport.txt
412         for an example situation where the plugin would want to declare
413         parameters to other Tors.
414
415       - USE-EXTENDED-PORT:1
416
417         If this option is set, the server plugin is planning to connect
418         to Tor's extended server port.
419
420   SMETHOD and CMETHOD lines may be interspersed, to allow the proxies to
421   report methods as they become available, even when some methods may
422   require probing your network, connecting to some kind of peers, etc
423   before they are set up. After the final SMETHOD line, the proxy says
424   "SMETHODS DONE".
425
426   The proxy SHOULD NOT tell Tor about a server or client method
427   unless it is actually open and ready to use.
428
429   Tor clients SHOULD NOT use any method from a client proxy or
430   advertise any method from a server proxy UNLESS it is listed as a
431   possible method for that proxy in torrc, and it is listed by the
432   proxy as a method it supports.
433
434   Proxies should respond to a single INT signal by closing their
435   listener ports and not accepting any new connections, but keeping
436   all connections open, then terminating when connections are all
437   closed.  Proxies should respond to a second INT signal by shutting
438   down cleanly.
439
440   The managed proxy configuration protocol version defined in this
441   section is "1".
442   So, for example, if tor supports this configuration protocol it
443   should set the environment variable:
444     TOR_PT_MANAGED_TRANSPORT_VER=1
445
446 The Extended ORPort protocol
447
448   The Extended ORPort protocol is described in proposal 196.
449
450 Advertising bridge methods
451
452   Bridges put the 'method' lines in their extra-info documents.
453
454      transport SP <transportname> SP <address:port> [SP arglist] NL
455
456   The address:port are as returned from an SMETHOD line (unless they are
457   replaced by the FORWARD: directive).  The arglist is a K=V,... list as
458   returned in the ARGS: part of the SMETHOD line's Options component.
459
460   If the SMETHOD line includes a DECLARE: part, the router descriptor gets
461   a new line:
462
463      transport-info SP <transportname> [SP arglist] NL
464
465 Bridge authority behavior
466
467   We need to specify a way to test different transport methods that
468   bridges claim to support.  We should test as many as possible.  We
469   should NOT require that we have a way to test every possible
470   transport method before we allow its use: the point of this design
471   is to remove bottlenecks in transport deployment.
472
473 Bridgedb behavior
474
475   Bridgedb can, given a set of router descriptors and their
476   corresponding extrainfo documents, generate a set of bridge lines
477   for each bridge.  Bridgedb may want to avoid handing out
478   methods that seem to get bridges blocked quickly.
479
480 Implementation plan
481
482   First, we should implement per-bridge proxies via the "external
483   proxy" method described in "Specifications: Client behavior".  Also,
484   we'll want to build the
485   extended-server-port mechanism.  This will let bridges run
486   transport proxies such that they can generate bridge lines to
487   give to clients for testing, so long as the user configures and
488   launches their proxies on their own.
489
490   Once that's done, we can see if we need any managed proxies, or if
491   the whole idea there is silly.
492
493   If we do, the next most important part seems to be getting
494   the client-side automation part written.  And once that's done, we
495   can evaluate how much of the server side is easy for people to do
496   and how much is hard.
497
498   The "obfsproxy" obfuscating proxy is a likely candidate for an
499   initial transport (trac entry #2760), as is Steven Murdoch's http
500   thing (trac entry #2759) or something similar.
501
502 Notes on plugins to write
503
504    We should ship a couple of null plugin implementations in one or two
505    popular, portable languages so that people get an idea of how to
506    write the stuff.
507
508    1. We should have one that's just a proof of concept that does
509       nothing but transfer bytes back and forth.
510
511    2. We should implement DNS or HTTP using other software (as Geoff Goodell
512       did years ago with DNS) as an example of wrapping existing code into
513       our plugin model.
514
515    3. The obfuscated-ssh superencipherment is pretty trivial and pretty
516       useful.  It makes the protocol stringwise unfingerprintable.
517
518    4. If we do a raw-traffic proxy, openssh tunnels would be the logical
519       choice.
520
521 Appendix: recommendations for transports
522
523   Be free/open-source software.  Also, if you think your code might
524   someday do so well at circumvention that it should be implemented
525   inside Tor, it should use the same license as Tor.
526
527   Tor already uses OpenSSL, Libevent, and zlib.  Before you go and decide
528   to use crypto++ in your transport plugin, ask yourself whether OpenSSL
529   wouldn't be a nicer choice.
530
531   Be portable: most Tor users are on Windows, and most Tor developers
532   are not, so designing your code for just one of these platforms will
533   make it either get a small userbase, or poor auditing.
534
535   Think secure: if your code is in a C-like language, and it's hard to
536   read it and become convinced it's safe, then it's probably not safe.
537
538   Think small: we want to minimize the bytes that a Windows user needs
539   to download for a transport client.
540
541   Avoid security-through-obscurity if possible.  Specify.
542
543   Resist trivial fingerprinting: There should be no good string or regex
544   to search for to distinguish your protocol from protocols permitted by
545   censors.
546
547   Imitate a real profile: There are many ways to implement most
548   protocols -- and in many cases, most possible variants of a given
549   protocol won't actually exist in the wild.
550