[tor-commits] [torspec/master] Move implemented parts of proposal 180 to /pt-spec.txt
nickm at torproject.org
nickm at torproject.org
Thu Jun 14 16:51:28 UTC 2012
commit 41f4fcc4816de39bb5f410a73fe800678a32340d
Author: George Kadianakis <desnacked at riseup.net>
Date: Thu Jun 14 18:44:28 2012 +0300
Move implemented parts of proposal 180 to /pt-spec.txt
---
pt-spec.txt | 296 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 296 insertions(+), 0 deletions(-)
diff --git a/pt-spec.txt b/pt-spec.txt
new file mode 100644
index 0000000..c8f107f
--- /dev/null
+++ b/pt-spec.txt
@@ -0,0 +1,296 @@
+
+ Pluggable Transport Specification
+
+ Jacob Appelbaum
+ Nick Mathewson
+
+
+
+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.
+
+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
+ 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.
+
+ Method names must be C identifiers.
+
+ For reference, the old bridge format was
+ Bridge address[:port] [id-fingerprint]
+ where port defaults to 443 and the id-fingerprint is optional. The
+ new format can be distinguished from the old one by checking if the
+ first argument has any non-C-identifier characters. (Looking for a
+ period should be a simple way.) Also, while the id-fingerprint could
+ optionally include whitespace in the old format, whitespace in the
+ id-fingerprint is not permitted in the new format.
+
+ Example: if the bridge line is "bridge trebuchet www.example.com:3333
+ keyid=09F911029D74E35BD84156C5635688C009F909F9 rocks=20 height=5.6m"
+ AND if the Tor client knows that the 'trebuchet' method is supported,
+ the client should connect to the proxy that provides the 'trebuchet'
+ method, 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 <methods> 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.
+
+ In managed proxies, <methods> can be a comma-separated list of
+ pluggable transport method names, as in:
+ "ClientTransportPlugin pawn,bishop,rook exec /bin/ptproxy --managed".
+
+ If instead of a transport method, the torrc lists "*" for a managed
+ proxy, Tor uses that proxy for all transport methods that the plugin
+ supports. So "ClientTransportPlugin * exec /usr/libexec/tor/foobar"
+ tells Tor that Tor should use the foobar plugin for every method that
+ the proxy supports. See the "Managed proxy interface" section below
+ for details on how Tor learns which methods a plugin supports.
+
+ If two plugins 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.
+
+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 managed proxies 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 <methods> 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 or relay launches a managed proxy, it communicates
+ via environment variables. At a minimum, it sets (in addition to the
+ normal environment variables inherited from Tor):
+
+ {Client and server}
+
+ "TOR_PT_STATE_LOCATION" -- A filesystem directory path 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 MUST NOT store state elsewhere.
+ Example: TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
+
+ "TOR_PT_MANAGED_TRANSPORT_VER" -- 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. Valid version characters
+ are non-space, non-comma printing ASCII characters.
+ Example: TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2,4B
+
+ {Client only}
+
+ "TOR_PT_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.
+ Example: TOR_PT_CLIENT_TRANSPORTS=trebuchet,battering_ram,ballista
+
+ {Server only}
+
+ "TOR_PT_EXTENDED_SERVER_PORT" -- An <address>:<port> where tor
+ should be listening for connections speaking the extended
+ ORPort protocol (See the "The extended ORPort protocol" section
+ below). If tor does not support the extended ORPort protocol,
+ it MUST use the empty string as the value of this environment
+ variable.
+ Example: TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
+
+ "TOR_PT_ORPORT" -- Our regular ORPort in a form suitable
+ for local connections, i.e. connections from the proxy to
+ the ORPort.
+ Example: TOR_PT_ORPORT=127.0.0.1:9001
+
+ "TOR_PT_SERVER_BINDADDR" -- A comma seperated list of
+ <key>-<value> pairs, where <key> is a transport name and
+ <value> is the adress:port on which it should listen for client
+ proxy connections.
+ The keys holding transport names must appear on the same order
+ as they appear on TOR_PT_SERVER_TRANSPORTS.
+ 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().
+ Example:
+ TOR_PT_SERVER_BINDADDR=trebuchet-127.0.0.1:1984,ballista-127.0.0.1:4891
+
+ "TOR_PT_SERVER_TRANSPORTS" -- A comma-separated list of server
+ methods that the proxy should support, or * if all methods
+ should be enabled. The proxy SHOULD ignore methods that it
+ doesn't recognize.
+ Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista
+
+ The transport proxy replies by writing NL-terminated lines to
+ stdout. The line metaformat is
+
+ <Line> ::= <Keyword> <OptArgs> <NL>
+ <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
+ <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
+ <OptArgs> ::= <Args>*
+ <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
+ <ArgChar> ::= <any US-ASCII character but NUL or NL>
+ <SP> ::= <US-ASCII whitespace symbol (32)>
+ <NL> ::= <US-ASCII newline (line feed) character (10)>
+
+ Tor MUST ignore lines with keywords that it doesn't recognize.
+
+ First, if there's an error parsing the environment variables, the
+ proxy should write:
+ ENV-ERROR <errormessage>
+ and exit.
+
+ If the environment variables were correctly formatted, the proxy
+ should write:
+ VERSION <configuration protocol version>
+ to say that it supports this configuration protocol version (example
+ "VERSION 1"). It must either pick a version that Tor told it about
+ in TOR_PT_MANAGED_TRANSPORT_VER, or pick no version at all, say:
+ VERSION-ERROR no-version
+ 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 to 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> <errormessage>
+
+ A proxy should also 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> <errormessage>
+ as in
+ SMETHOD-ERROR trebuchet could not setup 'trebuchet' method
+
+ The 'address:port' part of an SMETHOD line is the address to put
+ in the bridge line. The Options part is a list of space-separated
+ K:V flags that Tor should know about. Recognized options are:
+
+ SMETHOD and CMETHOD lines may be interspersed, to allow the proxies to
+ report methods as they become available, even when some methods may
+ require probing your network, connecting to some kind of peers, etc
+ before they are set up. After the final 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 managed proxy configuration protocol version defined in this
+ section is "1".
+ So, for example, if tor supports this configuration protocol it
+ should set the environment variable:
+ TOR_PT_MANAGED_TRANSPORT_VER=1
More information about the tor-commits
mailing list