TorProxy and Shadow

Tor Proxy LogoShadow Logo

This work is the result of a ten week summer project in the Digital Technology Group. The software was written by Connell Gauld and supervised by Alastair Beresford and Andrew Rice.

TorProxy is an Android application that makes it possible to use Internet sites and services anonymously from a mobile device. This is possible thanks to the Tor network and OnionCoffee. TorProxy can be used by many different Android applications to obtain an anonymous Internet application. For example, if you want to browse website anonymously you will need to install a web browser which uses TorProxy such as Shadow (see below).

Shadow is an Android application that allows you to browse the Web anonymously from your mobile phone. The Shadow browser requires TorProxy (see above) to do this. In addition to using the Tor network to anonymously retrieve information from the Web, Shadow also helps you manage any "cookies" sent to Shadow by Websites to protect your browsing history.

The source code of TorProxy and Shadow are available under the GPL v2 license. Details on how to access our SVN repository to obtain the source code are further down this page. We are happy to answer questions via email.

How to use TorProxy and Shadow

  1. Install TorProxy and Shadow by downloading them from the Android Marketplace.
  2. Start the TorProxy application.
  3. Select a profile for TorProxy:
    • off — do not connect to the tor network.
    • on-demand — only connect to the tor network if a program (e.g. Shadow) needs it. This profile is probably the best choice if you only want to make occassional use of an anonymous Internet connection.
    • always on — maintain an anonymous connection whenever the phone is actively in use.
  4. Once a connection to the Tor network is requested, a notification of the state of the connection appears in the notification bar. A countdown will appear with an estimate of the time remaining before an anonymous connection becomes available. This will take approximately one minute in the first instance, and around 35 seconds when reconnecting after the phone has woken up from a sleep state.
  5. To browse the Web, start the Shadow web browser. Shadow works in a very similar way to the normal Android Web browser. The Menu button reveals the usual browser options. Typing in a URL will initiate an anonymous connection over the Internet via Tor.

Frequently asked questions

Why is the Google Website frequently displayed in a foreign language?

Google determines the language you want from the internet address of your device. When browsing anonymously, the Tor network may provide an internet address from another country. You can click on the "Google.com in English" link to see the website in English.

Why does TorProxy sit with a red dot over the tor icon in the notification bar when connecting via a mobile data connection (i.e. 3G or GPRS)?

Sometimes it takes longer to connect via a mobile data connection than it does when using WiFi. Please be patient and wait until the red dot disappears before trying to connect anonymously via Shadow.

Press coverage

Source download

The TorProxy and Shadow source code is available through anonymous access to our SVN repository:

svn co http://www.cl.cam.ac.uk/research/dtg/code/svn/android-tor

We developed and compile this code using Eclipse with Subclipse and the Android developer SDK. Each of the four modules in the above repository should be checked out as separate eclipse projects (each has its own .project file).

Compiling TorProxyLib

  1. Checkout URL: http://www.cl.cam.ac.uk/research/dtg/code/svn/android-tor/TorProxyLib
  2. Build in Eclipse as normal
  3. Right click on export-torproxylib.jardesc and choose Create Jar

Compiling TorProxy

  1. Checkout URL: http://www.cl.cam.ac.uk/research/dtg/code/svn/android-tor/TorProxy

Compiling Shadow

  1. Checkout URL: http://www.cl.cam.ac.uk/research/dtg/code/svn/android-tor/Shadow

Compiling TorProxyExamples

  1. Checkout URL: http://www.cl.cam.ac.uk/research/dtg/code/svn/android-tor/TorProxyExamples

Documentation for application developers

Overview

In order to anonymize your application's Internet communication:

1. Import TorProxyLib.jar into your project

2. Connect to the TorProxy control service

3. Register for the TorProxy status change broadcast

4. When the Tor connection is available, create your socket and tunnel it through SocksProxy

1. TorProxyLib

This library contains everything you need to allow your application to anonymize its sockets.

Add TorProxyLib.jar to your build path.

2. Connect to the TorProxy control service

The TorProxy service exports an interface which you can use to check the availability of the anonymous connection and register your desire to use it.

Example:

// Keep track of the control service
private ITorProxyControl mControlService = null;
private final IntentFilter torStatusFilter = new IntentFilter(

                TorProxyLib.STATUS_CHANGE_INTENT);


// Service connection to TorProxy service
private ServiceConnection mSvcConn = new ServiceConnection() {

        @Override
        public void onServiceConnected(ComponentName name, IBinder service) {

                mControlService = ITorProxyControl.Stub.asInterface(service);
                // Connected to Control Service
                // Perhaps check Tor status here

        }

        @Override
        public void onServiceDisconnected(ComponentName name) {

                mControlService = null;
                // Connection to Control Service lost
        }

};


@Override
protected void onResume() {

        // ...

        // Register to receive Tor status update broadcasts

        registerReceiver(mBroadcastReceiver, torStatusFilter);

        // Bind to the TorProxy control service
        bindService(new Intent().setComponent(new ComponentName(

                        TorProxyLib.CONTROL_SERVICE_PACKAGE,
                        TorProxyLib.CONTROL_SERVICE_CLASS)), mSvcConn, BIND_AUTO_CREATE);

        // ...

}


@Override
protected void onPause() {

        // ...

        // Registered in onResume so unregister here
        unregisterReceiver(mBroadcastReceiver);
        unbindService(mSvcConn);

        // ...
}


private BroadcastReceiver mBroadcastReceiver = new BroadcastReceiver() {

        @Override
        public void onReceive(Context context, Intent intent) {

                if (TorProxyLib.STATUS_CHANGE_INTENT.equals(intent.getAction())) {

                        // TorProxy has broadcast a Tor status update
                        // Check Tor status here
                }
        }
};

Using the control service

The control service has a current profile. The anonymous data connection has a current state.

The profiles are:

  • PROFILE_OFF - the anonymous data connection is turned off
  • PROFILE_ONDEMAND - you may have to register your interest to get an anonymous connection
  • PROFILE_ON - the anonymous data connection will be made available (automatically) if possible

The states are:

  • STATUS_UNAVAILABLE - the anonymous data connection is currently unavailable
  • STATUS_REQUIRES_DEMAND - the anonymous data connection is currently off but may be available if you register your demand
  • STATUS_CONNECTING - the anonymous data connection is being set up
  • STATUS_ON - the anonymous data connection is available for use

You can get the current profile using:

mControlService.getProfile()

You can get the current status using:

mControlService.getStatus()

Tunneling a socket through SocksProxy

int proxyPort = mControlService.getSOCKSPort();

SocksProxy proxy = new SocksProxy(proxyPort);

Socket s = proxy.connectSocksProxy(null, destHost, destPort, 0);

// Use s as normal