From 968d94d4710616ebf94cde4f3c35d469e227e910 Mon Sep 17 00:00:00 2001 From: Jim Shaver Date: Tue, 17 Mar 2015 00:26:42 -0400 Subject: Removes all of the platform specific certificate installation instructions. --- doc-src/_nav.html | 7 --- .../android-settingssecurityinstallca.png | Bin 57723 -> 0 bytes .../certinstall/android-settingssecuritymenu.png | Bin 75679 -> 0 bytes .../android-settingssecurityuserinstalledca.png | Bin 47263 -> 0 bytes .../certinstall/android-shellwgetmitmproxyca.png | Bin 22198 -> 0 bytes doc-src/certinstall/android.html | 53 --------------------- doc-src/certinstall/firefox.html | 31 ------------ doc-src/certinstall/index.py | 7 --- doc-src/certinstall/ios-simulator.html | 23 --------- doc-src/certinstall/ios.html | 27 ----------- doc-src/certinstall/java.html | 13 ----- doc-src/certinstall/osx.html | 16 ------- doc-src/certinstall/windows7.html | 35 -------------- doc-src/ssl.html | 10 +--- doc-src/tutorials/gamecenter.html | 5 +- 15 files changed, 3 insertions(+), 224 deletions(-) delete mode 100644 doc-src/certinstall/android-settingssecurityinstallca.png delete mode 100644 doc-src/certinstall/android-settingssecuritymenu.png delete mode 100644 doc-src/certinstall/android-settingssecurityuserinstalledca.png delete mode 100644 doc-src/certinstall/android-shellwgetmitmproxyca.png delete mode 100644 doc-src/certinstall/android.html delete mode 100644 doc-src/certinstall/firefox.html delete mode 100644 doc-src/certinstall/ios-simulator.html delete mode 100644 doc-src/certinstall/ios.html delete mode 100644 doc-src/certinstall/java.html delete mode 100644 doc-src/certinstall/osx.html delete mode 100644 doc-src/certinstall/windows7.html (limited to 'doc-src') diff --git a/doc-src/_nav.html b/doc-src/_nav.html index 69175c0c..91d2118f 100644 --- a/doc-src/_nav.html +++ b/doc-src/_nav.html @@ -31,13 +31,6 @@
  • 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)!$ - $!nav("certinstall/ios-simulator.html", this, state)!$ - $!nav("certinstall/java.html", this, state)!$ - $!nav("certinstall/osx.html", this, state)!$ - $!nav("certinstall/windows7.html", this, state)!$
  • Transparent Proxying
    • $!nav("transparent.html", this, state)!$ diff --git a/doc-src/certinstall/android-settingssecurityinstallca.png b/doc-src/certinstall/android-settingssecurityinstallca.png deleted file mode 100644 index f0f97273..00000000 Binary files a/doc-src/certinstall/android-settingssecurityinstallca.png and /dev/null differ diff --git a/doc-src/certinstall/android-settingssecuritymenu.png b/doc-src/certinstall/android-settingssecuritymenu.png deleted file mode 100644 index fea412fe..00000000 Binary files a/doc-src/certinstall/android-settingssecuritymenu.png and /dev/null differ diff --git a/doc-src/certinstall/android-settingssecurityuserinstalledca.png b/doc-src/certinstall/android-settingssecurityuserinstalledca.png deleted file mode 100644 index 1f7717ad..00000000 Binary files a/doc-src/certinstall/android-settingssecurityuserinstalledca.png and /dev/null differ diff --git a/doc-src/certinstall/android-shellwgetmitmproxyca.png b/doc-src/certinstall/android-shellwgetmitmproxyca.png deleted file mode 100644 index 4a4e326f..00000000 Binary files a/doc-src/certinstall/android-shellwgetmitmproxyca.png and /dev/null differ diff --git a/doc-src/certinstall/android.html b/doc-src/certinstall/android.html deleted file mode 100644 index 73fc4d8b..00000000 --- a/doc-src/certinstall/android.html +++ /dev/null @@ -1,53 +0,0 @@ -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": - - - -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): - - - -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 deleted file mode 100644 index bb9ba05b..00000000 --- a/doc-src/certinstall/firefox.html +++ /dev/null @@ -1,31 +0,0 @@ -## 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: - - -
      -
    1. If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target.
      2. - -
    2. Open preferences, click on "Advanced", then select"Certificates": - -
      3. - -
    3. Click "View Certificates", "Import", and select the certificate file: - -
      4. - -
    - - -## Installing the certificate - -
      -
    1. Tick "Trust this CA to identify web sites", and click "Ok": - -
      2. - -
    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 d6b1e417..fd422cb3 100644 --- a/doc-src/certinstall/index.py +++ b/doc-src/certinstall/index.py @@ -2,12 +2,5 @@ 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"), Page("mitm.it-error.html", "Error: No proxy configured"), ] diff --git a/doc-src/certinstall/ios-simulator.html b/doc-src/certinstall/ios-simulator.html deleted file mode 100644 index 9eb98108..00000000 --- a/doc-src/certinstall/ios-simulator.html +++ /dev/null @@ -1,23 +0,0 @@ - -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 deleted file mode 100644 index c12d65f6..00000000 --- a/doc-src/certinstall/ios.html +++ /dev/null @@ -1,27 +0,0 @@ - -## 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. You will be prompted to install a profile. Click "Install": - -
      2. - -
    2. Accept the warning by clicking "Install" again: - -
      3. - -
    3. The certificate should now be trusted: - -
      4. - -
    diff --git a/doc-src/certinstall/java.html b/doc-src/certinstall/java.html deleted file mode 100644 index f6420991..00000000 --- a/doc-src/certinstall/java.html +++ /dev/null @@ -1,13 +0,0 @@ - -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. - diff --git a/doc-src/certinstall/osx.html b/doc-src/certinstall/osx.html deleted file mode 100644 index a532d538..00000000 --- a/doc-src/certinstall/osx.html +++ /dev/null @@ -1,16 +0,0 @@ - -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 deleted file mode 100644 index 7a4cc3d2..00000000 --- a/doc-src/certinstall/windows7.html +++ /dev/null @@ -1,35 +0,0 @@ - -How to install the __mitmproxy__ certificate authority in Windows 7: - -
      - -
    1. 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.
      2. - -
    2. - 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. - -
    - diff --git a/doc-src/ssl.html b/doc-src/ssl.html index de45bd29..cccde1b7 100644 --- a/doc-src/ssl.html +++ b/doc-src/ssl.html @@ -87,13 +87,5 @@ You can use your own certificate authority by passing the --confdir o mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists, it will be generated automatically. -Installing the mitmproxy CA ---------------------------- - -* [Firefox](@!urlTo("certinstall/firefox.html")!@) -* [OSX](@!urlTo("certinstall/osx.html")!@) -* [Windows 7](@!urlTo("certinstall/windows7.html")!@) -* [iPhone/iPad](@!urlTo("certinstall/ios.html")!@) -* [IOS Simulator](@!urlTo("certinstall/ios-simulator.html")!@) -* [Android](@!urlTo("certinstall/android.html")!@) + diff --git a/doc-src/tutorials/gamecenter.html b/doc-src/tutorials/gamecenter.html index 5998f889..b51b6faf 100644 --- a/doc-src/tutorials/gamecenter.html +++ b/doc-src/tutorials/gamecenter.html @@ -2,9 +2,8 @@ ## The setup In this tutorial, I'm going to show you how simple it is to creatively -interfere with Apple Game Center traffic using mitmproxy. To set things up, I -registered my mitmproxy CA certificate with my iPhone - there's a [step by step -set of instructions](@!urlTo("certinstall/ios.html")!@) elsewhere in this manual. I then +interfere with Apple Game Center traffic using mitmproxy. To set things up, +you must install the [mitmproxy root certificate](@!urlTo("certinstall/webapp.html")!@) elsewhere in this manual. I then started mitmproxy on my desktop, and configured the iPhone to use it as a proxy. -- cgit v1.2.3 From f3dab52a6297d4ea2fe0f0bc444bf0a3265e887a Mon Sep 17 00:00:00 2001 From: Jim Shaver Date: Tue, 17 Mar 2015 00:30:18 -0400 Subject: Better english --- doc-src/tutorials/gamecenter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc-src') diff --git a/doc-src/tutorials/gamecenter.html b/doc-src/tutorials/gamecenter.html index b51b6faf..d192232c 100644 --- a/doc-src/tutorials/gamecenter.html +++ b/doc-src/tutorials/gamecenter.html @@ -3,7 +3,7 @@ In this tutorial, I'm going to show you how simple it is to creatively interfere with Apple Game Center traffic using mitmproxy. To set things up, -you must install the [mitmproxy root certificate](@!urlTo("certinstall/webapp.html")!@) elsewhere in this manual. I then +you must install the [mitmproxy root certificate](@!urlTo("certinstall/webapp.html")!@). I then started mitmproxy on my desktop, and configured the iPhone to use it as a proxy. -- cgit v1.2.3 From e0e36f5dae4572ea4053821e6fef1487de87642e Mon Sep 17 00:00:00 2001 From: Jim Shaver Date: Wed, 18 Mar 2015 00:22:18 -0400 Subject: consolidated down all SSL documentation into one document --- doc-src/_nav.html | 3 +- doc-src/certinstall/index.py | 2 +- doc-src/certinstall/webapp.html | 13 ------ doc-src/index.py | 1 - doc-src/ssl.html | 91 --------------------------------------- doc-src/tutorials/gamecenter.html | 2 +- 6 files changed, 3 insertions(+), 109 deletions(-) delete mode 100644 doc-src/certinstall/webapp.html delete mode 100644 doc-src/ssl.html (limited to 'doc-src') diff --git a/doc-src/_nav.html b/doc-src/_nav.html index 91d2118f..3efff40b 100644 --- a/doc-src/_nav.html +++ b/doc-src/_nav.html @@ -29,8 +29,7 @@
  • Installing Certificates
    • - $!nav("ssl.html", this, state)!$ - $!nav("certinstall/webapp.html", this, state)!$ + $!nav("certinstall/ssl.html", this, state)!$
  • Transparent Proxying
    • $!nav("transparent.html", this, state)!$ diff --git a/doc-src/certinstall/index.py b/doc-src/certinstall/index.py index fd422cb3..67e6185b 100644 --- a/doc-src/certinstall/index.py +++ b/doc-src/certinstall/index.py @@ -1,6 +1,6 @@ from countershape import Page pages = [ - Page("webapp.html", "Using the Web App"), + Page("ssl.html", "SSL Options"), Page("mitm.it-error.html", "Error: No proxy configured"), ] diff --git a/doc-src/certinstall/webapp.html b/doc-src/certinstall/webapp.html deleted file mode 100644 index 478da96c..00000000 --- a/doc-src/certinstall/webapp.html +++ /dev/null @@ -1,13 +0,0 @@ - -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. - -Make sure you aren't using a bandwith optimizer (like Google's Data Compression -Proxy on Chrome for Android) or the page will not load. diff --git a/doc-src/index.py b/doc-src/index.py index 753f90a5..1c1203f8 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -67,7 +67,6 @@ pages = [ Page("mitmdump.html", "mitmdump"), Page("config.html", "configuration"), - Page("ssl.html", "Overview"), Directory("certinstall"), Directory("scripting"), Directory("tutorials"), diff --git a/doc-src/ssl.html b/doc-src/ssl.html deleted file mode 100644 index cccde1b7..00000000 --- a/doc-src/ssl.html +++ /dev/null @@ -1,91 +0,0 @@ - -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). 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: - - - - - - - - - - - - - - - - - - -
    mitmproxy-ca.pemThe private key and certificate in PEM format.
    mitmproxy-ca-cert.pemThe certificate in PEM format. Use this to distribute to most - non-Windows platforms.
    mitmproxy-ca-cert.p12The certificate in PKCS12 format. For use on Windows.
    mitmproxy-ca-cert.cerSame file as .pem, but with an extension expected by some Android - devices.
    - - -Using a custom certificate --------------------------- - -You can use your own certificate by passing the --cert option to mitmproxy. mitmproxy then uses the provided -certificate for interception of the specified domains instead of generating a cert signed by its own CA. - -The certificate file is expected to be in the PEM format. -You can include intermediary certificates right below your leaf certificate, so that you PEM file roughly looks like -this: - -
    ------BEGIN PRIVATE KEY-----
-<private key>
------END PRIVATE KEY-----
------BEGIN CERTIFICATE-----
-<cert>
------END CERTIFICATE-----
------BEGIN CERTIFICATE-----
-<intermediary cert (optional)>
------END CERTIFICATE-----
-
    - -For example, you can generate a certificate in this format using these instructions: - -
    -> openssl genrsa -out cert.key 8192
-> openssl req -new -x509 -key cert.key -out cert.crt
-    (Specify the mitm domain as Common Name, e.g. *.google.com)
-> cat cert.key cert.crt > cert.pem
-> mitmproxy --cert=cert.pem
-
    - -Using a client side certificate ------------------------------------- -You can use a client certificate by passing the --client-certs DIRECTORY option to mitmproxy. -If you visit example.org, mitmproxy looks for a file named example.org.pem in the specified directory -and uses this as the client cert. The certificate file needs to be in the PEM format and should contain -both the unencrypted private key as well as the certificate. - - -Using a custom certificate authority ------------------------------------- - -By default, mitmproxy will (generate and) use ~/.mitmproxy/mitmproxy-ca.pem as the default certificate -authority to generate certificates for all domains for which no custom certificate is provided (see above). -You can use your own certificate authority by passing the --confdir option to mitmproxy. -mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists, -it will be generated automatically. - - - diff --git a/doc-src/tutorials/gamecenter.html b/doc-src/tutorials/gamecenter.html index d192232c..8d2e9bc5 100644 --- a/doc-src/tutorials/gamecenter.html +++ b/doc-src/tutorials/gamecenter.html @@ -3,7 +3,7 @@ In this tutorial, I'm going to show you how simple it is to creatively interfere with Apple Game Center traffic using mitmproxy. To set things up, -you must install the [mitmproxy root certificate](@!urlTo("certinstall/webapp.html")!@). I then +you must install the [mitmproxy root certificate](@!urlTo("certinstall/ssl.html")!@). I then started mitmproxy on my desktop, and configured the iPhone to use it as a proxy. -- cgit v1.2.3 From 36bec7b77e1a8c02211c706b3e651fee13a3b3e2 Mon Sep 17 00:00:00 2001 From: Jim Shaver Date: Wed, 18 Mar 2015 00:29:54 -0400 Subject: now actually tracking ssl.html --- doc-src/certinstall/ssl.html | 113 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 doc-src/certinstall/ssl.html (limited to 'doc-src') diff --git a/doc-src/certinstall/ssl.html b/doc-src/certinstall/ssl.html new file mode 100644 index 00000000..8b2b8ed7 --- /dev/null +++ b/doc-src/certinstall/ssl.html @@ -0,0 +1,113 @@ +SSL traffic poses a potential problem when using mitmproxy, as it is encrypted, it is opaque to inspection. +In order to be able to decrypt the traffic, you must use a certificate that the client, whose traffic you are intercepting, trusts. +This document outlines the different options you have for either using the certificate that mitmproxy generates or using your own. + +Quick Setup +----------- + +By far the easiest way to install the mitmproxy certificates 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 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. + +Certificates are installed via several different methods depending on the client. +There are too many to go into in this document, consult the documentation for +the client that you would to have trust the mitmproxy root certificate, +for specific installation instructions. + + +More On mitmproxy Certificates +------------------------------ + +The first time __mitmproxy__ or __mitmdump__ is run, the mitmproxy Certificate +Authority(CA) is created in the config directory (~/.mitmproxy by default). +This CA is used for on-the-fly generation of dummy certificates for each of the +SSL sites that your client visits. Since your browser won't trust the +__mitmproxy__ CA out of the box , you will see an SSL certificate +warning every time you visit a new SSL domain through __mitmproxy__. When +you are 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: + + + + + + + + + + + + + + + + + + +
    mitmproxy-ca.pemThe private key and certificate in PEM format.
    mitmproxy-ca-cert.pemThe certificate in PEM format. Use this to distribute to most + non-Windows platforms.
    mitmproxy-ca-cert.p12The certificate in PKCS12 format. For use on Windows.
    mitmproxy-ca-cert.cerSame file as .pem, but with an extension expected by some Android + devices.
    + + +Using a custom certificate +-------------------------- + +You can use your own certificate by passing the --cert option to mitmproxy. mitmproxy then uses the provided +certificate for interception of the specified domains instead of generating a certificate signed by its own CA. + +The certificate file is expected to be in the PEM format. +You can include intermediary certificates right below your leaf certificate, so that you PEM file roughly looks like +this: + +
    +-----BEGIN PRIVATE KEY-----
+<private key>
+-----END PRIVATE KEY-----
+-----BEGIN CERTIFICATE-----
+<cert>
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+<intermediary cert (optional)>
+-----END CERTIFICATE-----
+
    + +For example, you can generate a certificate in this format using these instructions: + +
    +> openssl genrsa -out cert.key 2048
+> openssl req -new -x509 -key cert.key -out cert.crt
+    (Specify the mitm domain as Common Name, e.g. *.google.com)
+> cat cert.key cert.crt > cert.pem
+> mitmproxy --cert=cert.pem
+
    + +Using a client side certificate +------------------------------------ +You can use a client certificate by passing the --client-certs DIRECTORY option to mitmproxy. +If you visit example.org, mitmproxy looks for a file named example.org.pem in the specified directory +and uses this as the client cert. The certificate file needs to be in the PEM format and should contain +both the unencrypted private key as well as the certificate. + + +Using a custom certificate authority +------------------------------------ + +By default, mitmproxy will (generate and) use ~/.mitmproxy/mitmproxy-ca.pem as the default certificate +authority to generate certificates for all domains for which no custom certificate is provided (see above). +You can use your own certificate authority by passing the --confdir option to mitmproxy. +mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists, +it will be generated automatically. -- cgit v1.2.3 From 6c6639a78aed12a7c19e692c873606ee9bc46852 Mon Sep 17 00:00:00 2001 From: Jim Shaver Date: Tue, 7 Apr 2015 01:33:45 -0400 Subject: Cleaned up wrapping and added links to external CA instructions. --- doc-src/certinstall/ssl.html | 76 +++++++++++++++++++++----------------------- 1 file changed, 36 insertions(+), 40 deletions(-) (limited to 'doc-src') diff --git a/doc-src/certinstall/ssl.html b/doc-src/certinstall/ssl.html index 8b2b8ed7..8d27f0ef 100644 --- a/doc-src/certinstall/ssl.html +++ b/doc-src/certinstall/ssl.html @@ -1,39 +1,44 @@ -SSL traffic poses a potential problem when using mitmproxy, as it is encrypted, it is opaque to inspection. -In order to be able to decrypt the traffic, you must use a certificate that the client, whose traffic you are intercepting, trusts. -This document outlines the different options you have for either using the certificate that mitmproxy generates or using your own. +SSL traffic poses a potential problem when using mitmproxy, as it is encrypted, it is opaque to inspection. In order to be able to decrypt the traffic, you must use a certificate that the client, whose traffic you are intercepting, trusts. This document outlines the different options you have for either using the certificate that mitmproxy generates or using your own. Quick Setup ----------- -By far the easiest way to install the mitmproxy certificates 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 domain **mitm.it**. +By far the easiest way to install the mitmproxy certificates 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 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. +Just click on the relevant icon, and then follow the setup instructions for the platform you're on. -Certificates are installed via several different methods depending on the client. -There are too many to go into in this document, consult the documentation for -the client that you would to have trust the mitmproxy root certificate, -for specific installation instructions. +Certificates are installed via several different methods depending on the client. There are too many to go into in this document, consult the documentation for the client that you would to have trust the mitmproxy root certificate, for specific installation instructions. +Installing the mitmproxy CA Certificate Manually +------------------------------------------------ + +Most of the time you can easily install mitmproxy's CA certificate through the webapp, and just follow the prompts. In a couple of situations, such as Java or the iOS Simulator, there aren't any obvious ways to install the CA certificate. + + + + + + + + + + + + + + + + + +
    iOS SimulatorJava
    WindowsMac OS X
    Ubuntu/DebianFirefox
    iOSAndroid/Android Simulator
    More On mitmproxy Certificates ------------------------------ -The first time __mitmproxy__ or __mitmdump__ is run, the mitmproxy Certificate -Authority(CA) is created in the config directory (~/.mitmproxy by default). -This CA is used for on-the-fly generation of dummy certificates for each of the -SSL sites that your client visits. Since your browser won't trust the -__mitmproxy__ CA out of the box , you will see an SSL certificate -warning every time you visit a new SSL domain through __mitmproxy__. When -you are 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. +The first time __mitmproxy__ or __mitmdump__ is run, the mitmproxy Certificate Authority(CA) is created in the config directory (~/.mitmproxy by default). This CA is used for on-the-fly generation of dummy certificates for each of the SSL sites that your client visits. Since your browser won't trust the __mitmproxy__ CA out of the box , you will see an SSL certificate warning every time you visit a new SSL domain through __mitmproxy__. When you are 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 @@ -66,12 +71,9 @@ The files created by mitmproxy in the .mitmproxy directory are as follows: Using a custom certificate -------------------------- -You can use your own certificate by passing the --cert option to mitmproxy. mitmproxy then uses the provided -certificate for interception of the specified domains instead of generating a certificate signed by its own CA. +You can use your own certificate by passing the --cert option to mitmproxy. mitmproxy then uses the provided certificate for interception of the specified domains instead of generating a certificate signed by its own CA. -The certificate file is expected to be in the PEM format. -You can include intermediary certificates right below your leaf certificate, so that you PEM file roughly looks like -this: +The certificate file is expected to be in the PEM format. You can include intermediary certificates right below your leaf certificate, so that you PEM file roughly looks like this: 
     -----BEGIN PRIVATE KEY-----
@@ -88,26 +90,20 @@ this:
 For example, you can generate a certificate in this format using these instructions:
 
 
    -> openssl genrsa -out cert.key 2048
-> openssl req -new -x509 -key cert.key -out cert.crt
+$ openssl genrsa -out cert.key 2048
+$ openssl req -new -x509 -key cert.key -out cert.crt
     (Specify the mitm domain as Common Name, e.g. *.google.com)
-> cat cert.key cert.crt > cert.pem
-> mitmproxy --cert=cert.pem
+$ cat cert.key cert.crt > cert.pem
+$ mitmproxy --cert=cert.pem
 
    
 
 Using a client side certificate
 ------------------------------------
-You can use a client certificate by passing the --client-certs DIRECTORY option to mitmproxy.
-If you visit example.org, mitmproxy looks for a file named example.org.pem in the specified directory
-and uses this as the client cert. The certificate file needs to be in the PEM format and should contain
-both the unencrypted private key as well as the certificate.
+You can use a client certificate by passing the --client-certs DIRECTORY option to mitmproxy.  If you visit example.org, mitmproxy looks for a file named example.org.pem in the specified directory and uses this as the client cert. The certificate file needs to be in the PEM format and should contain both the unencrypted private key as well as the certificate.
 
 
 Using a custom certificate authority
 ------------------------------------
 
-By default, mitmproxy will (generate and) use ~/.mitmproxy/mitmproxy-ca.pem as the default certificate
-authority to generate certificates for all domains for which no custom certificate is provided (see above).
-You can use your own certificate authority by passing the --confdir option to mitmproxy.
-mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists,
-it will be generated automatically.
+By default, mitmproxy will (generate and) use ~/.mitmproxy/mitmproxy-ca.pem as the default certificate authority to generate certificates for all domains for which no custom certificate is provided (see above).  You can use your own certificate authority by passing the --confdir option to mitmproxy.  mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists, it will be generated automatically.
+
-- 
cgit v1.2.3


From 5ca85bc5f4accf701dc07b09744e51b2af4334a7 Mon Sep 17 00:00:00 2001
From: Jim Shaver 
Date: Fri, 10 Apr 2015 02:20:43 -0400
Subject: Minor reorg and add link for Chrome on Linux

---
 doc-src/certinstall/ssl.html | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

(limited to 'doc-src')

diff --git a/doc-src/certinstall/ssl.html b/doc-src/certinstall/ssl.html
index 8d27f0ef..e9b7df72 100644
--- a/doc-src/certinstall/ssl.html
+++ b/doc-src/certinstall/ssl.html
@@ -21,6 +21,11 @@ Most of the time you can easily install mitmproxy's CA certificate through the w
         iOS Simulator
         Java
     
+    
+        iOS
+        Android/Android Simulator
+    
+
     
         Windows
         Mac OS X
@@ -30,9 +35,9 @@ Most of the time you can easily install mitmproxy's CA certificate through the w
         Firefox
     
     
-        iOS
-        Android/Android Simulator
+        Chrome on Linux
     
+
 
 
 More On mitmproxy Certificates
-- 
cgit v1.2.3


From d4766d8bd03dfaf29bda5860d52d11a8a877a10e Mon Sep 17 00:00:00 2001
From: Jim Shaver 
Date: Sat, 11 Apr 2015 20:04:27 -0400
Subject: Added on page documentation

---
 doc-src/certinstall/ssl.html | 35 +++++++++++++++++++++--------------
 1 file changed, 21 insertions(+), 14 deletions(-)

(limited to 'doc-src')

diff --git a/doc-src/certinstall/ssl.html b/doc-src/certinstall/ssl.html
index e9b7df72..147f5e46 100644
--- a/doc-src/certinstall/ssl.html
+++ b/doc-src/certinstall/ssl.html
@@ -1,7 +1,19 @@
+## On This Page
+
+* [Introduction](#docIntro)
+* [Quick Setup](#docQuick)
+* [Installing the mitmproxy CA certificate manually](#docManual)
+* [More on mitmproxy certificates](#docMore)
+* [CA and cert files](#docCertfiles)
+* [Using a custom certificate](#docCustom)
+* [Using a client side certificate](#docClient)
+* [Using a custom certificate authority](#docCA)
+
+## Introduction
+
 SSL traffic poses a potential problem when using mitmproxy, as it is encrypted, it is opaque to inspection.  In order to be able to decrypt the traffic, you must use a certificate that the client, whose traffic you are intercepting, trusts.  This document outlines the different options you have for either using the certificate that mitmproxy generates or using your own.
 
-Quick Setup
------------
+## Quick Setup
 
 By far the easiest way to install the mitmproxy certificates 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 domain **mitm.it**.
 You should see something like this:
@@ -12,8 +24,7 @@ Just click on the relevant icon, and then follow the setup instructions for the
 
 Certificates are installed via several different methods depending on the client.  There are too many to go into in this document, consult the documentation for the client that you would to have trust the mitmproxy root certificate, for specific installation instructions.
 
-Installing the mitmproxy CA Certificate Manually
-------------------------------------------------
+## Installing the mitmproxy CA certificate manually
 
 Most of the time you can easily install mitmproxy's CA certificate through the webapp, and just follow the prompts.  In a couple of situations, such as Java or the iOS Simulator, there aren't any obvious ways to install the CA certificate.
 
@@ -40,14 +51,12 @@ Most of the time you can easily install mitmproxy's CA certificate through the w
 
 
    
 
-More On mitmproxy Certificates
-------------------------------
+## More on mitmproxy certificates
 
 The first time __mitmproxy__ or __mitmdump__ is run, the mitmproxy Certificate Authority(CA) is created in the config directory (~/.mitmproxy by default).  This CA is used for on-the-fly generation of dummy certificates for each of the SSL sites that your client visits. Since your browser won't trust the __mitmproxy__ CA out of the box , you will see an SSL certificate warning every time you visit a new SSL domain through __mitmproxy__. When you are 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
------------------
+## CA and cert files
 
 The files created by mitmproxy in the .mitmproxy directory are as follows: 
 
@@ -73,8 +82,7 @@ The files created by mitmproxy in the .mitmproxy directory are as follows:
 
     
 
-Using a custom certificate
---------------------------
+## Using a custom certificate
 
 You can use your own certificate by passing the --cert option to mitmproxy. mitmproxy then uses the provided certificate for interception of the specified domains instead of generating a certificate signed by its own CA.
 
@@ -102,13 +110,12 @@ $ cat cert.key cert.crt > cert.pem
 $ mitmproxy --cert=cert.pem
    -Using a client side certificate ------------------------------------- +## Using a client side certificate + You can use a client certificate by passing the --client-certs DIRECTORY option to mitmproxy. If you visit example.org, mitmproxy looks for a file named example.org.pem in the specified directory and uses this as the client cert. The certificate file needs to be in the PEM format and should contain both the unencrypted private key as well as the certificate. -Using a custom certificate authority ------------------------------------- +## Using a custom certificate authority By default, mitmproxy will (generate and) use ~/.mitmproxy/mitmproxy-ca.pem as the default certificate authority to generate certificates for all domains for which no custom certificate is provided (see above). You can use your own certificate authority by passing the --confdir option to mitmproxy. mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists, it will be generated automatically. -- cgit v1.2.3