mirror of
https://github.com/Grasscutters/mitmproxy.git
synced 2024-11-30 11:19:23 +00:00
152 lines
6.0 KiB
HTML
152 lines
6.0 KiB
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-----
|
|
<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.
|