14 files changed, 220 insertions, 0 deletions

diff --git a/doc-src/certinstall/android-settingssecurityinstallca.png b/doc-src/certinstall/android-settingssecurityinstallca.png
new file mode 100644
index 00000000..f0f97273
--- /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..fea412fe
--- /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..1f7717ad
--- /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..4a4e326f
--- /dev/null
+++ b/doc-src/certinstall/android-shellwgetmitmproxyca.png
diff --git a/doc-src/certinstall/android.html b/doc-src/certinstall/android.html
new file mode 100644
index 00000000..73fc4d8b
--- /dev/null
+++ b/doc-src/certinstall/android.html
@@ -0,0 +1,53 @@
+The proxy situation on Android is [an
+embarrasment](http://code.google.com/p/android/issues/detail?id=1273).  It's
+scarcely credible, but Android didn't have a global proxy setting at all until
+quite recently, and it's still not supported on many common Android versions.
+In the meantime the app ecosystem has grown used to life without this basic
+necessity, and many apps merrily ignore it even if it's there. This situation
+is improving, but in many circumstances using [transparent
+mode](@!urlTo("transparent.html")!@) is mandatory for testing Android apps.
+
+We used both an Asus Transformer Prime TF201 (Android 4.0.3) and a Nexus 4
+(Android 4.4.4) in the examples below - your device may differ, but the broad
+process should be similar.  On **emulated devices**, there are some [additional
+quirks](https://github.com/mitmproxy/mitmproxy/issues/204#issuecomment-32837093)
+to consider.
+
+
+## Getting the certificate onto the device
+
+The easiest way to get the certificate to the device is to use [the web
+app](@!urlTo("webapp.html")!@). In the rare cases where the web app doesn't
+work, you will need to get the __mitmproxy-ca-cert.cer__ file into the
+__/sdcard__ folder on the device (/sdcard/Download on older devices). This can
+be accomplished in a number of ways:
+
+- If you have the Android Developer Tools installed, you can use [__adb
+push__](http://developer.android.com/tools/help/adb.html).
+- Using a file transfer program like wget (installed on the Android device) to
+copy the file over.
+- Transfer the file using external media like an SD Card. 
+
+Once we have the certificate on the local disk, we need to import it into the
+list of trusted CAs. Go to Settings -> Security -> Credential Storage,
+and select "Install from storage":
+
+<img src="android-settingssecuritymenu.png"/>
+
+The certificate in /sdcard is automatically located and offered for
+installation. Installing the cert will delete the download file from the local
+disk.
+
+
+## Installing the certificate
+
+You should now see something like this (you may have to explicitly name the
+certificate):
+
+<img src="android-settingssecurityinstallca.png"/>
+
+Click OK, and you should then see the certificate listed in the Trusted
+Credentials store:
+
+<img src="android-settingssecurityuserinstalledca.png"/>
+
diff --git a/doc-src/certinstall/firefox.html b/doc-src/certinstall/firefox.html
new file mode 100644
index 00000000..2652f5c6
--- /dev/null
+++ b/doc-src/certinstall/firefox.html
@@ -0,0 +1,31 @@
+## Get the certificate to the browser
+
+The easiest way to get the certificate to the browser is to use [the web
+app](@!urlTo("webapp.html")!@). If this fails, do the following:
+
+
+<ol class="tlist">
+    <li> If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target. </li>
+
+    <li>Open preferences, click on "Advanced", then select"Encryption":
+        <img src="@!urlTo('firefox3.jpg')!@"/>
+    </li>
+
+    <li> Click "View Certificates", "Import", and select the certificate file: 
+        <img src="@!urlTo('firefox3-import.jpg')!@"/>
+    </li>
+
+</ol>
+
+
+## Installing the certificate
+
+<ol class="tlist">
+    <li>Tick "Trust this CS to identify web sites", and click "Ok":
+        <img src="@!urlTo('firefox3-trust.jpg')!@"/>
+    </li>
+
+    <li> You should now see the mitmproxy certificate listed in the Authorities
+    tab.</li>
+</ol>
+
diff --git a/doc-src/certinstall/index.py b/doc-src/certinstall/index.py
new file mode 100644
index 00000000..32927401
--- /dev/null
+++ b/doc-src/certinstall/index.py
@@ -0,0 +1,12 @@
+from countershape import Page
+
+pages = [
+    Page("webapp.html", "Using the Web App"),
+    Page("firefox.html", "Firefox"),
+    Page("osx.html", "OSX"),
+    Page("windows7.html", "Windows 7"),
+    Page("ios.html", "IOS"),
+    Page("ios-simulator.html", "IOS Simulator"),
+    Page("android.html", "Android"),
+    Page("java.html", "Java"),
+]
diff --git a/doc-src/certinstall/ios-simulator.html b/doc-src/certinstall/ios-simulator.html
new file mode 100644
index 00000000..9eb98108
--- /dev/null
+++ b/doc-src/certinstall/ios-simulator.html
@@ -0,0 +1,23 @@
+
+How to install the __mitmproxy__ certificate authority in the IOS simulator:
+
+<ol class="tlist">
+
+    <li> First, check out the <a
+    href="https://github.com/ADVTOOLS/ADVTrustStore">ADVTrustStore</a> tool
+    from github.</li>
+
+    <li> Now, run the following command:
+
+    <pre class="terminal">./iosCertTrustManager.py -a ~/.mitmproxy/mitmproxy-ca-cert.pem</pre>
+
+    </li>
+
+</ol>
+
+
+Note that although the IOS simulator has its own certificate store, it shares
+the proxy settings of the host operating system. You will therefore to have
+configure your OSX host's proxy settings to use the mitmproxy instance you want
+to test with.
+
diff --git a/doc-src/certinstall/ios.html b/doc-src/certinstall/ios.html
new file mode 100644
index 00000000..c12d65f6
--- /dev/null
+++ b/doc-src/certinstall/ios.html
@@ -0,0 +1,27 @@
+
+## Getting the certificate onto the device
+
+The easiest way to get the certificate to the device is to use [the web
+app](@!urlTo("webapp.html")!@). In the rare cases where the web app doesn't
+work, you will need to get the __mitmproxy-ca-cert.pem__ file to the device to
+install it. The easiest way to accomplish this is to set up the Mail app on the
+device, and to email it over as an attachment. Open the email, tap on the
+attachment, then proceed with the install.
+
+
+## Installing the certificate
+
+<ol class="tlist">
+    <li>You will be prompted to install a profile. Click "Install":
+
+    <img src="@!urlTo('ios-profile.png')!@"/></li>
+
+    <li>Accept the warning by clicking "Install" again:
+
+    <img src="@!urlTo('ios-warning.png')!@"/></li>
+
+    <li>The certificate should now be trusted:
+
+    <img src="@!urlTo('ios-installed.png')!@"/></li>
+
+</ol>
diff --git a/doc-src/certinstall/java.html b/doc-src/certinstall/java.html
new file mode 100644
index 00000000..f6420991
--- /dev/null
+++ b/doc-src/certinstall/java.html
@@ -0,0 +1,13 @@
+
+You can add the mitmproxy certificates to the Java trust store using
+[keytool](http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html).
+On OSX, the required command looks like this:
+
+<pre class="terminal">
+sudo keytool -importcert -alias mitmproxy -storepass "password" \
+-keystore /System/Library/Java/Support/CoreDeploy.bundle/Contents/Home/lib/security/cacerts \
+-trustcacerts -file ~/.mitmproxy/mitmproxy-ca-cert.pem
+</pre>
+
+Note that your store password will (hopefully) be different from the one above.
+
diff --git a/doc-src/certinstall/osx.html b/doc-src/certinstall/osx.html
new file mode 100644
index 00000000..a532d538
--- /dev/null
+++ b/doc-src/certinstall/osx.html
@@ -0,0 +1,16 @@
+
+How to install the __mitmproxy__ certificate authority in OSX:
+
+<ol class="tlist">
+
+    <li>Open Finder, and double-click on the mitmproxy-ca-cert.pem file.</li>
+
+    <li>You will be prompted to add the certificate. Click "Always Trust": 
+
+        <img src="@!urlTo('osx-addcert-alwaystrust.png')!@"/>
+    </li>
+
+    <li> You may be prompted for your password. You should now see the
+    mitmproxy cert listed under "Certificates".</li>
+</ol>
+
diff --git a/doc-src/certinstall/webapp.html b/doc-src/certinstall/webapp.html
new file mode 100644
index 00000000..6cb9ef22
--- /dev/null
+++ b/doc-src/certinstall/webapp.html
@@ -0,0 +1,10 @@
+
+By far the easiest way to install the mitmproxy certs is to use the built-in
+web app. To do this, start mitmproxy and configure your target device with the
+correct proxy settings. Now start a browser on the device, and visit the magic
+domain **mitm.it**. You should see something like this:
+
+<img src="@!urlTo("webapp.png")!@"></img>
+
+Just click on the relevant icon, and then follow the setup instructions
+for the platform you're on.
diff --git a/doc-src/certinstall/webapp.png b/doc-src/certinstall/webapp.png
new file mode 100644
index 00000000..10e795cd
--- /dev/null
+++ b/doc-src/certinstall/webapp.png
diff --git a/doc-src/certinstall/windows7.html b/doc-src/certinstall/windows7.html
new file mode 100644
index 00000000..7a4cc3d2
--- /dev/null
+++ b/doc-src/certinstall/windows7.html
@@ -0,0 +1,35 @@
+
+How to install the __mitmproxy__ certificate authority in Windows 7:
+
+<ol class="tlist">
+
+    <li> The easiest way to get the certificate to the device is to use <a
+        href="@!urlTo("webapp.html")!@">the web app</a>. If this fails for some
+    reason, simply copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the
+    target system and double-click it.  </li>
+
+    <li> 
+        You should see a certificate import wizard: 
+
+        <img src="@!urlTo('win7-wizard.png')!@"/>
+    </li>
+
+    <li> 
+        Click "Next" until you're prompted for the certificate store:
+
+        <img src="@!urlTo('win7-certstore.png')!@"/>
+
+    </li>
+
+
+    <li> 
+        <p>Select "Place all certificates in the following store", and select "Trusted Root Certification Authorities":</p>
+
+        <img src="@!urlTo('win7-certstore-trustedroot.png')!@"/>
+
+    </li>
+
+    <li> Click "Next" and "Finish". </li>
+
+</ol>
+