SSLSPLIT(1)

NAME
sslsplit -- transparent and scalable SSL/TLS interception

SYNOPSIS
sslsplit [-kCKOPZdDgGseujplLS] -c pem proxyspecs [...]
sslsplit [-kCKOPZdDgGseujplLS] -c pem -t dir proxyspecs [...]
sslsplit [-OPZdDgGseujplLS] -t dir proxyspecs [...]
sslsplit -E
sslsplit -V
sslsplit -h

DESCRIPTION
SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS encrypted network connections. Connections are transparently intercepted through a network address translation engine and redirected to SSLsplit. SSLsplit terminates SSL/TLS and initiates a new SSL/TLS connection to the original destination address, while logging all data transmitted. SSLsplit is intended to be useful for network forensics and penetration testing.

SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over both IPv4 and IPv6. For SSL and HTTPS connections, SSLsplit generates and signs forged X509v3 certificates on-the-fly, based on the original server certificate subject DN and subjectAltName extension. SSLsplit fully supports Server Name Indication (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and ECDHE cipher suites. SSLsplit can also use existing certificates of which the private key is available, instead of generating forged ones. SSLsplit supports NULL-prefix CN certificates and can deny OCSP requests in a generic way. SSLsplit removes HPKP response headers in order to prevent public key pinning.

SSLsplit supports a number of NAT engines, static forwarding and SNI DNS lookups to determine the original destination of redirected connections (see NAT ENGINES and PROXY SPECIFICATIONS below).

To actually implement an attack, you also need to redirect the traffic to the system running sslsplit. Your options include running sslsplit 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.

OPTIONS

-c pemfile
    Use CA certificate from pemfile to sign certificates forged on-the-fly. If pemfile also contains the matching CA private key, it is also loaded, otherwise it must be provided with -k. If pemfile also contains Diffie-Hellman group parameters, they are also loaded, otherwise they can be provided with -g. If -t is also given, SSLsplit will only forge a certificate if there is no matching certificate in the provided certificate directory.

-C pemfile
    Use CA certificates from pemfile as extra certificates in the certificate chain. This is needed if the CA given with -k and -c is a sub-CA, in which case any intermediate CA certificates and the root CA certificate must be included in the certificate chain.

-d  Detach from TTY and run as a daemon, logging error messages to syslog instead of standard error.

-D  Run in debug mode, log lots of debugging information to standard error. This also forces foreground mode and cannot be used with -d.

-e engine
    Use engine as the default NAT engine for proxyspecs without explicit NAT engine, static destination address or SNI mode. engine can be any of the NAT engines supported by the system, as returned by -E.

-E  List all supported NAT engines available on the system and exit. See NAT ENGINES for a list of NAT engines currently supported by SSLsplit.

-g pemfile
    Use Diffie-Hellman group parameters from pemfile for Ephemereal Diffie-Hellman (EDH/DHE) cipher suites. If -g is not given, SSLsplit first tries to load DH parameters from the PEM files given by -K, -k or -c. If no DH parameters are found in the key files, built-in 512 or 1024 bit group parameters are automatically used iff a non-RSA private key is given with -K. This is because DSA/DSS private keys can by themselves only be used for signing and thus require DH to exchange an SSL/TLS session key. If -g is given, the parameters from the given pemfile will always be used, even with RSA private keys (within the cipher suites available in OpenSSL). The -g option is only available if SSLsplit was built against a version of OpenSSL which supports Diffie-Hellman cipher suites.

-G curve
    Use the named curve for Ephemereal Elliptic Curve Diffie-Hellman (EECDH) cipher suites. If -G is not given, a default curve (secp160r2) is used automatically iff a non-RSA private key is given with -K. This is because ECDSA/ECDSS private keys can by themselves only be used for signing and thus require ECDH to exchange an SSL/TLS session key. If -G is given, the named curve will always be used, even with RSA private keys (within the cipher suites available in OpenSSL). The -G option is only available if SSLsplit was built against a version of OpenSSL which supports Elliptic Curve Diffie-Hellman cipher suites.

-h  Display help on usage and exit.

-j jaildir
    Change the root directory to jaildir using chroot(2) after opening files. If -j is not given, SSLsplit will automatically change root directory to /var/empty if run as root and -S is not used.

-k pemfile
    Use CA private key from pemfile to sign certificates forged on-the-fly. If pemfile also contains the matching CA certificate, it is also loaded, otherwise it must be provided with -c. If pemfile also contains Diffie-Hellman group parameters, they are also loaded, otherwise they can be provided with -g. If -t is also given, SSLsplit will only forge a certificate if there is no matching certificate in the provided certificate directory.

-K pemfile
    Use private key from pemfile for certificates forged on-the-fly. If -K is not given, SSLsplit will generate a random 1024-bit RSA key.

-l logfile
    Log connections to logfile in a single line per connection format, including addresses and ports and some HTTP and SSL information, if available.

-L logfile
    Log connection content to logfile. The content log will contain a parsable log format with transmitted data, prepended with headers identifying the connection and the data length of each logged segment.

-O  Deny all Online Certificate Status Protocol (OCSP) requests on all proxyspecs and for all OCSP servers with an OCSP response of tryLater, causing OCSP clients to temporarily accept even revoked certificates. HTTP requests are being treated as OCSP requests if the method is GET and the URI contains a syntactically valid OCSPRequest ASN.1 structure parsable by OpenSSL, or if the method is POST and the Content-Type is application/ocsp-request. For this to be effective, SSLsplit must be handling traffic destined to the port used by the OCSP server. In particular, SSLsplit must be configured to receive traffic to all ports used by OCSP servers of targetted certificates within the certdir specified by -t.

-p pidfile
    Write the process ID to pidfile and refuse to run if the pidfile is already in use by another process.

-P  Passthrough SSL/TLS connections which cannot be split instead of dropping them. Connections cannot be split if -c and -k are not given and the site does not match any certificate loaded using -t, or if the connection to the original server gives SSL/TLS errors. Specifically, this happens if the site requests a client certificate. Passthrough with -P results in uninterrupted service for the clients, while dropping is the more secure alternative if unmonitored connections must be prevented.

-s ciphers
    Use OpenSSL ciphers specification for both server and client SSL/TLS connections. If -s is not given, a cipher list of ALL:-aNULL is used. Normally, SSL/TLS implementations choose the most secure cipher suites, not the fastest ones. By specifying an appropriate OpenSSL cipher list, the set of cipher suites can be limited to fast algorithms, or eNULL cipher suites can be added. Note that for connections to be successful, the SSLsplit cipher suites must include at least one cipher suite supported by both the client and the server of each connection. See ciphers(1) for details on how to construct OpenSSL cipher lists.

-S logdir
    Log connection content to separate log files under logdir. For each connection, a log file will be written, which will contain both directions of data as transmitted. Information about the connection will be contained in the filename only. If -S is used with -j, logdir is relative to jaildir. If -S is used with -u, logdir must be writable by user.

-t certdir
    Use private key, certificate and certificate chain from PEM files in certdir for sites matching the respective common names, instead of using certificates forged on-the-fly. A single PEM file must contain a single private key, a single certificate and optionally intermediate and root CA certificates to use as certificate chain. If -c and -k are also given, certificates will be forged on-the-fly for sites matching none of the certificates loaded from certdir. Otherwise, connections matching no certificate will be dropped, or if -P is given, passed through without splitting SSL/TLS.

-u  Drop privileges after opening sockets and files by setting the real, effective and stored user IDs to user and loading the appropriate primary and ancillary groups. If -u is not given, SSLsplit will drop privileges to the stored UID if EUID != UID (setuid bit scenario), or to _sslsplit if running with full root privileges (EUID == UID == 0) and -S is not used.

-V  Display version and compiled features information and exit.

-Z  Disable SSL/TLS compression on all connections. This is useful if your limiting factor is CPU, not network bandwidth. The -Z option is only available if SSLsplit was built against a version of OpenSSL which supports disabling compression.

PROXY SPECIFICATIONS
Proxy specifications (proxyspecs) consist of the connection type, listen address and static forward address or address resolution mechanism (NAT engine, SNI DNS lookup):

https listenaddr port [nat-engine|fwdaddr port|sni port]
ssl listenaddr port [nat-engine|fwdaddr port|sni port]
http listenaddr port [nat-engine|fwdaddr port]
tcp listenaddr port [nat-engine|fwdaddr port]

listenaddr port
    IPv4 or IPv6 address and port or service name to listen on. This is the address and port where the NAT engine should redirect connections to.

nat-engine
    NAT engine to query for determining the original destination address and port of transparently redirected connections. If no engine is given, the default engine is used, unless overridden with -e. When using a NAT engine, sslsplit needs to run on the same system as the NAT rules redirecting the traffic to sslsplit. See NAT ENGINES for a list of supported NAT engines.

fwdaddr port
    Static destination address, IPv4 or IPv6, with port or service name. When this is used, connections are forwarded to the given server address and port.

sni port
    Use the Server Name Indication (SNI) hostname sent by the client in the ClientHello SSL/TLS message to determine the IP address of the server to connect to. This only works for ssl and https proxyspecs and needs a port or service name as an argument. Because this requires DNS lookups, it is preferrable to use NAT engine lookups (see above), except when that is not possible, such as when there is no supported NAT engine or when running sslsplit on a different system than the NAT rules redirecting the actual connections.

NAT ENGINES
SSLsplit currently supports the following NAT engines:

pf  OpenBSD packet filter (pf), using NAT redirects (rdr-to), also available on FreeBSD and NetBSD. Fully supported, including IPv6, but note that divert sockets (divert-to) are preferred (see the ipfw NAT engine). Assuming inbound interface em0:

    pass in quick on em0 proto tcp from 2001:db8::/64 to any port  80 \
             rdr-to       ::1 port 10080
    pass in quick on em0 proto tcp from 2001:db8::/64 to any port 443 \
             rdr-to       ::1 port 10443
    pass in quick on em0 proto tcp from  192.0.2.0/24 to any port  80 \
             rdr-to 127.0.0.1 port 10080
    pass in quick on em0 proto tcp from  192.0.2.0/24 to any port 443 \
             rdr-to 127.0.0.1 port 10443

ipfw
    FreeBSD IP firewall (IPFW), also available on Mac OS X. Also OpenBSD packet filter (pf), using divert-to. Fully supported on FreeBSD and OpenBSD, including IPv6. Only supports IPv4 on Mac OS X due to the ancient version of IPFW included.

    ipfw add fwd       ::1,10080 tcp from 2001:db8::/64 to any  80
    ipfw add fwd       ::1,10443 tcp from 2001:db8::/64 to any 443
    ipfw add fwd 127.0.0.1,10080 tcp from 192.0.2.0/24  to any  80
    ipfw add fwd 127.0.0.1,10443 tcp from 192.0.2.0/24  to any 443

    pass in quick on em0 proto tcp from 2001:db8::/64 to any port  80 \
             divert-to       ::1 port 10080
    pass in quick on em0 proto tcp from 2001:db8::/64 to any port 443 \
             divert-to       ::1 port 10443
    pass in quick on em0 proto tcp from  192.0.2.0/24 to any port  80 \
             divert-to 127.0.0.1 port 10080
    pass in quick on em0 proto tcp from  192.0.2.0/24 to any port 443 \
             divert-to 127.0.0.1 port 10443

ipfilter
    IPFilter (ipfilter, ipf), available on many systems, including FreeBSD, NetBSD, Linux and Solaris. Only supports IPv4 due to limitations in the SIOCGNATL ioctl(2) interface. Assuming inbound interface bge0:

    rdr bge0 0.0.0.0/0 port  80 -> 127.0.0.1 port 10080
    rdr bge0 0.0.0.0/0 port 443 -> 127.0.0.1 port 10443

netfilter
    Linux netfilter using the iptables REDIRECT target. Only supports IPv4 due to limitations in the SO_ORIGINAL_DST getsockopt(2) interface.

    iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
             -p tcp --dport  80 \
             -j REDIRECT --to-ports 10080
    iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
             -p tcp --dport 443 \
             -j REDIRECT --to-ports 10443

tproxy
    Linux netfilter using the iptables TPROXY target together with routing table magic to allow non-local traffic to originate on local sockets. Fully supported, including IPv6.

    ip -f inet6 rule add fwmark 1 lookup 100
    ip -f inet6 route add local default dev lo table 100
    ip6tables -t mangle -N DIVERT
    ip6tables -t mangle -A DIVERT -j MARK --set-mark 1
    ip6tables -t mangle -A DIVERT -j ACCEPT
    ip6tables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
    ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
              -p tcp --dport 80 \
              -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
    ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
              -p tcp --dport 443 \
              -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443
    ip -f inet rule add fwmark 1 lookup 100
    ip -f inet route add local default dev lo table 100
    iptables -t mangle -N DIVERT
    iptables -t mangle -A DIVERT -j MARK --set-mark 1
    iptables -t mangle -A DIVERT -j ACCEPT
    iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
    iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
             -p tcp --dport 80 \
             -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
    iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
             -p tcp --dport 443 \
             -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443

    Note that return path filtering (rp_filter) also needs to be disabled on interfaces which handle TPROXY redirected traffic.

EXAMPLES
Matching the above NAT engine configuration samples, intercept HTTP and HTTPS over IPv4 and IPv6 using forged certificates with CA private key ca.key and certificate ca.crt, logging connections to connect.log and connection data into separate files under /tmp (add -e nat-engine to select the appropriate engine if multiple engines are available on your system):

sslsplit -k ca.key -c ca.crt -l connect.log -L /tmp \
         https ::1 10443  https 127.0.0.1 10443 \
         http  ::1 10080  http  127.0.0.1 10080

Intercepting IMAP/IMAPS using the same settings:

sslsplit -k ca.key -c ca.crt -l connect.log -L /tmp \
         ssl ::1 10993  ssl 127.0.0.1 10993 \
         tcp ::1 10143  tcp 127.0.0.1 10143

A more targetted setup, HTTPS only, using certificate/chain/key files from /path/to/cert.d and statically redirecting to www.example.org instead of querying a NAT engine:

sslsplit -t /path/to/cert.d -l connect.log -L /tmp \
         https ::1       10443 www.example.org 443 \
         https 127.0.0.1 10443 www.example.org 443

The original example, but using SSL options optimized for speed by disabling compression and selecting only fast block cipher cipher suites and using a precomputed private key leaf.key for the forged certificates (most significant speed increase is gained by choosing fast algorithms and small keysizes for the CA and leaf private keys; check openssl speed for algorithm performance on your system):

sslsplit -Z -s NULL:RC4:AES128 -K leaf.key \
         -k ca.key -c ca.crt -l connect.log -L /tmp \
         https ::1 10443  https 127.0.0.1 10443 \
         http  ::1 10080  http  127.0.0.1 10080

The original example, but running as a daemon under user sslsplit and writing a PID file:

sslsplit -d -p /var/run/sslsplit.pid -u sslsplit \
         -k ca.key -c ca.crt -l connect.log -L /tmp \
         https ::1 10443  https 127.0.0.1 10443 \
         http  ::1 10080  http  127.0.0.1 10080

To generate a CA private key ca.key and certificate ca.crt using OpenSSL:

cat >x509v3ca.cnf <<'EOF'
[ req ]
distinguished_name = reqdn
[ reqdn ]
[ v3_ca ]
basicConstraints        = CA:TRUE
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid:always,issuer:always
EOF
openssl genrsa -out ca.key 1024
openssl req -new -nodes -x509 -sha1 -out ca.crt -key ca.key \
        -config x509v3ca.cnf -extensions v3_ca \
        -subj '/O=SSLsplit Root CA/CN=SSLsplit Root CA/' \
        -set_serial 0 -days 3650

SCALABILITY
SSLsplit is scalable to a relatively high number of listeners and connections due to a multithreaded, event based architecture based on libevent, taking advantage of platform specific select() replacements such as kqueue. The main thread handles the listeners and signalling, while a number of worker threads equal to twice the number of CPU cores is used for handling the actual connections in separate event bases, including the CPU-intensive SSL/TLS handling.

Care has been taken to choose scalable data structures for caching certificates and SSL sessions. Logging is implemented in separate disk writer threads to ensure that socket event handling threads don't have to block on disk I/O. DNS lookups are performed asynchroniously. SSLsplit uses SSL session caching on both ends to minimize the amount of full SSL handshakes, but even then, the limiting factor in handling SSL connections are the actual bignum computations.

SEE ALSO
openssl(1), ciphers(1), speed(1), pf(4), ipfw(8), iptables(8), ip6tables(8), ip(8), hostapd(8), arpspoof(8), parasite6(8), yersinia(8)

AUTHORS
Daniel Roethlisberger <daniel@roe.ch>

BUGS
Session resumption does not work for SSLv2-only clients. As a workaround, clients attempting to resume a session will always be given a new one and thus require a full handshake on every connection, resulting in degraded performance with SSLv2 clients. However, SSLv2-only clients should be rare these days.