now actually tracking ssl.html

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-----
+&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>
+
+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.