guardianproject/NetCipher

NetCipher: Secured Networking for Android

Better TLS and Tor App Integration

NetCipher is a library for Android that provides multiple means to improve network security in mobile applications. It provides best practices TLS settings using the standard Android HTTP methods, HttpURLConnection and Apache HTTP Client, provides simple Tor integration, makes it easy to configure proxies for HTTP connections and WebView instances.

More specifically this library provides:

• Hardening of TLS protocol support and cipher suites, especially on older versions of Android (e.g. 4.4 and older)
• Proxied Connection Support: HTTP and SOCKS proxy connection support for HTTP and HTTPS traffic through specific configuration
• OrbotHelper: a utility class to support application integration with Orbot (Tor for Android). Check if its installed, automatically start it, etc.
• Optional, custom certificate store based on the open Debian root CA trust store, which is built with Mozilla's CA collection.

IT MUST BE NOTED, that you can use this library without using Orbot/Tor, but obviously we think using strong TLS/SSL connections over Tor is just about the best thing in the world.

Developers can create their own CACert store using the information provided by our CACertMan project: https://github.com/guardianproject/cacert

It can be used in combination with the MemorizingTrustManager, to support user prompted override for non-validating certificates.

Proxied Connections (aka Orlib)

Once Orbot connects successfully to the Tor network, it offers two proxy servers running on localhost that applications can route their traffic through.

HTTP Proxy: localhost:8118 SOCKS 4/5 Proxy: localhost:9050

The sample project shows the basics of how to use this library to open sockets and make HTTP requests via the SOCKS and HTTP proxies available from Orbot. The standard HttpURLConnection and Apache HTTP Client libraries provide calls to setup proxying. This sample code demonstrates that. All applications using the SOCKS proxy should not resolve their DNS locally, and instead should pass the hostnames through the SOCKS proxy.

Orbot Helper

Provides simple helper to check if Orbot is installed, and whether it is currently running or not. Allows your app to request Orbot to start (user is optionally prompted whether to start or not). Finally, it can show a user prompt to install Orbot, either from Google Play, F-Droid, or via direct APK download as a last resort.

For apps with on-device servers, it can also assists in requesting a Tor Hidden Service from Orbot, and discovering the assigned .onion address.

Downloads

The binary jar, source jar, and javadoc jar are all available on jcenter(), and they all include GPG signatures. To include this library using gradle, add this line to your build.gradle:

implementation 'info.guardianproject.netcipher:netcipher:2.1.0'

Otherwise, the files can also be downloaded directly from bintray.com.

The Strong Builders

The simplest way to use NetCipher to integrate with Tor via Orbot is to use the StrongBuilder implementations. There is one of these for each of the four most popular HTTP client APIs for Android:

(HttpClient is supported by means of the cz.msebera.android:httpclient artifact, not the discontinued HttpClient implementation in the Android SDK)

Requesting the Dependency

You will need up to three dependencies to pull in the right bits for your project.

At minimum, you will need the netcipher base artifact. The StrongBuilder classes are in 2.1.0 and higher:

implementation 'info.guardianproject.netcipher:netcipher:2.1.0'

If you are planning on using HttpURLConnection and StrongConnectionBuilder, that is all you need.

If you plan on using one of the other supported HTTP client APIs and its associated builder, you need to also request the appropriate artifact in addition to requesting the netcipher artifact:

Plus, you will need whatever artifact contains your HTTP client API:

So, for example, a project wishing to use OkHttp3 and NetCipher together would have these dependencies, in addition to any others that the project needs:

implementation 'info.guardianproject.netcipher:netcipher:2.1.0'
implementation 'info.guardianproject.netcipher:netcipher-okhttp3:2.1.0'
implementation 'com.squareup.okhttp3:okhttp:3.4.2'

Creating the OrbotHelper

OrbotHelper is a singleton that manages a lot of the asynchronous communication between your app and Orbot. It is designed to be initialized fairly early on in your app's lifecycle. One likely candidate is to have a custom Application subclass, where you override onCreate() and set up OrbotHelper.

So, you might have something like this:

public class SampleApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();

    OrbotHelper.get(this).init();
  }
}

SampleApplication would need to be registered in your manifest via the <application> tag:

<application
    android:name=".SampleApplication"
    ...
    >

Creating a Builder

Each of the four builder classes has a public constructor, taking a Context as a parameter, that you could use.

A better choice is to call the static forMaxSecurity() method, which also takes a Context as a parameter:

StrongOkHttpClientBuilder builder=StrongOkHttpClientBuilder.forMaxSecurity(this)

(assuming that this is a Context, such as an Activity)

Note that the StrongBuilder classes will hold onto the Application context to avoid memory leaks, so you do not have to worry about that yourself.

The forMaxSecurity() method will ensure that your builder is configured with defaults that maximize security. In particular, it pre-configures the builder with withBestProxy(), described below.

Configuring the Builder

If you want, you can call a series of methods on the builder to further configure its behavior. As the name suggests, methods on these builder classes return the builder object itself, implementing a builder-style API.

The key methods are:

• withBestProxy(), which chooses either the HTTP or the SOCKS proxy offered by Orbot, based on which is available for use by the HTTP client API you are trying to use (e.g., OkHttp3 does not support SOCKS)

• withHttpProxy() or withSocksProxy(), if you are really sure that you want to not use withBestProxy()

• withTrustManagers(), if you have a TrustManager[] that you wish to use to tailor the behavior of any SSL connections made through the HTTP client API

• withWeakCiphers(), if you are running into compatibility issues with the stock selection of supported ciphers

• withTorValidation(), if you want to confirm that not only we use Orbot, but that the communications via Orbot appear to be happening over Tor itself

Of these, withTrustManagers() is the most likely one to be used, and then only if you are implementing special SSL handling (e.g., certificate pinning).

In addition, if you are using HttpURLConnection, you need to call connectTo(), passing in the URL that you wish to connect to (either as a String or a URL). This pre-configuration of the URL is not required for the other three builders, making them much more flexible and reusable.

Requesting a Connection

To get a connection, call build() on the builder. This takes a StrongBuilder.Callback<C> parameter, where C depends on which of the four HTTP client APIs you are using:

Your Callback needs to implement four methods.

The big one is void onConnected(C client), where you are handed an instance of your designated HTTP API connection (e.g., an OkHttpClient for OkHttp3). At this point, the client object is set up to communicate through Tor by means of Orbot, and you are free to start using it for your HTTP requests. However, do not make any assumptions about the thread on which onConnected() is called; please do your HTTP I/O on your own background thread.

You also need to implement:

• void onConnectionException(Exception e), which is called if we ran into some problem, so you can report it to the user, log it to your crash reporting server, etc.

• void onTimeout(), which is called if we were unable to talk to Orbot within 30 seconds

• void onInvalid(), which is called if you requested that we validate the Tor connection and that test failed

Note that build() itself may throw an Exception as well, which you will need to address. Otherwise, build() is asynchronous; you will find out the results via your Callback. Note that the Callback methods may be invoked on any thread — do not assume that the methods will be called on any particular thread.

For example, assuming that this implements StrongBuilder.Callback<OkHttpClient>, you could have code like:

private void doThatHttpThing() {
  try {
    StrongOkHttpClientBuilder
      .forMaxSecurity(this)
      .build(this);
  }
  catch (Exception e) {
    // do something useful
  }
}

@Override
public void onConnected(final OkHttpClient client) {
  // use the OkHttpClient on a background thread
}

@Override
public void onConnectionException(Exception e) {
  // do something useful
}

@Override
public void onTimeout() {
  // do something useful
}

WebView

NetCipher also comes with a helper library which makes it trivial to proxy settings for WebViews. It is also packaged with maven:

dependencies {

    implementation 'info.guardianproject.netcipher:netcipher-webkit:2.0.0-alpha1'

}

On Android 5.0 (API level 21) or newer the simplest way to use WebkitProxy is by initializing it on App start. WebView proxying works globally.

class App extends Application {

    public void onCreate() {
        try {
            WebkitProxy.setProxy(SampleApplication.class.getName(), this.getApplicationContext(), null, "localhost", 8118);
        } catch (Exception e) {
            Log.e(TAG, "Could not start WebkitProxy", e);
        }
    }
}

If you want to support older Android versions you'll also need to pass a reference of your WebView when calling WebkitProxy.setProxy().

Sample Apps

This project contains a sample app for each of the four HTTP client APIs:

Each of the four apps does the same thing: request the latest Stack Overflow android questions and show them in a list. What differs between the samples is which dependency and HTTP client API that they use.

Get help

Do not hesitate to contact us with any questions. The best place to start is our community forums and https://devsq.net. To send a direct message, email [email protected]

We want your feedback! Please report any problems, bugs or feature requests to our issue tracker: