SSLsplit - transparent SSL/TLS interception

Copyright 2009–2019 Daniel Roethlisberger and contributors. All rights reserved.

Licensed under a two-clause BSD license.

tl;dr

Latest release: sslsplit-0.5.5.tar.bz2 (.asc)

Documentation: sslsplit(1) — sslsplit.conf(5) — README.md — NEWS.md

Development: droe/sslsplit — gitter — follow @droethlisberger for news

Overview

SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS encrypted network connections. It is intended to be useful for network forensics, application security analysis and penetration testing.

SSLsplit is designed to transparently terminate connections that are redirected 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. It also has the ability to dynamically upgrade plain TCP to SSL in order to generically support SMTP STARTTLS and similar upgrade mechanisms. SSLsplit fully supports Server Name Indication (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and ECDHE cipher suites. Depending on the version of OpenSSL built against, 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 certificates on-the-fly, mimicking the original server certificate’s subject 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.

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 mangles headers to prevent server-instructed public key pinning (HPKP), avoid strict transport security restrictions (HSTS), avoid Certificate Transparency enforcement (Expect-CT) and prevent switching to QUIC/SPDY, HTTP/2 or WebSockets (Upgrade, Alternate Protocols). HTTP compression, encodings and keep-alive are disabled to make the logs more readable.

Logging options include traditional SSLsplit connect and content log files as well as PCAP files and mirroring decrypted traffic to a network interface. Additionally, certificates, master secrets and local process information can be logged.

Usage

% sslsplit -h Usage: sslsplit [-D] [-f conffile] [-o opt=val] [options...] [proxyspecs...] -f conffile use conffile to load configuration from -o opt=val override conffile option opt with value val -c pemfile use CA cert (and key) from pemfile to sign forged certs -k pemfile use CA key (and cert) from pemfile to sign forged certs -C pemfile use CA chain from pemfile (intermediate and root CA certs) -K pemfile use key from pemfile for leaf certs (default: generate) -q crlurl use URL as CRL distribution point for all forged certs -t certdir use cert+chain+key PEM files from certdir to target all sites matching the common names (non-matching: -T or generate if CA) -A pemfile use cert+chain+key PEM file as fallback leaf cert when none of those given by -t match, instead of generating one on the fly -w gendir write leaf key and only generated certificates to gendir -W gendir write leaf key and all certificates to gendir -O deny all OCSP requests on all proxyspecs -P passthrough SSL connections if they cannot be split because of client cert auth or no matching cert and no CA (default: drop) -a pemfile use cert from pemfile when destination requests client certs -b pemfile use key from pemfile when destination requests client certs -g pemfile use DH group params from pemfile (default: keyfiles or auto) -G curve use ECDH named curve (default: prime256v1) -Z disable SSL/TLS compression on all connections -r proto only support one of ssl3 tls10 tls11 tls12 (default: all) -R proto disable one of ssl3 tls10 tls11 tls12 (default: none) -s ciphers use the given OpenSSL cipher suite spec (default: ALL:-aNULL) -x engine load OpenSSL engine with the given identifier -e engine specify default NAT engine to use (default: pf) -E list available NAT engines and exit -u user drop privileges to user (default if run as root: nobody) -m group when using -u, override group (default: primary group of user) -j jaildir chroot() to jaildir (impacts sni proxyspecs, see manual page) -p pidfile write pid to pidfile (default: no pid file) -l logfile connect log: log one line summary per connection to logfile -L logfile content log: full data to file or named pipe (excludes -S/-F) -S logdir content log: full data to separate files in dir (excludes -L/-F) -F pathspec content log: full data to sep files with % subst (excl. -L/-S): %T - initial connection time as an ISO 8601 UTC timestamp %d - destination host and port %D - destination host %p - destination port %s - source host and port %S - source host %q - source port %x - base name of local process (requires -i) %X - full path to local process (requires -i) %u - user name or id of local process (requires -i) %g - group name or id of local process (requires -i) %% - literal '%' e.g. "/var/log/sslsplit/%X/%u-%s-%d-%T.log" -X pcapfile pcap log: packets to pcapfile (excludes -Y/-y) -Y pcapdir pcap log: packets to separate files in dir (excludes -X/-y) -y pathspec pcap log: packets to sep files with % subst (excl. -X/-Y): see option -F for pathspec format -I if mirror packets to interface -T addr mirror packets to target address (used with -I) -M logfile log master keys to logfile in SSLKEYLOGFILE format -i look up local process owning each connection for logging -d daemon mode: run in background, log error messages to syslog -D debug mode: run in foreground, log debug messages on stderr -V print version information and exit -h print usage information and exit proxyspec = type listenaddr+port [natengine|targetaddr+port|"sni"+port] e.g. http 0.0.0.0 8080 www.roe.ch 80 # http/4; static hostname dst https ::1 8443 2001:db8::1 443 # https/6; static address dst https 127.0.0.1 9443 sni 443 # https/4; SNI DNS lookups tcp 127.0.0.1 10025 # tcp/4; default NAT engine ssl 2001:db8::2 9999 pf # ssl/6; NAT engine 'pf' autossl ::1 10025 # autossl/6; STARTTLS et al Example: sslsplit -k ca.key -c ca.pem -P https 127.0.0.1 8443 https ::1 8443

See the manual page sslsplit(1) for details on using SSLsplit and setting up the various NAT engines.

Requirements

SSLsplit depends on the OpenSSL, libevent 2.x, libpcap and libnet 1.1.x libraries by default; libpcap and libnet are not needed if the mirroring feature is omitted. The build depends on GNU make and a POSIX.2 environment in PATH . If available, pkg-config is used to locate and configure the dependencies. The optional unit tests depend on the check library.

SSLsplit currently supports the following operating systems and NAT engines:

FreeBSD: pf rdr and divert-to, ipfw fwd, ipfilter rdr

OpenBSD: pf rdr-to and divert-to

Linux: netfilter REDIRECT and TPROXY

Mac OS X: ipfw fwd and pf rdr

Support for local process information ( -i ) is currently available on Mac OS X and FreeBSD.

SSL/TLS features and compatibility greatly depend on the version of OpenSSL linked against. For optimal results, use a recent release of OpenSSL or LibreSSL.

Installation

SSLsplit is available as a package or port on the following systems, with varying up-to-dateness:

FreeBSD: security/sslsplit

OpenBSD: security/sslsplit

NetBSD: security/sslsplit

DragonFly BSD: security/sslsplit

Mac OS X Homebrew: sslsplit

Arch Linux: sslsplit

ALT Linux autoimports: sslsplit

Debian: sslsplit

Ubuntu: sslsplit

Gentoo: net-analyzer/sslsplit

Fedora/RHEL/CentOS: sslsplit

OpenSUSE: security/sslsplit

Mageia: sslsplit

ArchAssault: sslsplit

BlackArch Linux: sslsplit

Kali Linux: sslsplit

Backtrack: sslsplit

WiFi Pineapple Infusion: sslsplit

To install from source:

make make test # optional unit tests make sudotest # optional unit tests requiring privileges make install # optional install

Dependencies are autoconfigured using pkg-config. If dependencies are not picked up and fixing PKG_CONFIG_PATH does not help, you can specify their respective locations manually by setting OPENSSL_BASE , LIBEVENT_BASE , LIBPCAP_BASE , LIBNET_BASE and/or CHECK_BASE to the respective prefixes.

You can override the default install prefix ( /usr/local ) by setting PREFIX . For more build options and build-time defaults see GNUmakefile and defaults.h .

Development

SSLsplit is being developed on Github. For bug reports, please use the Github issue tracker. For patch submissions, please send me pull requests.

https://github.com/droe/sslsplit

New releases are announced on my Twitter feed @droethlisberger and by pushing release tags to Github.

Further Reading and Success Stories

These links are provided in the hope that they may be useful, but without implying endorsement of any kind.

Foreign language original content:

Videos featuring SSLsplit:

SSLsplit is also mentioned in the following books: