Rewrite description for clarity

Issue:		#60, #93

README.md

@@ -6,25 +6,38 @@ http://www.roe.ch/SSLsplit
 ## Overview
 
 SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS encrypted
-network connections.  Connections are transparently intercepted through a
+network connections.  It is intended to be useful for network forensics,
-network address translation engine and redirected to SSLsplit.  SSLsplit
+application security analysis and penetration testing.
-terminates SSL/TLS and initiates a new SSL/TLS connection to the original
+
-destination address, while logging all data transmitted.  SSLsplit is intended
+SSLsplit is designed to transparently terminate connections that are redirected
-to be useful for network forensics and penetration testing.
+to it using a network address translation engine.  SSLsplit then terminates
+SSL/TLS and initiates a new SSL/TLS connection to the original destination
+address, while logging all data transmitted.  Besides NAT based operation,
+SSLsplit also supports static destinations and using the server name indicated
+by SNI as upstream destination.  SSLsplit is purely a transparent proxy and
+cannot act as a HTTP or SOCKS proxy configured in a browser.
 
 SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over both
-IPv4 and IPv6.  For SSL and HTTPS connections, SSLsplit generates and signs
+IPv4 and IPv6.  SSLsplit fully supports Server Name Indication (SNI) and is
-forged X509v3 certificates on-the-fly, based on the original server certificate
+able to work with RSA, DSA and ECDSA keys and DHE and ECDHE cipher suites.
-subject DN and subjectAltName extension.  SSLsplit fully supports Server Name
+Depending on the version of OpenSSL built against, SSLsplit supports SSL 3.0,
-Indication (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and
+TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0 as well.
-ECDHE cipher suites.  Depending on the version of OpenSSL, SSLsplit supports
+
-SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0 as well.
+For SSL and HTTPS connections, SSLsplit generates and signs forged X509v3
-SSLsplit can also use existing certificates of which the private key is
+certificates on-the-fly, mimicking the original server certificate's subject
-available, instead of generating forged ones.  SSLsplit supports NULL-prefix CN
+DN, subjectAltName extension and other  characteristics.  SSLsplit has the
-certificates and can deny OCSP requests in a generic way.  For HTTP and HTTPS
+ability to use existing certificates of which the private key is available,
-connections, SSLsplit removes response headers for HPKP in order to prevent
+instead of generating forged ones.  SSLsplit supports NULL-prefix CN
-public key pinning, for HSTS to allow the user to accept untrusted
+certificates but otherwise does not implement exploits against specific
-certificates, and Alternate Protocols to prevent switching to QUIC/SPDY.
+certificate verification vulnerabilities in SSL/TLS stacks.
+
+SSLsplit implements a number of defences against mechanisms which would
+normally prevent MitM attacks or make them more difficult.  SSLsplit can deny
+OCSP requests in a generic way.  For HTTP and HTTPS connections, SSLsplit
+removes response headers for HPKP in order to prevent public key pinning, for
+HSTS to allow the user to accept untrusted certificates, and Alternate
+Protocols to prevent switching to QUIC/SPDY.  For HTTP, compression is disabled
+to make the logs more readable.
 
 See the manual page sslsplit(1) for details on using SSLsplit and setting up
 the various NAT engines.

sslsplit.1

@@ -49,37 +49,50 @@ sslsplit \-\- transparent SSL/TLS interception
 .ad
 .SH DESCRIPTION
 SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS encrypted
-network connections.  Connections are transparently intercepted through a
+network connections.  It is intended to be useful for network forensics,
-network address translation engine and redirected to SSLsplit.  SSLsplit
+application security analysis and penetration testing.
-terminates SSL/TLS and initiates a new SSL/TLS connection to the original
+.LP
-destination address, while logging all data transmitted.  SSLsplit is intended
+SSLsplit is designed to transparently terminate connections that are redirected
-to be useful for network forensics and penetration testing.
+to it using a network address translation engine.  SSLsplit then terminates
+SSL/TLS and initiates a new SSL/TLS connection to the original destination
+address, while logging all data transmitted.
+Besides NAT based operation, SSLsplit also supports static destinations and
+using the server name indicated by SNI as upstream destination.
+SSLsplit is purely a transparent proxy and cannot act as a HTTP or SOCKS proxy
+configured in a browser.
+See NAT ENGINES and PROXY SPECIFICATIONS below for specifics on the different
+modes of operation.
 .LP
 SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over both
-IPv4 and IPv6.  For SSL and HTTPS connections, SSLsplit generates and signs
+IPv4 and IPv6.
-forged X509v3 certificates on-the-fly, based on the original server certificate
+SSLsplit fully supports Server Name Indication (SNI) and is able to work with
-subject DN and subjectAltName extension.  SSLsplit fully supports Server Name
+RSA, DSA and ECDSA keys and DHE and ECDHE cipher suites.  Depending on the
-Indication (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and
+version of OpenSSL, SSLsplit supports SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2,
-ECDHE cipher suites.  Depending on the version of OpenSSL, SSLsplit supports
+and optionally SSL 2.0 as well.
-SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0 as well.
+.LP
-SSLsplit can also use existing certificates of which the private key is
+For SSL and HTTPS connections, SSLsplit generates and signs forged X509v3
-available, instead of generating forged ones.  SSLsplit supports NULL-prefix
+certificates on-the-fly, mimicking the original server certificate's subject
-CN certificates and can deny OCSP requests in a generic way.
+DN, subjectAltName extension and other characteristics.
+SSLsplit has the ability to use existing certificates of which the private key
+is available, instead of generating forged ones.  SSLsplit supports NULL-prefix
+CN certificates but otherwise does not implement exploits against specific
+certificate verification vulnerabilities in SSL/TLS stacks.
+.LP
+SSLsplit implements a number of defences against mechanisms which would
+normally prevent MitM attacks or make them more difficult.
+SSLsplit can deny OCSP requests in a generic way.
 For HTTP and HTTPS connections, SSLsplit removes response headers
 for HPKP in order to prevent public key pinning,
 for HSTS to allow the user to accept untrusted certificates,
 and Alternate Protocols to prevent switching to QUIC/SPDY.
+For HTTP, compression is disabled to make the logs more readable.
 .LP
-SSLsplit supports a number of NAT engines, static forwarding and SNI DNS
+SSLsplit does not automagically redirect any network traffic.  To actually
-lookups to determine the original destination of redirected connections
+implement an attack, you also need to redirect the traffic to the system
-(see NAT ENGINES and PROXY SPECIFICATIONS below).
+running \fBsslsplit\fP.  Your options include running \fBsslsplit\fP on a
-.LP
+legitimate router, ARP spoofing, ND spoofing, DNS poisoning, deploying a rogue
-To actually implement an attack, you also need to redirect the traffic to the
+access point (e.g. using hostap mode), physical recabling, malicious VLAN
-system running \fBsslsplit\fP.  Your options include running \fBsslsplit\fP on
-a legitimate router, ARP spoofing, ND spoofing, DNS poisoning, deploying a
-rogue access point (e.g. using hostap mode), physical recabling, malicious VLAN
 reconfiguration or route injection, /etc/hosts modification and so on.
-SSLsplit does not implement the actual traffic redirection.
 .SH OPTIONS
 .TP
 .B \-c \fIpemfile\fP