diff --git a/doc-src/_nav.html b/doc-src/_nav.html index 6dfbaba57..5460601ff 100644 --- a/doc-src/_nav.html +++ b/doc-src/_nav.html @@ -22,6 +22,7 @@
  • Installing Certificates
    • $!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 bb0165f73..73fc4d8b5 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: - - - -## 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): -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: diff --git a/doc-src/certinstall/firefox.html b/doc-src/certinstall/firefox.html index 66fa9d797..2652f5c6b 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:
    1. If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target.
      2. @@ -12,12 +15,17 @@ How to install the __mitmproxy__ certificate authority in Firefox: +
    + + +## Installing the certificate + +
    1. Tick "Trust this CS to identify web sites", and click "Ok":
    2. You should now see the mitmproxy certificate listed in the Authorities tab.
      3. -
    diff --git a/doc-src/certinstall/index.py b/doc-src/certinstall/index.py index ebdc730f2..329274016 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 fd14e65aa..c12d65f69 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. + + +## Installing the certificate
      -
    1. Set up the Mail app on the device to receive email.
      2. - -
    2. Mail the mitmproxy-ca-cert.pem file to the device, and tap on the attachment.
      3. -
    3. You will be prompted to install a profile. Click "Install":
      4. diff --git a/doc-src/certinstall/webapp.html b/doc-src/certinstall/webapp.html new file mode 100644 index 000000000..6cb9ef226 --- /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: + + + +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 000000000..10e795cdc Binary files /dev/null and b/doc-src/certinstall/webapp.png differ diff --git a/doc-src/certinstall/windows7.html b/doc-src/certinstall/windows7.html index 47c807c6e..7a4cc3d26 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:
        -
      1. Copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the target system.
        2. +
      2. The easiest way to get the certificate to the device is to use the web app. If this fails for some + reason, simply copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the + target system and double-click it.
      3. - Double-click the certificate file. You should see a certificate import wizard: + You should see a certificate import wizard:
        4. diff --git a/doc-src/ssl.html b/doc-src/ssl.html index c904cf617..91225d793 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: @@ -24,15 +37,6 @@ for the mitmproxy Certificate Authority are created in the config directory
        -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 --------------------------