Repository files navigation

https://www.roe.ch/SSLsplit

SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS encryptednetwork 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 redirectedto it using a network address translation engine. SSLsplit then terminatesSSL/TLS and initiates a new SSL/TLS connection to the original destinationaddress, while logging all data transmitted. Besides NAT based operation,SSLsplit also supports static destinations and using the server name indicatedby SNI as upstream destination. SSLsplit is purely a transparent proxy andcannot act as a HTTP or SOCKS proxy configured in a browser.

SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over bothIPv4 and IPv6. It also has the ability to dynamically upgrade plain TCP to SSLin order to generically support SMTP STARTTLS and similar upgrade mechanisms.SSLsplit fully supports Server Name Indication (SNI) and is able to work withRSA, DSA and ECDSA keys and DHE and ECDHE cipher suites. Depending on theversion of OpenSSL built against, SSLsplit supports SSL 3.0, TLS 1.0, TLS 1.1and TLS 1.2, and optionally SSL 2.0 as well.

For SSL and HTTPS connections, SSLsplit generates and signs forged X509v3certificates on-the-fly, mimicking the original server certificate's subjectDN, subjectAltName extension and other characteristics. SSLsplit has theability to use existing certificates of which the private key is available,instead of generating forged ones. SSLsplit supports NULL-prefix CNcertificates but otherwise does not implement exploits against specificcertificate verification vulnerabilities in SSL/TLS stacks.

SSLsplit implements a number of defences against mechanisms which wouldnormally prevent MitM attacks or make them more difficult. SSLsplit can denyOCSP requests in a generic way. For HTTP and HTTPS connections, SSLsplitmangles headers to prevent server-instructed public key pinning (HPKP), avoidstrict transport security restrictions (HSTS), avoid Certificate Transparencyenforcement (Expect-CT) and prevent switching to QUIC/SPDY, HTTP/2 orWebSockets (Upgrade, Alternate Protocols). HTTP compression, encodings andkeep-alive are disabled to make the logs more readable.

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

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

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

SSLsplit currently supports the following operating systems and NAT mechanisms:

• 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: pf rdr and ipfw fwd

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

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

With the requirements above available, run:

makemake test       # optional unit testsmake sudotest   # optional unit tests requiring privilegesmake install    # optional install

Dependencies are autoconfigured using pkg-config. If dependencies are notpicked up and fixingPKG_CONFIG_PATH does not help, you can specify theirrespective locations manually by settingOPENSSL_BASE,LIBEVENT_BASE,LIBPCAP_BASE,LIBNET_BASE and/orCHECK_BASE to the respective prefixes.

You can override the default install prefix (/usr/local) by settingPREFIX.For more build options and build-time defaults seeGNUmakefileanddefaults.h.

See the manual pagessslsplit(1) andsslsplit.conf(5) for userdocumentation. SeeNEWS.md for release notes listing significantchanges between releases andSECURITY.md for information onsecurity vulnerability disclosure.

SSLsplit is provided under a 2-clause BSD license.SSLsplit contains components licensed under the MIT and APSL licenses.SeeLICENSE,LICENSE.contrib andLICENSE.third as well as the respective source file headersfor details.

SeeAUTHORS.md for the list of contributors.

SSLsplit was inspired bymitm-ssl by Claes M. Nyberg andsslsniff by MoxieMarlinspike, but shares no source code with them.