mitmproxy/doc-src/certinstall.html

## 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-----
&lt;private key&gt;
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
&lt;cert&gt;
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
&lt;intermediary cert (optional)&gt;
-----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.