Android configuration docs.

7 files changed, 99 insertions, 4 deletions

diff --git a/doc-src/certinstall/android-proxydroidinstall.png b/doc-src/certinstall/android-proxydroidinstall.png
new file mode 100644
index 00000000..02d378cc
--- /dev/null
+++ b/doc-src/certinstall/android-proxydroidinstall.png
diff --git a/doc-src/certinstall/android-proxydroidsettings.png b/doc-src/certinstall/android-proxydroidsettings.png
new file mode 100644
index 00000000..8b516e2a
--- /dev/null
+++ b/doc-src/certinstall/android-proxydroidsettings.png
diff --git a/doc-src/certinstall/android-settingssecurityinstallca.png b/doc-src/certinstall/android-settingssecurityinstallca.png
new file mode 100644
index 00000000..afe24cab
--- /dev/null
+++ b/doc-src/certinstall/android-settingssecurityinstallca.png
diff --git a/doc-src/certinstall/android-settingssecuritymenu.png b/doc-src/certinstall/android-settingssecuritymenu.png
new file mode 100644
index 00000000..5444f1c6
--- /dev/null
+++ b/doc-src/certinstall/android-settingssecuritymenu.png
diff --git a/doc-src/certinstall/android-settingssecurityuserinstalledca.png b/doc-src/certinstall/android-settingssecurityuserinstalledca.png
new file mode 100644
index 00000000..fdd0c3c2
--- /dev/null
+++ b/doc-src/certinstall/android-settingssecurityuserinstalledca.png
diff --git a/doc-src/certinstall/android-shellwgetmitmproxyca.png b/doc-src/certinstall/android-shellwgetmitmproxyca.png
new file mode 100644
index 00000000..3b2e3a74
--- /dev/null
+++ b/doc-src/certinstall/android-shellwgetmitmproxyca.png
diff --git a/doc-src/certinstall/android.html b/doc-src/certinstall/android.html
index 388ede1a..46e6be15 100644
--- a/doc-src/certinstall/android.html
+++ b/doc-src/certinstall/android.html
@@ -1,13 +1,108 @@
 
-The Android Proxy Problem
--------------------------
+The proxy situation on Android is [unutterably
+woeful](http://code.google.com/p/android/issues/detail?id=1273). It beggars
+belief, but until recently Android didn't have a global proxy setting at all.
+Recent releases have repaired this, but in the meantime the app ecosystem has
+grown used to life without this basic necessity, and many apps merrily ignore
+it. The upshot is that the only way to make reliable interception work on
+Android is to do it without using the proxy settings.
 
 
 The Solution
-------------
+============
+
+In response to Android's proxy situation, a number of apps have been created to
+duct-tape proxy support onto the OS. These tools work by running a rudimentary
+local proxy on the device, and forwarding all traffic destined for HTTP/S ports
+to it using iptables. Since the proxy is running locally, it can detect what
+the final IP address of the redirected traffic would have been. The local proxy
+then connects to a user-configured upstream, and forwards the requests with a
+proxy CONNECT request to the destination IP.
+
+Now, if the configured upstream proxy is mitmproxy, we have a slight problem.
+Proxy requests from the Android device in this scheme will specify only the
+destination IP address, __not__ the destination domain. But mitmproxy needs the
+target domain to generate a valid interception certificate. The solution is
+mitmproxy's [upstream certificate](@!urlTo("upstreamcerts.html")!@) option.
+When this is active, mitmproxy makes a connection to the upstream server to
+obtain the certificate Common Name and Subject Alternative Names. 
+
+Adding all this together, we can achieve reliable Android interception with
+only a few minutes of setup.
 
 
 Step-by-step
-------------
+============
+
+The instructions below show how to set up an Android device with
+[ProxyDroid](https://play.google.com/store/apps/details?id=org.proxydroid)
+(the local "duct-tape" proxy implementation) to achieve interception. We've
+used an Asus Transformer Prime TF201 with Android 4.0.3 - your device may
+differ, but the broad setup process will be the same. 
+
+Before continuing, make sure your device is rooted - this is required to
+install ProxyDroid. 
+
+Run mitmproxy
+-------------
+
+Start a mitmproxy instance on your interception host, making sure that the
+upstream certificate option is set (use the _--upstream-cert_ command-line
+option, or enable it interactively using the _o_ shortcut).
+
+    mitmproxy --upstream-cert
+
+
+Install the mitmproxy certificate
+---------------------------------
+
+The first step is to install mitmproxy's interception certificate on the
+Android device. In your ~/.mitmproxy directory, there should be a file called
+__mitmproxy-ca-cert.cer__ - we need to transfer this file to
+__/sdcard/Downloads__ on the Android device. If this file doesn't exist for
+you, your certs were generated with an older version of mitmproxy - just copy
+the __mitmproxy-ca-cert.pem__ file to __mitmproxy-ca-cert.ca__ and proceed from
+there.
+
+In this case, we're using wget from the terminal to transfer the certificate
+from a local HTTP server:
+
+<img src="android-shellwgetmitmproxyca.png"/>
+
+Once we have the certificate on the local disk, we need to import it into the
+list of trusted CAs. Go to Settings -&gt; Security -&gt; Credential Storage,
+and select "Install from storage":
+
+<img src="android-settingssecuritymenu.png"/>
+
+The certificate in /sdcard/Downloads is automatically located and offered for
+installation. Installing the cert will delete the download file from the local
+disk:
+
+<img src="android-settingssecurityinstallca.png"/>
+
+Afterwards, you should see the certificate listed in the Trusted Credentials
+store:
+
+<img src="android-settingssecurityuserinstalledca.png"/>
+
+
+Install ProxyDroid
+------------------
+
+Now, install ProxyDroid from the Google Play store:
+
+<img src="android-proxydroidinstall.png"/>
+
+You will be prompted for super-user access, which you must allow. Next, enter
+the ProxyDroid settings, and change the proxy settings to point to your
+mitmproxy instance. When you're done, it should look something lke this:
+
+<img src="android-proxydroidsettings.png"/>
+
+In this case, our mitmproxy instance is at the host __maru.otago.ac.nz__,
+running on port __8080__.
 
+And that's it - you should now have full SSL interception enabled for your
+Android device. Happy hacking!