--How the pluggable transports factory works--

Pluggable transports make Tor harder to detect. They are "pluggable" and Tor should be able to support a variety of transports [0].

For this reason, it should be easy to write new pluggable transports. Writing a pluggable transport involves understanding how Tor bridges work and how the Tor pluggable transport interface works [1] . Software like obfsproxy and pyptlib (both in Python) might help to abstract away the details of the pluggable transport interface [2].

If you plan to write a pluggable transport, here are a few things that you might want to think about:

- Before you start coding.

If you have a good pluggable transport idea, it would be wise to contact us before spending weeks hacking on it. We might know someone who is already working on a similar concept, or we might be able to help you with the design/implementation of your transport. Send an email to tor-dev@lists.torproject.org (note that tor-dev is a public list. Use tor-assistants@torproject.org if it's your sekrit research project).

Even before coding, you should have a clear threat model in mind for your transport. You should also compose a clean and readable protocol specification document. See [3] for some specs and threat models of already existing pluggable transports.

It's up to you to decide on a programming language for your pluggable transport. We have currently deployed transports written in Python, C and Go. We don't really care which language you end up using, as long as it's multiplatform (works on Windows) and you can write secure and comprehensive code with it.

A pluggable transport should not make users less safe. Note that this means that if you write your transport in C or C++, we will spend much more time nitpicking on your code so that it feels secure. Worst-case-scenario we might ask you to rewrite your transport in a more confidence-inspiring language.

Finally, check out how already existing transports have been deployed. See how their torrc looks like, how Tor communicates with them, etc. Tor expects a certain interface from pluggable transports, and your transport should be able to follow it. If your idea can't work as a Tor pluggable transport, then contact us and we can think of ways to bend it into shape.

- While you are coding

While you are writing your pluggable transport, try to be conservative on the libraries you use. Are you coding in Python and you want to import PySketchCrypto? Make sure that the library is widely used and its code is clean and secure. Feel responsible for the libraries you choose.

Try to think of the end goal while you are writing your pluggable transports. Make sure that the networking architecture you are using is compatible with the one Tor expects from pluggable transports. Don't forget to actually test your pluggable transport with Tor (in the same way that it would get deployed) before you conclude that "it works" (see the ClientTransportPlugin/Bridge torrc options).

- After you finish coding

When you have finished writing your pluggable transport, put it in a git repository. Don't forget to include the threat model and the protocol specification of your transport in your repository. Send an email to the tor-dev mailing list and let us know of your creation.

- After you go public

The final step is to get your transport included in the Pluggable Transport Browser Bundle.

Before this happens we will nitpick on your idea, your threat model and your specification, review your code, request fixes, etc. This might be a frustrating procedure, but hopefully it will result in better and more maintainable software (most likely we will be the ones fixing any bugs in your code after it gets deployed).

After your transort has reached a certain level of legitimacy it will be time to include it in the Pluggable Transport Browser Bundle. This procedure usually involves taking the latest Pluggable Transport Tor Browser Bundle, compiling your transport and your libs, adding them in the bundle, and finally signing it and releasing it to the world.

Refs:

[0]: https://www.torproject.org/docs/pluggable-transports.html.en

[1]: https://gitweb.torproject.org/torspec.git/blob/HEAD:/pt-spec.txt https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/196-transport...

[2]: https://gitweb.torproject.org/pluggable-transports/obfsproxy.git https://gitweb.torproject.org/pluggable-transports/pyptlib.git http://pyptlib.readthedocs.org/en/latest/

[3]: https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/... https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/... https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/... https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/... https://gitweb.torproject.org/flashproxy.git/blob/HEAD:/doc/design.txt