pt-spec.txt

   1
   2                            Pluggable Transport Specification
   3
   4                                      Jacob Appelbaum
   5                                      Nick Mathewson
   6
   7
   8
   9 Overview
  10
  11   This proposal describes a way to decouple protocol-level obfuscation
  12   from the core Tor protocol in order to better resist client-bridge
  13   censorship.  Our approach is to specify a means to add pluggable
  14   transport implementations to Tor clients and bridges so that they can
  15   negotiate a superencipherment for the Tor protocol.
  16
  17   It is based on Proposal 180: see that document and its discussion for
  18   more background and motivation issue, and a discussion of issues in
  19   writing pluggable transpots.
  20
  21 Specifications: Client behavior
  22
  23   We extend the bridge line format to allow you to say which method
  24   to use to connect to a bridge.
  25
  26   The new format is:
  27      Bridge method address:port [[keyid=]id-fingerprint] [k=v] [k=v] [k=v]
  28
  29   To connect to such a bridge, the Tor program needs to know which
  30   SOCKS proxy will support the transport called "method".  It
  31   then connects to this proxy, and asks it to connect to
  32   address:port.  If [id-fingerprint] is provided, Tor should expect
  33   the public identity key on the TLS connection to match the digest
  34   provided in [id-fingerprint].  If any [k=v] items are provided,
  35   they are configuration parameters for the proxy: Tor should
  36   separate them with semicolons and put them in the user and
  37   password fields of the request, splitting them across the fields
  38   as necessary.  If a key or value value must contain a semicolon or
  39   a backslash, it is escaped with a backslash.
  40
  41   Method names must be C identifiers.
  42
  43   For reference, the old bridge format was
  44     Bridge address[:port] [id-fingerprint]
  45   where port defaults to 443 and the id-fingerprint is optional. The
  46   new format can be distinguished from the old one by checking if the
  47   first argument has any non-C-identifier characters. (Looking for a
  48   period should be a simple way.) Also, while the id-fingerprint could
  49   optionally include whitespace in the old format, whitespace in the
  50   id-fingerprint is not permitted in the new format.
  51
  52   Example: if the bridge line is "bridge trebuchet www.example.com:3333
  53      keyid=09F911029D74E35BD84156C5635688C009F909F9 rocks=20 height=5.6m"
  54      AND if the Tor client knows that the 'trebuchet' method is supported,
  55      the client should connect to the proxy that provides the 'trebuchet'
  56      method, ask it to connect to www.example.com, and provide the string
  57      "rocks=20;height=5.6m" as the username, the password, or split
  58      across the username and password.
  59
  60   There are two ways to tell Tor clients about protocol proxies:
  61   external proxies and managed proxies.  An external proxy is configured
  62   with
  63      ClientTransportPlugin <method> socks4 <address:port> [auth=X]
  64   or
  65      ClientTransportPlugin <method> socks5 <address:port> [username=X] [password=Y]
  66   as in
  67      "ClientTransportPlugin trebuchet socks5 127.0.0.1:9999".
  68   This example tells Tor that another program is already running to handle
  69   'trubuchet' connections, and Tor doesn't need to worry about it.
  70
  71   A managed proxy is configured with
  72      ClientTransportPlugin <methods> exec <path> [options]
  73   as in
  74     "ClientTransportPlugin trebuchet exec /usr/libexec/trebuchet --managed".
  75   This example tells Tor to launch an external program to provide a
  76   socks proxy for 'trebuchet' connections. The Tor client only
  77   launches one instance of each external program with a given set of
  78   options, even if the same executable and options are listed for
  79   more than one method.
  80
  81   In managed proxies, <methods> can be a comma-separated list of
  82   pluggable transport method names, as in:
  83     "ClientTransportPlugin pawn,bishop,rook exec /bin/ptproxy --managed".
  84
  85   If instead of a transport method, the torrc lists "*" for a managed
  86   proxy, Tor uses that proxy for all transport methods that the plugin
  87   supports. So "ClientTransportPlugin * exec /usr/libexec/tor/foobar"
  88   tells Tor that Tor should use the foobar plugin for every method that
  89   the proxy supports. See the "Managed proxy interface" section below
  90   for details on how Tor learns which methods a plugin supports.
  91
  92   If two plugins support the same method, Tor should use whichever
  93   one is listed first.
  94
  95   The same program can implement a managed or an external proxy: it just
  96   needs to take an argument saying which one to be.
  97
  98 Server behavior
  99
 100   Server proxies are configured similarly to client proxies.  When
 101   launching a proxy, the server must tell it what ORPort it has
 102   configured, and what address (if any) it can listen on.  The
 103   server must tell the proxy which (if any) methods it should
 104   provide if it can; the proxy needs to tell the server which
 105   methods it is actually providing, and on what ports.
 106
 107   When a client connects to the proxy, the proxy may need a way to
 108   tell the server some identifier for the client address.  It does
 109   this in-band.
 110
 111   As before, the server lists proxies in its torrc.  These can be
 112   external proxies that run on their own, or managed proxies that Tor
 113   launches.
 114
 115   An external server proxy is configured as
 116      ServerTransportPlugin <method> proxy <address:port> <param=val> ...
 117   as in
 118      "ServerTransportPlugin trebuchet proxy 127.0.0.1:999 rocks=heavy".
 119   The param=val pairs and the address are used to make the bridge
 120   configuration information that we'll tell users.
 121
 122   A managed proxy is configured as
 123      ServerTransportPlugin <methods> exec </path/to/binary> [options]
 124   or
 125      ServerTransportPlugin * exec </path/to/binary> [options]
 126
 127   When possible, Tor should launch only one binary of each binary/option
 128   pair configured.  So if the torrc contains
 129
 130      ClientTransportPlugin foo exec /usr/bin/megaproxy --foo
 131      ClientTransportPlugin bar exec /usr/bin/megaproxy --bar
 132      ServerTransportPlugin * exec /usr/bin/megaproxy --foo
 133
 134   then Tor will launch the megaproxy binary twice: once with the option
 135   --foo and once with the option --bar.
 136
 137 Managed proxy interface
 138
 139    When the Tor client or relay launches a managed proxy, it communicates
 140    via environment variables.  At a minimum, it sets (in addition to the
 141    normal environment variables inherited from Tor):
 142
 143       {Client and server}
 144
 145       "TOR_PT_STATE_LOCATION" -- A filesystem directory path where the
 146        proxy should store state if it wants to.  This directory is not
 147        required to exist, but the proxy SHOULD be able to create it if
 148        it doesn't.  The proxy MUST NOT store state elsewhere.
 149       Example: TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
 150
 151       "TOR_PT_MANAGED_TRANSPORT_VER" -- To tell the proxy which
 152        versions of this configuration protocol Tor supports.  Future
 153        versions will give a comma-separated list.  Clients MUST accept
 154        comma-separated lists containing any version that they
 155        recognize, and MUST work correctly even if some of the versions
 156        they don't recognize are non-numeric.  Valid version characters
 157        are non-space, non-comma printing ASCII characters.
 158       Example: TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2,4B
 159
 160       {Client only}
 161
 162       "TOR_PT_CLIENT_TRANSPORTS" -- A comma-separated list of which
 163        methods this client should enable, or * if all methods should
 164        be enabled.  The proxy SHOULD ignore methods that it doesn't
 165        recognize.
 166       Example: TOR_PT_CLIENT_TRANSPORTS=trebuchet,battering_ram,ballista
 167
 168       {Server only}
 169
 170       "TOR_PT_EXTENDED_SERVER_PORT" -- An <address>:<port> where tor
 171        should be listening for connections speaking the extended
 172        ORPort protocol (See the "The extended ORPort protocol" section
 173        below). If tor does not support the extended ORPort protocol,
 174        it MUST use the empty string as the value of this environment
 175        variable.
 176       Example: TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
 177
 178       "TOR_PT_ORPORT" -- Our regular ORPort in a form suitable
 179        for local connections, i.e. connections from the proxy to
 180        the ORPort.
 181       Example: TOR_PT_ORPORT=127.0.0.1:9001
 182
 183       "TOR_PT_SERVER_BINDADDR" -- A comma seperated list of
 184        <key>-<value> pairs, where <key> is a transport name and
 185        <value> is the adress:port on which it should listen for client
 186        proxy connections.
 187        The keys holding transport names must appear on the same order
 188        as they appear on TOR_PT_SERVER_TRANSPORTS.
 189        This might be the advertised address, or might be a local
 190        address that Tor will forward ports to.  It MUST be an address
 191        that will work with bind().
 192       Example:
 193         TOR_PT_SERVER_BINDADDR=trebuchet-127.0.0.1:1984,ballista-127.0.0.1:4891
 194
 195       "TOR_PT_SERVER_TRANSPORTS" -- A comma-separated list of server
 196        methods that the proxy should support, or * if all methods
 197        should be enabled.  The proxy SHOULD ignore methods that it
 198        doesn't recognize.
 199       Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista
 200
 201   The transport proxy replies by writing NL-terminated lines to
 202   stdout.  The line metaformat is
 203
 204       <Line> ::= <Keyword> <OptArgs> <NL>
 205       <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
 206       <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
 207       <OptArgs> ::= <Args>*
 208       <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
 209       <ArgChar> ::= <any US-ASCII character but NUL or NL>
 210       <SP> ::= <US-ASCII whitespace symbol (32)>
 211       <NL> ::= <US-ASCII newline (line feed) character (10)>
 212
 213   Tor MUST ignore lines with keywords that it doesn't recognize.
 214
 215   First, if there's an error parsing the environment variables, the
 216   proxy should write:
 217     ENV-ERROR <errormessage>
 218   and exit.
 219
 220   If the environment variables were correctly formatted, the proxy
 221   should write:
 222     VERSION <configuration protocol version>
 223   to say that it supports this configuration protocol version (example
 224   "VERSION 1"). It must either pick a version that Tor told it about
 225   in TOR_PT_MANAGED_TRANSPORT_VER, or pick no version at all, say:
 226      VERSION-ERROR no-version
 227   and exit.
 228
 229   The proxy should then open its ports.  If running as a client
 230   proxy, it should not use fixed ports; instead it should autoselect
 231   ports to avoid conflicts.  A client proxy should by default only
 232   listen on localhost for connections.
 233
 234   A server proxy SHOULD try to listen at a consistent port, though it
 235   SHOULD pick a different one if the port it last used is now allocated.
 236
 237   A client or server proxy then should tell which methods it has
 238   made available and how.  It does this by printing zero or more
 239   CMETHOD and SMETHOD lines to its stdout.  These lines look like:
 240
 241    CMETHOD <methodname> socks4/socks5 <address:port> [ARGS=arglist] \
 242         [OPT-ARGS=arglist]
 243
 244   as in
 245
 246    CMETHOD trebuchet socks5 127.0.0.1:19999 ARGS=rocks,height \
 247               OPT-ARGS=tensile-strength
 248
 249   The ARGS field lists mandatory parameters that must appear in
 250   every bridge line for this method. The OPT-ARGS field lists
 251   optional parameters.  If no ARGS or OPT-ARGS field is provided,
 252   Tor should not check the parameters in bridge lines for this
 253   method.
 254
 255   The proxy should print a single "CMETHODS DONE" line after it is
 256   finished telling Tor about the client methods it provides.  If it
 257   tries to supply a client method but can't for some reason, it
 258   should say:
 259     CMETHOD-ERROR <methodname> <errormessage>
 260
 261   A proxy should also tell Tor about the server methods it is providing
 262   by printing zero or more SMETHOD lines.  These lines look like:
 263
 264     SMETHOD <methodname> <address:port> [options]
 265
 266   If there's an error setting up a configured server method, the
 267   proxy should say:
 268     SMETHOD-ERROR <methodname> <errormessage>
 269   as in
 270     SMETHOD-ERROR trebuchet could not setup 'trebuchet' method
 271
 272   The 'address:port' part of an SMETHOD line is the address to put
 273   in the bridge line.  The Options part is a list of space-separated
 274   K:V flags that Tor should know about.  Recognized options are:
 275
 276   SMETHOD and CMETHOD lines may be interspersed, to allow the proxies to
 277   report methods as they become available, even when some methods may
 278   require probing your network, connecting to some kind of peers, etc
 279   before they are set up. After the final SMETHOD line, the proxy says
 280   "SMETHODS DONE".
 281
 282   The proxy SHOULD NOT tell Tor about a server or client method
 283   unless it is actually open and ready to use.
 284
 285   Tor clients SHOULD NOT use any method from a client proxy or
 286   advertise any method from a server proxy UNLESS it is listed as a
 287   possible method for that proxy in torrc, and it is listed by the
 288   proxy as a method it supports.
 289
 290   Proxies should respond to a single INT signal by closing their
 291   listener ports and not accepting any new connections, but keeping
 292   all connections open, then terminating when connections are all
 293   closed.  Proxies should respond to a second INT signal by shutting
 294   down cleanly.
 295
 296   The managed proxy configuration protocol version defined in this
 297   section is "1".
 298   So, for example, if tor supports this configuration protocol it
 299   should set the environment variable:
 300     TOR_PT_MANAGED_TRANSPORT_VER=1