[tor-commits] [torspec/master] Give a proposal number to pluggable transport.
nickm at torproject.org
nickm at torproject.org
Tue Mar 15 21:15:09 UTC 2011
commit 57c77a2110616a6a5d0bbdee260936c1c13cad9a
Author: Nick Mathewson <nickm at torproject.org>
Date: Tue Mar 15 17:15:37 2011 -0400
Give a proposal number to pluggable transport.
---
proposals/000-index.txt | 2 +
proposals/180-pluggable-transport.txt | 530 +++++++++++++++++++++++++++
proposals/ideas/xxx-pluggable-transport.txt | 530 ---------------------------
3 files changed, 532 insertions(+), 530 deletions(-)
diff --git a/proposals/000-index.txt b/proposals/000-index.txt
index be9b4e2..f55afc7 100644
--- a/proposals/000-index.txt
+++ b/proposals/000-index.txt
@@ -100,6 +100,7 @@ Proposals by number:
177 Abstaining from votes on individual flags [OPEN]
178 Require majority of authorities to vote for consensus parameters [OPEN]
179 TLS certificate and parameter normalization [DRAFT]
+180 Pluggable transports for circumvention [OPEN]
Proposals by status:
@@ -132,6 +133,7 @@ Proposals by status:
176 Proposed version-3 link handshake for Tor [for 0.2.3]
177 Abstaining from votes on individual flags
178 Require majority of authorities to vote for consensus parameters
+ 180 Pluggable transports for circumvention
ACCEPTED:
110 Avoiding infinite length circuits [for 0.2.1.x] [in 0.2.1.3-alpha]
117 IPv6 exits [for 0.2.1.x]
diff --git a/proposals/180-pluggable-transport.txt b/proposals/180-pluggable-transport.txt
new file mode 100644
index 0000000..2df0ced
--- /dev/null
+++ b/proposals/180-pluggable-transport.txt
@@ -0,0 +1,530 @@
+Filename: 180-pluggable-transport.txt
+Title: Pluggable transports for circumvention
+Author: Jacob Appelbaum, Nick Mathewson
+Created: 15-Oct-2010
+Status: Open
+
+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 <method> exec <path> [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.
+
+
+
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 <method> exec <path> [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.
-
-
-
More information about the tor-commits
mailing list