Pluggable Transports
Pluggable Transports (PTs) were created to help uses who can't access the Tor network due to some type of censorship against Tor.
PTs can transform the Tor traffic flow between the client and the bridge. This way, censors who monitor traffic between the client and the bridge will see innocent-looking transformed traffic instead of the actual Tor traffic. External programs can talk to Tor clients and Tor bridges using the Pluggable Transport API, to make it easier to build interoperable programs.
This wiki page contains:
- Information for the user: how to use it, list of PTs available and other circumvention mechanisms there are available.
- Information if you want to help as a PT bridge operator: tutorials on how to set up different PT bridges.
- Information if you wan to help becoming a PT developer: PT dev guidelines, technical spec, Tor Browser deployment guidelines etc.
- Miscellaneous information that might be interesting for the Tor community and researchers.
How to use Pluggable Transports
More info:
- You can download Tor Browser here.
- See List of Pluggable Transports page for the complete list of PTs.
- Other circumvention systems to know about
Help with the project!
Ways to follow and join the conversation:
| What | Where |
|---|---|
| Pluggable Transports Collaboration Space | https://obfuscation.github.io/ is a web space set up for collaboration on pluggable transports in the wider world outside Tor. |
| Pluggable Transport IRC channel and meetings | You can find us in #tor-dev at the OFTC network. You are welcome to join us if you are interested in researching or developing PTs or if you are generally curious about pluggable transports. |
| Traffic Obfuscation Mailing List | The traffic-obf list (private group, anonymous lurkers disallowed) is for private discussion of traffic obfuscation techniques, including pluggable transports. https://groups.google.com/d/forum/traffic-obf - to subscribe, send an email to traffic-obf+subscribe@googlegroups.com
|
Become a PT bridge operator!
How to set up a bridge with pluggable transports
Once you set up a transport type, your bridge will automatically advertise support for the transport in its descriptor.
obfs4:
- Tutorial on how to install the Debian package.
- obfs4proxy Debian package.
- See "Installation" at https://gitweb.torproject.org/pluggable-transports/obfs4.git/tree/README.md.
FTE:
- fteproxy binaries and pip installation tutorial
- fteproxy Debian package
- How to configure an "fte" bridge
ScrambleSuit:
It's not really useful to run a WebSocket (flash proxy) or meek bridge, unless you plan to use it for your own use. These transports have another layer that chooses which bridges get connected to. If you set up a bridge, it won't be used automatically like it would with the other transports.
Become a PT developer!
Help with current projects:
Want to build a new PT? This information will help guide through what you should consider while designing your PT:
- Guidelines for deploying Pluggable Transports on Tor Browser
- Pluggable Transports Evaluation Criteria
- PT technical spec
If you are lacking ideas but has time to code:
- Check out these ideas for new transports page for some cool suggestions.
Things to consider when adding a new pluggable transport
Read some background from developers
- [tor-dev] How the pluggable transports factory works (or: How to deploy your very own pluggable transport)\ https://lists.torproject.org/pipermail/tor-dev/2013-August/005231.html
- [tor-dev] Criteria for prioritizing pluggable transport work\ https://lists.torproject.org/pipermail/tor-dev/2013-September/005528.html
Strongly consider using a "safe" language
When getting your pluggable transport deployed, things will be considerably smoother if it is written in a memory safe language. There are exceptions to this rule, however as long term maintenance for pluggable transports is most likely going to end up being undertaken in part by developers/volunteers from the Tor project, languages that are harder to shoot yourself in the foot with are strongly preferred (If you have a reason in using something like C, you probably should talk to asn about it first).
Consider common attack vectors for your proposed protocol
At a minimum, your pluggable transport should be resistant to detection by a casual observer (Eg: DPI middleboxes). Note that it is strongly recommended that new pluggable transports be resistant to active probing: (obfs2 and obfs3 provide the minimum standard for the former. Scramblesuit was written to defeat the latter).
Also note that once, Iran terminated all TCP connections which did not look like HTTP after just 60 seconds.
If you are going to mimic/reuse an existing protocol, make sure that you read The Parrot is Dead: Observing Unobservable Network Communications and Cover Your ACKs: Pitfalls of Covert Channel Censorship Circumvention.
Ensure that your protocol works on currently supported platforms
Ideally your protocol should run on the platforms officially supported by the Tor project's official releases. This currently is Linux, OS X (Intel), and Microsoft Windows (>= Windows XP).
Miscellaneous PT matters
Visual comparison of different pluggable transports
See AChildsGardenOfPluggableTransports for visual descriptions of how some existing transports appear on the wire.
Combining pluggable transports
We've been working on software that can compose transports together. Our original use case was to combine flashproxy with obfsproxy, so that flashproxy streams are obfuscated using obfs3 and harder to DPI for.
However, such software should also be able to compose together arbitrary transports. For example, we can imagine an HTTP transport that needs to remove the redundancy from its input stream, hence it implements a key exchange before it starts sending application data. Using the transport combiner, the author of the HTTP transport doesn't have to implement this, and can instead just combine her transport with obfs3, effectively having http(obfs3(stream)).
We can also imagine another transport, delayer, that delays traffic so that it evades signatures based on interpacket arrival time. And another transport, chopper, that chops up streams to evade signatures based on packet sizes. Now we can combine these new transports with other transports to evade DPI as needed. For example, http(delayer(obfs3(stream))) is a fun one, or even just delayer(chopper(obfs3(stream))).
While the idea is funny, the software is still unfinished and under development. We have an experimental version that is able to combine flashproxy with obfsproxy, and some design notes on how to generalize that for arbitrary transports. The code can be found here: https://gitweb.torproject.org/pluggable-transports/fog.git and some relevant trac tickets are #9744 (moved), #10061 (moved), #7167 (moved) .
Can I use any proxy as a pluggable transport?
With some extra work, you can use a proxy tool (e.g. GNU httptunnel) as a Tor pluggable transport, by configuring it as an external proxy. See the documentation of the ClientTransportPlugin option—external proxies use the socks4 or socks5 keyword, instead of exec.
Tor supports tighter coupling with pluggable transports that are specifically written to support it. This is known as managed mode. In this mode, Tor takes care of starting and stopping the pluggable transport program. For this, there is a specific interface that pluggable transports must adhere to.
When Tor launches a pluggable transport proxy, it exchanges some information with it (e.g. the directory that the proxy should use if it wants to save files). This information exchange happens using environment variables and the standard output. See the pt-spec for more information. The pyptlib library is able to help with this task.
The client-side of a pluggable transport must implement a SOCKS proxy. When Tor wants to connect to an obfuscated bridge, it connects to the SOCKS proxy, orders a CONNECT towards the bridge host, and then pushes its traffic through the SOCKS proxy. The pluggable transport encodes traffic while it's passing through the SOCKS proxy. (Note: The SOCKS protocol and this architecture is not ideal. See #7153 (moved))
The server-side of a pluggable transport must implement a client of the notorious Extended ORPort protocol. A Tor bridge runs an Extended ORPort server and exchanges some metadata with the transport proxy before receiving the actual client data. For example, the pluggable transport proxy tells Tor the name of the pluggable transport used for each connection, so that it can be recorded as a statistic. See the spec and the code of obfsproxy and pt.DialOr in goptlib.
All the above interfaces and protocols are documented in the pt-spec and a pluggable transport proxy is expected to support them.
Can I use a pluggable transport as a TCP tunnel independently?
Yes. The pt-spec is not hard to implement. As a developer, you can implement this spec to make use of Tor PTs for your application. In this case, your application should act as Tor to communicate with pluggable transports. As end users, there are ptproxy and pluggabletransportadapter projects to use.
Using the Tor pluggable transports for other uses is worth trying because inventing your own circumvention protocol is hard. For example, you can run an HTTP or SOCKS5 proxy server, SSH or OpenVPN over such tunnels, to prevent these traffic from being identified and blocked. In this way, you won't sacrifice speed for anonymity if you just want to access blocked websites.