From f47d89ff4e710f6d2df755fe526e91a5cf236cfa Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Mon, 27 Jan 2014 14:16:23 +1300 Subject: Revert "Move the doc tree out into its own repo." This reverts commit 8f88fcedd601c0033b4469b66626a83011879baf. --- .../android-settingssecurityinstallca.png | Bin 0 -> 57723 bytes .../certinstall/android-settingssecuritymenu.png | Bin 0 -> 75679 bytes .../android-settingssecurityuserinstalledca.png | Bin 0 -> 47263 bytes .../certinstall/android-shellwgetmitmproxyca.png | Bin 0 -> 22198 bytes doc-src/certinstall/android.html | 45 +++++++++++++++++++++ doc-src/certinstall/firefox.html | 23 +++++++++++ doc-src/certinstall/index.py | 10 +++++ doc-src/certinstall/ios-simulator.html | 23 +++++++++++ doc-src/certinstall/ios.html | 21 ++++++++++ doc-src/certinstall/osx.html | 16 ++++++++ doc-src/certinstall/windows7.html | 32 +++++++++++++++ 11 files changed, 170 insertions(+) create mode 100644 doc-src/certinstall/android-settingssecurityinstallca.png create mode 100644 doc-src/certinstall/android-settingssecuritymenu.png create mode 100644 doc-src/certinstall/android-settingssecurityuserinstalledca.png create mode 100644 doc-src/certinstall/android-shellwgetmitmproxyca.png create mode 100644 doc-src/certinstall/android.html create mode 100644 doc-src/certinstall/firefox.html create mode 100644 doc-src/certinstall/index.py create mode 100644 doc-src/certinstall/ios-simulator.html create mode 100644 doc-src/certinstall/ios.html create mode 100644 doc-src/certinstall/osx.html create mode 100644 doc-src/certinstall/windows7.html (limited to 'doc-src/certinstall') diff --git a/doc-src/certinstall/android-settingssecurityinstallca.png b/doc-src/certinstall/android-settingssecurityinstallca.png new file mode 100644 index 00000000..f0f97273 Binary files /dev/null and b/doc-src/certinstall/android-settingssecurityinstallca.png differ diff --git a/doc-src/certinstall/android-settingssecuritymenu.png b/doc-src/certinstall/android-settingssecuritymenu.png new file mode 100644 index 00000000..fea412fe Binary files /dev/null and b/doc-src/certinstall/android-settingssecuritymenu.png differ diff --git a/doc-src/certinstall/android-settingssecurityuserinstalledca.png b/doc-src/certinstall/android-settingssecurityuserinstalledca.png new file mode 100644 index 00000000..1f7717ad Binary files /dev/null and b/doc-src/certinstall/android-settingssecurityuserinstalledca.png differ diff --git a/doc-src/certinstall/android-shellwgetmitmproxyca.png b/doc-src/certinstall/android-shellwgetmitmproxyca.png new file mode 100644 index 00000000..4a4e326f Binary files /dev/null and b/doc-src/certinstall/android-shellwgetmitmproxyca.png differ diff --git a/doc-src/certinstall/android.html b/doc-src/certinstall/android.html new file mode 100644 index 00000000..9b0c5d71 --- /dev/null +++ b/doc-src/certinstall/android.html @@ -0,0 +1,45 @@ +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 an Asus Transformer Prime TF201 with Android 4.0.3 in the examples +below - your device may differ, but the broad process should be similar. + + +## 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: + + + + +## Installing the certificate + +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": + + + +The certificate in /sdcard is automatically located and offered for +installation. Installing the cert will delete the download file from the local +disk: + + + +Afterwards, you should see the certificate listed in the Trusted Credentials +store: + + + diff --git a/doc-src/certinstall/firefox.html b/doc-src/certinstall/firefox.html new file mode 100644 index 00000000..66fa9d79 --- /dev/null +++ b/doc-src/certinstall/firefox.html @@ -0,0 +1,23 @@ + +How to install the __mitmproxy__ certificate authority in Firefox: + +
    +
  1. If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target.
    2. + +
  2. Open preferences, click on "Advanced", then select"Encryption": + +
    3. + +
  3. Click "View Certificates", "Import", and select the certificate file: + +
    4. + +
  4. Tick "Trust this CS to identify web sites", and click "Ok": + +
    5. + +
  5. You should now see the mitmproxy certificate listed in the Authorities + tab.
    6. + +
+ diff --git a/doc-src/certinstall/index.py b/doc-src/certinstall/index.py new file mode 100644 index 00000000..3f145fbc --- /dev/null +++ b/doc-src/certinstall/index.py @@ -0,0 +1,10 @@ +from countershape import Page + +pages = [ + 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"), +] 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: + +
    + +
  1. First, check out the ADVTrustStore tool + from github.
    2. + +
  2. Now, run the following command: + + 
    ./iosCertTrustManager.py -a ~/.mitmproxy/mitmproxy-ca-cert.pem
    + +
    3. + +
+ + +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..fd14e65a --- /dev/null +++ b/doc-src/certinstall/ios.html @@ -0,0 +1,21 @@ + +How to install the __mitmproxy__ certificate authority on IOS devices: + +
    +
  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. + +
  4. Accept the warning by clicking "Install" again: + +
    5. + +
  5. The certificate should now be trusted: + +
    6. + +
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: + +
    + +
  1. Open Finder, and double-click on the mitmproxy-ca-cert.pem file.
    2. + +
  2. You will be prompted to add the certificate. Click "Always Trust": + + +
    3. + +
  3. You may be prompted for your password. You should now see the + mitmproxy cert listed under "Certificates".
    4. +
+ diff --git a/doc-src/certinstall/windows7.html b/doc-src/certinstall/windows7.html new file mode 100644 index 00000000..47c807c6 --- /dev/null +++ b/doc-src/certinstall/windows7.html @@ -0,0 +1,32 @@ + +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. + Double-click the certificate file. You should see a certificate import wizard: + + +
    3. + +
  3. + Click "Next" until you're prompted for the certificate store: + + + +
    4. + + +
  4. +

    Select "Place all certificates in the following store", and select "Trusted Root Certification Authorities":

    + + + +
    5. + +
  5. Click "Next" and "Finish".
    6. + +
+ -- cgit v1.2.3 From 332eb67dfe292bb5b2b3bc1b55a33d6095d7e809 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Mon, 27 Jan 2014 14:17:16 +1300 Subject: Android doc update. --- doc-src/certinstall/android.html | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'doc-src/certinstall') diff --git a/doc-src/certinstall/android.html b/doc-src/certinstall/android.html index 9b0c5d71..bb0165f7 100644 --- a/doc-src/certinstall/android.html +++ b/doc-src/certinstall/android.html @@ -7,8 +7,11 @@ 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 an Asus Transformer Prime TF201 with Android 4.0.3 in the examples -below - your device may differ, but the broad process should be similar. +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 -- cgit v1.2.3 From 784f411273c4b09797529822e336ce34fa8d1f23 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Mon, 27 Jan 2014 14:45:20 +1300 Subject: Instructions for adding mitmproxy certificates to the Java trust store. Fixes #146 --- doc-src/certinstall/index.py | 1 + doc-src/certinstall/java.html | 13 +++++++++++++ 2 files changed, 14 insertions(+) create mode 100644 doc-src/certinstall/java.html (limited to 'doc-src/certinstall') diff --git a/doc-src/certinstall/index.py b/doc-src/certinstall/index.py index 3f145fbc..ebdc730f 100644 --- a/doc-src/certinstall/index.py +++ b/doc-src/certinstall/index.py @@ -7,4 +7,5 @@ pages = [ Page("ios.html", "IOS"), Page("ios-simulator.html", "IOS Simulator"), Page("android.html", "Android"), + Page("java.html", "Java"), ] 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: + +
+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
+
+ +Note that your store password will (hopefully) be different from the one above. + -- cgit v1.2.3 From f3369529abd601d7f10fcdb45ec280e8f6a7ad19 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Tue, 28 Jan 2014 13:24:11 +1300 Subject: Adjust docs for web app certificate installation. --- doc-src/certinstall/android.html | 43 +++++++++++++++++++++----------------- doc-src/certinstall/firefox.html | 12 +++++++++-- doc-src/certinstall/index.py | 1 + doc-src/certinstall/ios.html | 14 +++++++++---- doc-src/certinstall/webapp.html | 10 +++++++++ doc-src/certinstall/webapp.png | Bin 0 -> 61683 bytes doc-src/certinstall/windows7.html | 7 +++++-- 7 files changed, 60 insertions(+), 27 deletions(-) create mode 100644 doc-src/certinstall/webapp.html create mode 100644 doc-src/certinstall/webapp.png (limited to 'doc-src/certinstall') 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: - - - -## 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 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:
  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 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. -
    -
  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. +## Installing the certificate +
    1. You will be prompted to install a profile. Click "Install":
      2. 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: + + + +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 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 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:
        -
      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. -- cgit v1.2.3