.\" SSLsplit - transparent SSL/TLS interception .\" Copyright (c) 2009-2016, Daniel Roethlisberger .\" All rights reserved. .\" http://www.roe.ch/SSLsplit .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH SSLSPLIT 1 "1 April 2012" .SH NAME sslsplit \-\- transparent SSL/TLS interception .SH SYNOPSIS .na .B sslsplit [\fB-kCKwWOPZdDgGsrReumjplLSFi\fP] \fB-c\fP \fIpem\fP \fIproxyspecs\fP [...] .br .B sslsplit [\fB-kCKwWOPZdDgGsrReumjplLSFi\fP] \fB-c\fP \fIpem\fP \fB-t\fP \fIdir\fP \fIproxyspecs\fP [...] .br .B sslsplit [\fB-OPZwWdDgGsrReumjplLSFi\fP] \fB-t\fP \fIdir\fP \fIproxyspecs\fP [...] .br .B sslsplit -E .br .B sslsplit -V .br .B sslsplit -h .br .ad .SH DESCRIPTION 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. .LP 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. 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. 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, SSLsplit supports SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0 as well. .LP 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. .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. HTTP compression, encodings and keep-alive are disabled to make the logs more readable. .LP As an experimental feature, SSLsplit supports STARTTLS and similar mechanisms, where a protocol starts on a plain text TCP connection and is later upgraded to SSL/TLS through protocol-specific means, such as the STARTTLS command in SMTP. SSLsplit supports generic upgrading of TCP connections to SSL. .LP SSLsplit does not automagically redirect any network traffic. To actually implement an attack, you also need to redirect the traffic to the 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. .SH OPTIONS .TP .B \-c \fIpemfile\fP Use CA certificate from \fIpemfile\fP to sign certificates forged on-the-fly. If \fIpemfile\fP also contains the matching CA private key, it is also loaded, otherwise it must be provided with \fB-k\fP. If \fIpemfile\fP also contains Diffie-Hellman group parameters, they are also loaded, otherwise they can be provided with \fB-g\fP. If \fB-t\fP is also given, SSLsplit will only forge a certificate if there is no matching certificate in the provided certificate directory. .TP .B \-C \fIpemfile\fP Use CA certificates from \fIpemfile\fP as extra certificates in the certificate chain. This is needed if the CA given with \fB-k\fP and \fB-c\fP is a sub-CA, in which case any intermediate CA certificates and the root CA certificate must be included in the certificate chain. .TP .B \-d Detach from TTY and run as a daemon, logging error messages to syslog instead of standard error. .TP .B \-D Run in debug mode, log lots of debugging information to standard error. This also forces foreground mode and cannot be used with \fB-d\fP. .TP .B \-e \fIengine\fP Use \fIengine\fP as the default NAT engine for \fIproxyspecs\fP without explicit NAT engine, static destination address or SNI mode. \fIengine\fP can be any of the NAT engines supported by the system, as returned by \fB-E\fP. .TP .B \-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. .TP .B \-F \fIlogspec\fP 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. .TP .B \-g \fIpemfile\fP Use Diffie-Hellman group parameters from \fIpemfile\fP for Ephemereal Diffie-Hellman (EDH/DHE) cipher suites. If \fB-g\fP is not given, SSLsplit first tries to load DH parameters from the PEM files given by \fB-K\fP, \fB-k\fP or \fB-c\fP. If no DH parameters are found in the key files, built-in group parameters are automatically used. The \fB-g\fP option is only available if SSLsplit was built against a version of OpenSSL which supports Diffie-Hellman cipher suites. .TP .B \-G \fIcurve\fP Use the named \fIcurve\fP for Ephemereal Elliptic Curve Diffie-Hellman (ECDHE) cipher suites. If \fB-G\fP is not given, a default curve (\fBprime256v1\fP) is used automatically. The \fB-G\fP option is only available if SSLsplit was built against a version of OpenSSL which supports Elliptic Curve Diffie-Hellman cipher suites. .TP .B \-h Display help on usage and exit. .TP .B \-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 \fB-F\fP path specification directives. \fB-i\fP is available on Mac OS X and FreeBSD; support for other platforms has not been implemented yet. .TP .B \-j \fIjaildir\fP Change the root directory to \fIjaildir\fP using chroot(2) after opening files. Note that this has implications for \fBsni\fP \fIproxyspecs\fP. Depending on your operating system, you will need to copy files such as \fB/etc/resolv.conf\fP to \fIjaildir\fP in order for name resolution to work. Using \fBsni\fP proxyspecs depends on name resolution. Some operating systems require special device nodes such as \fB/dev/null\fP to be present within the jail. Check your system's documentation for details. .TP .B \-k \fIpemfile\fP Use CA private key from \fIpemfile\fP to sign certificates forged on-the-fly. If \fIpemfile\fP also contains the matching CA certificate, it is also loaded, otherwise it must be provided with \fB-c\fP. If \fIpemfile\fP also contains Diffie-Hellman group parameters, they are also loaded, otherwise they can be provided with \fB-g\fP. If \fB-t\fP is also given, SSLsplit will only forge a certificate if there is no matching certificate in the provided certificate directory. .TP .B \-K \fIpemfile\fP Use private key from \fIpemfile\fP for the leaf certificates forged on-the-fly. If \fB-K\fP is not given, SSLsplit will generate a random 1024-bit RSA key. .TP .B \-l \fIlogfile\fP Log connections to \fIlogfile\fP in a single line per connection format, including addresses and ports and some HTTP and SSL information, if available. SIGUSR1 will cause \fIlogfile\fP to be re-opened. .TP .B \-L \fIlogfile\fP Log connection content to \fIlogfile\fP. 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 \fIlogfile\fP to be re-opened. .TP .B \-m When dropping privileges using \fB-u\fP, override the target primary group to be set to \fIgroup\fP. .TP .B \-O Deny all Online Certificate Status Protocol (OCSP) requests on all \fIproxyspecs\fP and for all OCSP servers with an OCSP response of \fBtryLater\fP, causing OCSP clients to temporarily accept even revoked certificates. HTTP requests are being treated as OCSP requests if the method is \fBGET\fP and the URI contains a syntactically valid OCSPRequest ASN.1 structure parsable by OpenSSL, or if the method is \fBPOST\fP and the \fBContent-Type\fP is \fBapplication/ocsp-request\fP. 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 \fIcertdir\fP specified by \fB-t\fP. .TP .B \-p \fIpidfile\fP Write the process ID to \fIpidfile\fP and refuse to run if the \fIpidfile\fP is already in use by another process. .TP .B \-P Passthrough SSL/TLS connections which cannot be split instead of dropping them. Connections cannot be split if \fB-c\fP and \fB-k\fP are not given and the site does not match any certificate loaded using \fB-t\fP, 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 \fB-P\fP results in uninterrupted service for the clients, while dropping is the more secure alternative if unmonitored connections must be prevented. 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, \fB-P\fP does not currently work for clients that do not accept forged certificates. .TP .B \-r \fIproto\fP Force SSL/TLS protocol version on both client and server side to \fIproto\fP 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 \fIproto\fP are accepted: \fBssl2\fP, \fBssl3\fP, \fBtls10\fP, \fBtls11\fP and \fBtls12\fP. 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. .TP .B \-R \fIproto\fP Disable the SSL/TLS protocol version \fIproto\fP on both client and server side by disabling the respective protocols in OpenSSL. To disable multiple protocol versions, \fB-R\fP can be given multiple times. If \fI-r\fP 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 \fIproto\fP are accepted: \fBssl2\fP, \fBssl3\fP, \fBtls10\fP, \fBtls11\fP and \fBtls12\fP. 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. .TP .B \-s \fIciphers\fP Use OpenSSL \fIciphers\fP specification for both server and client SSL/TLS connections. If \fB-s\fP is not given, a cipher list of \fBALL:-aNULL\fP 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 \fBeNULL\fP 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. .TP .B \-S \fIlogdir\fP Log connection content to separate log files under \fIlogdir\fP. 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. .TP .B \-t \fIcertdir\fP Use private key, certificate and certificate chain from PEM files in \fIcertdir\fP 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 \fB-t\fP, SSLsplit will first attempt to use a matching certificate loaded from \fIcertdir\fP. If \fB-c\fP and \fB-k\fP are also given, certificates will be forged on-the-fly for sites matching none of the common names in the certificates loaded from \fIcertdir\fP. Otherwise, connections matching no certificate will be dropped, or if \fB-P\fP is given, passed through without splitting SSL/TLS. .TP .B \-u Drop privileges after opening sockets and files by setting the real, effective and stored user IDs to \fIuser\fP and loading the appropriate primary and ancillary groups. If \fB-u\fP is not given, SSLsplit will drop privileges to the stored UID if EUID != UID (setuid bit scenario), or to \fBnobody\fP if running with full \fBroot\fP privileges (EUID == UID == 0). Due to an Apple bug, \fB-u\fP cannot be used with \fBpf\fP proxyspecs on Mac OS X. .TP .B \-V Display version and compiled features information and exit. .TP .B \-w \fIgendir\fP Write generated keys and certificates to individual files in \fIgendir\fP. For keys, the key identifier is used as 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. .TP .B \-W \fIgendir\fP Same as \fB-w\fP, but also write original certificates and certificates not newly generated, such as those loaded from \fB-t\fP. .TP .B \-Z Disable SSL/TLS compression on all connections. This is useful if your limiting factor is CPU, not network bandwidth. The \fB-Z\fP option is only available if SSLsplit was built against a version of OpenSSL which supports disabling compression. .SH "PROXY SPECIFICATIONS" Proxy specifications (\fIproxyspecs\fP) consist of the connection type, listen address and static forward address or address resolution mechanism (NAT engine, SNI DNS lookup): .LP .na \fBhttps\fP \fIlistenaddr port\fP [\fInat-engine\fP|\fIfwdaddr port\fP|\fBsni\fP \fIport\fP] .br \fBssl\fP \fIlistenaddr port\fP [\fInat-engine\fP|\fIfwdaddr port\fP|\fBsni\fP \fIport\fP] .br \fBhttp\fP \fIlistenaddr port\fP [\fInat-engine\fP|\fIfwdaddr port\fP] .br \fBtcp\fP \fIlistenaddr port\fP [\fInat-engine\fP|\fIfwdaddr port\fP] .br \fBautossl\fP \fIlistenaddr port\fP [\fInat-engine\fP|\fIfwdaddr port\fP] .ad .TP \fBhttps\fP SSL/TLS interception with HTTP protocol decoding, including the removal of HPKP, HSTS and Alternate Protocol response headers. .TP \fBssl\fP SSL/TLS interception without any lower level protocol decoding; decrypted connection content is treated as opaque stream of bytes and not modified. .TP \fBhttp\fP Plain TCP connection without SSL/TLS, with HTTP protocol decoding, including the removal of HPKP, HSTS and Alternate Protocol response headers. .TP \fBtcp\fP Plain TCP connection without SSL/TLS and without any lower level protocol decoding; decrypted connection content is treated as opaque stream of bytes and not modified. .TP \fBautossl\fP Plain TCP connection until a Client Hello SSL/TLS message appears in the byte stream, then automatic upgrade to SSL/TLS interception. This is generic, protocol-independent STARTTLS support, that may erroneously trigger on byte sequences that look like Client Hello messages even though there was no actual STARTTLS command issued. This is an experimental feature and may in its current state miss some Client Hello messages depending on circumstances. YMMV. Testing and patches highly welcome. .TP .I 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. .TP .I 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 \fB-e\fP. When using a NAT engine, \fBsslsplit\fP needs to run on the same system as the NAT rules redirecting the traffic to \fBsslsplit\fP. See NAT ENGINES for a list of supported NAT engines. .TP .I 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. If \fIfwdaddr\fP is a hostname, it will be resolved to an IP address. .TP \fBsni\fP \fIport\fP Use the Server Name Indication (SNI) hostname sent by the client in the Client Hello SSL/TLS message to determine the IP address of the server to connect to. This only works for \fBssl\fP and \fBhttps\fP \fIproxyspecs\fP 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 \fBsslsplit\fP on a different system than the NAT rules redirecting the actual connections. Note that when using \fB-j\fP with \fBsni\fP, you may need to prepare \fIjaildir\fP to make name resolution work from within the chroot directory. .SH SIGNALS A running \fBsslsplit\fP accepts SIGINT and SIGQUIT for a clean shutdown and SIGUSR1 to re-open the long-living log files (\fB-l\fP and \fB-L\fP). Per-connection log files (\fB-S\fP and \fB-F\fP) are not re-opened because their filename is specific to the connection. .SH "LOG SPECIFICATIONS" Log specifications are composed of zero or more printf-style directives; ordinary characters are included directly in the output path. SSLsplit current supports the following directives: .TP .I %T The initial connection time as an ISO 8601 UTC timestamp. .TP .I %d The destination host and port, separated by a comma, IPv6 addresses using underscore instead of colon. .TP .I %D The destination host, IPv6 addresses using underscore instead of colon. .TP .I %p The destination port. .TP .I %s The source host and port, separated by a comma, IPv6 addresses using underscore instead of colon. .TP .I %S The source host, IPv6 addresses using underscore instead of colon. .TP .I %q The source port. .TP .I %x The name of the local process. Requires \fB-i\fP to be used. If process information is unavailable, this directive will be omitted from the output path. .TP .I %X The full path of the local process. Requires \fB-i\fP to be used. If process information is unavailable, this directive will be omitted from the output path. .TP .I %u The username or numeric uid of the local process. Requires \fB-i\fP to be used. If process information is unavailable, this directive will be omitted from the output path. .TP .I %g The group name or numeric gid of the local process. Requires \fB-i\fP to be used. If process information is unavailable, this directive will be omitted from the output path. .TP .I %% A literal '%' character. .LP .SH "NAT ENGINES" SSLsplit currently supports the following NAT engines: .TP .B pf OpenBSD packet filter (pf) \fBrdr\fP/\fBrdr-to\fP NAT redirects, also available on FreeBSD, NetBSD and Mac OS X. Fully supported, including IPv6. Note that SSLsplit needs permission to open \fB/dev/pf\fP for reading, which by default means that it needs to run under \fBroot\fP privileges. Assuming inbound interface \fBem0\fP, first in old (FreeBSD, Mac OS X), then in new (OpenBSD 4.7+) syntax: .LP .RS .nf \fBrdr pass on em0 proto tcp from 2001:db8::/64 to any port 80 \\ -> ::1 port 10080\fP \fBrdr pass on em0 proto tcp from 2001:db8::/64 to any port 443 \\ -> ::1 port 10443\fP \fBrdr pass on em0 proto tcp from 192.0.2.0/24 to any port 80 \\ -> 127.0.0.1 port 10080\fP \fBrdr pass on em0 proto tcp from 192.0.2.0/24 to any port 443 \\ -> 127.0.0.1 port 10443\fP .fi .RE .LP .RS .nf \fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\ port 80 rdr-to ::1 port 10080\fP \fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\ port 443 rdr-to ::1 port 10443\fP \fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\ port 80 rdr-to 127.0.0.1 port 10080\fP \fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\ port 443 rdr-to 127.0.0.1 port 10443\fP .fi .RE .TP .B ipfw FreeBSD IP firewall (IPFW) divert sockets, also available on Mac OS X. Available on FreeBSD and OpenBSD using pf \fBdivert-to\fP. Fully supported on FreeBSD and OpenBSD, including IPv6. Only supports IPv4 on Mac OS X due to the ancient version of IPFW included. First in IPFW, then in pf \fBdivert-to\fP syntax: .LP .RS .nf \fBipfw add fwd ::1,10080 tcp from 2001:db8::/64 to any 80\fP \fBipfw add fwd ::1,10443 tcp from 2001:db8::/64 to any 443\fP \fBipfw add fwd 127.0.0.1,10080 tcp from 192.0.2.0/24 to any 80\fP \fBipfw add fwd 127.0.0.1,10443 tcp from 192.0.2.0/24 to any 443\fP .fi .RE .LP .RS .nf \fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\ port 80 divert-to ::1 port 10080\fP \fBpass in quick on em0 proto tcp from 2001:db8::/64 to any \\ port 443 divert-to ::1 port 10443\fP \fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\ port 80 divert-to 127.0.0.1 port 10080\fP \fBpass in quick on em0 proto tcp from 192.0.2.0/24 to any \\ port 443 divert-to 127.0.0.1 port 10443\fP .fi .RE .TP .B ipfilter IPFilter (ipfilter, ipf), available on many systems, including FreeBSD, NetBSD, Linux and Solaris. Note that SSLsplit needs permission to open \fB/dev/ipnat\fP for reading, which by default means that it needs to run under \fBroot\fP privileges. Only supports IPv4 due to limitations in the SIOCGNATL ioctl(2) interface. Assuming inbound interface \fBbge0\fP: .LP .RS .nf \fBrdr bge0 0.0.0.0/0 port 80 -> 127.0.0.1 port 10080\fP \fBrdr bge0 0.0.0.0/0 port 443 -> 127.0.0.1 port 10443\fP .fi .RE .TP .B netfilter Linux netfilter using the iptables REDIRECT target. Only supports IPv4 due to limitations in the SO_ORIGINAL_DST getsockopt(2) interface. .LP .RS .nf \fBiptables -t nat -A PREROUTING -s 192.0.2.0/24 \\ -p tcp --dport 80 \\ -j REDIRECT --to-ports 10080\fP \fBiptables -t nat -A PREROUTING -s 192.0.2.0/24 \\ -p tcp --dport 443 \\ -j REDIRECT --to-ports 10443\fP .fi .LP 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. .RE .TP .B 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. .LP .RS .nf \fBip -f inet6 rule add fwmark 1 lookup 100\fP \fBip -f inet6 route add local default dev lo table 100\fP \fBip6tables -t mangle -N DIVERT\fP \fBip6tables -t mangle -A DIVERT -j MARK --set-mark 1\fP \fBip6tables -t mangle -A DIVERT -j ACCEPT\fP \fBip6tables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT\fP \fBip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \\ -p tcp --dport 80 \\ -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080\fP \fBip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \\ -p tcp --dport 443 \\ -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443\fP \fBip -f inet rule add fwmark 1 lookup 100\fP \fBip -f inet route add local default dev lo table 100\fP \fBiptables -t mangle -N DIVERT\fP \fBiptables -t mangle -A DIVERT -j MARK --set-mark 1\fP \fBiptables -t mangle -A DIVERT -j ACCEPT\fP \fBiptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT\fP \fBiptables -t mangle -A PREROUTING -s 192.0.2.0/24 \\ -p tcp --dport 80 \\ -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080\fP \fBiptables -t mangle -A PREROUTING -s 192.0.2.0/24 \\ -p tcp --dport 443 \\ -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443\fP .fi .LP Note that return path filtering (rp_filter) also needs to be disabled on interfaces which handle TPROXY redirected traffic. .RE .SH EXAMPLES Matching the above NAT engine configuration samples, intercept HTTP and HTTPS over IPv4 and IPv6 using forged certificates with CA private key \fBca.key\fP and certificate \fBca.crt\fP, logging connections to \fBconnect.log\fP and connection data into separate files under \fB/tmp\fP (add \fB-e\fP \fInat-engine\fP to select the appropriate engine if multiple engines are available on your system): .LP .HS .nf \fBsslsplit -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\fP .fi .RE .LP 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. .LP Intercepting IMAP/IMAPS using the same settings: .LP .HS .nf \fBsslsplit -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\fP .fi .RE .LP A more targetted setup, HTTPS only, using certificate/chain/key files from \fB/path/to/cert.d\fP and statically redirecting to \fBwww.example.org\fP instead of querying a NAT engine: .LP .HS .nf \fBsslsplit -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\fP .fi .RE .LP 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 \fBleaf.key\fP 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 \fBopenssl speed\fP 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. .LP .HS .nf \fBsslsplit -Z -s NULL:RC4:AES128:-DHE -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\fP .fi .RE .LP The original example, but running as a daemon under user \fBsslsplit\fP and writing a PID file: .LP .HS .nf \fBsslsplit -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\fP .fi .RE .LP To generate a CA private key \fBca.key\fP and certificate \fBca.crt\fP using OpenSSL: .LP .HS .nf \fBcat >x509v3ca.cnf <<'EOF'\fP [ req ] distinguished_name = reqdn [ reqdn ] [ v3_ca ] basicConstraints = CA:TRUE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always,issuer:always \fBEOF\fP \fBopenssl genrsa -out ca.key 2048\fP \fBopenssl 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\fP .fi .SH 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. 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. .LP 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 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. .SH "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), .I https://www.roe.ch/SSLsplit .SH AUTHORS SSLsplit was written by Daniel Roethlisberger . 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 and Richard Poole. .SH BUGS Use Github for submission of bug reports or patches: .LP .RS .I https://github.com/droe/sslsplit .RE .LP