Skip to content
GitLab

PluggableTransports · Changes

Page history
Apply conversion script to all *.md files. authored by Alexander Færøy's avatar Alexander Færøy
Hide whitespace changes
Inline Side-by-side
doc/PluggableTransports.md
View page @ a1a4b621
[[PageOutline]]
[[Image(https://2019.www.torproject.org/images/icon-Obfsproxy.jpg)]]
![https://2019.www.torproject.org/images/icon-Obfsproxy.jpg](https://2019.www.torproject.org/images/icon-Obfsproxy.jpg)
= Pluggable Transports =
# 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.
* 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 =
[[Image(https://2019.www.torproject.org/images/PT/2016-07-how-to-use-PT.png, 830px)]]
# How to use Pluggable Transports
![https://2019.www.torproject.org/images/PT/2016-07-how-to-use-PT.png, 830px](https://2019.www.torproject.org/images/PT/2016-07-how-to-use-PT.png, 830px)
== More info: ==
## More info:
* You can [https://www.torproject.org/projects/torbrowser.html download Tor Browser here].
* See [wiki:doc/PluggableTransports/list List of Pluggable Transports page] for the complete list of PTs.
* [wiki:doc/PluggableTransports/OthersCircumventionSystems Other circumvention systems] to know about
* You can [download Tor Browser here](https://www.torproject.org/projects/torbrowser.html).
* See [List of Pluggable Transports page](./doc/PluggableTransports/list) for the complete list of PTs.
* [Other circumvention systems](./doc/PluggableTransports/OthersCircumventionSystems) 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` ||
# 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'''
## 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''':
**obfs4**:
* [wiki:doc/PluggableTransports/obfs4proxy Tutorial on how to install the Debian package].
* [https://packages.debian.org/search?keywords=obfs4proxy obfs4proxy Debian package].
* [Tutorial on how to install the Debian package](./doc/PluggableTransports/obfs4proxy).
* [obfs4proxy Debian package](https://packages.debian.org/search?keywords=obfs4proxy).
* See "Installation" at https://gitweb.torproject.org/pluggable-transports/obfs4.git/tree/README.md.
'''FTE''':
**FTE**:
* [https://fteproxy.org/download.html fteproxy binaries and pip installation tutorial]
* [https://packages.debian.org/stretch/fteproxy fteproxy Debian package]
* [wiki:doc/fte/setup How to configure an "fte" bridge]
* [fteproxy binaries and pip installation tutorial](https://fteproxy.org/download.html)
* [fteproxy Debian package](https://packages.debian.org/stretch/fteproxy)
* [How to configure an "fte" bridge](./doc/fte/setup)
'''!ScrambleSuit''':
**ScrambleSuit**:
* https://lists.torproject.org/pipermail/tor-relays/2014-February/003886.html
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! ==
## Become a PT developer!
'''Help with current projects:'''
**Help with current projects:**
* [wiki:doc/PluggableTransports/WorkListForDevsToHelpOutWith Some work you can help out with]
* [Some work you can help out with](./doc/PluggableTransports/WorkListForDevsToHelpOutWith)
'''Want to build a new PT?''' This information will help guide through what you should consider while designing your PT:
* [wiki:doc/PluggableTransports/GuidelinesForDeployingPTs Guidelines for deploying Pluggable Transports on Tor Browser]
* [wiki:doc/PluggableTransports/PTEvaluationCriteria Pluggable Transports Evaluation Criteria]
* [https://spec.torproject.org/pt-spec PT technical spec]
**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](./doc/PluggableTransports/GuidelinesForDeployingPTs)
* [Pluggable Transports Evaluation Criteria](./doc/PluggableTransports/PTEvaluationCriteria)
* [PT technical spec](https://spec.torproject.org/pt-spec)
If you are lacking ideas but has time to code:
* Check out these [wiki:doc/PluggableTransports/ideas ideas for new transports page] for some cool suggestions.
* Check out these [ideas for new transports page](./doc/PluggableTransports/ideas) for some cool suggestions.
=== Things to consider when adding a new pluggable transport ===
### Things to consider when adding a new pluggable transport
'''Read some background from developers'''
**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'''
**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'''
**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 [https://www.usenix.org/system/files/conference/foci12/foci12-final2.pdf active probing]: (obfs2 and obfs3 provide the minimum standard for the former. Scramblesuit was written to defeat the latter).
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](https://www.usenix.org/system/files/conference/foci12/foci12-final2.pdf): (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 [https://lists.torproject.org/pipermail/tor-dev/2013-May/004787.html after just 60 seconds].
Also note that once, Iran terminated all TCP connections which did not look like HTTP [after just 60 seconds](https://lists.torproject.org/pipermail/tor-dev/2013-May/004787.html).
If you are going to mimic/reuse an existing protocol, make sure that you read [http://www.cs.utexas.edu/~shmat/shmat_oak13parrot.pdf The Parrot is Dead: Observing Unobservable Network Communications] and [http://www-users.cs.umn.edu/~hopper/ccs13-cya.pdf Cover Your ACKs: Pitfalls of Covert Channel Censorship Circumvention].
If you are going to mimic/reuse an existing protocol, make sure that you read [The Parrot is Dead: Observing Unobservable Network Communications](http://www.cs.utexas.edu/~shmat/shmat_oak13parrot.pdf) and [Cover Your ACKs: Pitfalls of Covert Channel Censorship Circumvention](http://www-users.cs.umn.edu/~hopper/ccs13-cya.pdf).
'''Ensure that your protocol works on currently supported platforms'''
**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 ===
# Miscellaneous PT matters
### Visual comparison of different pluggable transports
See [[AChildsGardenOfPluggableTransports|a Child's Garden of Pluggable Transports]] for visual descriptions of how some existing transports appear on the wire.
=== Combining pluggable transports ===
### 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)).
......@@ -110,22 +111,22 @@ We can also imagine another transport, delayer, that delays traffic so that it e
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, #10061, #7167 .
=== 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 [https://www.torproject.org/docs/tor-manual.html#ClientTransportPlugin ClientTransportPlugin option]—external proxies use the `socks4` or `socks5` keyword, instead of `exec`.
### 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](https://www.torproject.org/docs/tor-manual.html#ClientTransportPlugin)—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.
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 [https://spec.torproject.org/pt-spec pt-spec] for more information. The pyptlib library is able to help with this task.
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](https://spec.torproject.org/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)
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 [http://godoc.org/git.torproject.org/pluggable-transports/goptlib.git#DialOr pt.DialOr] in goptlib.
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](http://godoc.org/git.torproject.org/pluggable-transports/goptlib.git#DialOr) in goptlib.
All the above interfaces and protocols are documented in the [https://spec.torproject.org/pt-spec pt-spec] and a pluggable transport proxy is expected to support them.
All the above interfaces and protocols are documented in the [pt-spec](https://spec.torproject.org/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 [https://spec.torproject.org/pt-spec 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 [https://github.com/gumblex/ptproxy ptproxy] and [https://github.com/twisteroidambassador/pluggabletransportadapter pluggabletransportadapter] projects to use.
### Can I use a pluggable transport as a TCP tunnel independently?
Yes. The [pt-spec](https://spec.torproject.org/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](https://github.com/gumblex/ptproxy) and [pluggabletransportadapter](https://github.com/twisteroidambassador/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.
=== ===
###