From 57c77a2110616a6a5d0bbdee260936c1c13cad9a Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Tue, 15 Mar 2011 17:15:37 -0400 Subject: Give a proposal number to pluggable transport. --- proposals/ideas/xxx-pluggable-transport.txt | 530 ---------------------------- 1 file changed, 530 deletions(-) delete mode 100644 proposals/ideas/xxx-pluggable-transport.txt (limited to 'proposals/ideas') diff --git a/proposals/ideas/xxx-pluggable-transport.txt b/proposals/ideas/xxx-pluggable-transport.txt deleted file mode 100644 index 201f0ac..0000000 --- a/proposals/ideas/xxx-pluggable-transport.txt +++ /dev/null @@ -1,530 +0,0 @@ -Filename: xxx-pluggable-transport.txt -Title: Pluggable transports for circumvention -Author: Jacob Appelbaum, Nick Mathewson -Created: 15-Oct-2010 -Status: Draft - -Overview - - This proposal describes a way to decouple protocol-level obfuscation - from the core Tor protocol in order to better resist client-bridge - censorship. Our approach is to specify a means to add pluggable - transport implementations to Tor clients and bridges so that they can - negotiate a superencipherment for the Tor protocol. - -Scope - - This is a document about transport plugins; it does not cover - discovery improvements, or bridgedb improvements. While these - requirements might be solved by a program that also functions as a - transport plugin, this proposal only covers the requirements and - operation of transport plugins. - -Motivation - - Frequently, people want to try a novel circumvention method to help - users connect to Tor bridges. Some of these methods are already - pretty easy to deploy: if the user knows an unblocked VPN or open - SOCKS proxy, they can just use that with the Tor client today. - - Less easy to deploy are methods that require participation by both the - client and the bridge. In order of increasing sophistication, we - might want to support: - - 1. A protocol obfuscation tool that transforms the output of a TLS - connection into something that looks like HTTP as it leaves the - client, and back to TLS as it arrives at the bridge. - 2. An additional authentication step that a client would need to - perform for a given bridge before being allowed to connect. - 3. An information passing system that uses a side-channel in some - existing protocol to convey traffic between a client and a bridge - without the two of them ever communicating directly. - 4. A set of clients to tunnel client->bridge traffic over an existing - large p2p network, such that the bridge is known by an identifier - in that network rather than by an IP address. - - We could in theory support these almost fine with Tor as it stands - today: every Tor client can take a SOCKS proxy to use for its outgoing - traffic, so a suitable client proxy could handle the client's traffic - and connections on its behalf, while a corresponding program on the - bridge side could handle the bridge's side of the protocol - transformation. Nevertheless, there are some reasons to add support - for transportation plugins to Tor itself: - - 1. It would be good for bridges to have a standard way to advertise - which transports they support, so that clients can have multiple - local transport proxies, and automatically use the right one for - the right bridge. - - 2. There are some changes to our architecture that we'll need for a - system like this to work. For testing purposes, if a bridge blocks - off its regular ORPort and instead has an obfuscated ORPort, the - bridge authority has no way to test it. Also, unless the bridge - has some way to tell that the bridge-side proxy at 127.0.0.1 is not - the origin of all the connections it is relaying, it might decide - that there are too many connections from 127.0.0.1, and start - paring them down to avoid a DoS. - - 3. Censorship and anticensorship techniques often evolve faster than - the typical Tor release cycle. As such, it's a good idea to - provide ways to test out new anticensorship mechanisms on a more - rapid basis. - - 4. Transport obfuscation is a relatively distinct problem - from the other privacy problems that Tor tries to solve, and it - requires a fairly distinct skill-set from hacking the rest of Tor. - By decoupling transport obfuscation from the Tor core, we hope to - encourage people working on transport obfuscation who would - otherwise not be interested in hacking Tor. - - 5. Finally, we hope that defining a generic transport obfuscation plugin - mechanism will be useful to other anticensorship projects. - -Non-Goals - - We're not going to talk about automatic verification of plugin - correctness and safety via sandboxing, proof-carrying code, or - whatever. - - We need to do more with discovery and distribution, but that's not - what this proposal is about. We're pretty convinced that the problems - are sufficiently orthogonal that we should be fine so long as we don't - preclude a single program from implementing both transport and - discovery extensions. - - This proposal is not about what transport plugins are the best ones - for people to write. We do, however, make some general - recommendations for plugin authors in an appendix. - - We've considered issues involved with completely replacing Tor's TLS - with another encryption layer, rather than layering it inside the - obfuscation layer. We describe how to do this in an appendix to the - current proposal, though we are not currently sure whether it's a good - idea to implement. - - We deliberately reject any design that would involve linking more code - into Tor's process space. - -Design overview - - To write a new transport protocol, an implementer must provide two - pieces: a "Client Proxy" to run at the initiator side, and a "Server - Proxy" to run at the server side. These two pieces may or may not be - implemented by the same program. - - Each client may run any number of Client Proxies. Each one acts like - a SOCKS proxy that accepts connections on localhost. Each one - runs on a different port, and implements one or more transport - methods. If the protocol has any parameters, they are passed from Tor - inside the regular username/password parts of the SOCKS protocol. - - Bridges (and maybe relays) may run any number of Server Proxies: these - programs provide an interface like stunnel: they get connections from the - network (typically by listening for connections on the network) and relay - them to the Bridge's real ORPort. - - To configure one of these programs, it should be sufficient simply to - list it in your torrc. The program tells Tor which transports it - provides. The Tor consensus should carry a new approved version number that - is specific for pluggable transport; this will allow Tor to know when a - particular transport is known to be unsafe safe or non-functional. - - Bridges (and maybe relays) report in their descriptors which transport - protocols they support. This information can be copied into bridge - lines. Bridges using a transport protocol may have multiple bridge - lines. - - Any methods that are wildly successful, we can bake into Tor. - -Specifications: Client behavior - - We extend the bridge line format to allow you to say which method - to use to connect to a bridge. - - The new format is: - "bridge method address:port [[keyid=]id-fingerprint] [k=v] [k=v] [k=v]" - - To connect to such a bridge, the Tor program needs to know which - local SOCKS proxy will support the transport called "method". It - then connects to this proxy, and asks it to connect to - address:port. If [id-fingerprint] is provided, Tor should expect - the public identity key on the TLS connection to match the digest - provided in [id-fingerprint]. If any [k=v] items are provided, - they are configuration parameters for the proxy: Tor should - separate them with semicolons and put them in the user and - password fields of the request, splitting them across the fields - as necessary. If a key or value value must contain a semicolon or - a backslash, it is escaped with a backslash. - - The "id-fingerprint" field is always provided in a field named - "keyid", if it was given. Method names must be C identifiers. - - Example: if the bridge line is "bridge trebuchet www.example.com:3333 - rocks=20 height=5.6m" AND if the Tor client knows that the - 'trebuchet' method is provided by a SOCKS5 proxy on - 127.0.0.1:19999, the client should connect to that proxy, ask it to - connect to www.example.com, and provide the string - "rocks=20;height=5.6m" as the username, the password, or split - across the username and password. - - There are two ways to tell Tor clients about protocol proxies: - external proxies and managed proxies. An external proxy is configured - with - ClientTransportPlugin method socks4 address:port [auth=X] - or - ClientTransportPlugin method socks5 address:port [username=X] [password=Y] - as in - "ClientTransportPlugin trebuchet socks5 127.0.0.1:9999". - This example tells Tor that another program is already running to handle - 'trubuchet' connections, and Tor doesn't need to worry about it. - - A managed proxy is configured with - ClientTransportPlugin exec [options] - as in - "ClientTransportPlugin trebuchet exec /usr/libexec/trebuchet --managed" - This example tells Tor to launch an external program to provide a - socks proxy for 'trebuchet' connections. The Tor client only - launches one instance of each external program with a given set of - options, even if the same executable and options are listed for - more than one method. - - If instead of a transport name, the torrc lists "*" for a managed proxy, - tor uses that proxy for all transports that it supports. So - "ClientTransportPlugin * exec /usr/libexec/tor/foobar" tells Tor - that it should use the foobar plugin for everything that it supports. - - If two proxies support the same method, Tor should use whichever - one is listed first. - - The same program can implement a managed or an external proxy: it just - needs to take an argument saying which one to be. - - See "Managed proxy behavior" for more information on the managed - proxy interface. - -Server behavior - - Server proxies are configured similarly to client proxies. When - launching a proxy, the server must tell it what ORPort it has - configured, and what address (if any) it can listen on. The - server must tell the proxy which (if any) methods it should - provide if it can; the proxy needs to tell the server which - methods it is actually providing, and on what ports. - - When a client connects to the proxy, the proxy may need a way to - tell the server some identifier for the client address. It does - this in-band. - - As before, the server lists proxies in its torrc. These can be - external proxies that run on their own, or managedproxies that Tor - launches. - - An external server proxy is configured as - ServerTransportPlugin method proxy address:port param=val.. - as in - ServerTransportPlugin trebuchet proxy 127.0.0.1:999 rocks=heavy - The param=val pairs and the address are used to make the bridge - configuration information that we'll tell users. - - A managed proxy is configured as - ServerTransportPlugin method exec /path/to/binary [options] - or - ServerTransportPlugin * exec /path/to/binary [options] - - When possible, Tor should launch only one binary of each binary/option - pair configured. So if the torrc contains - - ClientTransportPlugin foo exec /usr/bin/megaproxy --foo - ClientTransportPlugin bar exec /usr/bin/megaproxy --bar - ServerTransportPlugin * exec /usr/bin/megaproxy --foo - - then Tor will launch the megaproxy binary twice: once with the option - --foo and once with the option --bar. - -Managed proxy interface - - When the Tor client launches a client proxy from the command - line, it communicates via environment variables. At a minimum, - it sets: - - {Client and server} - HOME, PATH -- as you'd expect. - - "STATE_LOCATION" -- a directory where the proxy should store - state if it wants to. This directory is not required to - exist, but the proxy SHOULD be able to create it if it - doesn't. The proxy SHOULD NOT store state elsewhere. - - "MANAGED_TRANSPORT_VER=1" -- To tell the proxy which versions - of this configuration protocol Tor supports. Future versions - will give a comma-separated list. Clients MUST accept - comma-separated lists containing any version that they - recognize, and MUST work correctly even if some of the - versions they don't recognize are non-numeric. - - {Client only} - - "CLIENT_TRANSPORTS" -- a comma-separated list of which methods - this client should enable, or * if all methods should be - enabled. The proxy SHOULD ignore methods that it doesn't - recognize. - - {Server only} - - "EXT_SERVER_PORT=addr:portnum" -- A port (probably on localhost) that - speaks the extended server protocol. - - "ORPORT=addr:portnum" -- Our regular ORPort in a form suitable - for local connections. - - "BINDADDR=addr" -- An address on which to listen for local - connections. This might be the advertised address, or might - be a local address that Tor will forward ports to. It MUST - be an address that will work with bind(). - - "SERVER_TRANSPORTS=..." -- A comma-separated list of server - methods that the proxy should support, or * - - The transport proxy replies by writing NL-terminated lines to - stdout. The metaformat is - - Keyword OptArgs NL - OptArgs = Args | - Args = SP ArgChar | Args ArgChar - ArgChar = Any character but NUL or NL - Keyword = KeywordChar | Keyword KeywordChar - KeyWordChar = All alphanumeric characters, dash, and underscore. - - Tor MUST ignore lines with keywords that it doesn't recognize. - - First, the proxy writes "VERSION 1" to say that it supports this - protocol. It must either pick a version that Tor told it about, or - pick no version at all, and say "ERROR no-version\n" and exit. - - The proxy should then open its ports. If running as a client - proxy, it should not use fixed ports; instead it should autoselect - ports to avoid conflicts. A client proxy should by default only - listen on localhost for connections. - - A server proxy SHOULD try listen at a consistent port, though it - SHOULD pick a different one if the port it last used is now allocated. - - A client or server proxy then should tell which methods it has - made available and how. It does this by printing zero or more - CMETHOD and SMETHOD lines to its stdout. These lines look like: - - CMETHOD methodname SOCKS4/SOCKS5 address:port [ARGS=arglist] \ - [OPT-ARGS=arglist] - - as in - - CMETHOD trebuchet SOCKS5 127.0.0.1:19999 ARGS=rocks,height \ - OPT-ARGS=tensile-strength - - The ARGS field lists mandatory parameters that must appear in - every bridge line for this method. The OPT-ARGS field lists - optional parameters. If no ARGS or OPT-ARGS field is provided, - Tor should not check the parameters in bridge lines for this - method. - - The proxy should print a single "CMETHODS DONE" line after it is - finished telling Tor about the client methods it provides. If it - tries to supply a client method but can't for some reason, it - should say: - CMETHOD-ERROR methodname "Message" - - A proxy should tell Tor about the server methods it is providing - by printing zero or more SMETHOD lines. These lines look like: - - SMETHOD methodname address:port [Options] - - If there's an error setting up a configured server method, the - proxy should say: - SMETHOD-ERROR methodname "message" - - The 'address:port' part of an SMETHOD line is the address to put - in the bridge line. The ARGS: part is a list of key-value pairs - that the client needs to know. The Options part is a list of - space-separated K:V flags that Tor should know about. Recognized - options are: - - - FORWARD:1 - - If this option is set, and address:port is not a publicly - accessible address, then the bridge needs to forward some - other address:port to address:port via upnp-helper. - - - ARGS:k=v,k=v,k=v - - If this option is set, the K=V arguments are added to the - extrainfo document. - - - DECLARE:K=V,... - - If this option is set, all the K=V options should be - added as extension entries to the router descriptor. (See - below) - - - USE-EXTPORT:1 - - If this option is set, the server plugin is using the - extended server port. - - SMETHOD and CMETHOD lines may be interspersed. After the list - SMETHOD line, the proxy says "SMETHODS DONE" - - The proxy SHOULD NOT tell Tor about a server or client method - unless it is actually open and ready to use. - - Tor clients SHOULD NOT use any method from a client proxy or - advertise any method from a server proxy UNLESS it is listed as a - possible method for that proxy in torrc, and it is listed by the - proxy as a method it supports. - - Proxies should respond to a single INT signal by closing their - listener ports and not accepting any new connections, but keeping - all connections open, then terminating when connections are all - closed. Proxies should respond to a second INT signal by shutting - down cleanly. - -The extended ORPort protocol. - - Server transports may need to connect to the bridge and pass - additional information about client connections that the bridge - would ordinarily receive from the kernel's TCP stack. To to this, - they connect to the "extended server port" as given in - SERVER_PORT, sent a short amount of information, wait for a - response, and then send the user traffic on that port. - - The extended server port protocol is as follows: - - COMMAND [2 bytes, big-endian] - BODYLEN [2 bytes, big-endian] - BODY [Bodylen bytes] - - Commands sent from the transport to the server are: - - [0x0000] DONE: There is no more information to give. (body ignored) - - [0x0001] USERADDR: an address:port string that represents the user's - address. If the transport doesn't actually do addresses, - this shouldn't be sent. - - Replies sent from tor to the proxy are: - - [0x1001] OKAY: Send the user's traffic. (body ignored) - - [0x1002] DENY: Tor would prefer not to get more traffic from - this address for a while. (body ignored) - - [We could also use an out-of-band signalling method to tell Tor - about client addresses, but that's a historically error-prone way - to go about annotating connections.] - -Advertising bridge methods: - - Bridges put the 'method' lines in their extra-info documents. - - method SP methodname SP address:port SP arglist NL - - The address:port parse are as returned from an SMETHOD line. The - arglist is a K=V,... list as retuned in the ARGS part of the - SMETHOD line. - - If the SMETHOD line includes a DECLARE: part, the routerinfo gets - a new line: - - method-info SP methodname SP arglist NL - -Bridge authority behavior - - We need to specify a way to test different transport methods that - bridges claim to support. We should test as many as possible. We - should NOT require that we have a way to tra - -Bridgedb behavior: - - Bridgedb can, given a set of router descriptors and their - corresponding extrainfo documents, generate a set of bridge lines - for each descriptor. Bridgedb may want to avoid handing out - methods that seem to get bridges blocked quickly. - -Implementation plan - - First, we should implement per-bridge socks settings (as - described above in "manually configuring a client proxy for a - bridge") and the extended-server-port mechanism. This will let - bridges run transport proxies such that they can hand-generate - bridge lines to give to clients for testing. - - Once that's done, we can improve usability a little bit by - implementing external proxies. Once that's done, we can see if we - need any managed proxies, or if the whole idea there is silly. - - If we do, the next most important part seems to be getting - the client-side automatic part written. And once that's done, we - can evaluate how much of the server side is easy for people to do - and how much is hard. - - The "obfsproxy" obfuscating proxy is a likely candidate for an - initial transport, as is Steven Murdoch's http thing or something - similar. - -Notes on plugins to write: - - We should ship a couple of null plugin implementations in one or two - popular, portable languages so that people get an idea of how to - write the stuff. - - 1. We should have one that's just a proof of concept that does - nothing but transfer bytes back and forth. - - 1. We should not do a rot13 one. - - 2. We should implement a basic proxy that does not transform the bytes at all - - 1. We should implement DNS or HTTP using other software (as goodesll - did years ago with DNS) as an example of wrapping existing code into - our plugin model. - - 2. The obfuscated-ssh superencipherment is pretty trivial and pretty - useful. It makes the protocol stringwise unfingerprintable. - - 1. Nick needs to be told firmly not to bikeshed the obfuscated-ssh - superencipherment too badly - - 1. Go ahead, bikeshed my day - - 1. If we do a raw-traffic proxy, openssh tunnels would be the logical choice. - -Appendix: recommendations for transports - - Be free/open-source software. Also, if you think your code might - someday do so well at circumvention that it should be implemented - inside Tor, it should use the same license as Tor. - - Use libraries that Tor already requires. (You can rely on openssl and - libevent being present if current Tor is present.) - - Be portable: most Tor users are on Windows, and most Tor developers - are not, so designing your code for just one of these platforms will - make it either get a small userbase, or poor auditing. - - Think secure: if your code is in a C-like language, and it's hard to - read it and become convinced it's safe, then it's probably not safe. - - Think small: we want to minimize the bytes that a Windows user needs - to download for a transport client. - - Avoid security-through-obscurity if possible. Specify. - - Resist trivial fingerprinting: There should be no good string or regex - to search for to distinguish your protocol from protocols permitted by - censors. - - Imitate a real profile: There are many ways to implement most - protocols -- and in many cases, most possible variants of a given - protocol won't actually exist in the wild. - - - -- cgit v1.2.3-54-g00ecf