Updated MITM documentation and LP version

Author: jekh

mitm/README.md

@@ -1,23 +1,26 @@
 # MITM with LittleProxy
-The MITM module is a LittleProxy-compatible module that enables man-in-the-middle interception of HTTPS requests. Though it is developed and distributed with BrowserMob Proxy, it has no dependency on BMP and can be used in a LittleProxy-only environment. (The only transitive dependency of the MITM module is the Bouncy Castle encryption library.)
+The MITM module is a LittleProxy-compatible module that enables man-in-the-middle interception of HTTPS requests. MITM allows you to:
+- [Generate both RSA and EC private keys](#improving-performance-with-elliptic-curve-ec-cryptography) (EC provides a significant performance boost, ~50x faster than RSA)
+- [Use a custom Certificate Authority](#using-a-custom-certificate-authority) (e.g. a corporate CA) to sign impersonated certificates, or generate (and optionally save) a new CA on-the-fly
+- [Specify a custom trust store](#trusted-root-certificates-and-custom-trust-stores) on proxy-to-server connections, allowing the proxy to trust personal or corporate CAs
+- [Use OpenSSL](#openssl-support), improving performance over Java's built-in TLS implementation
 
-## Quick start
-The MITM module uses "sensible" default settings that should work for the vast majority of users without any further configuration.
+Though MITM is developed and distributed with BrowserMob Proxy, it has no dependency on BMP and can be used in a LittleProxy-only environment. The only additional dependency is the Bouncy Castle encryption library.
 
+## Quick start
 ### LittleProxy (without BrowserMob Proxy)
-**Note:** The MITM module requires Java 7
 
-To use MITM with standalone LittleProxy, add a dependency to the mitm module in your pom:
+To use MITM with standalone LittleProxy, add a dependency on the `mitm` module in your pom:
 
 ```xml
     <!-- existing LittleProxy dependency -->
     <dependency>
         <groupId>org.littleshoot</groupId>
         <artifactId>littleproxy</artifactId>
-        <version>1.1.1</version>
+        <version>1.1.2</version>
     </dependency>
 
-    <-- new dependency on the MITM module -->
+    <!-- new dependency on the MITM module -->
     <dependency>
         <groupId>net.lightbody.bmp</groupId>
         <artifactId>mitm</artifactId>
@@ -37,7 +40,7 @@ The default implementation of `ImpersonatingMitmManager` will generate a new CA
 ### BrowserMob Proxy
 The MITM module is enabled by default with BrowserMob Proxy. No additional steps are required to enable MITM with BrowserMob Proxy. 
 
-By default, BrowserMob Proxy will use the `ca-keystore-rsa.p12` file to load its CA Root Certificate and Private Key. The corresponding certificate file is `ca-certificate-rsa.cer`, which can be installed as a trusted Certification Authority in browsers or other HTTP clients to avoid HTTPS warnings when using BrowserMob Proxy.
+By default, BrowserMob Proxy will use the `ca-keystore-rsa.p12` file to load its CA Root Certificate and Private Key. The corresponding certificate file is `ca-certificate-rsa.cer`, which can be installed as a trusted Certificate Authority in browsers or other HTTP clients to avoid HTTPS warnings when using BrowserMob Proxy.
 
 ## Examples
 Several examples are available to help you get started:
@@ -49,7 +52,6 @@ Example File | Configuration
 [CustomCAKeyStoreExample.java](src/test/java/net/lightbody/bmp/mitm/example/CustomCAKeyStoreExample.java) and [CustomCAPemFileExample.java](src/test/java/net/lightbody/bmp/mitm/example/CustomCAPemFileExample.java) | Use an existing CA certificate and private key
 [EllipticCurveCAandServerExample.java](src/test/java/net/lightbody/bmp/mitm/example/EllipticCurveCAandServerExample.java) | Use EC cryptography when generating the CA private key and when impersonating server certificates
 
-
 ## Generating and Saving Root Certificates
 By default, when using the MITM module with LittleProxy, the CA Root Certificate and Private Key are generated dynamically. The dynamically generated Root Certificate and Private Key can be saved for installation in a browser or later reuse by using the methods on the `RootCertificateGenerator` class. For example:
 
@@ -76,7 +78,7 @@ By default, when using the MITM module with LittleProxy, the CA Root Certificate
             .withManInTheMiddle(mitmManager);
 ```
 
-## Using a Custom Certification Authority
+## Using a Custom Certificate Authority
 Whether you are using the MITM module with LittleProxy or BrowserMob Proxy, you can provide your own root certificate and private key to use when signing impersonated server certificates. To use a root certificate and private key from a key store (PKCS12 or JKS), use the `KeyStoreFileCertificateSource` class:
 
 ```java
@@ -99,7 +101,7 @@ Whether you are using the MITM module with LittleProxy or BrowserMob Proxy, you
 
 You can also load the root certificate and private key from separate PEM-encoded files using the `PemFileCertificateSource` class, or create an implementation of `CertificateAndKeySource` that loads the certificate and private key from another source.
 
-## Trusted Root Certificates
+## Trusted Root Certificates and Custom Trust Stores
 The MITM module trusts the Certificate Authorities in the JVM's default trust store, as well as a default list of trusted CAs derived from NSS/Firefox's list of trusted CAs (courtesy of the cURL team: https://curl.haxx.se/ca/cacert.pem).
 
 To add your own CA to the list of root CAs trusted by the MITM module, use the `add()` methods in the `net.lightbody.bmp.mitm.TrustSource` class. Alternatively, it is possible to disable upstream server validation, but this is only recommended when testing. Examples:
@@ -124,14 +126,14 @@ To add your own CA to the list of root CAs trusted by the MITM module, use the `
 ## Improving Performance with Elliptic Curve (EC) Cryptography
 By default, the certificates generated by the MITM module use RSA private keys for both impersonated server certificates and for generated CA root certificates. However, all modern browsers support Elliptic Curve Cryptography, which uses smaller key sizes. As a result, impersonated EC server certificates can be generated significantly faster (approximately 50x faster is common, typically <10ms per impersonated certificate).
 
-Unforunately, due to a bug in Java's SSL handshake, EC keys cannot be used with RSA Certification Authorities (i.e. impersonated EC server certificates must be digitally signed by a CA's EC private key -- see https://bugs.openjdk.java.net/browse/JDK-8136442). 
-
-The MITM module's RootCertificateGenerator can be configured to generate an EC root certificate for use with EC server certificates. If you are using your own CA root certificate and private key, make sure to generate an EC private key if you intend to use impersonated EC server certificates.
+The MITM module's RootCertificateGenerator can be configured to generate an EC root certificate for use with EC server certificates. If you are using your own CA root certificate
+and private key, make sure to generate an EC private key if you intend to use impersonated EC server certificates. (Though it is possible to generate "hybrid"
+server certificates with an EC key signed by an RSA CA, they are uncommon, and not all clients support them. In particular, Java clients and servers [before 8u92 do not support hybrid certificates.](https://bugs.openjdk.java.net/browse/JDK-8136442))
 
 To generate EC certificates for impersonated servers, set the `serverKeyGenerator` to `ECKeyGenerator` in ImpersonatingMitmManager. To generate an EC root certificate and private key, set the `keyGenerator` to `ECKeyGenerator` in RootCertificateGenerator:
 
 ```java
-    // create a RootCertificateGenerator that generates EC Certification Authorities; you may also load your 
+    // create a RootCertificateGenerator that generates EC Certificate Authorities; you may also load your
     // own EC certificate and private key using any other CertificateAndKeySource implementation 
     // (KeyStoreFileCertificateSource, PemFileCertificateSource, etc.).
     CertificateAndKeySource rootCertificateGenerator = RootCertificateGenerator.builder()
@@ -153,5 +155,10 @@ To generate EC certificates for impersonated servers, set the `serverKeyGenerato
     proxy.setMitmManager(mitmManager);
 ```
 
+## OpenSSL support
+The MITM module takes advantage of Netty's support for OpenSSL, allowing you to use OpenSSL instead of Java's built-in TLS implementation, which may provide
+significant performance benefits. The MITM module itself requires no additional configuration to use OpenSSL: all you need is an OpenSSL installation and a dependency on the `netty-tcnative` library for your platform.
+See Netty's OpenSSL instructions for details: http://netty.io/wiki/requirements-for-4.x.html#tls-with-openssl
+
 ## Acknowledgements
 The MITM module would not have been possible without the efforts of Frank Ganske, the Zed Attack Proxy, and Brad Hill. Thank you for all your excellent work!

mitm/pom.xml

@@ -15,7 +15,7 @@
         <dependency>
             <groupId>org.littleshoot</groupId>
             <artifactId>littleproxy</artifactId>
-            <version>1.1.1</version>
+            <version>1.1.2</version>
             <optional>true</optional>
             <exclusions>
                 <exclusion>

mitm/src/main/java/net/lightbody/bmp/mitm/manager/ImpersonatingMitmManager.java

@@ -287,7 +287,7 @@ private SslContext createImpersonatingSslContext(CertificateInfo certificateInfo
         // to impersonate the real upstream server, and will use the private key to encrypt the channel.
         KeyPair serverKeyPair = serverKeyGenerator.generate();
 
-        // get the CA root certificate and private key that will be used to sign the forced certificate
+        // get the CA root certificate and private key that will be used to sign the forged certificate
         X509Certificate caRootCertificate = rootCertificate.get().getCertificate();
         PrivateKey caPrivateKey = rootCertificate.get().getPrivateKey();
         if (caRootCertificate == null || caPrivateKey == null) {