174 lines
5.8 KiB
ReStructuredText
174 lines
5.8 KiB
ReStructuredText
.. _certinstall:
|
|
|
|
About Certificates
|
|
==================
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
.. image:: certinstall-webapp.png
|
|
|
|
Click on the relevant icon, follow the setup instructions for the platform
|
|
you're on and you are good to go.
|
|
|
|
|
|
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.
|
|
|
|
The mitmproxy CA cert is located in ``~/.mitmproxy`` after it has been generated at the first
|
|
start of mitmproxy.
|
|
|
|
|
|
iOS
|
|
^^^
|
|
|
|
http://kb.mit.edu/confluence/pages/viewpage.action?pageId=152600377
|
|
|
|
iOS Simulator
|
|
^^^^^^^^^^^^^
|
|
|
|
See https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore
|
|
|
|
Java
|
|
^^^^
|
|
|
|
See http://docs.oracle.com/cd/E19906-01/820-4916/geygn/index.html
|
|
|
|
Android/Android Simulator
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
See http://wiki.cacert.org/FAQ/ImportRootCert#Android_Phones_.26_Tablets
|
|
|
|
Windows
|
|
^^^^^^^
|
|
|
|
See http://windows.microsoft.com/en-ca/windows/import-export-certificates-private-keys#1TC=windows-7
|
|
|
|
Windows (automated)
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
>>> certutil.exe -importpfx mitmproxy-ca-cert.p12
|
|
|
|
See also: https://technet.microsoft.com/en-us/library/cc732443.aspx
|
|
|
|
Mac OS X
|
|
^^^^^^^^
|
|
|
|
See https://support.apple.com/kb/PH7297?locale=en_US
|
|
|
|
Ubuntu/Debian
|
|
^^^^^^^^^^^^^
|
|
|
|
See http://askubuntu.com/questions/73287/how-do-i-install-a-root-certificate/94861#94861
|
|
|
|
Mozilla Firefox
|
|
^^^^^^^^^^^^^^^
|
|
|
|
See https://wiki.mozilla.org/MozillaRootCertificate#Mozilla_Firefox
|
|
|
|
Chrome on Linux
|
|
^^^^^^^^^^^^^^^
|
|
|
|
See https://code.google.com/p/chromium/wiki/LinuxCertManagement
|
|
|
|
|
|
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. For security reasons, the mitmproxy CA is generated uniquely on the first
|
|
start and is not shared between mitmproxy installations on different devices.
|
|
|
|
|
|
CA and cert files
|
|
-----------------
|
|
|
|
The files created by mitmproxy in the .mitmproxy directory are as follows:
|
|
|
|
===================== ====================================================================================
|
|
mitmproxy-ca.pem The certificate **and the private key** in PEM format.
|
|
mitmproxy-ca-cert.pem The certificate in PEM format. Use this to distribute on most non-Windows platforms.
|
|
mitmproxy-ca-cert.p12 The certificate in PKCS12 format. For use on Windows.
|
|
mitmproxy-ca-cert.cer Same file as .pem, but with an extension expected by some Android devices.
|
|
===================== ====================================================================================
|
|
|
|
Using a custom certificate
|
|
--------------------------
|
|
|
|
You can use your own certificate by passing the ``--cert`` 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:
|
|
|
|
.. code-block:: none
|
|
|
|
-----BEGIN PRIVATE KEY-----
|
|
<private key>
|
|
-----END PRIVATE KEY-----
|
|
-----BEGIN CERTIFICATE-----
|
|
<cert>
|
|
-----END CERTIFICATE-----
|
|
-----BEGIN CERTIFICATE-----
|
|
<intermediary cert (optional)>
|
|
-----END CERTIFICATE-----
|
|
|
|
|
|
For example, you can generate a certificate in this format using these instructions:
|
|
|
|
|
|
>>> 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
|
|
|
|
|
|
Using a custom certificate authority
|
|
------------------------------------
|
|
|
|
By default, mitmproxy will use ``~/.mitmproxy/mitmproxy-ca.pem`` 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 ``--confdir`` option to mitmproxy. Mitmproxy
|
|
will then look for ``mitmproxy-ca.pem`` in the specified directory. If
|
|
no such file exists, it will be generated automatically.
|
|
|
|
|
|
Using a client side certificate
|
|
-------------------------------
|
|
|
|
You can use a client certificate by passing the ``--client-certs DIRECTORY``
|
|
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.
|
|
|