1sslsplit(1) SSLsplit sslsplit(1)
2
6 sslsplit -- transparent SSL/TLS interception
7
9 sslsplit [-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab] -c pem proxyspecs [...]
10 sslsplit [-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab] -c pem -t dir prox‐
11 yspecs [...]
12 sslsplit [-OPZwWdDgGsrRxeumjplLSFXYyTIMiab] -t dir proxyspecs [...]
13 sslsplit [-kCKwWOPZdDgGsrRxeumjplLSFXYyTIMi] -f conffile
14 sslsplit -E
15 sslsplit -V
16 sslsplit -h
17
19 SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS en‐
20 crypted network connections. It is intended to be useful for network
21 forensics, application security analysis and penetration testing.
22 SSLsplit is designed to transparently terminate connections that are
24 redirected to it using a network address translation engine. SSLsplit
25 then terminates SSL/TLS and initiates a new SSL/TLS connection to the
26 original destination address, while logging all data transmitted. Be‐
27 sides NAT based operation, SSLsplit also supports static destinations
28 and using the server name indicated by SNI as upstream destination.
29 SSLsplit is purely a transparent proxy and cannot act as a HTTP or
30 SOCKS proxy configured in a browser. See NAT ENGINES and PROXY SPECI‐
31 FICATIONS below for specifics on the different modes of operation.
32 SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over
34 both IPv4 and IPv6. It also has the ability to dynamically upgrade
35 plain TCP to SSL in order to generically support SMTP STARTTLS and sim‐
36 ilar upgrade mechanisms. SSLsplit fully supports Server Name Indica‐
37 tion (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and
38 ECDHE cipher suites. Depending on the version of OpenSSL, SSLsplit
39 supports SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0
40 as well.
41 For SSL and HTTPS connections, SSLsplit generates and signs forged
43 X509v3 certificates on-the-fly, mimicking the original server certifi‐
44 cate's subject DN, subjectAltName extension and other characteristics.
45 SSLsplit has the ability to use existing certificates of which the pri‐
46 vate key is available, instead of generating forged ones. SSLsplit
47 supports NULL-prefix CN certificates but otherwise does not implement
48 exploits against specific certificate verification vulnerabilities in
49 SSL/TLS stacks.
50 SSLsplit implements a number of defences against mechanisms which would
52 normally prevent MitM attacks or make them more difficult. SSLsplit
53 can deny OCSP requests in a generic way. For HTTP and HTTPS connec‐
54 tions, SSLsplit mangles headers to prevent server-instructed public key
55 pinning (HPKP), avoid strict transport security restrictions (HSTS),
56 avoid Certificate Transparency enforcement (Expect-CT) and prevent
57 switching to QUIC/SPDY, HTTP/2 or WebSockets (Upgrade, Alternate Proto‐
58 cols). HTTP compression, encodings and keep-alive are disabled to make
59 the logs more readable.
60 Logging options include traditional SSLsplit connect and content log
62 files as well as PCAP files and mirroring decrypted traffic to a net‐
63 work interface. Additionally, certificates, master secrets and local
64 process information can be logged.
65 In order to maximize the chances that a connection can be successfully
67 split, SSLsplit does not verify upstream server certificates by de‐
68 fault. Instead, all certificates including self-signed are accepted
69 and if the expected hostname signalled in SNI is missing from the
70 server certificate, it will be added to dynamically forged certifi‐
71 cates.
72 SSLsplit does not automagically redirect any network traffic. To actu‐
74 ally implement an attack, you also need to redirect the traffic to the
75 system running sslsplit. Your options include running sslsplit on a
76 legitimate router, ARP spoofing, ND spoofing, DNS poisoning, deploying
77 a rogue access point (e.g. using hostap mode), physical recabling, ma‐
78 licious VLAN reconfiguration or route injection, /etc/hosts modifica‐
79 tion and so on.
80
82 -a pemfile
83 Use client certificate from pemfile when destination server re‐
84 quests a client certificate. -A pemfile Use private key, cer‐
85 tificate and certificate chain from PEM file pemfile as leaf
86 certificate instead of generating a leaf certificate on the fly.
87 The PEM file must contain a single private key, a single cer‐
88 tificate and optionally intermediate and root CA certificates to
89 use as certificate chain. When using -t, SSLsplit will first
90 attempt to use a matching certificate loaded from certdir. If
91 -t is also used and a connection matches any certificate in the
92 directory specified with the -t option, that matching certifi‐
93 cate is used instead, taking precedence over the certificate
94 specified with -A.
95 -b pemfile
97 Use client private key from pemfile when destination server re‐
98 quests a client certificate.
99 -c pemfile
101 Use CA certificate from pemfile to sign certificates forged on-
102 the-fly. If pemfile also contains the matching CA private key,
103 it is also loaded, otherwise it must be provided with -k. If
104 pemfile also contains Diffie-Hellman group parameters, they are
105 also loaded, otherwise they can be provided with -g. If -t is
106 also given, SSLsplit will only forge a certificate if there is
107 no matching certificate in the provided certificate directory.
108 -C pemfile
110 Use CA certificates from pemfile as extra certificates in the
111 certificate chain. This is needed if the CA given with -k and
112 -c is a sub-CA, in which case any intermediate CA certificates
113 and the root CA certificate must be included in the certificate
114 chain.
115 -d Detach from TTY and run as a daemon, logging error messages to
117 syslog instead of standard error.
118 -D Run in debug mode, log lots of debugging information to standard
120 error. This also forces foreground mode and cannot be used with
121 -d.
122 -e engine
124 Use engine as the default NAT engine for proxyspecs without ex‐
125 plicit NAT engine, static destination address or SNI mode. en‐
126 gine can be any of the NAT engines supported by the system, as
127 returned by -E.
128 -E List all supported NAT engines available on the system and exit.
130 See NAT ENGINES for a list of NAT engines currently supported by
131 SSLsplit.
132 -f conffile
134 Read configuration from conffile.
135 -F logspec
137 Log connection content to separate log files with the given path
138 specification (see LOG SPECIFICATIONS below). For each connec‐
139 tion, a log file will be written, which will contain both direc‐
140 tions of data as transmitted. Information about the connection
141 will be contained in the filename only. Only one of -F, -L and
142 -S may be used (last one wins).
143 -g pemfile
145 Use Diffie-Hellman group parameters from pemfile for Ephemereal
146 Diffie-Hellman (EDH/DHE) cipher suites. If -g is not given,
147 SSLsplit first tries to load DH parameters from the PEM files
148 given by -K, -k or -c. If no DH parameters are found in the key
149 files, built-in group parameters are automatically used. The -g
150 option is only available if SSLsplit was built against a version
151 of OpenSSL which supports Diffie-Hellman cipher suites.
152 -G curve
154 Use the named curve for Ephemereal Elliptic Curve Diffie-Hellman
155 (ECDHE) cipher suites. If -G is not given, a default curve
156 (prime256v1) is used automatically. The -G option is only
157 available if SSLsplit was built against a version of OpenSSL
158 which supports Elliptic Curve Diffie-Hellman cipher suites.
159 -h Display help on usage and exit.
161 -i For each connection, find the local process owning the connec‐
163 tion. This makes process information such as pid, owner:group
164 and executable path for connections originating on the same sys‐
165 tem as SSLsplit available to the connect log and enables the re‐
166 spective -F path specification directives. -i is available on
167 Mac OS X and FreeBSD; support for other platforms has not been
168 implemented yet.
169 -I if Mirror connection content as emulated packets to interface if
171 with destination address given by -T. This option is not avail‐
172 able if SSLsplit was built without mirroring support.
173 -j jaildir
175 Change the root directory to jaildir using chroot(2) after open‐
176 ing files. Note that this has implications for sni proxyspecs.
177 Depending on your operating system, you will need to copy files
178 such as /etc/resolv.conf to jaildir in order for name resolution
179 to work. Using sni proxyspecs depends on name resolution. Some
180 operating systems require special device nodes such as /dev/null
181 to be present within the jail. Check your system's documenta‐
182 tion for details.
183 -k pemfile
185 Use CA private key from pemfile to sign certificates forged on-
186 the-fly. If pemfile also contains the matching CA certificate,
187 it is also loaded, otherwise it must be provided with -c. If
188 pemfile also contains Diffie-Hellman group parameters, they are
189 also loaded, otherwise they can be provided with -g. If -t is
190 also given, SSLsplit will only forge a certificate if there is
191 no matching certificate in the provided certificate directory.
192 -K pemfile
194 Use private key from pemfile for the leaf certificates forged
195 on-the-fly. If -K is not given, SSLsplit will generate a random
196 2048 bit RSA key.
197 -l logfile
199 Log connections to logfile in a single line per connection for‐
200 mat, including addresses and ports and some HTTP and SSL infor‐
201 mation, if available. SIGUSR1 will cause logfile to be re-
202 opened.
203 -L logfile
205 Log connection content to logfile. The content log will contain
206 a parsable log format with transmitted data, prepended with
207 headers identifying the connection and the data length of each
208 logged segment. SIGUSR1 will cause logfile to be re-opened.
209 Only one of -F, -L and -S may be used (last one wins).
210 -m When dropping privileges using -u, override the target primary
212 group to be set to group.
213 -M logfile
215 Log master keys to logfile in SSLKEYLOGFILE format as defined by
216 Mozilla. Logging master keys in this format allows for decryp‐
217 tion of SSL/TLS traffic using Wireshark. Note that unlike
218 browsers implementing this feature, setting the SSLKEYLOGFILE
219 environment variable has no effect on SSLsplit. SIGUSR1 will
220 cause logfile to be re-opened.
221 -O Deny all Online Certificate Status Protocol (OCSP) requests on
223 all proxyspecs and for all OCSP servers with an OCSP response of
224 tryLater, causing OCSP clients to temporarily accept even re‐
225 voked certificates. HTTP requests are being treated as OCSP re‐
226 quests if the method is GET and the URI contains a syntactically
227 valid OCSPRequest ASN.1 structure parsable by OpenSSL, or if the
228 method is POST and the Content-Type is application/ocsp-request.
229 For this to be effective, SSLsplit must be handling traffic des‐
230 tined to the port used by the OCSP server. In particular,
231 SSLsplit must be configured to receive traffic to all ports used
232 by OCSP servers of targeted certificates within the certdir
233 specified by -t.
234 -p pidfile
236 Write the process ID to pidfile and refuse to run if the pidfile
237 is already in use by another process.
238 -P Passthrough SSL/TLS connections which cannot be split instead of
240 dropping them. Connections cannot be split if -c and -k are not
241 given and the site does not match any certificate loaded using
242 -t, or if the connection to the original server gives SSL/TLS
243 errors. Specifically, this happens if the site requests a
244 client certificate. In these situations, passthrough with -P
245 results in uninterrupted service for the clients, while dropping
246 is the more secure alternative if unmonitored connections must
247 be prevented. Passthrough mode currently does not apply to
248 SSL/TLS errors in the connection from the client, since the con‐
249 nection from the client cannot easily be retried. Specifically,
250 -P does not currently work for clients that do not accept forged
251 certificates.
252 -q crlurl
254 Set CRL distribution point (CDP) crlurl on forged leaf certifi‐
255 cates. Some clients, such as some .NET applications, reject
256 certificates that do not carry a CDP. When using -q, you will
257 need to generate an empty CRL signed by the CA certificate and
258 key provided with -c and -k, and make it available at crlurl.
259 -r proto
261 Force SSL/TLS protocol version on both client and server side to
262 proto by selecting the respective OpenSSL method constructor in‐
263 stead of the default SSLv23_method() which supports all protocol
264 versions. This is useful when analyzing traffic to a server
265 that only supports a specific version of SSL/TLS and does not
266 implement proper protocol negotiation. Depending on build op‐
267 tions and the version of OpenSSL that is used, the following
268 values for proto are accepted: ssl2, ssl3, tls10, tls11 and
269 tls12. Note that SSL 2.0 support is not built in by default be‐
270 cause some servers don't handle SSL 2.0 Client Hello messages
271 gracefully.
272 -R proto
274 Disable the SSL/TLS protocol version proto on both client and
275 server side by disabling the respective protocols in OpenSSL.
276 To disable multiple protocol versions, -R can be given multiple
277 times. If -r is also given, there will be no effect in dis‐
278 abling other protocol versions. Disabling protocol versions is
279 useful when analyzing traffic to a server that does not handle
280 some protocol versions well, or to test behaviour with different
281 protocol versions. Depending on build options and the version
282 of OpenSSL that is used, the following values for proto are ac‐
283 cepted: ssl2, ssl3, tls10, tls11 and tls12. Note that SSL 2.0
284 support is not built in by default because some servers don't
285 handle SSL 2.0 Client Hello messages gracefully.
286 -s ciphers
288 Use OpenSSL ciphers specification for both server and client
289 SSL/TLS connections. If -s is not given, a cipher list of
290 ALL:-aNULL is used. Normally, SSL/TLS implementations choose
291 the most secure cipher suites, not the fastest ones. By speci‐
292 fying an appropriate OpenSSL cipher list, the set of cipher
293 suites can be limited to fast algorithms, or eNULL cipher suites
294 can be added. Note that for connections to be successful, the
295 SSLsplit cipher suites must include at least one cipher suite
296 supported by both the client and the server of each connection.
297 See ciphers(1) for details on how to construct OpenSSL cipher
298 lists.
299 -S logdir
301 Log connection content to separate log files under logdir. For
302 each connection, a log file will be written, which will contain
303 both directions of data as transmitted. Information about the
304 connection will be contained in the filename only. Only one of
305 -F, -L and -S may be used (last one wins).
306 -t certdir
308 Use private key, certificate and certificate chain from PEM
309 files in certdir for connections to hostnames matching the re‐
310 spective certificates, instead of using certificates forged on-
311 the-fly. A single PEM file must contain a single private key, a
312 single certificate and optionally intermediate and root CA cer‐
313 tificates to use as certificate chain. When using -t, SSLsplit
314 will first attempt to use a matching certificate loaded from
315 certdir. If -A is also given, when there is no match in cert‐
316 dir, the default key, certificate and certificate chain from the
317 PEM file specified with the -A option is used instead. Other‐
318 wise, if -c and -k are also given, certificates will be forged
319 on-the-fly for sites matching none of the common names in the
320 certificates loaded from certdir. Otherwise, connections match‐
321 ing no certificate will be dropped, or if -P is given, passed
322 through without splitting SSL/TLS.
323 -T addr
325 Mirror connection content as emulated packets to destination ad‐
326 dress addr on the interface given by -I. Only IPv4 target ad‐
327 dresses are currently supported. This option is not available
328 if SSLsplit was built without mirroring support.
329 -u user
331 Drop privileges after opening sockets and files by setting the
332 real, effective and stored user IDs to user and loading the ap‐
333 propriate primary and ancillary groups. If -u is not given,
334 SSLsplit will drop privileges to the stored UID if EUID != UID
335 (setuid bit scenario), or to nobody if running with full root
336 privileges (EUID == UID == 0). User user needs to be allowed to
337 make outbound TCP connections, and in some configurations, to
338 also perform DNS resolution. Dropping privileges enables privi‐
339 lege separation, which incurs latency for certain options, such
340 as separate per-connection log files. By using -u root,
341 SSLsplit can be run as root without dropping privileges. Due to
342 an Apple bug, -u cannot be used with pf proxyspecs on Mac OS X.
343 -x engine
345 Use the OpenSSL engine with identifier engine as a default en‐
346 gine. The engine must be available within the OpenSSL ecosystem
347 under the specified identifier, that is, they must be loaded
348 from the global OpenSSL configuration. If engine is an absolute
349 path, it will be interpreted as path to an engine dynamically
350 linked library and loaded by path, regardless of global OpenSSL
351 configuration. This option is only available if built against a
352 version of OpenSSL with engine support.
353 -X pcapfile
355 Log connection content to pcapfile in PCAP format, with emulated
356 TCP, IP and Ethernet headers. SIGUSR1 will cause pcapfile to be
357 re-opened. Only one of -X, -Y and -y may be used (last one
358 wins).
359 -Y pcapdir
361 Log connection content to separate PCAP files under pcapdir.
362 For each connection, a separate PCAP file will be written. Only
363 one of -X, -Y and -y may be used (last one wins).
364 -y pcapspec
366 Log connection content to separate PCAP files with the given
367 path specification (see LOG SPECIFICATIONS below). For each
368 connection, a separate PCAP file will be written. Only one of
369 -X, -Y and -y may be used (last one wins).
370 -V Display version and compiled features information and exit.
372 -w gendir
374 Write generated keys and certificates to individual files in
375 gendir. For keys, the key identifier is used as filename, which
376 consists of the SHA-1 hash of the ASN.1 bit string of the public
377 key, as referenced by the subjectKeyIdentifier extension in cer‐
378 tificates. For certificates, the SHA-1 fingerprints of the
379 original and the used (forged) certificate are combined to form
380 the filename. Note that only newly generated certificates are
381 written to disk.
382 -W gendir
384 Same as -w, but also write original certificates and certifi‐
385 cates not newly generated, such as those loaded from -t.
386 -Z Disable SSL/TLS compression on all connections. This is useful
388 if your limiting factor is CPU, not network bandwidth. The -Z
389 option is only available if SSLsplit was built against a version
390 of OpenSSL which supports disabling compression.
391
393 Proxy specifications (proxyspecs) consist of the connection type, lis‐
394 ten address and static forward address or address resolution mechanism
395 (NAT engine, SNI DNS lookup):
396 https listenaddr port [nat-engine|fwdaddr port|sni port]
398 ssl listenaddr port [nat-engine|fwdaddr port|sni port]
399 http listenaddr port [nat-engine|fwdaddr port]
400 tcp listenaddr port [nat-engine|fwdaddr port]
401 autossl listenaddr port [nat-engine|fwdaddr port]
402 https SSL/TLS interception with HTTP protocol decoding, including the
404 removal of HPKP, HSTS, Upgrade and Alternate Protocol response
405 headers. This mode currently suppresses WebSockets and HTTP/2.
406 ssl SSL/TLS interception without any lower level protocol decoding;
408 decrypted connection content is treated as opaque stream of
409 bytes and not modified.
410 http Plain TCP connection without SSL/TLS, with HTTP protocol decod‐
412 ing, including the removal of HPKP, HSTS, Upgrade and Alternate
413 Protocol response headers. This mode currently suppresses Web‐
414 Sockets and HTTP/2.
415 tcp Plain TCP connection without SSL/TLS and without any lower level
417 protocol decoding; decrypted connection content is treated as
418 opaque stream of bytes and not modified.
419 autossl
421 Plain TCP connection until a Client Hello SSL/TLS message ap‐
422 pears in the byte stream, then automatic upgrade to SSL/TLS in‐
423 terception. This is generic, protocol-independent STARTTLS sup‐
424 port, that may erroneously trigger on byte sequences that look
425 like Client Hello messages even though there was no actual
426 STARTTLS command issued.
427 listenaddr port
429 IPv4 or IPv6 address and port or service name to listen on.
430 This is the address and port where the NAT engine should redi‐
431 rect connections to.
432 nat-engine
434 NAT engine to query for determining the original destination ad‐
435 dress and port of transparently redirected connections. If no
436 engine is given, the default engine is used, unless overridden
437 with -e. When using a NAT engine, sslsplit needs to run on the
438 same system as the NAT rules redirecting the traffic to
439 sslsplit. See NAT ENGINES for a list of supported NAT engines.
440 fwdaddr port
442 Static destination address, IPv4 or IPv6, with port or service
443 name. When this is used, connections are forwarded to the given
444 server address and port. If fwdaddr is a hostname, it will be
445 resolved to an IP address.
446 sni port
448 Use the Server Name Indication (SNI) hostname sent by the client
449 in the Client Hello SSL/TLS message to determine the IP address
450 of the server to connect to. This only works for ssl and https
451 proxyspecs and needs a port or service name as an argument. Be‐
452 cause this requires DNS lookups, it is preferable to use NAT en‐
453 gine lookups (see above), except when that is not possible, such
454 as when there is no supported NAT engine or when running
455 sslsplit on a different system than the NAT rules redirecting
456 the actual connections. Note that when using -j with sni, you
457 may need to prepare jaildir to make name resolution work from
458 within the chroot directory.
459
461 Log specifications are composed of zero or more printf-style direc‐
462 tives; ordinary characters are included directly in the output path.
463 SSLsplit current supports the following directives:
464 %T The initial connection time as an ISO 8601 UTC timestamp.
466 %d The destination host and port, separated by a comma, IPv6 ad‐
468 dresses using underscore instead of colon.
469 %D The destination host, IPv6 addresses using underscore instead of
471 colon.
472 %p The destination port.
474 %s The source host and port, separated by a comma, IPv6 addresses
476 using underscore instead of colon.
477 %S The source host, IPv6 addresses using underscore instead of
479 colon.
480 %q The source port.
482 %x The name of the local process. Requires -i to be used. If
484 process information is unavailable, this directive will be omit‐
485 ted from the output path.
486 %X The full path of the local process. Requires -i to be used. If
488 process information is unavailable, this directive will be omit‐
489 ted from the output path.
490 %u The username or numeric uid of the local process. Requires -i
492 to be used. If process information is unavailable, this direc‐
493 tive will be omitted from the output path.
494 %g The group name or numeric gid of the local process. Requires -i
496 to be used. If process information is unavailable, this direc‐
497 tive will be omitted from the output path.
498 %% A literal '%' character.
500
502 SSLsplit currently supports the following NAT engines:
503 pf OpenBSD packet filter (pf) rdr/rdr-to NAT redirects, also avail‐
505 able on FreeBSD, NetBSD and Mac OS X. Fully supported, includ‐
506 ing IPv6. Note that SSLsplit needs permission to open /dev/pf
507 for reading, which by default means that it needs to run under
508 root privileges. Assuming inbound interface em0, first in old
509 (FreeBSD, Mac OS X), then in new (OpenBSD 4.7+) syntax:
510 rdr pass on em0 proto tcp from 2001:db8::/64 to any port 80 \
512 -> ::1 port 10080
513 rdr pass on em0 proto tcp from 2001:db8::/64 to any port 443 \
514 -> ::1 port 10443
515 rdr pass on em0 proto tcp from 192.0.2.0/24 to any port 80 \
516 -> 127.0.0.1 port 10080
517 rdr pass on em0 proto tcp from 192.0.2.0/24 to any port 443 \
518 -> 127.0.0.1 port 10443
519 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
521 port 80 rdr-to ::1 port 10080
522 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
523 port 443 rdr-to ::1 port 10443
524 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
525 port 80 rdr-to 127.0.0.1 port 10080
526 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
527 port 443 rdr-to 127.0.0.1 port 10443
528 ipfw FreeBSD IP firewall (IPFW) divert sockets, also available on Mac
530 OS X. Available on FreeBSD and OpenBSD using pf divert-to.
531 Fully supported on FreeBSD and OpenBSD, including IPv6. Only
532 supports IPv4 on Mac OS X due to the ancient version of IPFW in‐
533 cluded. First in IPFW, then in pf divert-to syntax:
534 ipfw add fwd ::1,10080 tcp from 2001:db8::/64 to any 80
536 ipfw add fwd ::1,10443 tcp from 2001:db8::/64 to any 443
537 ipfw add fwd 127.0.0.1,10080 tcp from 192.0.2.0/24 to any 80
538 ipfw add fwd 127.0.0.1,10443 tcp from 192.0.2.0/24 to any 443
539 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
541 port 80 divert-to ::1 port 10080
542 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
543 port 443 divert-to ::1 port 10443
544 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
545 port 80 divert-to 127.0.0.1 port 10080
546 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
547 port 443 divert-to 127.0.0.1 port 10443
548 ipfilter
550 IPFilter (ipfilter, ipf), available on many systems, including
551 FreeBSD, NetBSD, Linux and Solaris. Note that SSLsplit needs
552 permission to open /dev/ipnat for reading, which by default
553 means that it needs to run under root privileges. Only supports
554 IPv4 due to limitations in the SIOCGNATL ioctl(2) interface.
555 Assuming inbound interface bge0:
556 rdr bge0 0.0.0.0/0 port 80 -> 127.0.0.1 port 10080
558 rdr bge0 0.0.0.0/0 port 443 -> 127.0.0.1 port 10443
559 netfilter
561 Linux netfilter using the iptables REDIRECT target. Fully sup‐
562 ported including IPv6 since Linux v3.8-rc1; on older kernels
563 only supports IPv4 due to limitations in the SO_ORIGINAL_DST
564 getsockopt(2) interface.
565 iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
567 -p tcp --dport 80 \
568 -j REDIRECT --to-ports 10080
569 iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
570 -p tcp --dport 443 \
571 -j REDIRECT --to-ports 10443
572 # please contribute a tested ip6tables config
573 Note that SSLsplit is only able to accept incoming connections
575 if it binds to the correct IP address (e.g. 192.0.2.1) or on all
576 interfaces (0.0.0.0). REDIRECT uses the local interface address
577 of the incoming interface as target IP address, or 127.0.0.1 for
578 locally generated packets.
579 tproxy Linux netfilter using the iptables TPROXY target together with
581 routing table magic to allow non-local traffic to originate on
582 local sockets. Fully supported, including IPv6.
583 ip -f inet6 rule add fwmark 1 lookup 100
585 ip -f inet6 route add local default dev lo table 100
586 ip6tables -t mangle -N DIVERT
587 ip6tables -t mangle -A DIVERT -j MARK --set-mark 1
588 ip6tables -t mangle -A DIVERT -j ACCEPT
589 ip6tables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
590 ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
591 -p tcp --dport 80 \
592 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
593 ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
594 -p tcp --dport 443 \
595 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443
596 ip -f inet rule add fwmark 1 lookup 100
597 ip -f inet route add local default dev lo table 100
598 iptables -t mangle -N DIVERT
599 iptables -t mangle -A DIVERT -j MARK --set-mark 1
600 iptables -t mangle -A DIVERT -j ACCEPT
601 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
602 iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
603 -p tcp --dport 80 \
604 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
605 iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
606 -p tcp --dport 443 \
607 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443
608 Note that return path filtering (rp_filter) also needs to be
610 disabled on interfaces which handle TPROXY redirected traffic.
611
613 A running sslsplit accepts SIGINT and SIGTERM for a clean shutdown and
614 SIGUSR1 to re-open the single-file log files (such as -l, -L and -X).
615 The canonical way to rotate or post-process logs is to rename the ac‐
616 tive log file, send SIGUSR1 to the PID in the PID file given by -p,
617 give SSLsplit some time to flush buffers after closing the old file,
618 and then post-process the renamed log file. Per-connection log files
619 (such as -S and -F) are not re-opened because their filename is spe‐
620 cific to the connection.
621
623 The sslsplit process will exit with 0 on regular shutdown (SIGINT,
624 SIGTERM), and 128 + signal number on controlled shutdown based on re‐
625 ceiving a different signal such as SIGHUP. Exit status in the range
626 1..127 indicates error conditions.
627
629 Matching the above NAT engine configuration samples, intercept HTTP and
630 HTTPS over IPv4 and IPv6 using forged certificates with CA private key
631 ca.key and certificate ca.crt, logging connections to connect.log and
632 connection data into separate files under /tmp (add -e nat-engine to
633 select the appropriate engine if multiple engines are available on your
634 system):
635 sslsplit -k ca.key -c ca.crt -l connect.log -S /tmp \
637 https ::1 10443 https 127.0.0.1 10443 \
638 http ::1 10080 http 127.0.0.1 10080
639 If the Linux netfilter engine is used with the iptables REDIRECT tar‐
641 get, it is important to listen to the correct IP address (e.g.
642 192.0.2.1) or on all interfaces (0.0.0.0), otherwise SSLsplit is not
643 able to accept incoming connections.
644 Intercepting IMAP/IMAPS using the same settings:
646 sslsplit -k ca.key -c ca.crt -l connect.log -S /tmp \
648 ssl ::1 10993 ssl 127.0.0.1 10993 \
649 tcp ::1 10143 tcp 127.0.0.1 10143
650 A more targeted setup, HTTPS only, using certificate/chain/key files
652 from /path/to/cert.d and statically redirecting to www.example.org in‐
653 stead of querying a NAT engine:
654 sslsplit -t /path/to/cert.d -l connect.log -S /tmp \
656 https ::1 10443 www.example.org 443 \
657 https 127.0.0.1 10443 www.example.org 443
658 The original example, but using plain ssl and tcp proxyspecs to avoid
660 header modifications, and logging to a single PCAP file for post-pro‐
661 cessing with an external tool. To facilitate log rotation via SIGUSR1,
662 -p is also given, so external log rotation tools or scripts can read
663 the PID from the PID file.
664 sslsplit -k ca.key -c ca.crt -X log.pcap -p /var/run/sslsplit.pid \
666 ssl ::1 10443 ssl 127.0.0.1 10443 \
667 tcp ::1 10080 tcp 127.0.0.1 10080
668 The original example, but using SSL options optimized for speed by dis‐
670 abling compression and selecting only fast cipher cipher suites and us‐
671 ing a precomputed private key leaf.key for the forged certificates.
672 Most significant speed increase is gained by choosing fast algorithms
673 and small keysizes for the CA and leaf private keys. Check openssl
674 speed for algorithm performance on your system. Note that clients may
675 not support all algorithms and key sizes. Also, some clients warn
676 their users about cipher suites they consider weak.
677 sslsplit -Z -s NULL:RC4:AES128:-DHE -K leaf.key \
679 -k ca.key -c ca.crt -l connect.log -S /tmp \
680 https ::1 10443 https 127.0.0.1 10443 \
681 http ::1 10080 http 127.0.0.1 10080
682 The original example, but running as a daemon under user sslsplit and
684 writing a PID file:
685 sslsplit -d -p /var/run/sslsplit.pid -u sslsplit \
687 -k ca.key -c ca.crt -l connect.log -S /tmp \
688 https ::1 10443 https 127.0.0.1 10443 \
689 http ::1 10080 http 127.0.0.1 10080
690 To generate a CA private key ca.key and certificate ca.crt using
692 OpenSSL:
693 cat >x509v3ca.cnf <<'EOF'
695 [ req ]
696 distinguished_name = reqdn
697 [ reqdn ]
699 [ v3_ca ]
701 basicConstraints = CA:TRUE
702 subjectKeyIdentifier = hash
703 authorityKeyIdentifier = keyid:always,issuer:always
704 EOF
705 openssl genrsa -out ca.key 2048
707 openssl req -new -nodes -x509 -sha256 -out ca.crt -key ca.key \
708 -config x509v3ca.cnf -extensions v3_ca \
709 -subj '/O=SSLsplit Root CA/CN=SSLsplit Root CA/' \
710 -set_serial 0 -days 3650
711
713 SSLsplit is able to handle a relatively high number of listeners and
714 connections due to a multithreaded, event based architecture based on
715 libevent, taking advantage of platform specific select() replacements
716 such as kqueue. The main thread handles the listeners and signaling,
717 while a number of worker threads equal to twice the number of CPU cores
718 is used for handling the actual connections in separate event bases,
719 including the CPU-intensive SSL/TLS handling.
720 Care has been taken to choose well-performing data structures for
722 caching certificates and SSL sessions. Logging is implemented in sepa‐
723 rate disk writer threads to ensure that socket event handling threads
724 don't have to block on disk I/O. DNS lookups are performed asyn‐
725 chronously. SSLsplit uses SSL session caching on both ends to minimize
726 the amount of full SSL handshakes, but even then, the limiting factor
727 in handling SSL connections are the actual bignum computations.
728 For high performance and low latency and when running SSLsplit as root
730 or otherwise in a privilege separation mode, avoid using options which
731 require a privileged operation to be invoked through privilege separa‐
732 tion for each connection. These are currently all per-connection log
733 types: content log to per-stream file in dir or filespec (-F, -S), con‐
734 tent log to per-stream PCAP in dir or filespec (-Y, -y), and generated
735 or all certificates to files in directory (-w, -W). Instead, use the
736 respective single-file variants where available. It is possible, al‐
737 beit not recommended, to bypass the default privilege separation when
738 run as root by using -u root, thereby bypassing privilege separation
739 entirely.
740
742 sslsplit.conf(5), openssl(1), ciphers(1), speed(1), pf(4), ipfw(8),
743 iptables(8), ip6tables(8), ip(8), hostapd(8), arpspoof(8), para‐
744 site6(8), yersinia(8), https://www.roe.ch/SSLsplit
745
747 SSLsplit was written by Daniel Roethlisberger <daniel@roe.ch>.
748 SSLsplit is currently maintained by Daniel Roethlisberger and Soner
749 Tari.
750 The following individuals have contributed code or documentation, in
752 chronological order of their first contribution: Steve Wills, Landon
753 Fuller, Wayne Jensen, Rory McNamara, Alexander Neumann, Adam Jacob
754 Muller, Richard Poole, Maciej Kotowicz, Eun Soo Park, Christian
755 Groschupp, Alexander Savchenkov, Soner Tari, Petr Vanek, Hilko Bengen,
756 Philip Duldig, Levente Polyak, Nick French, Cihan Komecoglu and Sergey
757 Pinaev.
758 SSLsplit contains work sponsored by HackerOne.
760
762 Use Github for submission of bug reports or patches:
763 https://github.com/droe/sslsplit
765sslsplit 0.5.5 2023-01-13 sslsplit(1)