Tor Pluggable Transport Specification The Tor PT team A Table of Contents: 0. Motivation 1. Tor PT interface overview 2. Specification 2.0. Pluggable Transport names 2.1. Tor Configuration 2.1.0. Client Configuration 2.1.0.0. ClientTransportPlugin torrc lines 2.1.0.1. Bridge torrc lines 2.1.0.2. Connecting to a bridge via a client PT proxy 2.1.0.3. Passing PT-specific parameters to a client PT 2.1.1. Server (bridge) Configuration 2.1.1.0. ServerTransportPlugin lines 2.1.1.1. Passing PT-specific parameters to a server PT 2.1.1.2. Specify the bind address of a server PT 2.2. Managed proxy interface 2.2.0. Tor -> PT communication (environment variables) 2.2.1. PT -> Tor communication (stdout) 2.2.1.0. Client PT behaviour (CMETHOD lines) 2.2.1.1. Server PT behaviour (SMETHOD lines) 2.2.2. Managed proxy protocol behaviour +---- Extended ORPort | connection v +-----------+ +------------+ SOCKS -> +-----| PT client |------------| PT server |----+ connection | +-----------+ ^ +------------+ | | | | +------------+ Obfuscated +--------------+ | Tor Client | traffic | Tor Bridge | +------------+ +--------------+ 0. Motivation This specification describes how Tor uses Pluggable Transports (PTs). This document is different from pt-spec.txt because it contains Tor-specific information, whereas the pt-spec.txt aims to be system-independent. 1. Tor PT interface overview Pluggable Transports must implement a specific interface to be able to harmoniously coordinate with Tor. This article attempts to document this interface. TODO: Make this section more useful (SOCKS, ExtORport, etc.) 2. Specification 2.0. Pluggable Transport names Tor treats Pluggable Transport names as unique identifiers. Every PT MUST have a unique name. Furthermore, PT names MUST be C identifiers. That is, PT names MUST begin with a letter or underscore and the rest of the characters be letters, numbers or underscores. No length limit is imposed. PT names MUST satisfy the regular expression "[a-zA-Z_][a-zA-Z0-9_]*". 2.1. Tor Configuration 2.1.0. Client Configuration Users use the Tor configuration file (torrc) to specify if and how Pluggable Transports should be used. Specifically, a user is expected to use the Bridge and ClientTransportPlugin torrc lines to configure their PTs. 2.1.0.0. ClientTransportPlugin torrc lines ClientTranportPlugin torrc lines are used by Tor to configure Pluggable Transports. They specify the location of the PT executable, and which PT protocols the executable is able to perform. The standard format of a ClientTransportPlugin line is: ClientTransportPlugin exec [] where are the (comma-separated) names of the PTs that this line specifies. is a filesystem path pointing to an executable that can "perform" this PT. are (optional) command-line arguments and switches that should be used when invoking the executable. For example: ClientTransportPlugin obfs2,obfs3 exec /usr/bin/obfsproxy --managed This line tells Tor to launch the executable "/usr/bin/obfsproxy" with the command-line switch "--managed". That executable should be able to perform two PTs: obfs2 and obfs3. If two ClientTransportPlugin lines specify the same PT, Tor SHOULD use whichever one is listed first. TODO: Document external mode 2.1.0.1. Bridge torrc lines Bridge lines specify how Tor should connect to a bridge. The Bridge line format is: Bridge []
: [] [=] [=] [=] The PT-specific parts of this format are the [transport] and [k=v] values. is the name of the PT that MUST be used when connecting to the bridge, and the = values are PT-specific parameters that MUST be passed to the PT when connecting to the bridge (this MAY include keys, passwords or other PT configuration options) as specified in [CLIENTPARAMS]. Upon encountering such a Bridge line in the torrc, Tor iterates over the ClientTransportPlugin lines and checks if there is a line that specifies how is performed. If a corresponding ClientTransportPlugin line is found, Tor is expected to execute and enable that PT via the process specified in [MANAGEDPROXY]. If no such line could be found, Tor SHOULD warn the user that there is no way to perform that PT. When a PT-supporting bridge needs to be used in a Tor circuit, Tor uses the PT as a proxy as specified in 2.1.0.2. 2.1.0.2. Connecting to a bridge via a client PT proxy Consider a fictitious example of the torrc lines: ClientTransportPlugin btc,ltc exec /usr/bin/btcproxy Bridge btc 192.0.2.1:6612 tx_size=0.2 In this example, to connect to the bridge at 192.0.2.1:6612, Tor is expected to use the PT "btc" via the PT proxy at /usr/bin/btcproxy. Using the managed proxy protocol (specified in [MANAGEDPROXY]), the PT proxy exposes a SOCKS proxy server and informs Tor of the address. Tor connects to 192.0.2.1:6612 via the PT SOCKS proxy and routes regular Tor traffic through the SOCKS connection. The PT proxy is expected to transform the Tor traffic to and from the bridge. Furthermore, as "tx_size=0.2" was specified as a PT-specific parameter, Tor will pass that to the PT proxy via the method specified in [CLIENTPARAMS]. 2.1.0.3. Passing PT-specific parameters to a client PT [CLIENTPARAMS] If PT-specific parameters are specified in a Bridge line, Tor MUST pass them to the PT proxy every time a connection is made to that bridge. To do so, the authentication mechanism of the SOCKS protocol is (ab)used. Specifically, if any = values are specified in a Bridge line, Tor should join them with semicolons and place them in the user and password fields of the SOCKS handshake (splitting them across the fields if needed). If a key or value contains a semicolon or a backslash, it is escaped with a backslash. For example: Bridge trebuchet 192.0.2.1:6612 rocks=20 height=5.6m when connecting to that bridge, Tor is expected to encode the PT parameters in the SOCKS handshake as the following string: rocks=20;height=5.6m 2.1.1. Server (bridge) Configuration Server-side PTs are configured similarly to client proxies. Bridge operators use ServerTransportPlugin lines to configure their PTs. If a server-side PT requires additional parameters, they need to be specified using the ServerTransportOptions torrc parameter. Also, instead of using the ORPort, server PTs SHOULD use the Extended ORPort to pass data to Tor. The Extended ORPort protocol is an ORPort enhanced with an additional metadata channel to carry various metadata about client connections (which PT was used, what was the actual IP of the client, etc.). The Extended ORPort is specified in [EXTORPORT]. 2.1.1.0. ServerTransportPlugin lines ServerTransportPlugin lines are used to tell Tor about pluggable transports. They specify where a PT can be found if it needs to provide service for a Tor bridge. The standard format of a ServerTransportPlugin line is: ServerTransportPlugin exec [] with the same format as ClientTransportPlugin lines.That is, are the (comma-separated) names of the PTs that this line specifies. is a filesystem path pointing to an executable that can "perform" this PT. are command-line arguments and switches that should be used when calling the executable. Upon encountering a ServerTransportPlugin line, Tor needs to launch and configure the corresponding PT using the managed proxy protocol (as specified in [MANAGEDPROXY]). 2.1.1.1. Passing PT-specific parameters to a server PT Further configuration parameters (like the = values passed to client PTs using Bridge lines) can be passed to server PTs using the ServerTransportOptions option. The format of the ServerTransportOptions line is: ServerTransportOptions ... For example, a valid instance of this line would be: ServerTransportOptions hieroglyphics locale=egypt which would pass the parameter "locale=egypt" to the hieroglyphics PT. In contrast to the client PT parameters, the server PT parameters are valid for the whole runtime of the PT, instead of only being used per-connection. They are passed to the PT proxy using the managed proxy protocol (as specified in [MANAGEDPROXY]). 2.1.1.2. Specify the bind address of a server PT By default, server PTs will bind to IPADDR_ANY and to a random TCP port the first time they get launched and will attempt to bind to the same port in subsequent runs. A bridge operator that wants to specify a different address or port should use the ServerTransportListenAddr torrc line. The format of such a line is: ServerTransportListenAddr For example, some valid instances of this line would be: ServerTransportListenAddr rot26 98.23.4.45:4200 ServerTransportListenAddr sound_pt [::]:1025 2.2. Launching PT proxies (managed proxy protocol) [MANAGEDPROXY] When Tor is instructed to enable a PT, it launches the executable file specified in the ClientTransportPlugin line or the ServerTransportPlugin line. This can be done using execve(2) or any other process-spawning API. After Tor has launched the PT, the PT must be configured to ensure that the right transports will be used, that it will bind in the proper address/port, etc. To achieve this, Tor and the PT use the "managed proxy protocol". This is a communication protocol where Tor speaks to the PT using environment variables, and the PT replies by printing lines to its stdout. 2.2.0. Tor -> PT communication (environment variables) When the Tor client or relay launches a managed proxy, it communicates via environment variables. At a minimum, TOR MUST set the following enviornment variables: {Both client and server} "TOR_PT_STATE_LOCATION" -- A filesystem directory path where the PT is allowed to store permanent state if required. This directory is not required to exist, but the proxy SHOULD be able to create it if it does not. The proxy MUST NOT store state elsewhere. Example: TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/ "TOR_PT_MANAGED_TRANSPORT_VER" -- Used to tell the proxy which versions of this configuration protocol Tor supports. Clients MUST accept comma-separated lists containing any version that they recognise, and MUST work correctly even if some of the versions they do not recognise are non-numeric. Valid version characters are non-space, non-comma printable ASCII characters. Example: TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2,4B {Client only} "TOR_PT_CLIENT_TRANSPORTS" -- A comma-separated list of the PTs this client should enable. The proxy SHOULD ignore transport names that it doesn't recognise. Example: TOR_PT_CLIENT_TRANSPORTS=trebuchet,battering_ram,ballista "TOR_PT_PROXY" -- This is the address of an outgoing proxy that the pluggable transport proxy MUST use (see proposal 232 for more details). It is of the format: ://[][:][@]: The TOR_PT_PROXY is optional and MAY be omitted if there is no need to connect via an outgoing proxy. Example: socks5://tor:test1234@198.51.100.1:8000 socks4a://198.51.100.2:8001 {Server only} "TOR_PT_EXTENDED_SERVER_PORT" -- An
: where Tor should be listening for connections speaking the extended ORPort protocol (as specified in [EXTORPORT]). 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" -- The
: of the ORPort of the bridge where the PT is supposed to send the deobfuscated traffic. Example: TOR_PT_ORPORT=127.0.0.1:9001 "TOR_PT_SERVER_BINDADDR" -- A comma separated list of - pairs, where is a transport name and is the adress:port on which it should listen for client proxy connections. The keys holding transport names MUST be in the same order as they are in 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 transports that the proxy should support. The proxy SHOULD ignore transport names that it doesn't recognise. Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista "TOR_PT_AUTH_COOKIE_FILE" -- A filesystem path where the proxy should expect to find the authentication cookie to be able to communicate with the Extended ORPort and TransportControlPort. TOR_PT_AUTH_COOKIE_FILE is optional and might not be present in the environment of the proxy. Example: TOR_PT_AUTH_COOKIE_FILE=/var/lib/tor/extended_orport_auth_cookie "TOR_PT_SERVER_TRANSPORT_OPTIONS" -- A semicolon-separated list of : pairs, where is a transport name and is a k=v string value with options that are to be passed to the transport. Colons, semicolons, equal signs and backslashes MUST be escaped with a backslash. TOR_PT_SERVER_TRANSPORT_OPTIONS is optional and might not be present in the environment of the proxy if no options are need to be passed to transports. Example: TOR_PT_SERVER_TRANSPORT_OPTIONS=scramblesuit:key=banana;automata:rule=110;automata:depth=3 will pass to 'scramblesuit' the parameter 'key=banana' and to 'automata' the arguments 'rule=110' and 'depth=3'. 2.2.1. PT -> Tor communication (stdout) The transport proxy replies by writing NL-terminated lines to stdout. The line metaformat is: ::= ::= | ::= ::= * ::= | ::= ::= ::= Tor MUST ignore lines with keywords that it does not recognize. If there is an error parsing the environment variables, the proxy SHOULD write: ENV-ERROR and exit. If the environment variables were correctly formatted, the proxy should write: VERSION to announce the supported configuration protocol version (eg: "VERSION 1"). It MUST either pick a version among those listed in the TOR_PT_MANAGED_TRANSPORT_VER enviornment variable. If no supported versions are listed in the enviornment variable the proxy SHOULD write: 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 only listen on the loopback interface for connections by default. A PT should then tell which transports it has made available and how. It does this by printing zero or more CMETHOD (client) or SMETHOD (server) lines to its stdout. 2.2.1.0. Client PT behaviour 2.2.1.0.0. Client PT outgoing proxy (PROXY lines) If the client PT is provided with a TOR_PT_PROXY environment variable, it MUST make all outgoing network connections via the supplied proxy. If it is unable to do so for any reason (eg: malformed value, unsupported proxy type, unreachable proxy address), it MUST return a `PROXY_ERROR` and terminate. If the value of the TOR_PT_PROXY environment variable is a proxy URL usable by the pluggable transport plugin (as specified by proposal 232-pluggable-transports-through-proxy.txt), the plugin writes to stdout: PROXY DONE On failure it writes: PROXY-ERROR 2.2.1.0.1. Client PT configuration (CMETHOD lines) Client PTs report their transports via zero or more CMETHOD lines, with the following format: CMETHOD socks4/socks5 For example: CMETHOD trebuchet socks5 127.0.0.1:19999 The 'address:port' component of a CMETHOD line is the IP address and TCP port of the SOCKS proxy server the client PT has exposed. If the PT tries to supply a client method but can not for some reason, it MUST write: CMETHOD-ERROR For example: CMETHOD-ERROR trebuchet no rocks available After it is finished communicating all of the client methods it provides, the proxy MUST print a single "CMETHODS DONE" line. At this point the managed proxy configuration is complete. 2.2.1.1. Server PT behaviour (SMETHOD lines) Server PTs report their transports via zero or more SMETHOD lines, with the following format: SMETHOD [options] The 'address:port' component of a SMETHOD line is the IP address and port where the server PT is listening for incoming client connections. The optional 'options' component is a list of space-separated K:V flags that Tor should know about. Recognised options are: - ARGS:K=V,K=V,K=V If this option is set, the K=V arguments are added to Tor's extrainfo document. Equal signs and commas must be escaped with a backslash. If the PT tries to supply a server method but can not for some reason, it MUST write: SMETHOD-ERROR After it is finished communicating all of the server methods it provides, the PT should print a single "SMETHODS DONE" line. At this point the server PT configuration is complete. 2.2.2. Managed proxy protocol behaviour This section specifies some behaviours that Tor and PTs SHOULD abide too while performing the managed proxy protocol: 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 the network, connecting to external peers, etc before they are set up. 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. 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 2.3. Extended ORPort [EXTORPORT] Server-side PTs SHOULD pass additional information about their clients to Tor for statistics gathering. This is done using the Extended ORPort protocol, which is a variant of the ORPort with an extra metadata channel. For example, PTs are expected to use the Extended ORPort metadata channel to inform Tor about the PT used in each connection, so that Tor can keep track on the number of connections per PT. The Extended ORPort protocol is specified in proposal 196-transport-control-ports.txt. TODO: Managed proxy protocol test vectors