diff options
| -rw-r--r-- | doc-src/_nav.html | 1 | ||||
| -rw-r--r-- | doc-src/certinstall/android.html | 43 | ||||
| -rw-r--r-- | doc-src/certinstall/firefox.html | 12 | ||||
| -rw-r--r-- | doc-src/certinstall/index.py | 1 | ||||
| -rw-r--r-- | doc-src/certinstall/ios.html | 14 | ||||
| -rw-r--r-- | doc-src/certinstall/webapp.html | 10 | ||||
| -rw-r--r-- | doc-src/certinstall/webapp.png | bin | 0 -> 61683 bytes | |||
| -rw-r--r-- | doc-src/certinstall/windows7.html | 7 | ||||
| -rw-r--r-- | doc-src/ssl.html | 24 |
9 files changed, 75 insertions, 37 deletions
diff --git a/doc-src/_nav.html b/doc-src/_nav.html index 6dfbaba5..5460601f 100644 --- a/doc-src/_nav.html +++ b/doc-src/_nav.html @@ -22,6 +22,7 @@ <li class="nav-header">Installing Certificates</li> $!nav("ssl.html", this, state)!$ + $!nav("certinstall/webapp.html", this, state)!$ $!nav("certinstall/android.html", this, state)!$ $!nav("certinstall/firefox.html", this, state)!$ $!nav("certinstall/ios.html", this, state)!$ diff --git a/doc-src/certinstall/android.html b/doc-src/certinstall/android.html index bb0165f7..73fc4d8b 100644 --- a/doc-src/certinstall/android.html +++ b/doc-src/certinstall/android.html @@ -7,27 +7,26 @@ 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. +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 -First we need to get the __mitmproxy-ca-cert.cer__ file into the -__/sdcard__ folder on the device (/sdcard/Download on older devices). There are a number of ways to do -this. If you have the Android Developer Tools installed, you can use [__adb -push__](http://developer.android.com/tools/help/adb.html) to accomplish this. -Depending on your device, you could also transfer the file using external media -like an SD Card. In this example, we're using wget from within a terminal -emulator to transfer the certificate from a local HTTP server: +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: -<img src="android-shellwgetmitmproxyca.png"/> - - -## Installing the certificate +- 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, @@ -37,12 +36,18 @@ and select "Install from storage": The certificate in /sdcard is automatically located and offered for installation. Installing the cert will delete the download file from the local -disk: +disk. + + +## Installing the certificate + +You should now see something like this (you may have to explicitly name the +certificate): <img src="android-settingssecurityinstallca.png"/> -Afterwards, you should see the certificate listed in the Trusted Credentials -store: +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 index 66fa9d79..2652f5c6 100644 --- a/doc-src/certinstall/firefox.html +++ b/doc-src/certinstall/firefox.html @@ -1,5 +1,8 @@ +## 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: -How to install the __mitmproxy__ certificate authority in Firefox: <ol class="tlist"> <li> If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target. </li> @@ -12,12 +15,17 @@ How to install the __mitmproxy__ certificate authority in Firefox: <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 index ebdc730f..32927401 100644 --- a/doc-src/certinstall/index.py +++ b/doc-src/certinstall/index.py @@ -1,6 +1,7 @@ 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"), diff --git a/doc-src/certinstall/ios.html b/doc-src/certinstall/ios.html index fd14e65a..c12d65f6 100644 --- a/doc-src/certinstall/ios.html +++ b/doc-src/certinstall/ios.html @@ -1,11 +1,17 @@ -How to install the __mitmproxy__ certificate authority on IOS devices: +## 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. -<ol class="tlist"> - <li>Set up the Mail app on the device to receive email.</li> - <li>Mail the mitmproxy-ca-cert.pem file to the device, and tap on the attachment.</li> +## Installing the certificate +<ol class="tlist"> <li>You will be prompted to install a profile. Click "Install": <img src="@!urlTo('ios-profile.png')!@"/></li> 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 Binary files differnew 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 index 47c807c6..7a4cc3d2 100644 --- a/doc-src/certinstall/windows7.html +++ b/doc-src/certinstall/windows7.html @@ -3,10 +3,13 @@ How to install the __mitmproxy__ certificate authority in Windows 7: <ol class="tlist"> - <li> Copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the target system. </li> + <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> - Double-click the certificate file. You should see a certificate import wizard: + You should see a certificate import wizard: <img src="@!urlTo('win7-wizard.png')!@"/> </li> diff --git a/doc-src/ssl.html b/doc-src/ssl.html index c904cf61..91225d79 100644 --- a/doc-src/ssl.html +++ b/doc-src/ssl.html @@ -1,7 +1,20 @@ The first time __mitmproxy__ or __mitmdump__ is run, a set of certificate files for the mitmproxy Certificate Authority are created in the config directory -(~/.mitmproxy by default). The files are as follows: +(~/.mitmproxy by default). This CA is used for on-the-fly generation of dummy +certificates for SSL interception. Since your browser won't trust the +__mitmproxy__ CA out of the box (and rightly so), you will see an SSL cert +warning every time you visit a new SSL domain through __mitmproxy__. When +you're testing a single site through a browser, just accepting the bogus SSL +cert manually is not too much trouble, but there are a many circumstances where +you will want to configure your testing system or browser to trust the +__mitmproxy__ CA as a signing root authority. + + +CA and cert files +----------------- + +The files created by mitmproxy in the .mitmproxy directory are as follows: <table class="table"> <tr> @@ -24,15 +37,6 @@ for the mitmproxy Certificate Authority are created in the config directory </tr> </table> -This CA is used for on-the-fly generation of dummy certificates for SSL -interception. Since your browser won't trust the __mitmproxy__ CA out of the -box (and rightly so), you will see an SSL cert warning every time you visit a -new SSL domain through __mitmproxy__. When you're testing a single site through -a browser, just accepting the bogus SSL cert manually is not too much trouble, -but there are a many circumstances where you will want to configure your -testing system or browser to trust the __mitmproxy__ CA as a signing root -authority. - Using a custom certificate -------------------------- |
