Hello all, In an attempt to make Pluggable Transports more accessible to other people, and to have a spec that is more applicable and useful to other projects that seek to use Pluggable Transports for circumvention, I have drafted a re-write of the spec. This is not intended to alter existing behavior, but instead make it clear that the whole "Pluggable Transports" thing isn't just for Tor. Unless people have serious objections, this will replace the existing PT spec, to serve as a stop-gap while the next revision of the PT spec (that does alter behavior) is being drafted/implemented. Regards, -- Yawning Angel
Pluggable Transport Specification (Version 1)
Abstract
Pluggable Transports (PTs) are a generic mechanism for the rapid
development and deployment of censorship circumvention,
based around the idea of modular sub-processes that transform
traffic to defeat censors.
This document specifies the sub-process startup, shutdown,
and inter-process communication mechanisms required to utilize
PTs.
Table of Contents
1. Introduction
1.1. Requirements Notation
2. Architecture Overview
3. Specification
3.1. Pluggable Transport Naming
3.2. Pluggable Transport Configuration Environment Variables
3.2.1. Common Environment Variables
3.2.2. Pluggable Transport Client Environment Variables
3.2.3. Pluggable Transport Server Environment Variables
3.3. Pluggable Transport To Parent Process Communication
3.3.1. Common Messages
3.3.2. Pluggable Transport Client Messages
3.3.3. Pluggable Transport Server Messages
3.4. Pluggable Transport Shutdown
3.5. Pluggable Transport Client Per-Connection Arguments
4. Tor Configuration (torrc directives)
4.1. Client Configuration
4.1.1. ClientTransportPlugin
4.1.2. Bridge
4.2. Server Configuration
4.2.1. ServerTransportPlugin
4.2.2. ServerTransportListenAddr
4.2.3. ServerTransportOptions
5. Anonymity Considerations
6. Future Improvements
7. References
8. Acknowledgments
Appendix A. Example Client Pluggable Transport Session
Appendix B. Example Server Pluggable Transport Session
1. Introduction
This specification describes a way to decouple protocol-level
obfuscation from an application's client/server code, in a manner
that promotes rapid development of obfuscation/circumvention
tools and promotes reuse beyond the scope of the Tor Project's
efforts in that area.
This is accomplished by utilizing helper sub-processes that
implement the necessary forward/reverse proxy servers that handle
the censorship circumvention, with a well defined and
standardized configuration and management interface.
Any application code that implements the interfaces as specified
in this document will be able to use all spec compliant Pluggable
Transports.
1.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
2. Architecture Overview
+------------+ +---------------------------+
| Client App +-- Local Loopback --+ PT Client (SOCKS Proxy) +--+
+------------+ +---------------------------+ |
|
Public Internet (Obfuscated/Transformed traffic) ==> |
|
+------------+ +---------------------------+ |
| Server App +-- Local Loopback --+ PT Server (Reverse Proxy) +--+
+------------+ +---------------------------+
On the client's host, the PT Client software exposes a SOCKS proxy
[RFC1928] to the client application, and obfuscates or otherwise
transforms traffic before forwarding it to the server's host.
On the server's host, the PT Server software exposes a reverse proxy
that accepts connections from PT Clients, and handles reversing the
obfuscation/transformation applied to traffic, before forwarding it
to the actual server software. An optional lightweight protocol
exists to facilitate communicating connection meta-data that would
otherwise be lost such as the source IP address and port
[EXTORPORT].
All PT instances are configured by the respective parent process via
a set of standardized environment variables (3.2) that are set at
launch time, and report status information back to the parent via
writing output in a standardized format to stdout (3.3).
Each invocation of a PT MUST be either a client OR a server.
All PT client forward proxies MUST support either SOCKS 4 or SOCKS 5,
and SHOULD prefer SOCKS 5 over SOCKS 4.
3. Specification
Pluggable Transport proxies follow the following workflow
throughout their lifespan.
1) Parent process sets the required environment values (3.2)
and launches the PT proxy as a sub-process (fork()/exec()).
2) The PT Proxy determines the versions of the PT specification
supported by the parent"TOR_PT_MANAGED_TRANSPORT_VER" (3.2.1)
2.1) If there are no compatible versions, the PT proxy
writes a "VERSION-ERROR" message (3.3.1) to stdout and
terminates.
2.2) If there is a compatible version, the PT proxy writes
a "VERSION" message (3.3.1) to stdout.
3) The PT Proxy parses the rest of the environment values.
3.1) If the environment values are malformed, or otherwise
invalid, the PT proxy writes a "ENV-ERROR" message
(3.3.1) to stdout and terminates.
3.2) Determining if it is a client side forward proxy or
a server side reverse proxy can be done via examining
the "TOR_PT_CLIENT_TRANSPORTS" and "TOR_PT_SERVER_TRANSPORTS"
environment variables.
4) (Client only) If there is an upstream proxy specified via
"TOR_PT_PROXY" (3.2.2), the PT proxy validates the URI
provided.
4.1) If the upstream proxy is unusable, the PT proxy writes
a "PROXY-ERROR" message (3.3.2) to stdout and
terminates.
4.2) If there is a supported and well-formed upstream proxy
the PT proxy writes a "PROXY DONE" message (3.3.2) to
stdout.
5) The PT Proxy initializes the transports and reports the
status via stdout (3.3.2, 3.3.3)
6) The PT Proxy forwards and transforms traffic as appropriate.
7) Upon being signaled to terminate by the parent process (3.4),
the PT Proxy gracefully shuts down.
3.1. Pluggable Transport Naming
Pluggable Transport names serve as unique identifiers, and every
PT MUST have a unique name.
PT names MUST be valid C identifiers. PT names MUST begin with
a letter or underscore, and the remaining characters MUST be
ASCII letters, numbers or underscores. No length limit is
imposted.
PT names MUST satisfy the regular expression "[a-zA-Z_][a-zA-Z0-9_]*".
3.2. Pluggable Transport Configuration Environment Variables
All Pluggable Transport proxy instances are configured by their
parent process at launch time via a set of well defined
environment variables.
The "TOR_PT_" prefix is used for namespacing reasons and does not
indicate any relations to Tor, except for the origins of this
specification.
3.2.1. Common Environment Variables
When launching either a client or server Pluggable Transport proxy,
the following common environment variables MUST be set.
"TOR_PT_MANAGED_TRANSPORT_VER"
Specifies the versions of the Pluggable Transport specification
the parent process supports, delimited by commas. All PTs MUST
accept any well-formed list, as long as a compatible version is
present.
Valid versions MUST consist entirely of non-whitespace,
non-comma printable ASCII characters.
The version of the Pluggable Transport specification as of this
document is "1".
Example:
TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2b,this_is_a_valid_ver
"TOR_PT_STATE_LOCATION"
Specifies an absolute path to a directory where the PT is
allowed to store state that will be persisted across
invocations. The directory is not required to exist when
the PT is launched, however PT implementations SHOULD be
able to create it as required.
PTs MUST only store files in the path provided, and MUST NOT
create or modify files elsewhere on the system.
Example:
TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
"TOR_PT_EXIT_ON_STDIN_CLOSE"
Specifies that the parent process will close the PT proxy's
standard input (stdin) stream to indicate that the PT proxy
should gracefully exit.
PTs MUST NOT treat a closed stdin as a signal to terminate
unless this environment variable is set to "1".
PTs SHOULD treat stdin being closed as a signal to gracefully
terminate if this environment variable is set to "1".
Example:
TOR_PT_EXIT_ON_STDIN_CLOSE=1
3.2.2. Pluggable Transport Client Environment Variables
Client-side Pluggable Transport forward proxies are configured
via the following environment variables.
"TOR_PT_CLIENT_TRANSPORTS"
Specifies the PT protocols the client proxy should initialize,
as a comma separated list of PT names.
PTs SHOULD ignore PT names that it does not recognize.
Parent processes MUST set this environment variable when
launching a client-side PT proxy instance.
Example:
TOR_PT_CLIENT_TRANSPORTS=obfs2,obfs3,obfs4
"TOR_PT_PROXY"
Specifies an upstream proxy that the PT MUST use when making
outgoing network connections. It is a URI [RFC3986] of the
format:
<proxy_type>://[<user_name>[:<password>][@]<ip>:<port>.
The "TOR_PT_PROXY" environment variable is OPTIONAL and
MUST be omitted if there is no need to connect via an
upstream proxy.
Examples:
TOR_PT_PROXY=socks5://tor:test1234@xxxxxxxxxxxx:8000
TOR_PT_PROXY=socks4a://198.51.100.2:8001
TOR_PT_PROXY=http://198.51.100.3:443
3.2.3. Pluggable Transport Server Environment Variables
Server-side Pluggable Transport reverse proxies are configured
via the following environment variables.
"TOR_PT_SERVER_TRANSPORTS"
Specifies the PT protocols the server proxy should initialize,
as a comma separated list of PT names.
PTs SHOULD ignore PT names that it does not recognize.
Parent processes MUST set this environment variable when
launching a server-side PT reverse proxy instance.
Example:
TOR_PT_SERVER_TRANSPORTS=obfs3,scramblesuit
"TOR_PT_SERVER_TRANSPORT_OPTIONS"
Specifies per-PT protocol configuration directives, as a
semicolon-separated list of <key>:<value> pairs, where <key>
is a PT name and <value> 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.
If there are no arguments that need to be passed to any of
PT transport protocols, "TOR_PT_SERVER_TRANSPORT_OPTIONS"
MAY be omitted.
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'.
"TOR_PT_SERVER_BINDADDR"
A comma separated list of <key>-<value> pairs, where <key> is
a PT name and <value> is the <address>:<port> on which it
should listen for incoming client connections.
The keys holding transport names MUST be in the same order as
they appear in "TOR_PT_SERVER_TRANSPORTS".
The <address> MAY be a locally scoped address as long as port
forwarding is done externally.
The <address>:<port> combination MUST be an IP address
supported by `bind()`, and MUST NOT be a host name.
Applications MUST NOT set more than one <address>:<port> pair
per PT name.
If there is no specific <address>:<port> combination to be
configured for any transports, "TOR_PT_SERVER_BINDADDR" MAY
be omitted.
Example:
TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984,scramblesuit-127.0.0.1:4891
"TOR_PT_ORPORT"
Specifies the destination that the PT reverse proxy should forward
traffic to after transforming it as appropriate, as an
<address>:<port>.
Connections to the destination specified via "TOR_PT_ORPORT"
MUST only contain application payload. If the parent process
requires the actual source IP address of client connections
(or other metadata), it should set "TOR_PT_EXTENDED_SERVER_PORT"
instead.
Example:
TOR_PT_ORPORT=127.0.0.1:9001
"TOR_PT_EXTENDED_SERVER_PORT"
Specifies the destination that the PT reverse proxy should
forward traffic to, via the Extended ORPort protocol [EXTORPORT]
as an <address>:<port>.
The Extended ORPort protocol allows the PT reverse proxy to
communicate per-connection metadata such as the PT name and
client IP address/port to the parent process.
If the parent process does not support the ExtORPort protocol,
it MUST set "TOR_PT_EXTENDED_SERVER_PORT" to an empty string.
Example:
TOR_PT_EXTENDED_SERVER_PORT=127.0.0.1:4200
"TOR_PT_AUTH_COOKIE_FILE"
Specifies an absolute filesystem path to the Extended ORPort
authentication cookie, required to communicate with the
Extended ORPort specified via "TOR_PT_EXTENDED_SERVER_PORT".
If the parent process is not using the ExtORPort protocol for
incoming traffic, "TOR_PT_AUTH_COOKIE_FILE" MUST be omitted.
Example:
TOR_PT_AUTH_COOKIE_FILE=/var/lib/tor/extended_orport_auth_cookie
3.3. Pluggable Transport To Parent Process Communication
All Pluggable Transport Proxies communicate to the parent process
via 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)>
The parent process MUST ignore lines received from PT proxies with
unknown keywords.
3.3.1. Common Messages
When a PT proxy first starts up, it must determine which version
of the Pluggable Transports Specification to use to configure
itself.
It does this via the "TOR_PT_MANAGED_TRANSPORT_VER" (3.2.1)
environment variable which contains all of the versions supported
by the application.
Upon determining the version to use, or lack thereof, the PT
proxy responds with one of two messages.
VERSION-ERROR <ErrorMessage>
The "VERSION-ERROR" message is used to signal that there was
no compatible Pluggable Transport Specification version
present in the "TOR_PT_MANAGED_TRANSPORT_VER" list.
The <ErrorMessage> SHOULD be set to "no-version" for
historical reasons but MAY be set to a useful error message
instead.
PT proxies MUST terminate after outputting a "VERSION-ERROR"
message.
Example:
VERSION-ERROR no-version
VERSION <ProtocolVersion>
The "VERSION" message is used to signal the Pluggable Transport
Specification version (as in "TOR_PT_MANAGED_TRANSPORT_VER")
that the PT proxy will use to configure it's transports and
communicate with the parent process.
The version for the environment values and reply messages
specified by this document is "1".
PT proxies MUST either report an error and terminate, or output
a "VERSION" message before moving on to client/server proxy
initialization and configuration.
Example:
VERSION 1
After version negotiation has been completed the PT proxy must
then validate that all of the required environment variables are
provided, and that all of the configuration values supplied are
well formed.
At any point, if there is an error encountered related to
configuration supplied via the environment variables, it MAY
respond with an error message and terminate.
ENV-ERROR <ErrorMessage>
The "ENV-ERROR" message is used to signal the PT proxy's
failure to parse the configuration environment variables (3.2).
The <ErrorMessage> SHOULD consist of a useful error message
that can be used to diagnose and correct the root cause of
the failure.
PT proxies MUST terminate after outputting a "ENV-ERROR"
message.
Example:
ENV-ERROR No TOR_PT_AUTH_COOKIE_FILE when TOR_PT_EXTENDED_SERVER_PORT set
3.3.2. Pluggable Transport Client Messages
After negotiating the Pluggable Transport Specification version,
PT client proxies MUST first validate "TOR_PT_PROXY" (3.2.2) if
it is set, before initializing any transports.
Assuming that an upstream proxy is provided, PT client proxies
MUST respond with a message indicating that the proxy is valid,
supported, and will be used OR a failure message.
PROXY DONE
The "PROXY DONE" message is used to signal the PT proxy's
acceptance of the upstream proxy specified by "TOR_PT_PROXY".
PROXY-ERROR <ErrorMessage>
The "PROXY-ERROR" message is used to signal that the upstream
proxy is malformed/unsupported or otherwise unusable.
PT proxies MUST terminate immediately after outputting a
"PROXY-ERROR" message.
Example:
PROXY-ERROR SOCKS 4 upstream proxies unsupported.
After the upstream proxy (if any) is configured, PT clients then
iterate over the requested transports in "TOR_PT_CLIENT_TRANSPORTS"
and initialize the listeners.
For each transport initialized, the PT proxy reports the listener
status back to the parent via messages to stdout.
CMETHOD <transport> <'socks4','socks5'> <address:port>
The "CMETHOD" message is used to signal that a requested
PT transport has been launched, the protocol which the parent
should use to make outgoing connections, and the IP address
and port that the PT transport's forward proxy is listening on.
Example:
CMETHOD trebuchet socks5 127.0.0.1:19999
CMETHOD-ERROR <transport> <ErrorMessage>
The "CMETHOD-ERROR" message is used to signal that
requested PT transport was unable to be launched.
Example:
CMETHOD-ERROR trebuchet no rocks available
Once all PT transports have been initialized (or have failed), the
PT proxy MUST send a final message indicating that it has finished
initializing.
CMETHODS DONE
The "CMETHODS DONE" message signals that the PT proxy has
finished initializing all of the transports that it is capable
of handling.
Upon sending the "CMETHODS DONE" message, the PT proxy
initialization is complete.
Notes:
- Unknown transports in "TOR_PT_CLIENT_TRANSPORTS" are ignored
entirely, and MUST NOT result in a "CMETHOD-ERROR" message.
Thus it is entirely possible for a given PT proxy to
immediately output "CMETHODS DONE".
- Parent processes MUST handle "CMETHOD"/"CMETHOD-ERROR"
messages in any order, regardless of ordering in
"TOR_PT_CLIENT_TRANSPORTS".
3.3.3. Pluggable Transport Server Messages
PT server reverse proxies iterate over the requested transports
in "TOR_PT_CLIENT_TRANSPORTS" and initialize the listeners.
For each transport initialized, the PT proxy reports the listener
status back to the parent via messages to stdout.
SMETHOD <transport> <address:port> [options]
The "SMETHOD" message is used to signal that a requested
PT transport has been launched, the protocol which will be
used to handle incoming connections, and the IP address and
port that clients should use to reach the reverse-proxy.
If there is a specific <address:port> provided for a given
PT transport via "TOR_PT_SERVER_BINDADDR", the transport
MUST be initialized using that as the server address.
The OPTIONAL 'options' field is used to pass additional
per-transport information back to the parent process.
The currently recognized 'options' are:
ARGS:[<Key>=<Value>,]+[<Key>=<Value>]
The "ARGS" option is used to pass additional key/value
formatted information that clients will require to use
the reverse proxy.
Equal signs and commas MUST be escaped with a backslash.
Tor: The ARGS are included in the transport line of the
Bridge's extra-info document.
Examples:
SMETHOD trebuchet 198.51.100.1:19999
SMETHOD rot_by_N 198.51.100.1:2323 ARGS:N=13
SMETHOD-ERROR <transport> <ErrorMessage>
The "SMETHOD-ERROR" message is used to signal that
requested PT transport reverse proxy was unable to be
launched.
Example:
SMETHOD-ERROR trebuchet no cows available
Once all PT transports have been initialized (or have failed), the
PT proxy MUST send a final message indicating that it has finished
initializing.
SMETHODS DONE
The "SMETHODS DONE" message signals that the PT proxy has
finished initializing all of the transports that it is capable
of handling.
Upon sending the "SMETHODS DONE" message, the PT proxy
initialization is complete.
3.4. Pluggable Transport Shutdown
The recommended way for Pluggable Transport using applications and
Pluggable Transports to handle graceful shutdown is as follows.
- (Parent) Set "TOR_PT_EXIT_ON_STDIN_CLOSE" (3.2.1) when
launching the PT proxy, to indicate that stdin will be used
for graceful shutdown notification.
- (Parent) When the time comes to terminate the PT proxy:
1. Close the PT proxy's stdin.
2. Wait for a "reasonable" amount of time for the PT to exit.
3. Attempt to use OS specific mechanisms to cause graceful
PT shutdown (eg: 'SIGTERM')
4. Use OS specific mechanisms to force terminate the PT
(eg: 'SIGKILL', 'ProccessTerminate()').
- PT proxies SHOULD monitor stdin, and exit gracefully when
it is closed, if the parent supports that behavior.
- PT proxies SHOULD handle OS specific mechanisms to gracefully
terminate (eg: Install a signal handler on 'SIGTERM' that
causes cleanup and a graceful shutdown if able).
- PT proxies SHOULD attempt to detect when the parent has
terminated (eg: via detecting that it's parent process ID haso
changed on U*IX systems), and gracefully terminate.
3.5. Pluggable Transport Client Per-Connection Arguments
Certain PT transport protocols require that the client provides
per-connection arguments when making outgoing connections. On
the server side, this is handled by the "ARGS" optional argument
as part of the "SMETHOD" message.
On the client side, arguments are passed via the authentication
fields that are part of the SOCKS protocol.
First the "<Key>=<Value>" formatted arguments MUST be escaped,
such that all backslash, equal sign, and semicolon characters
are escaped with a backslash.
Second, all of the escaped are concatenated together.
Example:
shared-secret=rahasia;secrets-file=/tmp/blob
Lastly the arguments are transmitted when making the outgoing
connection using the authentication mechanism specific to the
SOCKS protocol version.
- In the case of SOCKS 4, the concatenated argument list is
transmitted in the "USERID" field of the "CONNECT" request.
- In the case of SOCKS 5, the parent process must negotiate
"Username/Password" authentication [RFC1929], and transmit
the arguments encoded in the "UNAME" and "PASSWD" fields.
If the encoded argument list is less than 255 bytes in
length, the "PLEN" field must be set to "1" and the "PASSWD"
field must contain a single NUL character.
4. Tor Configuration (torrc directives)
As the protocol originally was designed to be used by Tor clients
and Bridge relays, this specification also specifies the various
torrc configuration directives required to use PTs with Tor.
PT implementers and non-Tor PT aware applications can ignore this
section entirely.
4.1. Client Configuration
4.1.1. ClientTransportPlugin
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 should launch
forward proxies for.
The standard format of a ClientTransportPlugin line is:
ClientTransportPlugin <transports> exec <path> [<options>]
where <transports> are the (comma-separated) names of the PTs that
this line specifies. <path> is a file-system path pointing to an
executable that supports this PT transport. <options> 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
launch forward proxies that use the "obfs2" and "obfs3" transports
to make outgoing connections.
If two ClientTransportPlugin lines specify the same PT, Tor SHOULD use
whichever one is listed first.
TODO: Document external mode
4.1.2. Bridge
Bridge lines specify how Tor should connect to a bridge. The Bridge
line format is:
Bridge [<transport>] <address>:<port> [<id-fingerprint>] [<k>=<v>] [<k>=<v>] [<k>=<v>]
The PT-specific parts of this format are the [transport] and [k=v]
values.
<transport> is the name of the PT that MUST be used when connecting to
the Bridge, and the <k>=<v> 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 section 3.5.
Upon encountering such a Bridge line in the torrc, Tor iterates over
the ClientTransportPlugin lines and checks if there is a line that
specifies a PT that supports <transport>.
If a corresponding ClientTransportPlugin line is found, Tor is
expected to execute and enable that PT via the process specified in
section 3. If no such line could be found, Tor SHOULD warn the
user that there is no way to utilize that PT.
4.2. Server Configuration
4.2.1. ServerTransportPlugin
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 <transports> exec <path> [<options>]
with the same format as ClientTransportPlugin lines. That is,
<transports> are the (comma-separated) names of the PTs that this
line specifies. <path> is a filesystem path pointing to an
executable that supports this PT transport. <options> are
OPTIONAL 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 section 3).
4.2.2. ServerTransportListenAddr
By default, server Pluggable Transports 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 <transport> <address:port>
Examples:
ServerTransportListenAddr rot26 98.23.4.45:4200
ServerTransportListenAddr sound_pt [::]:1025
4.2.3. ServerTransportOptions
Further configuration parameters (like the <k>=<v> 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 <transport> <k=v> ...
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 section 3.2.3.).
5. Anonymity Considerations
When designing and implementing a Pluggable Transport, care
should be taken to preserve the privacy of clients and to avoid
leaking personally identifying information.
Examples of client related considerations are:
- Not logging client IP addresses to disk.
- Not leaking DNS addresses except when necessary.
- Ensuring that "TOR_PT_PROXY"'s "fail closed" behavior is
implemented correctly.
Additionally, certain obfuscation mechanisms rely on information
such as the server IP address/port being confidential, so clients
also need to take care to preserve server side information
confidential when applicable.
6. Future Improvements
There are several shortcomings with the current specification that
should be addressed in future versions.
In no particular order of importance:
- Limiting "TOR_PT_SERVER_BINDADDR" and "SMETHOD" to one per
transport is overly restrictive in the age of dual-stack
hosts.
- Provisions should exist for using an AF_UNIX sockets instead
of the loopback address where applicable.
- A mechanism should be specified for passing run-time logging
back to the parent process.
- The SOCKS 5 authentication mechanism based argument passing
has an upper limit of 510 bytes. This should be extended.
- Proposal 196 [EXTORPORT] should be incorporated into this
specification.
7. References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R.,
Koblas, D., Jones, L., "SOCKS Protocol Version 5",
RFC 1928, March 1996.
[EXTORPORT] Kadianakis, G., Mathewson, N., "Extended ORPort and
TransportControlPort", Tor Proposal 196, March 2012.
[RFC3986] Berners-Lee, T., Fielding, R., Masinter, L., "Uniform
Resource Identifier (URI): Generic Syntax", RFC 3986,
January 2005.
[RFC1929] Leech, M., "Username/Password Authentication for
SOCKS V5", RFC 1929, March 1996.
8. Acknowledgments
This specification draws heavily from prior versions done by Jacob
Appelbaum, Nick Mathewson, and George Kadianakis.
Appendix A. Example Client Pluggable Transport Session
Environment variables:
TOR_PT_MANAGED_TRANSPORT_VER=1
TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
TOR_PT_EXIT_ON_STDIN_CLOSE=1
TOR_PT_PROXY=socks5://127.0.0.1:8001
TOR_PT_CLIENT_TRANSPORTS=obfs3,obfs4
Messages the PT Proxy writes to stdin:
VERSION 1
PROXY DONE
CMETHOD obfs3 socks5 127.0.0.1:32525
CMETHOD obfs4 socks5 127.0.0.1:37347
CMETHODS DONE
Appendix B. Example Server Pluggable Transport Session
Environment variables:
TOR_PT_MANAGED_TRANSPORT_VER=1
TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state
TOR_PT_EXIT_ON_STDIN_CLOSE=1
TOR_PT_SERVER_TRANSPORTS=obfs3,obfs4
TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984
Messages the PT Proxy writes to stdin:
VERSION 1
SMETHOD obfs3 198.51.100.1:1984
SMETHOD obfs4 198.51.100.1:43734 ARGS:cert=HszPy3vWfjsESCEOo9ZBkRv6zQ/1mGHzc8arF0y2SpwFr3WhsMu8rK0zyaoyERfbz3ddFw,iat-mode=0
SMETHODS DONE
Attachment:
pgpvFqZQihfSb.pgp
Description: OpenPGP digital signature
_______________________________________________ tor-dev mailing list tor-dev@xxxxxxxxxxxxxxxxxxxx https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev