Building obfs4proxy for Tor-enabled iOS apps.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status
© 2016 Mike Tigas (@mtigas)
BSD 2-clause License

iObfs is an iOS build of obfs4proxy (alternate repo link) for use inside Tor apps, such as Onion Browser and iCepa.

obfs4proxy is a pluggable transport for Tor, which can allow users to defeat certain types of network censorship. (Read some great information about pluggable transports — and how they work — here and here.)

This work is supported in part by The Guardian Project.

Notes builds an Iobfs4proxy.framework, by using the gomobile bind tool. The current build script uses a fork of obfs4proxy with modifications such that:

  1. it can be built as a framework, with an externally-visible main()
  2. some of the environment variables that obfs4proxy (and other pluggable transports) expect are hard-coded in, such that we "fake" managed mode, per this. the PT_STATE uses the $TMPDIR environment variable, which on iOS contains the path to the app’s designated (sandboxed) temporary directory.
  3. the socks5 ports for the Tor<->obfs4proxy connections are hard-coded so the iOS side knows what to connect to. (TODO: this will be removed once we have a better way to communicate this out from obfs4proxy into the iOS main thread.)

The framework contains a header that exposes a GoIobfs4proxyMain(); function (the original main() from obfs4proxy). Note that this function must be called inside an NSThread subclass, otherwise your iOS app will be blocked on that function call. You can use ObfsThread.h and ObfsThread.m from this repo to do this for you.

In the future, iObfs will wrap the build script, Iobfs4proxy.framework, and ObfsThread utilities in a framework using Carthage to improve reusability -- see branch. A go compilation issue prevents this from working at the moment.

Please see the GitHub issues for known issues and caveats.

Using obfs4proxy in your app

(Note: this framework and these instructions are very much in development, so your mileage may vary. Some comfortability with Tor configuration is assumed.)

Given that you already have an iOS app with integrated Tor. On your machine, you'll also need a recent version of Go to build obfs4proxy. (1.5 should work, but this work has only been tested in Go 1.6.)

Run bash and wait a little while.

Copy Iobfs4proxy.framework/, ObfsThread.h, and ObfsThread.m into your existing Tor-powered iOS app.

Set the following lines in your app’s torrc:

ClientTransportPlugin obfs4 socks5
ClientTransportPlugin meek_lite socks5
ClientTransportPlugin obfs2 socks5
ClientTransportPlugin obfs3 socks5
ClientTransportPlugin scramblesuit socks5

Instantiate Tor normally within your app, then run an ObfsThread instance in your app (you might want to check first that the user has Bridge lines that require the pluggable transport). Something like:

ObfsWrapper *obfsproxy = [[ObfsWrapper alloc] init];
[obfsproxy start];

Then, if a user has the appropriate Bridge lines using one of those tranpsports (and given that you've set UseBridges 1 appropriately), your app’s Tor should successfully use obfuscated bridges.

You can see a short version of this in the example/ directory. The README will guide you through a couple of the commits.