docs++

1 files changed, 13 insertions, 13 deletions

diff --git a/docs/certinstall.rst b/docs/certinstall.rst
index 2e041837..5ec7b7ce 100644
--- a/docs/certinstall.rst
+++ b/docs/certinstall.rst
@@ -90,30 +90,28 @@ Chrome on Linux
 See https://code.google.com/p/chromium/wiki/LinuxCertManagement
 
 
-More on mitmproxy certificates
-------------------------------
+The mitmproxy certificate authority
+-----------------------------------
 
 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
+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.
+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.
 
-Some applications pin their SSL certificates in order to prevent MITM attacks.
+Certificate Pinning
+^^^^^^^^^^^^^^^^^^^
+
+Some applications employ `Certificate Pinning`_ to prevent man-in-the-middle attacks.
 This means that **mitmproxy** and **mitmdump's** certificates will not be
-accepted by these applications. This is because when an application pins a
-certificate it requires that SSL traffic is encrypted with a specific
-certificate rather than any certificate that is signed by a trusted Certificate
-Authority (CA). In order to work around this, it is recommended to use the 
-`Ignore Domains <http://docs.mitmproxy.org/en/stable/features/passthrough.html#ignore-domains>`_
-feature in order to prevent **mitmproxy** and **mitmdump** from intercepting
-traffic to these specific domains. 
+accepted by these applications without modifying them. It is recommended to use the
+:ref:`passthrough` feature in order to prevent **mitmproxy** and **mitmdump** from intercepting
+traffic to these specific domains. If you want to intercept the pinned connections, you need to patch the application manually. For Android and (jailbroken) iOS devices, various tools exist to accomplish this.
 
 
 CA and cert files
@@ -182,3 +180,5 @@ If you visit example.org, mitmproxy looks for a file named ``example.org.pem`` i
 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.
 
+
+.. _Certificate Pinning: http://security.stackexchange.com/questions/29988/what-is-certificate-pinning/
\ No newline at end of file