1SSLSPLIT(1) General Commands Manual SSLSPLIT(1)
2
6 sslsplit -- transparent SSL/TLS interception
7
9 sslsplit [-kCKqwWOPZdDgGsrReumjplLSFiM] -c pem proxyspecs [...]
10 sslsplit [-kCKqwWOPZdDgGsrReumjplLSFiM] -c pem -t dir proxyspecs [...]
11 sslsplit [-OPZwWdDgGsrReumjplLSFiM] -t dir proxyspecs [...]
12 sslsplit -E
13 sslsplit -V
14 sslsplit -h
15
17 SSLsplit is a tool for man-in-the-middle attacks against SSL/TLS
18 encrypted network connections. It is intended to be useful for network
19 forensics, application security analysis and penetration testing.
20 SSLsplit is designed to transparently terminate connections that are
22 redirected to it using a network address translation engine. SSLsplit
23 then terminates SSL/TLS and initiates a new SSL/TLS connection to the
24 original destination address, while logging all data transmitted.
25 Besides NAT based operation, SSLsplit also supports static destinations
26 and using the server name indicated by SNI as upstream destination.
27 SSLsplit is purely a transparent proxy and cannot act as a HTTP or
28 SOCKS proxy configured in a browser. See NAT ENGINES and PROXY SPECI‐
29 FICATIONS below for specifics on the different modes of operation.
30 SSLsplit supports plain TCP, plain SSL, HTTP and HTTPS connections over
32 both IPv4 and IPv6. It also has the ability to dynamically upgrade
33 plain TCP to SSL in order to generically support SMTP STARTTLS and sim‐
34 ilar upgrade mechanisms. SSLsplit fully supports Server Name Indica‐
35 tion (SNI) and is able to work with RSA, DSA and ECDSA keys and DHE and
36 ECDHE cipher suites. Depending on the version of OpenSSL, SSLsplit
37 supports SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2, and optionally SSL 2.0
38 as well.
39 For SSL and HTTPS connections, SSLsplit generates and signs forged
41 X509v3 certificates on-the-fly, mimicking the original server certifi‐
42 cate's subject DN, subjectAltName extension and other characteristics.
43 SSLsplit has the ability to use existing certificates of which the pri‐
44 vate key is available, instead of generating forged ones. SSLsplit
45 supports NULL-prefix CN certificates but otherwise does not implement
46 exploits against specific certificate verification vulnerabilities in
47 SSL/TLS stacks.
48 SSLsplit implements a number of defences against mechanisms which would
50 normally prevent MitM attacks or make them more difficult. SSLsplit
51 can deny OCSP requests in a generic way. For HTTP and HTTPS connec‐
52 tions, SSLsplit mangles headers to prevent server-instructed public key
53 pinning (HPKP), avoid strict transport security restrictions (HSTS),
54 and prevent switching to QUIC/SPDY, HTTP/2 or WebSockets (Upgrade,
55 Alternate Protocols). HTTP compression, encodings and keep-alive are
56 disabled to make the logs more readable.
57 In order to maximize the chances that a connection can be successfully
59 split, SSLsplit does not verify upstream server certificates. Instead,
60 all certificates including self-signed are accepted and if the expected
61 hostname signalled in SNI is missing from the server certificate, it
62 will be added to dynamically forged certificates.
63 SSLsplit does not automagically redirect any network traffic. To actu‐
65 ally implement an attack, you also need to redirect the traffic to the
66 system running sslsplit. Your options include running sslsplit on a
67 legitimate router, ARP spoofing, ND spoofing, DNS poisoning, deploying
68 a rogue access point (e.g. using hostap mode), physical recabling,
69 malicious VLAN reconfiguration or route injection, /etc/hosts modifica‐
70 tion and so on.
71
73 -c pemfile
74 Use CA certificate from pemfile to sign certificates forged on-
75 the-fly. If pemfile also contains the matching CA private key,
76 it is also loaded, otherwise it must be provided with -k. If
77 pemfile also contains Diffie-Hellman group parameters, they are
78 also loaded, otherwise they can be provided with -g. If -t is
79 also given, SSLsplit will only forge a certificate if there is
80 no matching certificate in the provided certificate directory.
81 -C pemfile
83 Use CA certificates from pemfile as extra certificates in the
84 certificate chain. This is needed if the CA given with -k and
85 -c is a sub-CA, in which case any intermediate CA certificates
86 and the root CA certificate must be included in the certificate
87 chain.
88 -d Detach from TTY and run as a daemon, logging error messages to
90 syslog instead of standard error.
91 -D Run in debug mode, log lots of debugging information to standard
93 error. This also forces foreground mode and cannot be used with
94 -d.
95 -e engine
97 Use engine as the default NAT engine for proxyspecs without
98 explicit NAT engine, static destination address or SNI mode.
99 engine can be any of the NAT engines supported by the system, as
100 returned by -E.
101 -E List all supported NAT engines available on the system and exit.
103 See NAT ENGINES for a list of NAT engines currently supported by
104 SSLsplit.
105 -F logspec
107 Log connection content to separate log files with the given path
108 specification (see LOG SPECIFICATIONS below). For each connec‐
109 tion, a log file will be written, which will contain both direc‐
110 tions of data as transmitted. Information about the connection
111 will be contained in the filename only.
112 -g pemfile
114 Use Diffie-Hellman group parameters from pemfile for Ephemereal
115 Diffie-Hellman (EDH/DHE) cipher suites. If -g is not given,
116 SSLsplit first tries to load DH parameters from the PEM files
117 given by -K, -k or -c. If no DH parameters are found in the key
118 files, built-in group parameters are automatically used. The -g
119 option is only available if SSLsplit was built against a version
120 of OpenSSL which supports Diffie-Hellman cipher suites.
121 -G curve
123 Use the named curve for Ephemereal Elliptic Curve Diffie-Hellman
124 (ECDHE) cipher suites. If -G is not given, a default curve
125 (prime256v1) is used automatically. The -G option is only
126 available if SSLsplit was built against a version of OpenSSL
127 which supports Elliptic Curve Diffie-Hellman cipher suites.
128 -h Display help on usage and exit.
130 -i For each connection, find the local process owning the connec‐
132 tion. This makes process information such as pid, owner:group
133 and executable path for connections originating on the same sys‐
134 tem as SSLsplit available to the connect log and enables the
135 respective -F path specification directives. -i is available on
136 Mac OS X and FreeBSD; support for other platforms has not been
137 implemented yet.
138 -j jaildir
140 Change the root directory to jaildir using chroot(2) after open‐
141 ing files. Note that this has implications for sni proxyspecs.
142 Depending on your operating system, you will need to copy files
143 such as /etc/resolv.conf to jaildir in order for name resolution
144 to work. Using sni proxyspecs depends on name resolution. Some
145 operating systems require special device nodes such as /dev/null
146 to be present within the jail. Check your system's documenta‐
147 tion for details.
148 -k pemfile
150 Use CA private key from pemfile to sign certificates forged on-
151 the-fly. If pemfile also contains the matching CA certificate,
152 it is also loaded, otherwise it must be provided with -c. If
153 pemfile also contains Diffie-Hellman group parameters, they are
154 also loaded, otherwise they can be provided with -g. If -t is
155 also given, SSLsplit will only forge a certificate if there is
156 no matching certificate in the provided certificate directory.
157 -K pemfile
159 Use private key from pemfile for the leaf certificates forged
160 on-the-fly. If -K is not given, SSLsplit will generate a random
161 1024-bit RSA key.
162 -l logfile
164 Log connections to logfile in a single line per connection for‐
165 mat, including addresses and ports and some HTTP and SSL infor‐
166 mation, if available. SIGUSR1 will cause logfile to be re-
167 opened.
168 -L logfile
170 Log connection content to logfile. The content log will contain
171 a parsable log format with transmitted data, prepended with
172 headers identifying the connection and the data length of each
173 logged segment. SIGUSR1 will cause logfile to be re-opened.
174 -m When dropping privileges using -u, override the target primary
176 group to be set to group.
177 -M logfile
179 Log master keys to logfile in SSLKEYLOGFILE format as defined by
180 Mozilla. Logging master keys in this format allows for decryp‐
181 tion of SSL/TLS traffic using Wireshark. Note that unlike
182 browsers implementing this feature, setting the SSLKEYLOGFILE
183 environment variable has no effect on SSLsplit. SIGUSR1 will
184 cause logfile to be re-opened.
185 -O Deny all Online Certificate Status Protocol (OCSP) requests on
187 all proxyspecs and for all OCSP servers with an OCSP response of
188 tryLater, causing OCSP clients to temporarily accept even
189 revoked certificates. HTTP requests are being treated as OCSP
190 requests if the method is GET and the URI contains a syntacti‐
191 cally valid OCSPRequest ASN.1 structure parsable by OpenSSL, or
192 if the method is POST and the Content-Type is application/ocsp-
193 request. For this to be effective, SSLsplit must be handling
194 traffic destined to the port used by the OCSP server. In par‐
195 ticular, SSLsplit must be configured to receive traffic to all
196 ports used by OCSP servers of targetted certificates within the
197 certdir specified by -t.
198 -p pidfile
200 Write the process ID to pidfile and refuse to run if the pidfile
201 is already in use by another process.
202 -P Passthrough SSL/TLS connections which cannot be split instead of
204 dropping them. Connections cannot be split if -c and -k are not
205 given and the site does not match any certificate loaded using
206 -t, or if the connection to the original server gives SSL/TLS
207 errors. Specifically, this happens if the site requests a
208 client certificate. In these situations, passthrough with -P
209 results in uninterrupted service for the clients, while dropping
210 is the more secure alternative if unmonitored connections must
211 be prevented. Passthrough mode currently does not apply to
212 SSL/TLS errors in the connection from the client, since the con‐
213 nection from the client cannot easily be retried. Specifically,
214 -P does not currently work for clients that do not accept forged
215 certificates.
216 -q crlurl
218 Set CRL distribution point (CDP) crlurl on forged leaf certifi‐
219 cates. Some clients, such as some .NET applications, reject
220 certificates that do not carry a CDP. When using -q, you will
221 need to generate an empty CRL signed by the CA certificate and
222 key provided with -c and -k, and make it available at crlurl.
223 -r proto
225 Force SSL/TLS protocol version on both client and server side to
226 proto by selecting the respective OpenSSL method constructor
227 instead of the default SSLv23_method() which supports all proto‐
228 col versions. This is useful when analyzing traffic to a server
229 that only supports a specific version of SSL/TLS and does not
230 implement proper protocol negotiation. Depending on build
231 options and the version of OpenSSL that is used, the following
232 values for proto are accepted: ssl2, ssl3, tls10, tls11 and
233 tls12. Note that SSL 2.0 support is not built in by default
234 because some servers don't handle SSL 2.0 Client Hello messages
235 gracefully.
236 -R proto
238 Disable the SSL/TLS protocol version proto on both client and
239 server side by disabling the respective protocols in OpenSSL.
240 To disable multiple protocol versions, -R can be given multiple
241 times. If -r is also given, there will be no effect in dis‐
242 abling other protocol versions. Disabling protocol versions is
243 useful when analyzing traffic to a server that does not handle
244 some protocol versions well, or to test behaviour with different
245 protocol versions. Depending on build options and the version
246 of OpenSSL that is used, the following values for proto are
247 accepted: ssl2, ssl3, tls10, tls11 and tls12. Note that SSL 2.0
248 support is not built in by default because some servers don't
249 handle SSL 2.0 Client Hello messages gracefully.
250 -s ciphers
252 Use OpenSSL ciphers specification for both server and client
253 SSL/TLS connections. If -s is not given, a cipher list of
254 ALL:-aNULL is used. Normally, SSL/TLS implementations choose
255 the most secure cipher suites, not the fastest ones. By speci‐
256 fying an appropriate OpenSSL cipher list, the set of cipher
257 suites can be limited to fast algorithms, or eNULL cipher suites
258 can be added. Note that for connections to be successful, the
259 SSLsplit cipher suites must include at least one cipher suite
260 supported by both the client and the server of each connection.
261 See ciphers(1) for details on how to construct OpenSSL cipher
262 lists.
263 -S logdir
265 Log connection content to separate log files under logdir. For
266 each connection, a log file will be written, which will contain
267 both directions of data as transmitted. Information about the
268 connection will be contained in the filename only.
269 -t certdir
271 Use private key, certificate and certificate chain from PEM
272 files in certdir for connections to hostnames matching the
273 respective certificates, instead of using certificates forged
274 on-the-fly. A single PEM file must contain a single private
275 key, a single certificate and optionally intermediate and root
276 CA certificates to use as certificate chain. When using -t,
277 SSLsplit will first attempt to use a matching certificate loaded
278 from certdir. If -c and -k are also given, certificates will be
279 forged on-the-fly for sites matching none of the common names in
280 the certificates loaded from certdir. Otherwise, connections
281 matching no certificate will be dropped, or if -P is given,
282 passed through without splitting SSL/TLS.
283 -u Drop privileges after opening sockets and files by setting the
285 real, effective and stored user IDs to user and loading the
286 appropriate primary and ancillary groups. If -u is not given,
287 SSLsplit will drop privileges to the stored UID if EUID != UID
288 (setuid bit scenario), or to nobody if running with full root
289 privileges (EUID == UID == 0). Due to an Apple bug, -u cannot
290 be used with pf proxyspecs on Mac OS X.
291 -V Display version and compiled features information and exit.
293 -w gendir
295 Write generated keys and certificates to individual files in
296 gendir. For keys, the key identifier is used as filename, which
297 consists of the SHA-1 hash of the ASN.1 bit string of the public
298 key, as referenced by the subjectKeyIdentifier extension in cer‐
299 tificates. For certificates, the SHA-1 fingerprints of the
300 original and the used (forged) certificate are combined to form
301 the filename. Note that only newly generated certificates are
302 written to disk.
303 -W gendir
305 Same as -w, but also write original certificates and certifi‐
306 cates not newly generated, such as those loaded from -t.
307 -Z Disable SSL/TLS compression on all connections. This is useful
309 if your limiting factor is CPU, not network bandwidth. The -Z
310 option is only available if SSLsplit was built against a version
311 of OpenSSL which supports disabling compression.
312
314 Proxy specifications (proxyspecs) consist of the connection type, lis‐
315 ten address and static forward address or address resolution mechanism
316 (NAT engine, SNI DNS lookup):
317 https listenaddr port [nat-engine|fwdaddr port|sni port]
319 ssl listenaddr port [nat-engine|fwdaddr port|sni port]
320 http listenaddr port [nat-engine|fwdaddr port]
321 tcp listenaddr port [nat-engine|fwdaddr port]
322 autossl listenaddr port [nat-engine|fwdaddr port]
323 https SSL/TLS interception with HTTP protocol decoding, including the
325 removal of HPKP, HSTS, Upgrade and Alternate Protocol response
326 headers. This mode currently suppresses WebSockets and HTTP/2.
327 ssl SSL/TLS interception without any lower level protocol decoding;
329 decrypted connection content is treated as opaque stream of
330 bytes and not modified.
331 http Plain TCP connection without SSL/TLS, with HTTP protocol decod‐
333 ing, including the removal of HPKP, HSTS, Upgrade and Alternate
334 Protocol response headers. This mode currently suppresses Web‐
335 Sockets and HTTP/2.
336 tcp Plain TCP connection without SSL/TLS and without any lower level
338 protocol decoding; decrypted connection content is treated as
339 opaque stream of bytes and not modified.
340 autossl
342 Plain TCP connection until a Client Hello SSL/TLS message
343 appears in the byte stream, then automatic upgrade to SSL/TLS
344 interception. This is generic, protocol-independent STARTTLS
345 support, that may erroneously trigger on byte sequences that
346 look like Client Hello messages even though there was no actual
347 STARTTLS command issued.
348 listenaddr port
350 IPv4 or IPv6 address and port or service name to listen on.
351 This is the address and port where the NAT engine should redi‐
352 rect connections to.
353 nat-engine
355 NAT engine to query for determining the original destination
356 address and port of transparently redirected connections. If no
357 engine is given, the default engine is used, unless overridden
358 with -e. When using a NAT engine, sslsplit needs to run on the
359 same system as the NAT rules redirecting the traffic to
360 sslsplit. See NAT ENGINES for a list of supported NAT engines.
361 fwdaddr port
363 Static destination address, IPv4 or IPv6, with port or service
364 name. When this is used, connections are forwarded to the given
365 server address and port. If fwdaddr is a hostname, it will be
366 resolved to an IP address.
367 sni port
369 Use the Server Name Indication (SNI) hostname sent by the client
370 in the Client Hello SSL/TLS message to determine the IP address
371 of the server to connect to. This only works for ssl and https
372 proxyspecs and needs a port or service name as an argument.
373 Because this requires DNS lookups, it is preferrable to use NAT
374 engine lookups (see above), except when that is not possible,
375 such as when there is no supported NAT engine or when running
376 sslsplit on a different system than the NAT rules redirecting
377 the actual connections. Note that when using -j with sni, you
378 may need to prepare jaildir to make name resolution work from
379 within the chroot directory.
380
382 A running sslsplit accepts SIGINT and SIGQUIT for a clean shutdown and
383 SIGUSR1 to re-open the long-living log files (-l and -L). Per-connec‐
384 tion log files (-S and -F) are not re-opened because their filename is
385 specific to the connection.
386
388 Log specifications are composed of zero or more printf-style direc‐
389 tives; ordinary characters are included directly in the output path.
390 SSLsplit current supports the following directives:
391 %T The initial connection time as an ISO 8601 UTC timestamp.
393 %d The destination host and port, separated by a comma, IPv6
395 addresses using underscore instead of colon.
396 %D The destination host, IPv6 addresses using underscore instead of
398 colon.
399 %p The destination port.
401 %s The source host and port, separated by a comma, IPv6 addresses
403 using underscore instead of colon.
404 %S The source host, IPv6 addresses using underscore instead of
406 colon.
407 %q The source port.
409 %x The name of the local process. Requires -i to be used. If
411 process information is unavailable, this directive will be omit‐
412 ted from the output path.
413 %X The full path of the local process. Requires -i to be used. If
415 process information is unavailable, this directive will be omit‐
416 ted from the output path.
417 %u The username or numeric uid of the local process. Requires -i
419 to be used. If process information is unavailable, this direc‐
420 tive will be omitted from the output path.
421 %g The group name or numeric gid of the local process. Requires -i
423 to be used. If process information is unavailable, this direc‐
424 tive will be omitted from the output path.
425 %% A literal '%' character.
427
429 SSLsplit currently supports the following NAT engines:
430 pf OpenBSD packet filter (pf) rdr/rdr-to NAT redirects, also avail‐
432 able on FreeBSD, NetBSD and Mac OS X. Fully supported, includ‐
433 ing IPv6. Note that SSLsplit needs permission to open /dev/pf
434 for reading, which by default means that it needs to run under
435 root privileges. Assuming inbound interface em0, first in old
436 (FreeBSD, Mac OS X), then in new (OpenBSD 4.7+) syntax:
437 rdr pass on em0 proto tcp from 2001:db8::/64 to any port 80 \
439 -> ::1 port 10080
440 rdr pass on em0 proto tcp from 2001:db8::/64 to any port 443 \
441 -> ::1 port 10443
442 rdr pass on em0 proto tcp from 192.0.2.0/24 to any port 80 \
443 -> 127.0.0.1 port 10080
444 rdr pass on em0 proto tcp from 192.0.2.0/24 to any port 443 \
445 -> 127.0.0.1 port 10443
446 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
448 port 80 rdr-to ::1 port 10080
449 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
450 port 443 rdr-to ::1 port 10443
451 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
452 port 80 rdr-to 127.0.0.1 port 10080
453 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
454 port 443 rdr-to 127.0.0.1 port 10443
455 ipfw FreeBSD IP firewall (IPFW) divert sockets, also available on Mac
457 OS X. Available on FreeBSD and OpenBSD using pf divert-to.
458 Fully supported on FreeBSD and OpenBSD, including IPv6. Only
459 supports IPv4 on Mac OS X due to the ancient version of IPFW
460 included. First in IPFW, then in pf divert-to syntax:
461 ipfw add fwd ::1,10080 tcp from 2001:db8::/64 to any 80
463 ipfw add fwd ::1,10443 tcp from 2001:db8::/64 to any 443
464 ipfw add fwd 127.0.0.1,10080 tcp from 192.0.2.0/24 to any 80
465 ipfw add fwd 127.0.0.1,10443 tcp from 192.0.2.0/24 to any 443
466 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
468 port 80 divert-to ::1 port 10080
469 pass in quick on em0 proto tcp from 2001:db8::/64 to any \
470 port 443 divert-to ::1 port 10443
471 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
472 port 80 divert-to 127.0.0.1 port 10080
473 pass in quick on em0 proto tcp from 192.0.2.0/24 to any \
474 port 443 divert-to 127.0.0.1 port 10443
475 ipfilter
477 IPFilter (ipfilter, ipf), available on many systems, including
478 FreeBSD, NetBSD, Linux and Solaris. Note that SSLsplit needs
479 permission to open /dev/ipnat for reading, which by default
480 means that it needs to run under root privileges. Only supports
481 IPv4 due to limitations in the SIOCGNATL ioctl(2) interface.
482 Assuming inbound interface bge0:
483 rdr bge0 0.0.0.0/0 port 80 -> 127.0.0.1 port 10080
485 rdr bge0 0.0.0.0/0 port 443 -> 127.0.0.1 port 10443
486 netfilter
488 Linux netfilter using the iptables REDIRECT target. Fully sup‐
489 ported including IPv6 since Linux v3.8-rc1; on older kernels
490 only supports IPv4 due to limitations in the SO_ORIGINAL_DST
491 getsockopt(2) interface.
492 iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
494 -p tcp --dport 80 \
495 -j REDIRECT --to-ports 10080
496 iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
497 -p tcp --dport 443 \
498 -j REDIRECT --to-ports 10443
499 # please contribute a tested ip6tables config
500 Note that SSLsplit is only able to accept incoming connections
502 if it binds to the correct IP address (e.g. 192.0.2.1) or on all
503 interfaces (0.0.0.0). REDIRECT uses the local interface address
504 of the incoming interface as target IP address, or 127.0.0.1 for
505 locally generated packets.
506 tproxy Linux netfilter using the iptables TPROXY target together with
508 routing table magic to allow non-local traffic to originate on
509 local sockets. Fully supported, including IPv6.
510 ip -f inet6 rule add fwmark 1 lookup 100
512 ip -f inet6 route add local default dev lo table 100
513 ip6tables -t mangle -N DIVERT
514 ip6tables -t mangle -A DIVERT -j MARK --set-mark 1
515 ip6tables -t mangle -A DIVERT -j ACCEPT
516 ip6tables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
517 ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
518 -p tcp --dport 80 \
519 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
520 ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
521 -p tcp --dport 443 \
522 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443
523 ip -f inet rule add fwmark 1 lookup 100
524 ip -f inet route add local default dev lo table 100
525 iptables -t mangle -N DIVERT
526 iptables -t mangle -A DIVERT -j MARK --set-mark 1
527 iptables -t mangle -A DIVERT -j ACCEPT
528 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
529 iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
530 -p tcp --dport 80 \
531 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
532 iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
533 -p tcp --dport 443 \
534 -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443
535 Note that return path filtering (rp_filter) also needs to be
537 disabled on interfaces which handle TPROXY redirected traffic.
538
540 Matching the above NAT engine configuration samples, intercept HTTP and
541 HTTPS over IPv4 and IPv6 using forged certificates with CA private key
542 ca.key and certificate ca.crt, logging connections to connect.log and
543 connection data into separate files under /tmp (add -e nat-engine to
544 select the appropriate engine if multiple engines are available on your
545 system):
546 sslsplit -k ca.key -c ca.crt -l connect.log -S /tmp \
548 https ::1 10443 https 127.0.0.1 10443 \
549 http ::1 10080 http 127.0.0.1 10080
550 If the Linux netfilter engine is used with the iptables REDIRECT tar‐
552 get, it is important to listen to the correct IP address (e.g.
553 192.0.2.1) or on all interfaces (0.0.0.0), otherwise SSLsplit is not
554 able to accept incoming connections.
555 Intercepting IMAP/IMAPS using the same settings:
557 sslsplit -k ca.key -c ca.crt -l connect.log -S /tmp \
559 ssl ::1 10993 ssl 127.0.0.1 10993 \
560 tcp ::1 10143 tcp 127.0.0.1 10143
561 A more targetted setup, HTTPS only, using certificate/chain/key files
563 from /path/to/cert.d and statically redirecting to www.example.org
564 instead of querying a NAT engine:
565 sslsplit -t /path/to/cert.d -l connect.log -S /tmp \
567 https ::1 10443 www.example.org 443 \
568 https 127.0.0.1 10443 www.example.org 443
569 The original example, but using SSL options optimized for speed by dis‐
571 abling compression and selecting only fast cipher cipher suites and
572 using a precomputed private key leaf.key for the forged certificates.
573 Most significant speed increase is gained by choosing fast algorithms
574 and small keysizes for the CA and leaf private keys. Check openssl
575 speed for algorithm performance on your system. Note that clients may
576 not support all algorithms and key sizes. Also, some clients warn
577 their users about cipher suites they consider weak.
578 sslsplit -Z -s NULL:RC4:AES128:-DHE -K leaf.key \
580 -k ca.key -c ca.crt -l connect.log -S /tmp \
581 https ::1 10443 https 127.0.0.1 10443 \
582 http ::1 10080 http 127.0.0.1 10080
583 The original example, but running as a daemon under user sslsplit and
585 writing a PID file:
586 sslsplit -d -p /var/run/sslsplit.pid -u sslsplit \
588 -k ca.key -c ca.crt -l connect.log -S /tmp \
589 https ::1 10443 https 127.0.0.1 10443 \
590 http ::1 10080 http 127.0.0.1 10080
591 To generate a CA private key ca.key and certificate ca.crt using
593 OpenSSL:
594 cat >x509v3ca.cnf <<'EOF'
596 [ req ]
597 distinguished_name = reqdn
598 [ reqdn ]
600 [ v3_ca ]
602 basicConstraints = CA:TRUE
603 subjectKeyIdentifier = hash
604 authorityKeyIdentifier = keyid:always,issuer:always
605 EOF
606 openssl genrsa -out ca.key 2048
608 openssl req -new -nodes -x509 -sha256 -out ca.crt -key ca.key \
609 -config x509v3ca.cnf -extensions v3_ca \
610 -subj '/O=SSLsplit Root CA/CN=SSLsplit Root CA/' \
611 -set_serial 0 -days 3650
612
614 SSLsplit is able to handle a relatively high number of listeners and
615 connections due to a multithreaded, event based architecture based on
616 libevent, taking advantage of platform specific select() replacements
617 such as kqueue. The main thread handles the listeners and signalling,
618 while a number of worker threads equal to twice the number of CPU cores
619 is used for handling the actual connections in separate event bases,
620 including the CPU-intensive SSL/TLS handling.
621 Care has been taken to choose well-performing data structures for
623 caching certificates and SSL sessions. Logging is implemented in sepa‐
624 rate disk writer threads to ensure that socket event handling threads
625 don't have to block on disk I/O. DNS lookups are performed asynchro‐
626 niously. SSLsplit uses SSL session caching on both ends to minimize
627 the amount of full SSL handshakes, but even then, the limiting factor
628 in handling SSL connections are the actual bignum computations.
629
631 openssl(1), ciphers(1), speed(1), pf(4), ipfw(8), iptables(8),
632 ip6tables(8), ip(8), hostapd(8), arpspoof(8), parasite6(8),
633 yersinia(8), https://www.roe.ch/SSLsplit
634
636 SSLsplit was written by Daniel Roethlisberger <daniel@roe.ch>.
637 The following individuals have contributed code or documentation, in
639 chronological order of their first contribution: Steve Wills, Landon
640 Fuller, Wayne Jensen, Rory McNamara, Alexander Neumann, Adam Jacob
641 Muller, Richard Poole, Maciej Kotowicz, Eun Soo Park, Christian
642 Groschupp, Alexander Savchenkov, Soner Tari, Petr Vanek, Hilko Bengen
643 and Philip Duldig.
644
646 Use Github for submission of bug reports or patches:
647 https://github.com/droe/sslsplit
649 1 April 2012 SSLSPLIT(1)