diff options
Diffstat (limited to 'doc-src/certinstall.html')
| -rw-r--r-- | doc-src/certinstall.html | 151 |
1 files changed, 0 insertions, 151 deletions
diff --git a/doc-src/certinstall.html b/doc-src/certinstall.html deleted file mode 100644 index 594049d9..00000000 --- a/doc-src/certinstall.html +++ /dev/null @@ -1,151 +0,0 @@ -## 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 class="img-responsive" 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 -Simulator 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. |