Add instructions for Ouinet integration in Java

2022-06-01 17:19:34 -05:00 · 2022-06-01 17:19:34 -05:00 · ff72769a0d
commit ff72769a0d
parent bbda3cc5bd
1 changed files with 193 additions and 0 deletions
--- a/android/java/README.md
+++ b/android/java/README.md
@ -0,0 +1,193 @@
+# 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**:
+
+```groovy
+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:
+
+```java
+import ie.equalit.ouinet.Ouinet;
+
+public class MainActivity extends AppCompatActivity {
+    private Ouinet ouinet;
+    
+    ...
+}
+```
+
+Import config and setup the Ouinet client:
+
+```java
+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:
+```groovy
+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**:
+```groovy
+...
+
+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`:
+
+```java
+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`:
+```java
+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):
+```java
+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`:
+```java
+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`
+
+```java
+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`:
+
+```java
+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:
+
+```java
+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
+```java
+Config config = new Config.ConfigBuilder(this)
+        ...
+    .setDisableProxyAccess(true)
+    .setDisableInjectorAccess(true)
+    .build();
+```
+
+* Force Injector Access
+```java
+Config config = new Config.ConfigBuilder(this)
+        ...
+        .setDisableOriginAccess(true)
+        .setDisableProxyAccess(true)
+        .build();
+```
+
+* Force Proxy Access
+```java
+Config config = new Config.ConfigBuilder(this)
+        ...
+        .setDisableOriginAccess(true)
+        .setDisableInjectorAccess(true)
+        .build();
+```