[tor-commits] [torspec/master] Finish writing all parts of the pluggable transport doc. Needs another edit.
nickm at torproject.org
nickm at torproject.org
Sat Mar 12 04:23:05 UTC 2011
commit dfc115e2325745da7438b5a787ec7026d11df4e7
Author: Nick Mathewson <nickm at torproject.org>
Date: Fri Mar 11 23:23:25 2011 -0500
Finish writing all parts of the pluggable transport doc. Needs another edit.
---
proposals/ideas/xxx-pluggable-transport.txt | 255 +++++++++++++++++++++++----
1 files changed, 221 insertions(+), 34 deletions(-)
diff --git a/proposals/ideas/xxx-pluggable-transport.txt b/proposals/ideas/xxx-pluggable-transport.txt
index c23ba92..92c14ef 100644
--- a/proposals/ideas/xxx-pluggable-transport.txt
+++ b/proposals/ideas/xxx-pluggable-transport.txt
@@ -172,29 +172,48 @@ Specifications: Client behavior
exec /usr/libexec/tor-proxies/trebuchet [options]", and tells Tor to launch
an external program on-demand to provide a socks proxy for 'trebuchet'
connections. The Tor client only launches one instance of each
- external program, even if the same executable is listed for more than
- one method.
- [What if the options are different? -RD]
+ 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.
The same program can implement a managed or an external proxy: it just
needs to take an argument saying which one to be.
Client proxy behavior
- When launched from the command-line by a Tor client, a transport
- proxy needs to tell Tor which methods and ports it supports. It does
- this by printing one or more CMETHOD: lines to its stdout. These look
- like
+ When the Tor client launches a client proxy from the command line, it
+ sets the environment variable
+ "CLIENT_TRANSPORT_VER=1"
+ to tell the proxy which versions of this configuration protocol
+ it supports. Future versions will give a comma-separated list.
+
+ The Tor client also sets the environment variable
+ CLIENT_TRANSPORTS to a comma-separated list of which methods this
+ client should enable, or * if all methods should be enabled.
+
+ The Tor client also sets STATE_LOCATION to a directory where
+ where the proxy should store state, if it wants to.
+
+ The transport proxy replies by printing "VERSION: 1\n" to its
+ stdout 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.
- CMETHOD: trebuchet SOCKS5 127.0.0.1:19999 ARGS:rocks,height \
- OPT-ARGS:tensile-strength
+ It then needs to tell Tor which methods and ports it
+ supports. It does this by printing zero or more CMETHOD: lines
+ to its stdout. These look like
+
+ 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 "METHODS: DONE" line after it is
+ The proxy should print a single "CMETHODS: DONE" line after it is
finished telling Tor about the methods it provides.
The transport proxy MUST exit cleanly when it receives a SIGTERM from
@@ -213,43 +232,216 @@ Client proxy behavior
is both listed as a possible method for that proxy in torrc, and it
is listed by the proxy as a method it supports.
- [XXXX say something about versioning.]
+Manually configuring a client proxy for a bridge
+
+ All clients will support the methods "socks4" and "socks5". Users can use
+ these to configure a local proxy that doesn't support this plug-in
+ infrastructure method; developers can use them to test new proxies before
+ they have added support for this plug-in in.
+
+ A bridge configured with these methods looks like:
+
+ bridge socks4 www.example.com:8888 keyid=(fingerprint) \
+ proxy=127.0.0.1:9999 auth=xyz
+
+ or
+
+ bridge socks5 www.example.com:8888 keyid=(fingerprint) \
+ proxy=127.0.0.1:9999 user=x password=y
+
+ The "proxy" argument for these methods is mandatory: it specifies a proxy
+ to use when talking to the bridge. The auth or user/password arguments for
+ these methods are optional: they are passed to the proxy either as its
+ authentication part (for socks4) or its username/password part (for
+ socks5).
+
+ The socks4 method uses SOCKS4 if the bridge is given as an IP
+ address, and SOCKS4A if the bridge is given as a hostname.
+
+ [We'll want to implement this part first, since it lets us test out
+ per-bridge proxies, albeit with a user-unfriendly manner.]
Server behavior
- Server proxies are configured similarly to client proxies.
+ 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 proxy is configured as
+
+ ServerTransportPlugin trebuchet address:port [options] -- param=val param=val...
+
+ A managed proxy is configured as
+
+ ServerTransportPlugin trebuchet exec /path/to/binary [options]
+ or
+ ServerTransportPlugin * exec /path/to/binary [options]
+ The param=val pairs in the external proxy configuration, and the address,
+ are advertised to make our bridge configuration.
+
+ 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.
+
+ When the server launches managed binaries, it sets these environment
+ variables:
+ SERVER_TRANSPORT_VER=1
+ (As CLIENT_TRANPORT_VER)
+
+ EXT_SERVER_PORT=addr:portnum
+ (A port 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 to connections. This might be the
+ advertised address, or might be a local address that Tor will
+ forward ports to.)
+
+ SERVER_TRANSPORTS=...
+ (A comma-separated list of server methods that the proxy
+ should support, or *).
+
+ STATE_LOCATION=...
+ (A directory where where the proxy should store state, if it
+ wants to.)
-
+ It also opens an extending server port as described below.
Server proxy behavior
+ The server proxy communicates with the server as the client does.
+ Both start with a version line to indicate which protocol they
+ have chosen (or an error line if it supports no version in common
+ with tor), then it lists a number of SMETHOD lines.
+ Each SMETHOD line is of the form:
- [so, we can have this work like client proxies, where the bridge
- launches some programs, and they tell the bridge, "I am giving you
- method X with parameters Y"? Do you have to take all the methods? If
- not, which do you specify?]
+ SMETHOD: methodname address:port ARGS:k=v,k=v,k=v [Options]
- [Do we allow programs that get started independently?]
+ Or:
- [We'll need to figure out how this works with port forwarding. Is
- port forwarding the bridge's problem, the proxy's problem, or some
- combination of the two?]
+ SMETHOD-ERROR: methodname message
- [If we're using the bridge authority/bridgedb system for distributing
- bridge info, the right place to advertise bridge lines is probably
- the extrainfo document. We also need a way to tell bridgedb
- "don't give out a default bridge line for me"]
+ SMETHOD and CMETHOD lines may be interspersed.
-Server behavior
+ After the list SMETHOD line, the proxy says "SMETHODS: DONE"
+
+ Each SMETHOD lime is a configured and working server method.
+
+ 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.
+
+ - 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)
+
+ Server transports may need to connect to the bridge and pass
+ additional information about client connections that the bridge would
+ ordinarily receive from . 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 besent.
+
+ 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
- Turn this into a draft proposal
+ 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,
+ 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.
- Circulate and discuss on or-dev.
+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
@@ -262,7 +454,7 @@ Implementation plan
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 goodell
+ 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.
@@ -295,8 +487,6 @@ Appendix: recommendations for transports
Think small: we want to minimize the bytes that a Windows user needs
to download for a transport client.
- Specify: if you can't come up with a good explanation [XXX]
-
Avoid security-through-obscurity if possible. Specify.
Resist trivial fingerprinting: There should be no good string or regex
@@ -307,8 +497,5 @@ Appendix: recommendations for transports
protocols -- and in many cases, most possible variants of a given
protocol won't actually exist in the wild.
-Appendix: Raw-traffic transports
- This section describes an optional extension to the proposal above.
- We are not sure whether it is a good idea.
More information about the tor-commits
mailing list