sslsplit(1)

📦
version 0.5.5 · 11 versions
, in ubuntu noble, ubuntu questing

🎀 NAME 🎀

sslsplit — transparent SSL/TLS interception. That's the whole name section, bestie, we're starting strong and we're not slowing down.

And just so we're clear on what we're reading: this is the sslsplit(1) page out of the SSLsplit manual, and it is long, so buckle up. 🦋

✨ SYNOPSIS ✨

sslsplit [-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab] -c pem proxyspecs [...]
sslsplit [-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab] -c pem -t dir proxyspecs
[...]
sslsplit [-OPZwWdDgGsrRxeumjplLSFXYyTIMiab] -t dir proxyspecs [...]
sslsplit [-kCKwWOPZdDgGsrRxeumjplLSFXYyTIMi] -f conffile
sslsplit -E
sslsplit -V
sslsplit -h

Look at that wall of flags. It's giving "final boss of getopt" and honestly? Iconic. 👑

🌸 DESCRIPTION 🌸

Okay so here's the tea: SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS encrypted network connections. It's meant to actually be useful for network forensics, application security analysis and penetration testing. So like, it's a menace, but a professional one. 💅

SSLsplit is designed to transparently terminate connections that get redirected to it using a network address translation engine. Then it terminates SSL/TLS and initiates a new SSL/TLS connection to the original destination address, all while logging every single byte of data transmitted. Besides NAT based operation, SSLsplit also supports static destinations and using the server name indicated by SNI as upstream destination. And this part matters: SSLsplit is purely a transparent proxy and cannot act as a HTTP or SOCKS proxy configured in a browser. So don't try to point Firefox at it, bestie, it will not go well. 👀 See NAT ENGINES and PROXY SPECIFICATIONS below for the specifics on the different modes of operation.

SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over both IPv4 and IPv6. It can also dynamically upgrade plain TCP to SSL, which is how it generically supports SMTP STARTTLS and similar upgrade mechanisms. It fully supports Server Name Indication (SNI) and plays nicely with RSA, DSA and ECDSA keys and DHE and 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. (Yes, SSL 2.0. We don't talk about SSL 2.0. 🙈)

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. It also has the ability to use existing certificates of which the private key is available, instead of generating forged ones. And it supports NULL-prefix CN certificates — but otherwise it does not implement exploits against specific certificate verification vulnerabilities in SSL/TLS stacks. So no, it's not doing that.

SSLsplit implements a bunch of defences against mechanisms that would normally prevent MitM attacks or make them more difficult. It can deny OCSP requests in a generic way. For HTTP and HTTPS connections, it 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 get disabled so the logs are actually readable. Thank you for your service, honestly. 🫶

Logging options include the traditional SSLsplit connect and content log files, plus PCAP files and mirroring decrypted traffic to a network interface. On top of that, certificates, master secrets and local process information can be logged too. Obsessed. ✨

In order to maximize the chances that a connection can be successfully split, SSLsplit does not verify upstream server certificates by default. Instead, all certificates including self-signed are accepted, and if the expected hostname signalled in SNI is missing from the server certificate, it will be added to dynamically forged certificates.

And the big one, no cap: SSLsplit does not automagically redirect any network traffic. 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. Pick your fighter. 🥊

💖 OPTIONS 💖

Every single one of these, in order, no skips. Let's go.

  • -a pemfile — Use client certificate from pemfile when the destination server requests a client certificate.
  • -A pemfile — Use private key, certificate and certificate chain from the PEM file pemfile as the leaf certificate instead of generating a leaf certificate on the fly. The PEM file must contain a single private key, a single certificate and optionally intermediate and root CA certificates to use as certificate chain. When using -t, SSLsplit will first attempt to use a matching certificate loaded from certdir. If -t is also used and a connection matches any certificate in the directory specified with the -t option, that matching certificate is used instead, taking precedence over the certificate specified with -A.
  • -b pemfile — Use client private key from pemfile when the destination server requests a client certificate.
  • -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. Bye bestie, you're on your own now. 👋
  • -D — Run in debug mode, log lots of debugging information to standard error. This also forces foreground mode and cannot be used with -d. Pick a lane, babe.
  • -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.
  • -f conffile — Read configuration from conffile.
  • -F logspec — Log connection content to separate log files with the given path specification (see LOG SPECIFICATIONS below). 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. Only one of -F, -L and -S may be used (last one wins).
  • -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 group parameters are automatically used. 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 (ECDHE) cipher suites. If -G is not given, a default curve (prime256v1) is used automatically. 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. The classic.
  • -i — For each connection, find the local process owning the connection. This makes process information such as pid, owner:group and executable path for connections originating on the same system as SSLsplit available to the connect log, and enables the respective -F path specification directives. -i is available on Mac OS X and FreeBSD; support for other platforms has not been implemented yet. 😭
  • -I if — Mirror connection content as emulated packets to interface if with destination address given by -T. This option is not available if SSLsplit was built without mirroring support.
  • -j jaildir — Change the root directory to jaildir using chroot(2) after opening files. Note that this has implications for sni proxyspecs. Depending on your operating system, you will need to copy files such as /etc/resolv.conf to jaildir in order for name resolution to work. Using sni proxyspecs depends on name resolution. Some operating systems require special device nodes such as /dev/null to be present within the jail. Check your system's documentation for details. This one is fiddly, so read it twice. 🧚
  • -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 the leaf certificates forged on-the-fly. If -K is not given, SSLsplit will generate a random 2048 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. SIGUSR1 will cause logfile to be re-opened.
  • -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. SIGUSR1 will cause logfile to be re-opened. Only one of -F, -L and -S may be used (last one wins).
  • -m — When dropping privileges using -u, override the target primary group to be set to group.
okay bestie, this page is a whole trilogy, and this was only part 1 — the rest of the options and the deep lore sections are still coming, so don't go anywhere 💜
  • -M logfile — bestie, this logs your master keys to logfile in SSLKEYLOGFILE format, as defined by Mozilla. Why do you care? Because logging master keys this way lets you decrypt SSL/TLS traffic in Wireshark 💅✨. Important tea though: unlike browsers that implement this feature, setting the SSLKEYLOGFILE environment variable does nothing to SSLsplit. Nada. Zero effect. Sending SIGUSR1 will cause logfile to be re-opened 🫶
  • -O — deny all Online Certificate Status Protocol (OCSP) requests on all proxyspecs and for all OCSP servers, responding with an OCSP response of tryLater — which lowkey causes OCSP clients to temporarily accept even revoked certificates 😭💀. Here's how SSLsplit decides something is an OCSP request: 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 actually work, 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 targeted certificates within the certdir specified by -t.
  • -p pidfile — write the process ID to pidfile, and straight up refuse to run if the pidfile is already in use by another process 🚫. One instance, one pidfile, no drama.
  • -P — passthrough SSL/TLS connections which cannot be split, instead of dropping them 🦋. When can a connection not be split, bestie? When -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 🙈. In these situations, passthrough with -P results in uninterrupted service for the clients — while dropping is the more secure alternative if unmonitored connections must be prevented. Periodt. > Heads up: passthrough mode currently does not apply to SSL/TLS errors in the connection from the client, since the connection from the client cannot easily be retried. Specifically, -P does not currently work for clients that do not accept forged certificates. 😭
  • -q crlurl — set the CRL distribution point (CDP) crlurl on forged leaf certificates 📜. Some clients, like some .NET applications, reject certificates that do not carry a CDP — not very demure of them. When you use -q, you will need to generate an empty CRL signed by the CA certificate and key provided with -c and -k, and make it available at crlurl. You got this 🫶
  • -r proto — force the SSL/TLS protocol version on both client and server side to proto by selecting the respective OpenSSL method constructor instead of the default SSLv23_method(), which supports all protocol versions 💅. This is useful when analyzing traffic to a server that only supports a specific version of SSL/TLS and does not implement proper protocol negotiation. Depending on build options and the version of OpenSSL that is used, the following values for proto are accepted: ssl2, ssl3, tls10, tls11 and tls12 ✨. > Note that SSL 2.0 support is not built in by default, because some servers don't handle SSL 2.0 Client Hello messages gracefully 🙈.
  • -R proto — disable the SSL/TLS protocol version proto on both client and server side by disabling the respective protocols in OpenSSL 🚫. To disable multiple protocol versions, -R can be given multiple times. If -r is also given, there will be no effect in disabling other protocol versions 👀. Disabling protocol versions is useful when analyzing traffic to a server that does not handle some protocol versions well, or to test behaviour with different protocol versions. Depending on build options and the version of OpenSSL that is used, the following values for proto are accepted: ssl2, ssl3, tls10, tls11 and tls12. > Same warning as above, bestie: SSL 2.0 support is not built in by default because some servers don't handle SSL 2.0 Client Hello messages gracefully 💀.
  • -s ciphers — use the 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 — icon behaviour, honestly. 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. > Only one of -F, -L and -S may be used (last one wins) 👑.
  • -t certdir — use the private key, certificate and certificate chain from PEM files in certdir for connections to hostnames matching the respective certificates, 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. When using -t, SSLsplit will first attempt to use a matching certificate loaded from certdir. If -A is also given, when there is no match in certdir, the default key, certificate and certificate chain from the PEM file specified with the -A option is used instead. Otherwise, if -c and -k are also given, certificates will be forged on-the-fly for sites matching none of the common names in the certificates loaded from certdir. Otherwise, connections matching no certificate will be dropped — or if -P is given, passed through without splitting SSL/TLS. So many branches, but you're slaying the flowchart fr fr 🌈.
  • -T addr — mirror connection content as emulated packets to destination address addr on the interface given by -I 🪞. Only IPv4 target addresses are currently supported. > This option is not available if SSLsplit was built without mirroring support 🚫.
  • -u user — 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 (the setuid bit scenario), or to nobody if running with full root privileges (EUID == UID == 0). User user needs to be allowed to make outbound TCP connections, and in some configurations, to also perform DNS resolution 👀. Dropping privileges enables privilege separation, which incurs latency for certain options, such as separate per-connection log files. By using -u root, SSLsplit can be run as root without dropping privileges. > Due to an Apple bug, -u cannot be used with pf proxyspecs on Mac OS X 💀.
  • -x engine — use the OpenSSL engine with identifier engine as the default engine ⚙️. The engine must be available within the OpenSSL ecosystem under the specified identifier, that is, they must be loaded from the global OpenSSL configuration. If engine is an absolute path, it will be interpreted as a path to an engine dynamically linked library and loaded by path, regardless of global OpenSSL configuration 🦋. > This option is only available if built against a version of OpenSSL with engine support.
  • -X pcapfile — log connection content to pcapfile in PCAP format, with emulated TCP, IP and Ethernet headers 📦. Sending SIGUSR1 will cause pcapfile to be re-opened. > Only one of -X, -Y and -y may be used (last one wins) ✨.
  • -Y pcapdir — log connection content to separate PCAP files under pcapdir 🗂️. For each connection, a separate PCAP file will be written. > Only one of -X, -Y and -y may be used (last one wins).
  • -y pcapspec — log connection content to separate PCAP files with the given path specification (see LOG SPECIFICATIONS below) 🌸. For each connection, a separate PCAP file will be written. > Only one of -X, -Y and -y may be used (last one wins).
  • -V — display version and compiled features information, then exit 👋. Short and sweet, we love a low-commitment flag.
  • -w gendir — write generated keys and certificates to individual files in gendir 💾. For keys, the key identifier is used as the filename, which consists of the SHA-1 hash of the ASN.1 bit string of the public key, as referenced by the subjectKeyIdentifier extension in certificates. For certificates, the SHA-1 fingerprints of the original and the used (forged) certificate are combined to form the filename 🔑. > Note that only newly generated certificates are written to disk.
  • -W gendir — same as -w, but also write original certificates and certificates not newly generated, such as those loaded from -t 💅. It's giving "give me everything, I'm nosy."
  • -Z — disable SSL/TLS compression on all connections 🚫🗜️. This is useful if your limiting factor is CPU, not network bandwidth — squeezing bytes is cute until it's eating your processor. > The -Z option is only available if SSLsplit was built against a version of OpenSSL which supports disabling compression.

🌈 PROXY SPECIFICATIONS 🌈

Okay bestie, a proxy specification (we call it a proxyspec, cute right?) is literally just three things: what kind of connection it is, where to listen, and where to send stuff — either a static forward address or some clever way of figuring out the address (a NAT engine, or an SNI DNS lookup). Here's the whole shape of it:

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]
autossl listenaddr port [nat-engine|fwdaddr port]

Now let's go one by one, because every single one of these slays differently 💅

  • https — SSL/TLS interception plus HTTP protocol decoding, and that includes ripping out the HPKP, HSTS, Upgrade and Alternate Protocol response headers. Heads up though: this mode currently suppresses WebSockets and HTTP/2. 😭
  • ssl — SSL/TLS interception with zero lower level protocol decoding. The decrypted connection content is treated as an opaque stream of bytes and it is not modified. Just vibes, no touchy.
  • http — Plain TCP connection, no SSL/TLS at all, but with HTTP protocol decoding, which again means removing those HPKP, HSTS, Upgrade and Alternate Protocol response headers. And yeah, this mode currently suppresses WebSockets and HTTP/2 too.
  • tcp — Plain TCP connection, no SSL/TLS, and no lower level protocol decoding whatsoever. The (decrypted) connection content is treated as an opaque stream of bytes and not modified.
  • autossl — Starts as a plain TCP connection and just chills there until a Client Hello SSL/TLS message shows up in the byte stream, then it automatically upgrades to SSL/TLS interception. This is generic, protocol-independent STARTTLS support, which is iconic ✨ — but warning bestie, it may erroneously trigger on byte sequences that look like Client Hello messages even when no actual STARTTLS command was ever issued. 👀
  • listenaddr port — The 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 — The NAT engine to query so sslsplit can figure out the original destination address and port of transparently redirected connections. If you don't name an engine, the default one is used, unless you override it with -e. And when you're using a NAT engine, sslsplit needs to run on the same system as the NAT rules that redirect the traffic to it. Full list of supported engines is down in NAT ENGINES. 👑
  • fwdaddr port — A static destination address, IPv4 or IPv6, plus a port or service name. When you use this, connections get forwarded to that given server address and port. If fwdaddr is a hostname, it will be resolved to an IP address.
  • sni port — Use the Server Name Indication (SNI) hostname that the client sent in the Client Hello SSL/TLS message to determine the IP address of the server to connect to. This only works for ssl and https proxyspecs, and it needs a port or service name as an argument. Because it requires DNS lookups, it's preferable to use NAT engine lookups (see above) — except when that's just not possible, like when there's no supported NAT engine, or when you're running sslsplit on a different system than the NAT rules redirecting the actual connections. Also, note that when using -j with sni, you may need to prepare jaildir to make name resolution work from inside the chroot directory. 🧚

🎀 LOG SPECIFICATIONS 🎀

Log specifications are built out of zero or more printf-style directives, and ordinary characters just get dropped straight into the output path. SSLsplit currently supports these directives, and honestly? They ate. 💖

  • %T — The initial connection time as an ISO 8601 UTC timestamp.
  • %d — The destination host and port, separated by a comma, with IPv6 addresses using underscore instead of colon.
  • %D — The destination host, IPv6 addresses using underscore instead of colon.
  • %p — The destination port.
  • %s — The source host and port, separated by a comma, IPv6 addresses using underscore instead of colon.
  • %S — The source host, IPv6 addresses using underscore instead of colon.
  • %q — The source port.
  • %x — The name of the local process. Requires -i to be used. If process information is unavailable, this directive will be omitted from the output path.
  • %X — The full path of the local process. Requires -i to be used. If process information is unavailable, this directive will be omitted from the output path.
  • %u — The username or numeric uid of the local process. Requires -i to be used. If process information is unavailable, this directive will be omitted from the output path.
  • %g — The group name or numeric gid of the local process. Requires -i to be used. If process information is unavailable, this directive will be omitted from the output path.
  • %% — A literal % character. That's it. That's the whole girl.

🔥 NAT ENGINES 🔥

SSLsplit currently supports these NAT engines, and each one has its own whole personality:

pf

OpenBSD packet filter (pf) rdr/rdr-to NAT redirects — also available on FreeBSD, NetBSD and Mac OS X. Fully supported, IPv6 included, no notes. 💯

Note that SSLsplit needs permission to open /dev/pf for reading, which by default means it needs to run under root privileges. So like, respect the power.

Assuming inbound interface em0, here it is first in old syntax (FreeBSD, Mac OS X), then in new syntax (OpenBSD 4.7+):

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

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) divert sockets, also available on Mac OS X. Available on FreeBSD and OpenBSD using pf divert-to. Fully supported on FreeBSD and OpenBSD, IPv6 included. On Mac OS X it only supports IPv4, because the version of IPFW bundled there is ancient. 💀

First in IPFW, then in pf divert-to syntax:

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 so many systems, including FreeBSD, NetBSD, Linux and Solaris. 🌍

Note that SSLsplit needs permission to open /dev/ipnat for reading, which by default means it needs to run under root privileges.

It only supports IPv4, because of 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. Fully supported including IPv6 since Linux v3.8-rc1; on older kernels it 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
# please contribute a tested ip6tables config
Note that SSLsplit is only able to accept incoming connections if it binds to the correct IP address (e.g. 192.0.2.1) or on all interfaces (0.0.0.0). REDIRECT uses the local interface address of the incoming interface as target IP address, or 127.0.0.1 for locally generated packets. Don't forget it bestie. 🙈

tproxy

Linux netfilter using the iptables TPROXY target together with routing table magic, so that non-local traffic can originate on local sockets. Fully supported, IPv6 included. ✨

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. Yeah, all of it. Do it. 🔥

📡 SIGNALS 📡

okay so when sslsplit is out there running, it's lowkey listening for vibes from you and here's the tea:

  • SIGINT and SIGTERM — bestie, these are the "we're done here, wrap it up" signals. Send one and you get a clean shutdown. 💅
  • SIGUSR1 — this one's the log rotation bestie. It tells sslsplit to re-open the single-file log files (think -l, -L and -X).

The canonical way to rotate or post-process your logs is literally this ritual, no cap:

  1. Rename the active log file.
  2. Send SIGUSR1 to the PID sitting in the PID file you gave with -p.
  3. Give SSLsplit some time to flush buffers after closing the old file. Be patient, she's working. 🫶
  4. Then post-process the renamed log file.
⚠️ important bestie: per-connection log files (like the ones from -S and -F) do not get re-opened, because their filename is specific to the connection. So don't @ them with SIGUSR1, it's not giving what you think it's giving.

🚪 EXIT STATUS 🚪

The sslsplit process will exit with 0 on regular shutdown (that's SIGINT, SIGTERM) — the clean girl exit ✨.

It'll exit with 128 + signal number on controlled shutdown based on receiving a different signal, such as SIGHUP.

And an exit status in the range 1..127? That's the error zone. 😭 That's when something went wrong.

🌈 EXAMPLES 🌈

Matching the NAT engine configuration samples from above: 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. (Also 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 -S /tmp \
         https ::1 10443  https 127.0.0.1 10443 \
         http  ::1 10080  http  127.0.0.1 10080

If the Linux netfilter engine is used with the iptables REDIRECT target, it is important to listen to the correct IP address (e.g. 192.0.2.1) or on all interfaces (0.0.0.0), otherwise SSLsplit is not able to accept incoming connections. No cap, that one bites people.

Intercepting IMAP/IMAPS using the same settings:

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

A more targeted 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 -S /tmp \
         https ::1       10443 www.example.org 443 \
         https 127.0.0.1 10443 www.example.org 443

The original example, but using plain ssl and tcp proxyspecs to avoid header modifications, and logging to a single PCAP file for post-processing with an external tool. To facilitate log rotation via SIGUSR1, -p is also given, so external log rotation tools or scripts can read the PID from the PID file. 🎀

sslsplit -k ca.key -c ca.crt -X log.pcap -p /var/run/sslsplit.pid \
         ssl ::1 10443  ssl 127.0.0.1 10443 \
         tcp ::1 10080  tcp 127.0.0.1 10080

The original example, but using SSL options optimized for speed by disabling compression and selecting only fast 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. Note that clients may not support all algorithms and key sizes. Also, some clients warn their users about cipher suites they consider weak. 😬

sslsplit -Z -s NULL:RC4:AES128:-DHE -K leaf.key \
         -k ca.key -c ca.crt -l connect.log -S /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 -S /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 — bestie this is the whole glow-up ritual:

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 2048
openssl req -new -nodes -x509 -sha256 -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

🧠 NOTES 🧠

SSLsplit is able to handle 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. She's built different, fr fr. 💅

The main thread handles the listeners and signaling, 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 well-performing 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 asynchronously. 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. The math is the main character here, sorry. 😭

For high performance and low latency and when running SSLsplit as root or otherwise in a privilege separation mode, avoid using options which require a privileged operation to be invoked through privilege separation for each connection. These are currently all per-connection log types:

  • content log to per-stream file in dir or filespec (-F, -S)
  • content log to per-stream PCAP in dir or filespec (-Y, -y)
  • generated or all certificates to files in directory (-w, -W)

Instead, use the respective single-file variants where available. 👑

It is possible, albeit not recommended, to bypass the default privilege separation when run as root by using -u root, thereby bypassing privilege separation entirely.

🚨 real talk: -u root skips the default privilege separation completely. It's possible. It's also not recommended. Choose wisely bestie.

👀 SEE ALSO 👀

sslsplit.conf(5), openssl(1), ciphers(1), speed(1), pf(4), ipfw(8), iptables(8), ip6tables(8), ip(8), hostapd(8), arpspoof(8), parasite6(8), yersinia(8), https://www.roe.ch/SSLsplit

🫶 AUTHORS 🫶

SSLsplit was written by Daniel Roethlisberger <daniel@roe.ch>. SSLsplit is currently maintained by Daniel Roethlisberger and Soner Tari. legends, honestly. 👑

The following individuals have contributed code or documentation, in chronological order of their first contribution: Steve Wills, Landon Fuller, Wayne Jensen, Rory McNamara, Alexander Neumann, Adam Jacob Muller, Richard Poole, Maciej Kotowicz, Eun Soo Park, Christian Groschupp, Alexander Savchenkov, Soner Tari, Petr Vanek, Hilko Bengen, Philip Duldig, Levente Polyak, Nick French, Cihan Komecoglu and Sergey Pinaev. 🌈✨ every single one of them ate.

SSLsplit contains work sponsored by HackerOne.

🐛 BUGS 🐛

Use Github for submission of bug reports or patches:

https://github.com/droe/sslsplit

and that's the whole page bestie!! 💖 this iconic lil manual is from sslsplit 0.5.5, dated 2024-04-01, and it lives at sslsplit(1). go forth and intercept responsibly, mwah 🎀🦋✨

📦 where this page comes from