Example Apps

Ouinet's test application in Kotlin

Prepare your app for using Ouinet

Add Ouinet lib and Relinker to your dependencies list in app/build.gradle:

dependencies {
    // ...
    implementation 'ie.equalit.ouinet:ouinet-armeabi-v7a:0.20.0'
    implementation 'com.getkeepsafe.relinker:relinker:1.4.4'
}

Import Ouinet in your Android activity and create a private variable to hold the client:

import ie.equalit.ouinet.Ouinet

class MainActivity : AppCompatActivity() {
    private lateinit var ouinet: Ouinet
    // ...
}

Import Config and setup the Ouinet client:

import ie.equalit.ouinet.Config
// ...

class MainActivity : AppCompatActivity() {
    // ...

    override fun onCreate(savedInstanceState: Bundle?) {

        var config = Config.ConfigBuilder(this)
            .setCacheType("bep5-http")
            .build()

        ouinet = Ouinet(this, config)
        ouinet.start()
        // ...
    }
}

Pass config values to Ouinet during the build process

You can have Ouinet keys and passwords added to the client during the building process by Gradle.

You just need to create a local.properties file in the root of this project and set the values as follows before building the app:

CACHE_PUB_KEY="YOUR OUINET CACHE PUB KEY"
INJECTOR_CREDENTIALS="ouinet:YOURINJECTORPASSWORD"
// It's important to keep the new line characters in the beggining and the end
// of certificate delimiters
INJECTOR_TLS_CERT="-----BEGIN CERTIFICATE-----\\n\
ABCDEFG...\
\\n-----END CERTIFICATE-----"

Those values should be loaded by Gradle during the build process in app/build.gradle:

...

Properties localProperties = new Properties()
localProperties.load(rootProject.file('local.properties').newDataInputStream())

android {
    compileSdk 32

    defaultConfig {
        ...
        buildConfigField "String", "CACHE_PUB_KEY", localProperties['CACHE_PUB_KEY']
        buildConfigField "String", "INJECTOR_CREDENTIALS", localProperties['INJECTOR_CREDENTIALS']
        buildConfigField "String", "INJECTOR_TLS_CERT", localProperties['INJECTOR_TLS_CERT']
    }
    ...
}

and can be referenced after that from Kotlin via BuildConfig:

var config = Config.ConfigBuilder(this)
    // ...
    .setCacheHttpPubKey(BuildConfig.CACHE_PUB_KEY)
    .setInjectorCredentials(BuildConfig.INJECTOR_CREDENTIALS)
    .setInjectorTlsCert(BuildConfig.INJECTOR_TLS_CERT)
    .build()

Send an HTTP request through Ouinet

Create a Proxy object pointing to Ouinet's service 127.0.0.1:8077:

val ouinetService = Proxy(Proxy.Type.HTTP, InetSocketAddress("127.0.0.1", 8077))

Pass the Proxy object to your HTTP client (we're using OKHTTPClient in this example):

OkHttpClient.Builder().proxy(ouinetService).build()

Validate Ouinet's TLS cert

A TLS certificate is automatically generated by Ouinet and used for it's interactions with the HTTP clients. You can implement a custom TrustManager:

inner private class OuinetTrustManager : X509TrustManager {
    // ...

    override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {
        //...
    }

    // ...
    override fun getAcceptedIssuers(): Array<X509Certificate> {
        return arrayOf(ca as X509Certificate)
    }
}

then you can load the X509TrustManager:

ouinetDir = config.ouinetDirectory
caInput = FileInputStream(ouinetDir + "/ssl-ca-cert.pem")
val cf = CertificateFactory.getInstance("X.509")
ca = cf.generateCertificate(caInput)

and add it to your own KeyChain:

val keyStore = KeyStore.getInstance(KeyStore.getDefaultType())
keyStore.load(null, null)
keyStore.setCertificateEntry("ca", certificateAuthority)

The resulting TrustManager can be used by the OKHttpClient.Builder to set a custom sslSocketFactory that verifies only the requests coming from Ouinet:

val builder = OkHttpClient.Builder()
builder.sslSocketFactory(
    getSSLSocketFactory(trustManagers),
    (trustManagers[0] as X509TrustManager)
)

Test Ouinet access mechanisms

During your tests you can easily disable any of the different access methods available in Ouinet when the Config object is build:

  • Force Origin Access
var config = Config.ConfigBuilder(this)
    // ...
    .setDisableProxyAccess(true)
    .setDisableInjectorAccess(true)
    .build()
  • Force Injector Access
var config = Config.ConfigBuilder(this)
    // ...
    .setDisableOriginAccess(true)
    .setDisableProxyAccess(true)
    .build()
  • Force Proxy Access
var config = Config.ConfigBuilder(this)
    // ...
    .setDisableOriginAccess(true)
    .setDisableInjectorAccess(true)
    .build()

Ouinet's test application in Java

Prepare your app for using Ouinet

Add Ouinet lib and Relinker to your dependencies list in app/build.gradle:

dependencies {
    ...
    implementation 'ie.equalit.ouinet:ouinet:1.5.0'
    implementation 'com.getkeepsafe.relinker:relinker:1.4.4'
}

Import Ouinet in your Android activity and create a private variable to hold the client:

import ie.equalit.ouinet.Ouinet;

public class MainActivity extends AppCompatActivity {
    private Ouinet ouinet;
    
    ...
}

Import config and setup the Ouinet client:

import ie.equalit.ouinet.Ouinet;

public class MainActivity extends AppCompatActivity {
    private Ouinet ouinet;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        
        Config config = new Config.ConfigBuilder(this)
                        .setCacheType("bep5-http")
                        .build();

        ouinet = new Ouinet(this, config);
        ouinet.start();
        
        ...
    }
}

Pass config values to Ouinet during the build process

You can have Ouinet keys and passwords added to the client during the building process by Gradle.

You just need to create a local.properties file in the root of this project and set the values as follows before building the app:

CACHE_PUB_KEY="YOUR OUINET CACHE PUB KEY"
INJECTOR_CREDENTIALS="ouinet:YOURINJECTORPASSWORD"
INJECTOR_TLS_CERT="-----BEGIN CERTIFICATE-----\\n\
ABCDEFG...\
\\n-----END CERTIFICATE-----"

Those values should be loaded by Gradle during the build process in app/build.gradle:

...

Properties localProperties = new Properties()
localProperties.load(rootProject.file('local.properties').newDataInputStream())

android {
    compileSdk 32

    defaultConfig {
        ...
        buildConfigField "String", "CACHE_PUB_KEY", localProperties['CACHE_PUB_KEY']
        buildConfigField "String", "INJECTOR_CREDENTIALS", localProperties['INJECTOR_CREDENTIALS']
        buildConfigField "String", "INJECTOR_TLS_CERT", localProperties['INJECTOR_TLS_CERT']
    }
    ...
}

and can be referenced after that from Java via BuildConfig:

public class MainActivity extends AppCompatActivity {
    ...

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...

        Config config = new Config.ConfigBuilder(this)
                .setCacheType("bep5-http")
                .setCacheHttpPubKey(BuildConfig.CACHE_PUB_KEY) //From local.properties
                .setInjectorCredentials(BuildConfig.INJECTOR_CREDENTIALS)
                .setInjectorTlsCert(BuildConfig.INJECTOR_TLS_CERT)
                .build();
        
        ...
    }
}

Send an HTTP request through Ouinet

Create a Proxy object pointing to Ouinet's service 127.0.0.1:8077:

Proxy ouinetService= new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 8077));

Pass the Proxy object to your HTTP client (we're using OKHTTPClient in this example):

OkHttpClient client = new OkHttpClient.Builder().proxy(ouinetService).build();

Validate Ouinet's TLS cert

A TLS certificate is automatically generated by Ouinet and used for it's interactions with the HTTP clients. You can implement a custom TrustManager:

private class OuinetTrustManager implements X509TrustManager {
    ...

    public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException {
        ...
    }

    public X509Certificate[] getAcceptedIssuers() {
        return new X509Certificate[]{(X509Certificate) ca};
    }
}

Then you can load the X509TrustManager

ouinet_dir = config.getOuinetDirectory();
caInput = new FileInputStream(ouinet_dir + "/ssl-ca-cert.pem");
CertificateFactory cf = CertificateFactory.getInstance("X.509");
ouinet_ca = cf.generateCertificate(caInput);

and add it to your own KeyChain:

KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(null, null);
keyStore.setCertificateEntry("ca", ouinet_ca);

The resulting TrustManager can be used by the OKHttpClient.Builder to set a custom sslSocketFactory that verifies only the requests coming from Ouinet:

OkHttpClient.Builder builder = new OkHttpClient.Builder();
builder.sslSocketFactory(
        getSSLSocketFactory(ouinetTrustManager),
        (X509TrustManager) ouinetTrustManager[0]);

Test Ouinet access mechanisms

During your tests you can easily disable any of the different access methods available in Ouinet when the Config object is build:

  • Force Origin Access
Config config = new Config.ConfigBuilder(this)
        ...
    .setDisableProxyAccess(true)
    .setDisableInjectorAccess(true)
    .build();
  • Force Injector Access
Config config = new Config.ConfigBuilder(this)
        ...
        .setDisableOriginAccess(true)
        .setDisableProxyAccess(true)
        .build();
  • Force Proxy Access
Config config = new Config.ConfigBuilder(this)
        ...
        .setDisableOriginAccess(true)
        .setDisableInjectorAccess(true)
        .build();