LEAP GSOC progress report, no1

Hello world, it’s been a week since i “officially” contribute to the LEAP project. \o/

Here’s a raw status report of my progress so far:


Started working on leap_platform. The idea so far is to have the possibility to deploy an obfsproxy service instance either alongside the eip service or standalone.

  • I wrote a puppet module that installs obfsproxy from wheezy-backports, creates the respective user and group, creates the necessary configuration files, logging files, init script and starts it as daemon.
  • I wrote the aforementioned init script to daemonize obfsproxy. No such script is included in the debian package at the moment.
  • A configuration file containing all the necessary parameters for obfsproxy is placed in /etc/obfsproxy.con and is then sourced by the init script. In specific, parameters contained are the pluggable transport used by obfsproxy, a special parameter for the transport, the listening port, the destination ip address and port to which the traffic will be forwarded and the log level of the daemon.
  • A manifest was added to site_shorewall so as firewall permits incoming traffic to the port obfsproxy listens to.
  • provider_base/services/obfsproxy.json was added. This is the base of the obfsproxy service. It’s compiled on leap platform admin’s side and outputs the shared secret of scramblesuit, the listening port and the openvpn gateway.

You can check the above commits and more in the feature/obfsproxy branch.


  • Two new macros are used in obsfproxy.json, one to pick a random base32 encoded string for scramblesuit transport and one to pick a random port within a specified range.

Those macros were merged in leap_cli. feature/obfsproxy_macros branch.

Obfsproxy and Scramblesuit

  • An issue was raised with the obfsproxy daemon. The pluggable transport which was chosen is scramblesuit. Scramblesuit protocol defines a shared password between a client and server, and this password is given from command line when obfsproxy is run unmanaged i.e. not managed by Tor. That way the password is visible in the system’s process list, which is considered a problem. This was actually reported some time ago, when obfs2 pluggable transport was still used.

I wrote and suggested a patch for the scramblesuit transport used in obfsproxy, so as the password can be read from a file. You can find more info on that issue, as well as the patch at the relevant ticket.

Things to be done

  • As long as daemon is configured and running, obfsproxy’s connection details should be passed to web_app. Authenticated clients should then be able to fetch a new version of eip-service.json via the api, which will contain everything necessary for them to obfuscate their connection.

Many thanks to every single person that helped me with comments, reviews, advices. Thanks!

OpenVPN socks proxy authentication methods, bug #377 fixed

obsfproxy is a tool providing traffic obfuscation between a client and a server. obfsproxy supports different obfuscation protocols, called pluggable transports. These define how the underlying traffic will be transformed eventually. Although obfsproxy is mainly used in Tor bridges, one can use it to obfuscate different kind of traffic such as VPN traffic.

While using OpenVPN with obfsproxy one has to use the socks-proxy functionality both client and server side, in order to route VPN traffic through the obfuscated channel. obfsproxy implements SOCKSv5 and supports socks authentication as a means to pass parameters to the pluggable transport in use.

SOCKS Protocol Version 5, as described in RFC 1928, defines various authentication methods, including “no-authentication” and “username-passwod”. Socks client advertises its desired methods and then socks server picks freely one among them.

So the problem was that OpenVPN client was advertising both “no-authentication” and “username-password” methods, even if the client did not want to authenticate or did not have authentication credentials at all. In RFC 1928 there is no explicit preference order of the authentication methods the client advertises. Since client was always advertising both methods, obfsproxy socks server picked “username-password”. This posed a problem when using a pluggable transport that does not actually have any parameters or credentials to pass (e.g obfs3). In that case the connection naturally was going to fail.

On the other hand if OpenVPN client did want to use credentials, it should not advertise “no-authentication” method at all.

This situation, described in bug #377, was fixed with a patch in src/openvpn/socks.c and will be part of OpenVPN as of version 2.3.4. After the patch, OpenVPN client forms the authentication negotiation message as follows :

 /* VER = 5, NMETHODS = 1, METHODS = [0 (no auth)] */
 char method_sel[3] = { 0x05, 0x01, 0x00 };
 if (p->authfile[0])
     method_sel[2] = 0x02; /* METHODS = [2 (plain login)] */
 const ssize_t size = send (sd, method_sel, sizeof (method_sel), MSG_NOSIGNAL);

Authentication method defaults to 0x01, meaning “no-authentication”, but if an authentication file is present then “username-password” method is advertised.

OpenVPN 2.3.4 was released on May 2nd 2014.

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
    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.