1sslsplit(1)                        SSLsplit                        sslsplit(1)
2
3
4

NAME

6       sslsplit -- transparent SSL/TLS interception
7

SYNOPSIS

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

DESCRIPTION

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
23       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
33       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
42       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
51       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
61       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
66       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
73       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

OPTIONS

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
96       -b pemfile
97              Use  client private key from pemfile when destination server re‐
98              quests a client certificate.
99
100       -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
109       -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
116       -d     Detach from TTY and run as a daemon, logging error  messages  to
117              syslog instead of standard error.
118
119       -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
123       -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
129       -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
133       -f conffile
134              Read configuration from conffile.
135
136       -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
144       -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
153       -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
160       -h     Display help on usage and exit.
161
162       -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
170       -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
174       -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
184       -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
193       -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
198       -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
204       -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
211       -m     When  dropping  privileges using -u, override the target primary
212              group to be set to group.
213
214       -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
222       -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
235       -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
239       -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
253       -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
260       -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
273       -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
287       -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
300       -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
307       -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
324       -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
330       -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
344       -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
354       -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
360       -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
365       -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
371       -V     Display version and compiled features information and exit.
372
373       -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
383       -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
387       -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

PROXY SPECIFICATIONS

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
397       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
403       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
407       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
411       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
416       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
420       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
428       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
433       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
441       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
447       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

LOG SPECIFICATIONS

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
465       %T     The initial connection time as an ISO 8601 UTC timestamp.
466
467       %d     The destination host and port, separated by a  comma,  IPv6  ad‐
468              dresses using underscore instead of colon.
469
470       %D     The destination host, IPv6 addresses using underscore instead of
471              colon.
472
473       %p     The destination port.
474
475       %s     The source host and port, separated by a comma,  IPv6  addresses
476              using underscore instead of colon.
477
478       %S     The  source  host,  IPv6  addresses  using underscore instead of
479              colon.
480
481       %q     The source port.
482
483       %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
487       %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
491       %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
495       %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
499       %%     A literal '%' character.
500

NAT ENGINES

502       SSLsplit currently supports the following NAT engines:
503
504       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
511              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
520              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
529       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
535              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
540              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
549       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
557              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
560       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
566              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
574              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
580       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
584              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
609              Note  that  return  path  filtering (rp_filter) also needs to be
610              disabled on interfaces which handle TPROXY redirected traffic.
611

SIGNALS

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

EXIT STATUS

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

EXAMPLES

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
636       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
640       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
645       Intercepting IMAP/IMAPS using the same settings:
646
647       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
651       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
655       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
659       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
665       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
669       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
678       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
683       The  original  example, but running as a daemon under user sslsplit and
684       writing a PID file:
685
686       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
691       To generate a CA private  key  ca.key   and  certificate  ca.crt  using
692       OpenSSL:
693
694       cat >x509v3ca.cnf <<'EOF'
695       [ req ]
696       distinguished_name = reqdn
697
698       [ reqdn ]
699
700       [ v3_ca ]
701       basicConstraints        = CA:TRUE
702       subjectKeyIdentifier    = hash
703       authorityKeyIdentifier  = keyid:always,issuer:always
704       EOF
705
706       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

NOTES

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
721       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
729       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

SEE ALSO

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

AUTHORS

747       SSLsplit   was   written   by  Daniel  Roethlisberger  <daniel@roe.ch>.
748       SSLsplit is currently maintained by  Daniel  Roethlisberger  and  Soner
749       Tari.
750
751       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
759       SSLsplit contains work sponsored by HackerOne.
760

BUGS

762       Use Github for submission of bug reports or patches:
763
764              https://github.com/droe/sslsplit
765
766sslsplit 0.5.5                    2023-01-21                       sslsplit(1)
Impressum