[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [torspec/master] Give a proposal number to pluggable transport.



commit 57c77a2110616a6a5d0bbdee260936c1c13cad9a
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
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.
-
-
-

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits