[tor-dev] How the pluggable transports factory works (or: How to deploy your very own pluggable transport)
desnacked at riseup.net
Thu Aug 8 11:53:57 UTC 2013
--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 .
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
 . Software like obfsproxy and pyptlib (both in Python) might help
to abstract away the details of the pluggable transport interface .
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 at lists.torproject.org (note that tor-dev is a public
list. Use tor-assistants at torproject.org if it's your sekrit research
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  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
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.
More information about the tor-dev