From a9f6d53562b8020b87a8feaba2ac1d16d0d869ee Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Mon, 18 May 2015 12:05:29 +1200 Subject: certificate docs: reorg, wording, tweaks --- doc-src/certinstall.html | 151 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 doc-src/certinstall.html (limited to 'doc-src/certinstall.html') diff --git a/doc-src/certinstall.html b/doc-src/certinstall.html new file mode 100644 index 00000000..d1435720 --- /dev/null +++ b/doc-src/certinstall.html @@ -0,0 +1,151 @@ +## 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 + +Mitmproxy can decrypt encrypted traffic on the fly, as long as the client +trusts its built-in certificate authority. Usually this means that the +mitmproxy CA certificates have to be installed on the client device. + +## Quick Setup + +By far the easiest way to install the mitmproxy certificates is to use the +built-in certificate installation app. To do this, just 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: + + + +Click on the relevant icon, and follow the setup instructions for the platform +you're on, and you are good to go. + + +## Installing the mitmproxy CA certificate manually + +Sometimes using the quick install app is not an option - Java or the IOS +similator spring to mind - or you just need to do it manually for some other +reason. Below is a list of pointers to manual certificate installation +documentation for some common platforms: + + + + + + + + + + + + + + + + + + + + + + + +
iOS SimulatorJava
iOSAndroid/Android Simulator
WindowsMac OS X
Ubuntu/DebianFirefox
Chrome on Linux
+ +## 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 and the certificate. + + +## Using a custom certificate authority + +By default, mitmproxy will use ~/.mitmproxy/mitmproxy-ca.pem as +the 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