Merge pull request #3669 from jannst/add_howto_install_android_system_ca

Add howto insert mitmproxy CA cert into the android system certificate store

1 files changed, 86 insertions, 0 deletions

diff --git a/docs/src/content/howto-install-system-trusted-ca-android.md b/docs/src/content/howto-install-system-trusted-ca-android.md
new file mode 100644
index 00000000..2ef67f30
--- /dev/null
+++ b/docs/src/content/howto-install-system-trusted-ca-android.md
@@ -0,0 +1,86 @@
+---
+title: "Install System CA on Android"
+menu:
+    howto:
+        weight: 4
+---
+
+# Install System CA Certificate on Android Emulator
+
+[Since Android 7, apps ignore user certificates](https://android-developers.googleblog.com/2016/07/changes-to-trusted-certificate.html), unless they are configured to use them.
+As most applications do not explicitly opt in to use user certificates, we need to place our mitmproxy CA certificate in the system certificate store,
+in order to avid having to patch each application, which we want to monitor.
+
+Please note, that apps can decide to ignore the system certificate store and maintain their own CA certificates. In this case you have to patch the application.
+
+## 1. Prerequisites
+
+  - Emulator from Android SDK with proxy settings pointing to mitmproxy
+
+  - Mitmproxy CA certificate
+    - Usually located in `~/.mitmproxy/mitmproxy-ca-cert.cer`
+    - If the folder is empty or does not exist, run `mitmproxy` in order to generate the certificates
+    
+## 2. Rename certificate
+Enter your certificate folder
+{{< highlight bash  >}}
+cd ~/.mitmproxy/
+{{< / highlight >}}
+
+  - CA Certificates in Android are stored by the name of their hash, with a '0' as extension
+  - Now generate the hash of your certificate
+  
+{{< highlight bash  >}}
+openssl x509 -inform PEM -subject_hash_old -in mitmproxy-ca-cert.cer | head -1
+{{< / highlight >}}
+Lets assume, the output is `c8450d0d`
+
+We can now copy `mitmproxy-ca-cert.cer` to `c8450d0d.0` and our system certificate is ready to use
+{{< highlight bash  >}}
+cp mitmproxy-ca-cert.cer c8450d0d.0
+{{< / highlight >}}
+
+## 3. Insert certificate into system certificate store
+
+Note, that Android 9 (API LEVEL 28) was used to test the following steps and that the `emulator` executable is located in the Android SDK
+
+  - Start your android emulator. 
+     - Get a list of your AVDs with `emulator -list-avds`
+     - Make sure to use the `-writable-system` option. Otherwise it will not be possible to write to `/system`
+     - Keep in mind, that the **emulator will load a clean system image when starting without `-writable-system` option**.
+     - This means you always have to start the emulator with `-writable-system` option in order to use your certificate
+
+{{< highlight bash  >}}
+emulator -avd <avd_name_here> -writable-system
+{{< / highlight >}}
+
+  - Restart adb as root
+  
+{{< highlight bash  >}}
+adb root
+{{< / highlight >}}
+
+  - Get write access to `/system` on the device
+  - In earlier versions (API LEVEL < 28) of Android you have to use `adb shell "mount -o rw,remount /system"`
+  
+{{< highlight bash  >}}
+adb shell "mount -o rw,remount /"
+{{< / highlight >}}
+
+  - Push your certificate to the system certificate store and set file permissions
+  
+{{< highlight bash  >}}
+adb push c8450d0d.0 /system/etc/security/cacerts
+adb shell "chmod 664 /system/etc/security/cacerts/c8450d0d.0"
+{{< / highlight >}}
+
+## 4. Reboot device and enjoy decrypted TLS traffic
+
+  - Reboot your device. 
+     - You CA certificate should now be system trusted
+         
+{{< highlight bash  >}}
+adb reboot
+{{< / highlight >}}
+
+**Remember**: You **always** have to start the emulator using the `-writable-system` option in order to use your certificate
\ No newline at end of file