diff options
Diffstat (limited to 'doc-src')
| -rw-r--r-- | doc-src/certinstall/ssl.html | 113 |
1 files changed, 113 insertions, 0 deletions
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: + +<img src="@!urlTo("webapp.png")!@"></img> + +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: + +<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 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> + +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 as well as the certificate. + + +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. |