[tor-commits] [torspec/master] interim commit while i clean up proposal 180
arma at torproject.org
arma at torproject.org
Mon Apr 11 19:19:30 UTC 2011
commit 6982edff1b24e5d185245216dae12e1acfec3143
Author: Roger Dingledine <arma at torproject.org>
Date: Mon Apr 11 15:10:21 2011 -0400
interim commit while i clean up proposal 180
---
proposals/180-pluggable-transport.txt | 121 ++++++++++++++++-----------------
1 files changed, 58 insertions(+), 63 deletions(-)
diff --git a/proposals/180-pluggable-transport.txt b/proposals/180-pluggable-transport.txt
index dc0564d..b1836e0 100644
--- a/proposals/180-pluggable-transport.txt
+++ b/proposals/180-pluggable-transport.txt
@@ -102,8 +102,8 @@ Non-Goals
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.
+ We deliberately reject any design that would involve linking the
+ transport plugins into Tor's process space.
Design overview
@@ -188,20 +188,19 @@ Specifications: Client behavior
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 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 proxies support the same method, Tor should use whichever
+ 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.
- See "Managed proxy behavior" for more information on the managed
- proxy interface.
-
Server behavior
Server proxies are configured similarly to client proxies. When
@@ -216,7 +215,7 @@ Server behavior
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
+ external proxies that run on their own, or managed proxies that Tor
launches.
An external server proxy is configured as
@@ -227,9 +226,9 @@ Server behavior
configuration information that we'll tell users.
A managed proxy is configured as
- ServerTransportPlugin method exec /path/to/binary [options]
+ ServerTransportPlugin method exec /path/to/binary [options]
or
- ServerTransportPlugin * exec /path/to/binary [options]
+ 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
@@ -243,12 +242,12 @@ Server behavior
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:
+ When the Tor client or relay launches a managed proxy, it communicates
+ via environment variables. At a minimum, it sets:
{Client and server}
- HOME, PATH -- as you'd expect.
+
+ "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
@@ -272,19 +271,23 @@ Managed proxy interface
{Server only}
- "EXT_SERVER_PORT=addr:portnum" -- A port (probably on localhost) that
- speaks the extended server protocol.
+ "EXTENDED_SERVER_PORT=addr:portnum" -- A port (probably on localhost)
+ that speaks the extended server protocol. (See the "The extended
+ ORPort protocol" section below.)
"ORPORT=addr:portnum" -- Our regular ORPort in a form suitable
- for local connections.
+ for local connections, i.e. connections from the proxy to
+ the ORPort.
- "BINDADDR=addr" -- An address on which to listen for local
+ "BINDADDR=addr" -- An address on which to listen for client proxy
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 *
+ methods that the proxy should support, or * if all methods
+ should be enabled. The proxy SHOULD ignore methods that it
+ doesn't recognize.
The transport proxy replies by writing NL-terminated lines to
stdout. The metaformat is
@@ -300,14 +303,14 @@ Managed proxy interface
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.
+ pick no version at all, 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
+ 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
@@ -334,20 +337,18 @@ Managed proxy interface
should say:
CMETHOD-ERROR methodname "Message"
- A proxy should tell Tor about the server methods it is providing
+ 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]
+ 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:
+ in the bridge line. The Options part is a list of space-separated
+ K:V flags that Tor should know about. Recognized options are:
- FORWARD:1
@@ -363,16 +364,18 @@ Managed proxy interface
- 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)
+ added as extension entries to the router descriptor, so other
+ relays can make use of it. (See below)
- - USE-EXTPORT:1
+ - USE-EXTENDED-PORT: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"
+ SMETHOD and CMETHOD lines may be interspersed, to allow the proxies to
+ report success even when some methods may require probing your network,
+ connecting to some kind of peers, etc. After the last 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.
@@ -388,7 +391,7 @@ Managed proxy interface
closed. Proxies should respond to a second INT signal by shutting
down cleanly.
-The extended ORPort protocol.
+The extended ORPort protocol
Server transports may need to connect to the bridge and pass
additional information about client connections that the bridge
@@ -422,17 +425,17 @@ The extended ORPort protocol.
about client addresses, but that's a historically error-prone way
to go about annotating connections.]
-Advertising bridge methods:
+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
+ arglist is a K=V,... list as returned in the ARGS part of the
SMETHOD line.
- If the SMETHOD line includes a DECLARE: part, the routerinfo gets
+ If the SMETHOD line includes a DECLARE: part, the router descriptor gets
a new line:
method-info SP methodname SP arglist NL
@@ -445,7 +448,7 @@ Bridge authority behavior
transport method before we allow its use: the point of this design
is to remove bottlenecks in transport deployment.
-Bridgedb behavior:
+Bridgedb behavior
Bridgedb can, given a set of router descriptors and their
corresponding extrainfo documents, generate a set of bridge lines
@@ -455,9 +458,10 @@ Bridgedb behavior:
Implementation plan
First, we should implement per-bridge proxies via the "external
- proxy" method described in "Specifications: Client behavior". the
+ proxy" method described in "Specifications: Client behavior". Also,
+ we'll want to build the
extended-server-port mechanism. This will let bridges run
- transport proxies such that they can give bridge lines to
+ transport proxies such that they can generate bridge lines to
give to clients for testing, so long as the user configures and
launches their proxies on their own.
@@ -465,15 +469,15 @@ Implementation plan
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
+ the client-side automation 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.
+ initial transport (trac entry #2760), as is Steven Murdoch's http
+ thing (trac entry #2759) or something similar.
-Notes on plugins to write:
+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
@@ -482,23 +486,15 @@ Notes on plugins to write:
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
+ 2. We should implement DNS or HTTP using other software (as Geoff Goodell
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.
+ 3. 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.
+ 4. If we do a raw-traffic proxy, openssh tunnels would be the logical
+ choice.
Appendix: recommendations for transports
@@ -506,8 +502,9 @@ Appendix: recommendations for transports
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.)
+ Tor already uses OpenSSL, Libevent, and zlib. Before you go and decide
+ to use crypto++ in your transport plugin, ask yourself whether OpenSSL
+ wouldn't be a nicer choice.
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
@@ -529,5 +526,3 @@ Appendix: recommendations for transports
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