[tor-dev] How the pluggable transports factory works (or: How to deploy your very own pluggable transport)

[George Kadianakis]

 --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 at lists.torproject.org (note that tor-dev is a public
 list. Use tor-assistants at 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-control-ports.txt

[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:/doc/obfs2/obfs2-protocol-spec.txt
https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/doc/obfs2/obfs2-threat-model.txt
https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/doc/obfs3/obfs3-protocol-spec.txt
https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/doc/obfs3/obfs3-threat-model.txt
https://gitweb.torproject.org/flashproxy.git/blob/HEAD:/doc/design.txt