diff options
Diffstat (limited to 'doc-src/certinstall.html')
| -rw-r--r-- | doc-src/certinstall.html | 151 |
1 files changed, 151 insertions, 0 deletions
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) + +## <a id="docIntro"></a>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. + +## <a id="docQuick"></a>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: + +<img src="@!urlTo("certinstall-webapp.png")!@"></img> + +Click on the relevant icon, and follow the setup instructions for the platform +you're on, and you are good to go. + + +## <a id="docManual"></a>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: + +<table class="table"> + <tr> + <td><a href="https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore"</a>iOS Simulator</td> + <td><a href="http://docs.oracle.com/cd/E19906-01/820-4916/geygn/index.html">Java</a></td> + </tr> + <tr> + <td><a href="http://kb.mit.edu/confluence/pages/viewpage.action?pageId=152600377">iOS</a></td> + <td><a href="http://wiki.cacert.org/FAQ/ImportRootCert#Android_Phones_.26_Tablets">Android/Android Simulator</a></td> + </tr> + + <tr> + <td><a href="http://windows.microsoft.com/en-ca/windows/import-export-certificates-private-keys#1TC=windows-7">Windows</a></td> + <td><a href="https://support.apple.com/kb/PH7297?locale=en_US">Mac OS X</a></td> + </tr> + <tr> + <td><a href="http://askubuntu.com/questions/73287/how-do-i-install-a-root-certificate/94861#94861">Ubuntu/Debian</a></td> + <td><a href="https://wiki.mozilla.org/MozillaRootCertificate#Mozilla_Firefox">Firefox</a></td> + </tr> + <tr> + <td><a href="https://code.google.com/p/chromium/wiki/LinuxCertManagement">Chrome on Linux</a></td> + </tr> + +</table> + +## <a id="docMore"></a>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. + + +## <a id="docCertfiles"></a>CA and cert files + +The files created by mitmproxy in the .mitmproxy directory are as follows: + +<table class="table"> + <tr> + <td class="nowrap">mitmproxy-ca.pem</td> + <td>The private key and certificate in PEM format.</td> + </tr> + <tr> + <td class="nowrap">mitmproxy-ca-cert.pem</td> + <td>The certificate in PEM format. Use this to distribute to most + non-Windows platforms.</td> + </tr> + <tr> + <td class="nowrap">mitmproxy-ca-cert.p12</td> + <td>The certificate in PKCS12 format. For use on Windows.</td> + </tr> + <tr> + <td class="nowrap">mitmproxy-ca-cert.cer</td> + <td>Same file as .pem, but with an extension expected by some Android + devices.</td> + </tr> +</table> + + +## <a id="docCustom"></a>Using a custom certificate + +You can use your own certificate by passing the <kbd>--cert</kbd> 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: + +<pre> +-----BEGIN PRIVATE KEY----- +<private key> +-----END PRIVATE KEY----- +-----BEGIN CERTIFICATE----- +<cert> +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +<intermediary cert (optional)> +-----END CERTIFICATE----- +</pre> + +For example, you can generate a certificate in this format using these instructions: + +<pre class="terminal"> +$ 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 +</pre> + +## <a id="docClient"></a>Using a client side certificate + +You can use a client certificate by passing the <kbd>--client-certs +DIRECTORY</kbd> 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. + + +## <a id="docCA"></a>Using a custom certificate authority + +By default, mitmproxy will use <samp>~/.mitmproxy/mitmproxy-ca.pem</samp> 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 <kbd>--confdir</kbd> option to mitmproxy. Mitmproxy +will then look for <samp>mitmproxy-ca.pem</samp> in the specified directory. If +no such file exists, it will be generated automatically. |