Proposal : Integrate obfsproxy with LEAP


obfsproxy is a python framework for obsfuscating traffic between two network points, particularly a client and a server. obfsproxy was initially designed and currently used with Tor software as a tool to obfuscate Tor traffic and bypass censorship tools. obfsproxy supports multiple protocols which specify how the underlying traffic will be transformed, these are called pluggable transports. Apart from using obfsproxy with Tor, it can be used to camouflage other types of traffic such as VPN or SSH connections.

This proposal is aiming to integrate obfsproxy with LEAP.

An overview of the problem

Censorship has a evolved to daily phenomenon in the Internet not only in totalitarian regimes but also in the democratic countries of the world. Censorship tools perform more and more complex operations and have stepped from blocking packets based on the IP address of source or destination, to examining packet’s payload and blocking protocols generally, e.g. blocking SSL/TLS. There’s an ongoing arms race between censors and censorship-resistance and Deep Packet Inspection (DPI) is proved to be a fundamental problem for secure and private internet communications. I expect this will affect sooner or later the accessibility of LEAP provider’s services, rendering them blocked for users behind DPI machines and restrictive firewalls, since LEAP fundamental service is VPN (encrypted internet proxy), a protocol which can be distinguished fairly easily.

An overview of the proposed solution.

My proposed solution aims for the integration of obfsproxy platform with LEAP services. obfsproxy will be integrated both in the leap platform i.e the node instrastructure of the leap service provider and in the leap client application.

On the provider side the administrator will have the ability to deploy nodes with obfsproxy installed and listening to a predefined port. Incoming connections to this port will be forwarded to the OpenVPN server. On the client side, user will be able to turn on obfsproxy and route OpenVPN client traffic to obfsproxy client listening to localhost. Then obfsproxy client will forward VPN traffic to LEAP provider’s known obfsproxy server. Both obfsproxies will use a set of pluggable transport, either obfs3 or scramblesuit. As a result traffic between LEAP client and server will be obfuscated and won’t be distinguished as VPN traffic thus making them more difficult to block.


  • obfsproxy integration with LEAP improves the accessibility level of LEAP services for users operating in restrictive network environments. obfsproxy will provide a pluggable transport obfsucating the VPN tunnel between LEAP client and LEAP provider, thus making it more expensive for a censor to identify and block LEAP user’s traffic.
  • obsproxy native support will make LEAP an attractive option for many users who seek to communicate securely even in an environment behind DPI censorship.
  • Choosing obfsproxy as a way to improve LEAP network behaviour and traffic indistinguishability, is a beneficial option since obfsproxy is a software used, actively supported and developped by the Tor project.
  • Additionally, obfsproxy provides just the base for various pluggable transport protocols. In the previously mentioned arms race, obfsproxy won’t be rendered useless when and if an entity starts blocking a specific pluggable transport. Pluggable transports continuously evolve to adapt the censorship reality and can be viewed as modules for the obfsproxy.

Implementation Details

The proposed integration between LEAP and obfsproxy needs to be implemented on two sides : the side of the leap provider infrastructure and the side of the bitmask leap client application.

Leap Platform

I intend to write a puppet module for obfsproxy which will be integrated to leap_platform following the existing puppet scheme. This module will install obfsproxy software and will provide all the necessary configuration, i.e. the address of the VPN server of the provider, the listening port and pluggable transport to use. As of version 0.2.7, obfsproxy supports SOCKS version 5, which is needed to connect with OpenVPN. It will take some time for this version to reach Debian stable, so I should use either Tor’s nightly debian repo or the Python Package Index or build from source. Later on, the Debian stable version can be used.

Additionally I will write a puppet manifest for shorewall, the firewall configuration tool currently used in leap_platform. As long as admin deploys obfsproxy service, iptables should permit traffic at the relevant listening port.

obfsproxy will be setup to listen to an arbitrary port for incoming obfuscated traffic, and will then pass it to the address:port where the OpenVPN server listens to. obfsproxy literally doesn’t care about the traffic it carries, it’s just the mediator.

Following that, leap provider administrator will be given the opportunity to deploy obfsproxy as a service either on the same or different node than the OpenVPN server. Note that deploying on different node shouldn’t be a problem since authentication, confidentiality and integrity are provided by OpenVPN.

Except for the puppet module, leap_platform will have to serve an appropriate .json file containing all the necessary details about how the client connects to the obfsproxy server, i.e. address, port and pluggable transport. At this point, either I could expand eip-service.json or just create a new one.

Bitmask client

On the client side, obfsproxy will have to be included in bitmask application bundle. Version 0.2.7 or newer will be used to support SOCKSv5.

The user should be able to enable OpenVPN traffic obfuscation at will. UI should be modified accordingly, providing a nice way to turn it on and off.

When the user enables obfsuscation, obfsproxy will be started and listen to a certain port at localhost. OpenVPN client will use the ‘socks-proxy’ option directing the traffic locally to obfsproxy which will then forward it to the remote obfsproxy server of the LEAP provider.

Client, while bootstrapping with the provider, will fetch the necessary .json file containing connection details with remote obfsproxy.

Choosing pluggable transport

As described before various pluggable transports can be used with obfsproxy, resulting in different traffic transformation. In the context of this proposal I will stick to the pluggable transports used by Tor obfs bridges, since Tor Network is literally in the frontline of the censorship resistance: obfs3 and scramblesuit.

obfs3 pluggable transport is the main protocol currently used by Tor bridges. obfs3 has no authentication between client and server, thus is susceptible to active probing. This means that the adversary may discover a bridge by simply trying to connect to the address:port. This is actually happenning in China. Selecting obfs3 for LEAP will work only with a patch for OpenVPN (read more below).

Scramblesuit is a fresh pluggable transport designed precisely to evade active probing. For that, scramblesuit uses authentication between client and server via a shared secret . scramblesuit was integrated in obfsproxy in February 2014 and there is a call for bridge operators to deploy the new transport.

With the above considerations I suggest using scramblesuit as transport protocol. There needs to be a shared secret between the provider and the user. This secret will be obtained during the bitmask client bootstrap process, along with the rest of VPN necessary files. Secret can be passed either as parameter when bitmask fires up obfsproxy client or via SOCKSv5 authentication. The obfsproxy authentication will be transparent to user. That way we’ll maintain the goal of usability.

Possible problems

  • During my investigation, an OpenVPN bug relevant to socks proxy’s use came up. This bug pose a problem when using obfs3 pluggable transport. Socks requests authentication although obfs3 doesn’t need any, so the connection fails. scramblesuit on the other hand works even with this bug, since the protocol includes a token authentication between cliend and server. Luckily, Yawning Angel provided a patch, so the problem is when and if will be merged upstream.
  • As I mentioned earlier, the obfsproxy version which supports SOCKSv5 hasn’t reached Debian wheezy. I can definitely use the PyPI repository or build from source, as long as this doesn’t contradict any leap_platform development policy.

Using Bitmask with obfsproxy - A threat model

Defining a threat model is always beneficial both for developers, provider administrators and users. Here’s a raw threat model for the combination of VPN and obfsproxy when using bitmask.

Some asumptions about the software :

  • When obfsproxy is enabled no unobfuscated traffic leaves the client.
  • Provider’s obfsproxy server is alive and listening

Some asumptions about the user :

  • User has obtained a valid copy of bitmask client
  • User has already created an account with some LEAP provider
  • User has fetched all necessary eip files

Some asumptions about the adversary :

  • Adversary uses Deep Packet Inspection technology
  • Adversary can be anywhere in the network path between bitmask client and LEAP provider
  • Adversary doesn’t control user’s computer
  • Adversary is able to distinguish OpenSSL/OpenVPN traffic
  • Adversary actively blocks this class of traffic

Then :

  • Adversary cannot distinguish and/or block user’s traffic, based on payload examination
  • Adversary can still block user’s traffic, based on destination’s address or destination’s port

Reality : The LEAP-obfsproxy combination will work under the asumption that network operator has not blocked traffic destined to LEAP provider’s obfsproxy IP address. This asumption will be true for any newly deployed obfsproxy server addresses. In the case the LEAP provider gains attraction, censor might take measures and block traffic. It’s fairly trivial to find out obfsproxy’s addresses in the same way an ordinary user does. This comes down to the same situation that Tor Project tries to anticipate to with Tor bridges and bridge distribution.

Concluding : obfsproxy is an obfuscation tool to evade payload-inspection-based blocking. If user’s provider obfsproxy address is blocked, then a circumvention tool must be used, such as Tor. Although related and certainly useful, Tor’s integration is not part of this proposal.

A rough timeline

Community Bonding period :

  • Better understand LEAP’s development guidelines and workflow
  • Pick some ’low hanging fruits’ bugs in order to get more familiar with various aspects of LEAP
  • Discuss with mentor(s) further details on the proposed implementation

Coding : May 19 - August 18

  • May 19 - June 23 start working server side writing the puppet module for obfsproxy tweak shorewall
  • June 24 - July 26 start working client side integrate obfsproxy with the rest of the bundle tweak eip
  • July 27 - August 10 documentation testing code refactoring
  • Auguest 11 - August 18 take a breath, evaluate


I came across LEAP project some months before GSoC. My desire, from the beginning, is to set up a LEAP provider. I think that’s one of the keypoints of the existence of LEAP. Giving the opportunity to the wider community to deploy independent service providers via a secure and robust way. We don’t need just a new-generation platform for secure digital communications, we also need decentralization of the services and diversity among the operators. That dream may come true when LEAP is a mature software.

LEAP doesn’t only take care of user’s security but also system administrator’s. User’s data are client side encrypted and controlled by the user. Thus, system administrators won’t be forced to disclose them to a malicious third party. Because they simply won’t have any data.

Since I learned about LEAP I wanted to contribute. GSoC seems to gave me a push.

I spent the last few weeks investigating this integration challenge. I actually managed to use obfsproxy and the scramblesuit pluggable transport, to obfuscate traffic between OpenVPN client and server, as a proof of concept. I used OpenVPN -without the proposed patch by Yawning- and built obfsproxy from source. As transport I selected scramblesuit. It worked.

Then I spent some time to get familiar with leap_cli and leap_platform.

I also deployed a couple of real leap nodes and built bitmask from source.

Post GSoC commitment

By all means I want to contribute to LEAP after the GSoC period. obfsproxy integration is something that will need improvement and maintenance. Apart from that I’m certainly looking forward a stable LEAP version for real provider use, and I’d be happy to give a hand.


My background leans more to deploying and maintaining systems and services. I love exploring, using and supporting free software tools and communities having to do with privacy, anonymity, cryptography. I contribute to the Tor network by maintaining a couple of Tor relays and (obfs) bridges. I also contribute to bitcoin community via maintaining a public electrum server.

I haven’t any considerable block of code publicly contributed to an open source project. You may check the aforementioned activity in github or take a look at some elementary python scripts for Stanford’s Cryptography course.