mitmproxy/doc-src/ssl.html

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: 

<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>
    

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 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:

<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 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
</pre>


Using a custom certificate authority
------------------------------------

By default, mitmproxy will (generate and) use <samp>~/.mitmproxy/mitmproxy-ca.pem</samp> 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 <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.

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")!@)