Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
sslproxy(1)			    SSLproxy			     sslproxy(1)

NAME
     sslproxy  -- transparent SSL/TLS proxy for decrypting and diverting network
     traffic to other programs for deep SSL inspection

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

DESCRIPTION
     SSLproxy is a proxy for SSL/TLS encrypted network connections.  It  is  in-
     tended  to  be  used  for decrypting and diverting network traffic to other
     programs, such as UTM services, for deep SSL inspection. But it can  handle
     unencrypted network traffic as well.

     The  UTMFW  project  uses SSLproxy to decyrpt and feed network traffic into
     its UTM services: Web Filter, POP3 Proxy, SMTP Proxy, and Inline  IPS;  and
     also  indirectly into Virus Scanner and Spam Filter through those UTM soft-
     ware.  Given that most of the Internet traffic is	encrypted  now,  without
     SSLproxy  it  wouldn't  be  possible  to deeply inspect most of the network
     traffic passing through UTMFW.

Mode of operation
     SSLproxy is designed to transparently terminate connections that are  redi-
     rected to it using a network address translation engine. SSLproxy then ter-
     minates SSL/TLS and initiates a new SSL/TLS connection to the original des-
     tination  address.  Packets  received  on the client side are decrypted and
     sent to the program listening on a port given in the  proxy  specification.
     SSLproxy  inserts	in the first packet the address and port it is expecting
     to receive the packets back from the program. Upon  receiving  the  packets
     back,  SSLproxy  re-encrypts  and sends them to their original destination.
     The return traffic follows the same path back to the client in reverse  or-
     der.

     This is similar in principle to divert sockets, divert(4), where the packet
     filter  diverts  the packets to a program listening on a divert socket, and
     after processing the packets the program reinjects them into the kernel. If
     there is no program listening on that divert socket or the program does not
     reinject the  packets  into  the  kernel,	the  connection  is  effectively
     blocked.  In  the case of SSLproxy, SSLproxy acts as both the packet filter
     and the kernel, and the communication occurs over networking sockets.

     SSLproxy supports split mode of operation similar to SSLsplit as  well.  In
     split  mode,  packets  are  not diverted to listening programs, effectively
     making SSLproxy behave similar to SSLsplit, but not exactly  like	it,  be-
     cause  SSLproxy has certain features non-existent in SSLsplit, such as user
     authentication, protocol validation, and filtering rules. Also,  note  that
     the  implementation of the proxy core in SSLproxy is different from the one
     in SSLsplit; for example, the proxy core in SSLproxy runs lockless, whereas
     SSLsplit implementation uses a thread manager level lock  (which  does  not
     necessarily  make	sslproxy  run  faster than sslsplit). In SSLproxy, split
     mode can be defined globally, per-proxyspec, or per-connection  using  fil-
     tering rules.

     SSLproxy  does not automagically redirect any network traffic.  To actually
     implement a proxy, you also need to redirect the traffic to the system run-
     ning sslproxy.  Your options  include  running  sslproxy  on  a  legitimate
     router,  ARP spoofing, ND spoofing, DNS poisoning, deploying a rogue access
     point (e.g. using hostap mode), physical recabling, malicious  VLAN  recon-
     figuration or route injection, /etc/hosts modification and so on.

     Proxy specifications
     SSLproxy  supports  three different types of proxy specifications, or prox-
     yspecs for short, which can be in divert or split style.

      - Command line proxyspecs passed on the command line
      - One line proxyspecs in configuration files
      - Structured proxyspecs in configuration files

     The syntax of command line proxyspecs is as follows:

     (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl)
       listenaddr listenport
       [up:divertport [ua:divertaddr ra:returnaddr]]
       [(targetaddr targetport|sni sniport|natengine)]

     The syntax of one line proxyspecs is the same as the syntax of command line
     proxyspecs, except for the leading ProxySpec keyword:

     ProxySpec (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl)
       listenaddr listenport
       [up:divertport [ua:divertaddr ra:returnaddr]]
       [(targetaddr targetport|sni sniport|natengine)]

     The syntax of structured proxyspecs is as follows, and they  can  configure
     connection options too:

     ProxySpec {
	 Proto (tcp|ssl|http|https|pop3|pop3s|smtp|smtps|autossl)
	 Addr listenaddr       # inline
	 Port listenport       # comments
	 DivertPort divertport # allowed
	 DivertAddr divertaddr
	 ReturnAddr returnaddr
	 TargetAddr targetaddr
	 TargetPort targetport
	 SNIPort sniport
	 NatEngine natengine

	 # Divert or split
	 Divert (yes|no)

	 # Connection options
	 Passthrough (yes|no)

	 DenyOCSP (yes|no)
	 CACert ca.crt
	 CAKey ca.key
	 ClientCert client.crt
	 ClientKey client.key
	 CAChain chain.crt
	 LeafCRLURL http://example.com/example.crl
	 DHGroupParams dh.pem
	 ECDHCurve prime256v1
	 SSLCompression (yes|no)
	 ForceSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 DisableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 EnableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 MinSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 MaxSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 Ciphers MEDIUM:HIGH
	 CipherSuites
     TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
	 VerifyPeer (yes|no)
	 AllowWrongHost (yes|no)

	 RemoveHTTPAcceptEncoding (yes|no)
	 RemoveHTTPReferer (yes|no)
	 MaxHTTPHeaderSize 8192
	 ValidateProto (yes|no)

	 UserAuth (yes|no)
	 UserTimeout 300
	 UserAuthURL https://192.168.0.1/userdblogin.php

	 # The DivertUsers, PassUsers, and PassSite options will be deprecated
	 DivertUsers userlist
	 PassUsers userlist
	 PassSite rules

	 Define $macro valuelist

	 (Divert|Split|Pass|Block|Match) one line filtering rules
	 FilterRule {...} structured filtering rules
     }

     For example, given the following command line proxyspec:

     https 127.0.0.1 8443 up:8080

      - SSLproxy listens for HTTPS connections on 127.0.0.1:8443.
      - Upon receiving a connection from the Client, it decrypts and diverts the
     packets  to  a  Program listening on 127.0.0.1:8080. The default divert ad-
     dress is 127.0.0.1, which can be configured by the ua option.
      - After processing the packets, the Program gives them  back  to	SSLproxy
     listening on a dynamically assigned address, which the Program obtains from
     the SSLproxy line in the first packet in the connection.
      - Then SSLproxy re-encrypts and sends the packets to the Server.

     The  response  from  the Server follows the same path back to the Client in
     reverse order.

     Split style proxyspecs configure for split mode  of  operation  similar  to
     SSLsplit.	See  the  SSLsplit  documentation for the details of split style
     proxyspecs.

     SSLproxy line
     Given the proxyspec example above, a sample line SSLproxy inserts into  the
     first packet in the connection may be the following:

     SSLproxy: [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s

      -  The  first IP:port pair is a dynamically assigned address that SSLproxy
     expects the program send the packets back to it.
      - The second and third IP:port pairs are the actual source and destination
     addresses of the connection, respectively. Since the program  receives  the
     packets  from  SSLproxy, it cannot determine the source and destination ad-
     dresses of the packets by itself, for example by  asking  the  NAT  engine,
     hence must rely on the information in the SSLproxy line.
      -  The  last letter is either s or p, for SSL/TLS encrypted or plain traf-
     fic, respectively. This information is also important for the program,  be-
     cause it cannot reliably determine if the actual network traffic it is pro-
     cessing was encrypted or not before being diverted to it.

     Listening programs
     The program that packets are diverted to should support this mode of opera-
     tion.  Specifically, it should be able to recognize the SSLproxy address in
     the  first  packet,  and give the first and subsequent packets back to SSL-
     proxy listening on that address, instead of sending them to their	original
     destination as it normally would.

     You can use any software as a listening program as long as it supports this
     mode of operation. So existing or new software developed in any programming
     language  can be modified to be used with SSLproxy to inspect and/or modify
     any or all parts of the packets diverted to it.

     Given the proxyspec example above, a program should be  listening	on  port
     8080.

     You  can  offload the system SSLproxy is running on by diverting packets to
     remote listening programs too. For example, given the following proxy spec-
     ification:

     https 127.0.0.1 8443 up:8080 ua:192.168.0.1 ra:192.168.1.1

      - The ua option instructs SSLproxy to divert packets to  192.168.0.1:8080,
     instead of 127.0.0.1:8080 as in the previous proxyspec example.
      - The ra option instructs SSLproxy to listen for returned packets from the
     program  on  192.168.1.1,	instead of 127.0.0.1 as in the previous SSLproxy
     line.

     Accordingly, the SSLproxy line now becomes (notice the first IP address):

     SSLproxy: [192.168.1.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s

     And a listening program should be running at address  192.168.0.1	on  port
     8080.

     So,  the  listening  program  can	be  running on a machine anywhere in the
     world.  Since the packets between SSLproxy and the  listening  program  are
     always unencrypted, you should be careful while using such a setup.

Protocols
     Supported protocols
     SSLproxy supports plain TCP, plain SSL, HTTP, HTTPS, POP3, POP3S, SMTP, and
     SMTPS  connections  over both IPv4 and IPv6. It also has the ability to dy-
     namically upgrade plain TCP to SSL in order  to  generically  support  SMTP
     STARTTLS  and  similar  upgrade  mechanisms.  Depending  on  the version of
     OpenSSL, SSLproxy supports SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3,
     and optionally SSL 2.0 as well. SSLproxy supports	Server	Name  Indication
     (SNI),  but  not Encrypted SNI in TLS 1.3. It is able to work with RSA, DSA
     and ECDSA keys and DHE and ECDHE cipher suites.

     The following features of SSLproxy are IPv4 only:

      - Divert addresses for listening programs in proxyspecs
      - SSLproxy return addresses dynamically assigned to connections
      - IP addresses in the ua and ra options
      - IP and ethernet addresses of clients in user authentication
      - Target IP and ethernet addresses in mirror logging

     OCSP, HPKP, HSTS, Upgrade et al.
     SSLproxy implements a number of defences  against	mechanisms  which  would
     normally  prevent	MitM  attacks  or make them more difficult. SSLproxy can
     deny OCSP requests in a generic way. For HTTP and HTTPS  connections,  SSL-
     proxy  mangles  headers  to  prevent  server-instructed  public key pinning
     (HPKP), avoid strict transport security restrictions (HSTS), avoid Certifi-
     cate  Transparency  enforcement  (Expect-CT)  and	prevent   switching   to
     QUIC/SPDY,  HTTP/2  or WebSockets (Upgrade, Alternate Protocols). HTTP com-
     pression, encodings and keep-alive are disabled to make the logs more read-
     able.

     Another reason to disable persistent connections is to reduce file descrip-
     tor usage. Accordingly, connections are closed if they remain  idle  for  a
     certain  period  of  time. The default timeout is 120 seconds, which can be
     configured by the ConnIdleTimeout option.

     Protocol validation
     Protocol validation makes sure the traffic handled by a proxyspec is  using
     the  protocol specified in that proxyspec. If a connection cannot pass pro-
     tocol validation, it is terminated. To enable protocol validation, the Val-
     idateProto option can be defined globally, per-proxyspec, or per-connection
     using filtering rules. This feature currently supports HTTP, POP3, and SMTP
     protocols.

     SSLproxy uses only client requests for  protocol  validation.  However,  it
     also  validates  SMTP responses until it starts processing the packets from
     the client. If there is no excessive fragmentation,  the  first  couple  of
     packets in the connection should be enough for validating protocols.

Certificates
     Certificate forging
     For  SSL  and HTTPS connections, SSLproxy generates and signs forged X509v3
     certificates on-the-fly, mimicking the original server  certificate's  sub-
     ject  DN,	subjectAltName extension and other characteristics. SSLproxy has
     the ability to use existing certificates of which the private key is avail-
     able, instead of generating forged ones. SSLproxy supports  NULL-prefix  CN
     certificates  but	otherwise  does  not implement exploits against specific
     certificate verification vulnerabilities in SSL/TLS stacks.

     Certificate verification
     SSLproxy verifies upstream certificates by  default.  If  the  verification
     fails,  the  connection  is  terminated immediately. This is in contrast to
     SSLsplit, because in order to maximize the chances that a connection can be
     successfully split, SSLsplit accepts all certificates by default, including
     self-signed ones. See the risks of SSL inspection for the reasons for  this
     difference.  You  can  enable or disable this feature by the VerifyPeer op-
     tion, which can be defined globally, per-proxyspec, or per-connection using
     filtering rules.

     Client certificates
     SSLproxy uses the certificate and key from the pemfiles configured  by  the
     ClientCert  and ClientKey options when the destination requests client cer-
     tificates. These options can be defined globally,	per-proxyspec,	or  per-
     connection using filtering rules.

     Alternatively,  you  can  use  Pass filtering rules to pass through certain
     destinations requesting client certificates.

User authentication
     If the UserAuth option is enabled, SSLproxy requires network users  to  log
     in to the system to establish connections to the external network.

     SSLproxy  determines  the user owner of a connection using a users table in
     an SQLite3 database configured by the UserDBPath option.  The  users  table
     should be created using the following SQL statement:

     CREATE TABLE USERS(
	IP	       CHAR(45)     PRIMARY KEY     NOT NULL,
	USER	       CHAR(31)     NOT NULL,
	ETHER	       CHAR(17)     NOT NULL,
	ATIME	       INT	    NOT NULL,
	DESC	       CHAR(50) );

     SSLproxy  does  not create this users table or the database file by itself,
     nor does it log users in or out. So the database file with the users  table
     should  already  exist at the location pointed to by the UserDBPath option.
     An external program should log users in and out on the users table. The ex-
     ternal program should fill out all the fields in user records, except  per-
     haps for the DESC field, which can be left blank.

     When SSLproxy accepts a connection,

      -  It searches the client IP address of the connection in the users table.
     If the client IP address is not in the users table, the connection is redi-
     rected to a login page configured by the UserAuthURL option.
      - If SSLproxy finds a user record for the client IP address in  the  users
     table,  it  obtains  the ethernet address of the client IP address from the
     arp cache of the system, and compares it with the value in the user  record
     for  that	IP address. If the client IP address is not in the arp cache, or
     the ethernet addresses do not match, the connection is  redirected  to  the
     login page.
      -  If  the  ethernet addresses match, SSLproxy compares the atime value in
     the user record with the current system time. If the difference is  greater
     than  the	value  configured  by  the UserTimeout option, the connection is
     redirected to the login page.

     If the connection passes all these checks, SSLproxy  proceeds  with  estab-
     lishing the connection.

     The  atime  of the IP address in the users table is updated with the system
     time while the connection is being terminated. Since this atime  update  is
     executed  using  a privsep command, it is expensive. So, to reduce the fre-
     quency of such updates, it is deferred until after the user  idle	time  is
     more than half of the timeout period.

     If  a  description  text is provided in the DESC field, it can be used with
     filtering rules to treat the user logged in from different locations,  i.e.
     from different client IP addresses, differently.

     If  the UserAuth option is enabled, the user owner of the connection is ap-
     pended at the end of the SSLproxy line, so that the listening  program  can
     parse and use this information in its logic and/or logging:

     SSLproxy:
     [127.0.0.1]:34649,[192.168.3.24]:47286,[192.168.111.130]:443,s,soner

     The user authentication feature is currently available on OpenBSD and Linux
     only.

Filtering rules
     SSLproxy can divert, split, pass, block, or match connections based on fil-
     tering rules. Filtering rules can be defined globally and/or per-proxyspec.

      - Divert action diverts packets to the listening program, allowing SSL in-
     spection by the listening program and content logging of packets
      -  Split	action	splits the connection but does not divert packets to the
     listening program, effectively disabling SSL inspection  by  the  listening
     program, but allowing content logging of packets
      -  Pass action passes the connection through by engaging passthrough mode,
     effectively disabling SSL inspection and content logging of packets
      - Block action terminates the connection
      - Match action specifies log actions and/or  connection  options	for  the
     connection without changing its filter action

     SSLproxy supports one line and structured filtering rules.

     The syntax of one line filtering rules is as follows:

     (Divert|Split|Pass|Block|Match)
      ([from (
	  user (username[*]|$macro|*) [desc (desc[*]|$macro|*)]|
	  desc (desc[*]|$macro|*)|
	  ip (clientip[*]|$macro|*)|
	  *)]
       [to (
	  (sni (servername[*]|$macro|*)|
	   cn (commonname[*]|$macro|*)|
	   host (host[*]|$macro|*)|
	   uri (uri[*]|$macro|*)|
	   ip (serverip[*]|$macro|*)) [port (serverport[*]|$macro|*)]|
	  port (serverport[*]|$macro|*)|
	  *)]
       [log ([[!]connect] [[!]master] [[!]cert]
	     [[!]content] [[!]pcap] [[!]mirror] [$macro]|[!]*)]
       |*) [# comment]

     The  syntax  of structured filtering rules is as follows, and they can con-
     figure connection options too:

     FilterRule {
	 Action (Divert|Split|Pass|Block|Match)

	 # From
	 User (username[*]|$macro|*)  # inline
	 Desc (desc[*]|$macro|*)      # comments
	 SrcIp (clientip[*]|$macro|*) # allowed

	 # To
	 SNI (servername[*]|$macro|*)
	 CN (commonname[*]|$macro|*)
	 Host (host[*]|$macro|*)
	 URI (uri[*]|$macro|*)
	 DstIp (serverip[*]|$macro|*)
	 DstPort (serverport[*]|$macro|*)

	 # Multiple Log lines allowed
	 Log ([[!]connect] [[!]master] [[!]cert]
	      [[!]content] [[!]pcap] [[!]mirror] [$macro]|[!]*)

	 ReconnectSSL (yes|no)

	 # Connection options
	 Passthrough (yes|no)

	 DenyOCSP (yes|no)
	 CACert ca.crt
	 CAKey ca.key
	 ClientCert client.crt
	 ClientKey client.key
	 CAChain chain.crt
	 LeafCRLURL http://example.com/example.crl
	 DHGroupParams dh.pem
	 ECDHCurve prime256v1
	 SSLCompression (yes|no)
	 ForceSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 DisableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 EnableSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 MinSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 MaxSSLProto (ssl2|ssl3|tls10|tls11|tls12|tls13)
	 Ciphers MEDIUM:HIGH
	 CipherSuites
     TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
	 VerifyPeer (yes|no)
	 AllowWrongHost (yes|no)

	 RemoveHTTPAcceptEncoding (yes|no)
	 RemoveHTTPReferer (yes|no)
	 MaxHTTPHeaderSize 8192
	 ValidateProto (yes|no)

	 UserAuth (yes|no)
	 UserTimeout 300
	 UserAuthURL https://192.168.0.1/userdblogin.php
     }

     The specification of which connections a filtering rule will be applied  to
     is achieved by the from and to parts of the filtering rule and by the prox-
     yspec that the rule is defined for.

      -  The  from  part  of a rule defines source filter based on client IP ad-
     dress, user and/or description, or * for all.
      - The to part defines destination filter based on server IP  and/or  port,
     SNI  or Common Names of SSL connections, Host or URI fields in HTTP Request
     headers, or * for all.
	 + Dst Host type of rules use the ip site field
	 + SSL type of rules use the sni or cn site field
	 + HTTP type of rules use the host or uri site field
	 + All rule types can use the port field
      - The proxyspec handling the connection defines the  protocol  filter  for
     the connection.

     If  and how a connection should be logged is specified using the log or Log
     part of one line or structured filtering rules, respectively:

      - connect enables logging connection information to connect log file
      - master enables logging of master keys
      - cert enables logging of generated certificates
      - content enables logging packet contents to content log file
      - pcap enables writing packets to pcap file
      - mirror enables mirroring packets to mirror interface or target

     You can add a negation prefix ! to a log action to disable that logging.

     Structured filtering rules can also specify connection options to be selec-
     tively applied to matching connections, not just globally or per-proxyspec.
     One line filtering rules cannot specify connection options.

     For example, if the following rules are defined in a structured HTTPS prox-
     yspec,

      Split from user soner desc notebook to sni example.com log content
      Pass from user soner desc android to cn .fbcdn.net*

     The first filtering rule above splits but does not divert HTTPS connections
     from the user soner who has logged in with the description notebook to  SSL
     sites with the SNI of example.com. Also, the rule specifies that the packet
     contents  of the matching connection be written to content log file config-
     ured globally.

     The second rule passes through HTTPS connections from the	user  soner  who
     has  logged  in  with  the description android to SSL sites with the Common
     Names containing the substring .fbcdn.net anywhere in it (notice the aster-
     isk at the end). Since connection contents cannot be written to  log  files
     in passthrough mode, the rule does not specify any content log action.

     The  default  filter  action is Divert. So, if those are the only filtering
     rules in that proxyspec, the other connections are diverted to the  listen-
     ing program specified in that proxyspec, without writing any logs.

     If  you want to enable, say, connect logging for the other connections han-
     dled by that proxyspec, without changing their default  Divert  filter  ac-
     tion, you can add a third filtering rule to that proxyspec:

      Match * log connect

     Note  that  the second example above is a filtering rule you can use to re-
     solve one of the certificate issues preventing the Facebook application  on
     Android smartphones to connect to the Internet from behind sslproxy.

     Filtering rules are applied based on certain precedence orders:

      -  More  specific  rules have higher precedence. Log actions increase rule
     precedence too.
      - The precedence of filter types is as HTTP > SSL > Dst Host. Because, the
     application order of filter types is as Dst Host > SSL > HTTP, and a filter
     type can override the actions of a preceding filter type.
      - The precedence of filter actions is as Divert > Split >  Pass  >  Block.
     This is only for the same type of filtering rules.
      -  The  precedence of site fields is as sni > cn for SSL filter and host >
     uri for HTTP filter.

     For example, the pass action of a Dst Host filter rule is taken before  the
     split  action  of	an SSL filter rule with the same from definition, due to
     the precedence order of filter types. Or, the pass action of  a  rule  with
     sni  site	field  is taken before the split action of the same rule with cn
     site field, due to the precedence order of site fields.

     Pass and Block filter actions are deferred until the last moment  they  can
     be  applied  to  a  connection, so that Divert and Split filter actions can
     override them.

     In terms of possible filter actions,

      - Dst Host filtering rules can take all of the filter and log actions.
      - SSL filtering rules can take all of the filter and log actions.
      - HTTP filtering rules can take match and block filter actions,  can  keep
     enabled  divert  and  split  modes, but cannot take pass action. Also, HTTP
     filtering rules can only disable logging.

     Log actions do not configure any loggers. Global loggers for respective log
     actions should have been configured for those log actions to have	any  ef-
     fect.

     If no filtering rules are defined for a proxyspec, all log actions for that
     proxyspec are enabled. Otherwise, all log actions are disabled, and filter-
     ing rules should enable them specifically.

     To  increase  rule reuse, one or more of SNI, CN, Host, URI, and DstIp site
     fields can be specified in the same structured filtering rule.

     Connection options specified in a structured filtering rule  can  have  any
     effect  only  if the rule matches the connection before global or proxyspec
     connection options are applied. Otherwise, the global or proxyspec  connec-
     tion  options  already  applied  to a connection cannot be overriden by the
     connection options specified in the matching structured filtering rule. For
     example, SSL options of a connection cannot be changed after the  SSL  con-
     nection  is  established.	So, normally SSL type of rules cannot modify SSL
     options of a connection, but you can use the ReconnectSSL option to  recon-
     nect the server side of an SSL connection to enforce the SSL options in the
     SSL type of filtering rules. In other words, the ReconnectSSL option allows
     for  using  the SNI and CN fields in stuctured filtering rules to match SSL
     connections and change their SSL configuration.

     Macro expansion is supported. The Define option can be  used  for	defining
     macros to be used in filtering rules. Macro names must start with a $ sign.
     The macro name must be followed by words separated by spaces.

     You can append an asterisk * to the fields in filtering rules for substring
     matching.	Otherwise, the filter searches for an exact match with the field
     in the rule. The filter uses B-trees for exact  string  matching  and  Aho-
     Corasick machines for substring matching.

     The ordering of filtering rules is important. The ordering of from, to, and
     log parts of one line filtering rules is not important. The ordering of log
     actions is not important.

     If the UserAuth option is disabled, only client IP addresses can be used in
     the from part of filtering rules.

     Excluding sites from SSL inspection
     PassSite  option  is  a special form of Pass filtering rule. PassSite rules
     can be written as Pass filtering rules. The PassSite option will be  depre-
     cated in favor of filtering rules in the future.

     PassSite  option  allows  certain SSL sites to be excluded from SSL inspec-
     tion.  If a PassSite rule matches the SNI or Common Names in the  SSL  cer-
     tificate  of a connection, the connection is passed through the proxy with-
     out  being  diverted  to  the  listening  program.  SSLproxy  engages   the
     Passthrough  mode for that purpose. For example, sites requiring client au-
     thentication can be added as PassSite rules.

     Per-site filters can be defined using client IP addresses, users,	and  de-
     scription. If the UserAuth option is disabled, only client IP addresses can
     be  used  in  PassSite  filters. Multiple sites can be defined, one on each
     line.  PassSite rules can search for exact or substring matches, but do not
     support macro expansion.

     User control lists
     User control lists can be implemented using  filtering  rules.  The  Diver-
     tUsers and PassUsers options will be deprecated in favor of filtering rules
     in the future.

     DivertUsers  and  PassUsers options can be used to divert, pass through, or
     block users.

      - If neither DivertUsers nor PassUsers is defined, all users are	diverted
     to listening programs.
      -  Connections from users in DivertUsers, if defined, are diverted to lis-
     tening programs.
      - Connections from users in  PassUsers,  if  defined,  are  simply  passed
     through  to  their  original destinations. SSLproxy engages the Passthrough
     mode for that purpose.
      - If both DivertUsers and PassUsers are defined, users not listed  in  ei-
     ther  of  the  lists  are blocked. SSLproxy simply terminates their connec-
     tions.
      - If *no* DivertUsers list is defined, only users  *not*	listed	in  Pas-
     sUsers are diverted to listening programs.

     These  user  control  lists  can be defined globally or per-proxyspec. User
     control lists do not support macro expansion.

Logging
     Logging options include connect and content log files as well as PCAP files
     and mirroring decrypted traffic to a network interface. Additionally,  cer-
     tificates,  master  secrets  and  local  process information can be logged.
     Filtering rules can selectively modify connection logging.

OPTIONS
     -a pemfile
	    Use client certificate from pemfile when destination server requests
	    a client certificate.

     -A pemfile
	    Use private key, certificate and certificate  chain  from  PEM  file
	    pemfile as leaf certificate instead of generating a leaf certificate
	    on	the fly.  The PEM file must contain a single private key, a sin-
	    gle certificate and optionally intermediate and root CA certificates
	    to use as certificate chain.  When using -t, SSLproxy will first at-
	    tempt to use a matching certificate loaded from certdir.  If  -t  is
	    also  used and a connection matches any certificate in the directory
	    specified with the -t option, that matching certificate is used  in-
	    stead, taking precedence over the certificate specified with -A.

     -b pemfile
	    Use client private key from pemfile when destination server requests
	    a client certificate.

     -B proto
	    Enable  the SSL/TLS protocol version proto on both client and server
	    side by enabling the respective protocols  in  OpenSSL.   To  enable
	    multiple protocol versions, -B can be given multiple times. This op-
	    tion can be used to enable any proto disabled before. Otherwise, all
	    available  protocols  are  enabled by default. See the -R option for
	    further details.

     -c pemfile
	    Use CA certificate from pemfile to sign certificates forged  on-the-
	    fly.   If  pemfile	also contains the matching CA private key, it is
	    also loaded, otherwise it must be provided with -k.  If pemfile also
	    contains Diffie-Hellman group parameters, they are also loaded, oth-
	    erwise they can be provided with -g.  If -t is also given,	SSLproxy
	    will only forge a certificate if there is no matching certificate in
	    the provided certificate directory.

     -C pemfile
	    Use  CA  certificates from pemfile as extra certificates in the cer-
	    tificate chain.  This is needed if the CA given with -k and -c is  a
	    sub-CA,  in which case any intermediate CA certificates and the root
	    CA certificate must be included in the certificate chain.

     -d     Detach from TTY and run as a daemon, logging error messages to  sys-
	    log instead of standard error.

     -D level
	    Run in debug mode, log lots of debugging information to standard er-
	    ror.   This  also forces foreground mode and cannot be used with -d.
	    Debug level can be a number from 1 to 4,  a  higher  number  meaning
	    more verbosity.

     -e engine
	    Use engine as the default NAT engine for proxyspecs without explicit
	    NAT  engine,  static destination address or SNI mode.  engine can be
	    any of the NAT engines supported by the system, as returned by -E.

     -E     List all supported NAT engines available on  the  system  and  exit.
	    See  NAT  ENGINES  for  a list of NAT engines currently supported by
	    SSLproxy.

     -f conffile
	    Read configuration from conffile. Configuration files  can	use  the
	    Include  option  for loading configuration from an include file too.
	    Note that the ordering of options, rules, and proxyspecs in configu-
	    ration files (and on the command line) is  important.  For	example,
	    rules  and	proxyspecs can only make use of the options defined ear-
	    lier.

     -F logspec
	    Log connection content to separate log files  with	the  given  path
	    specification  (see LOG SPECIFICATIONS below).  For each connection,
	    a log file will be written, which will contain  both  directions  of
	    data  as transmitted.  Information about the connection will be con-
	    tained in the filename only.  Only one of -F, -L and -S may be  used
	    (last one wins).

     -g pemfile
	    Use  Diffie-Hellman  group	parameters  from  pemfile for Ephemereal
	    Diffie-Hellman (EDH/DHE) cipher suites.  If -g is  not  given,  SSL-
	    proxy  first tries to load DH parameters from the PEM files given by
	    -K, -k or -c.  If no DH parameters	are  found  in	the  key  files,
	    built-in  group parameters are automatically used.	The -g option is
	    only available if SSLproxy was built against a  version  of  OpenSSL
	    which supports Diffie-Hellman cipher suites.

     -G curve
	    Use  the  named  curve  for Ephemereal Elliptic Curve Diffie-Hellman
	    (ECDHE) cipher  suites.   If  -G  is  not  given,  a  default  curve
	    (prime256v1) is used automatically.  The -G option is only available
	    if	SSLproxy  was  built against a version of OpenSSL which supports
	    Elliptic Curve Diffie-Hellman cipher suites.

     -h     Display help on usage and exit.

     -i     For each connection, find the local process owning	the  connection.
	    This  makes  process  information  such as pid, owner:group and exe-
	    cutable path for connections originating on the same system as  SSL-
	    proxy  available  to  the  connect log and enables the respective -F
	    path specification directives.  -i is available  on  Mac  OS  X  and
	    FreeBSD; support for other platforms has not been implemented yet.

     -I if  Mirror  connection	content as emulated packets to interface if with
	    destination address given by -T.  This option is  not  available  if
	    SSLproxy  was built without mirroring support. If -T is omitted, the
	    packets are blindly pushed to if.

     -j jaildir
	    Change the root directory to jaildir using chroot(2)  after  opening
	    files.  Note that this has implications for sni proxyspecs.  Depend-
	    ing  on  your  operating system, you will need to copy files such as
	    /etc/resolv.conf to jaildir in order for name  resolution  to  work.
	    Using  sni	proxyspecs  depends  on name resolution.  Some operating
	    systems require special device nodes such as /dev/null to be present
	    within the jail.  Check your system's documentation for details.

     -J     Enable connection statistics logging.

     -k pemfile
	    Use CA private key from pemfile to sign certificates forged  on-the-
	    fly.   If  pemfile	also contains the matching CA certificate, it is
	    also loaded, otherwise it must be provided with -c.  If pemfile also
	    contains Diffie-Hellman group parameters, they are also loaded, oth-
	    erwise they can be provided with -g.  If -t is also given,	SSLproxy
	    will only forge a certificate if there is no matching certificate in
	    the provided certificate directory.

     -K pemfile
	    Use  private  key  from pemfile for the leaf certificates forged on-
	    the-fly.  If -K is	not  given,  SSLproxy  will  generate  a  random
	    2048-bit RSA key.

     -l logfile
	    Log  connections  to logfile in a single line per connection format,
	    including addresses and ports and some HTTP and SSL information,  if
	    available.	SIGHUP or SIGUSR1 will cause logfile to be re-opened.

     -L logfile
	    Log  connection  content to logfile.  The content log will contain a
	    parsable log format with transmitted data,	prepended  with  headers
	    identifying  the  connection and the data length of each logged seg-
	    ment.  SIGHUP or SIGUSR1 will cause logfile to be  re-opened.   Only
	    one of -F, -L and -S may be used (last one wins).

     -m     When dropping privileges using -u, override the target primary group
	    to be set to group.

     -M logfile
	    Log  master  keys  to  logfile in SSLKEYLOGFILE format as defined by
	    Mozilla.  Logging master keys in this format allows  for  decryption
	    of	SSL/TLS  traffic using Wireshark.  Note that unlike browsers im-
	    plementing this feature, setting the SSLKEYLOGFILE environment vari-
	    able has no effect on SSLproxy.  SIGHUP or SIGUSR1 will  cause  log-
	    file to be re-opened.

     -O     Deny  all  Online Certificate Status Protocol (OCSP) requests on all
	    proxyspecs and for all OCSP servers with an OCSP  response	of  try-
	    Later,  causing OCSP clients to temporarily accept even revoked cer-
	    tificates.	HTTP requests are being treated as OCSP requests if  the
	    method is GET and the URI contains a syntactically valid OCSPRequest
	    ASN.1  structure  parsable	by OpenSSL, or if the method is POST and
	    the Content-Type is application/ocsp-request.  For this to be effec-
	    tive, SSLproxy must be handling traffic destined to the port used by
	    the OCSP server.  In particular, SSLproxy must be configured to  re-
	    ceive traffic to all ports used by OCSP servers of targeted certifi-
	    cates within the certdir specified by -t.

     -p pidfile
	    Write  the process ID to pidfile and refuse to run if the pidfile is
	    already in use by another process.

     -P     Passthrough SSL/TLS connections which cannot  be  split  instead  of
	    dropping  them.   Connections  cannot  be split if -c and -k are not
	    given and the site does not match any certificate loaded  using  -t,
	    or	if  the  connection to the original server gives SSL/TLS errors.
	    Specifically, this happens if the site requests  a	client	certifi-
	    cate.   In these situations, passthrough with -P results in uninter-
	    rupted service for the clients, while dropping is  the  more  secure
	    alternative   if   unmonitored   connections   must   be  prevented.
	    Passthrough mode currently does not apply to SSL/TLS errors  in  the
	    connection	from  the  client,  since the connection from the client
	    cannot easily be retried.  Specifically, -P does not currently  work
	    for clients that do not accept forged certificates.

     -Q     Quit after loading and testing configuration.

     -q crlurl
	    Set CRL distribution point (CDP) crlurl on forged leaf certificates.
	    Some  clients,  such  as some .NET applications, reject certificates
	    that do not carry a CDP.  When using -q, you will need  to	generate
	    an	empty  CRL signed by the CA certificate and key provided with -c
	    and -k, and make it available at crlurl.

     -r proto
	    Force SSL/TLS protocol version on both client  and	server	side  to
	    proto by selecting the respective OpenSSL method constructor instead
	    of the default SSLv23_method() which supports all protocol versions.
	    This is useful when analyzing traffic to a server that only supports
	    a specific version of SSL/TLS and does not implement proper protocol
	    negotiation.   Depending on build options and the version of OpenSSL
	    that is used, the following values for  proto  are	accepted:  ssl2,
	    ssl3,  tls10, tls11, tls12, and tls13.  Note that SSL 2.0 support is
	    not built in by default because some servers don't	handle	SSL  2.0
	    Client Hello messages gracefully.

     -R proto
	    Disable the SSL/TLS protocol version proto on both client and server
	    side  by  disabling the respective protocols in OpenSSL.  To disable
	    multiple protocol versions, -R can be given multiple times.   If  -r
	    is	also  given, there will be no effect in disabling other protocol
	    versions.  Disabling protocol  versions  is  useful  when  analyzing
	    traffic  to  a  server  that  does not handle some protocol versions
	    well, or to test behaviour with different  protocol  versions.   De-
	    pending  on  build	options and the version of OpenSSL that is used,
	    the following values for proto  are  accepted:  ssl2,  ssl3,  tls10,
	    tls11,  tls12, and tls13.  Note that SSL 2.0 support is not built in
	    by default because some servers don't handle SSL  2.0  Client  Hello
	    messages gracefully.

     -s ciphers
	    Use OpenSSL ciphers specification for both server and client SSL/TLS
	    connections.   If  -s  is  not given, a cipher list of ALL:-aNULL is
	    used.  Normally, SSL/TLS implementations choose the most secure  ci-
	    pher  suites,  not	the  fastest ones.  By specifying an appropriate
	    OpenSSL cipher list, the set of cipher suites can be limited to fast
	    algorithms, or eNULL cipher suites can be added.  Note that for con-
	    nections to be successful, the SSLproxy cipher suites  must  include
	    at	least  one  cipher  suite  supported  by both the client and the
	    server of each connection.	See ciphers(1) for  details  on  how  to
	    construct OpenSSL cipher lists.

     -S logdir
	    Log connection content to separate log files under logdir.	For each
	    connection,  a log file will be written, which will contain both di-
	    rections of data as transmitted.  Information about  the  connection
	    will  be  contained in the filename only.  Only one of -F, -L and -S
	    may be used (last one wins).

     -t certdir
	    Use private key, certificate and certificate chain from PEM files in
	    certdir for connections to hostnames matching  the	respective  cer-
	    tificates,	instead of using certificates forged on-the-fly.  A sin-
	    gle PEM file must contain a single private key, a single certificate
	    and optionally intermediate and root CA certificates to use as  cer-
	    tificate chain.  When using -t, SSLproxy will first attempt to use a
	    matching  certificate  loaded  from  certdir.  If -c and -k are also
	    given, certificates will be forged	on-the-fly  for  sites	matching
	    none  of  the  common names in the certificates loaded from certdir.
	    Otherwise, connections matching no certificate will be  dropped,  or
	    if -P is given, passed through without splitting SSL/TLS.

     -T addr
	    Mirror connection content as emulated packets to destination address
	    addr  on  the interface given by -I.  Only IPv4 target addresses are
	    currently supported. Also, only targets with  ethernet  address  as-
	    signed  can  be used with this option; for example, the loopback ad-
	    dress 127.0.0.1 cannot be used as target address. Not  used  if  the
	    target  is	irrelevant (e.g. mirror to dummy device). This option is
	    not available if SSLproxy was built without mirroring support.

     -u user
	    Drop privileges after opening sockets and files by setting the real,
	    effective and stored user IDs to user and  loading	the  appropriate
	    primary  and  ancillary  groups.   If -u is not given, SSLproxy will
	    drop privileges to the stored UID if EUID != UID  (setuid  bit  sce-
	    nario),  or  to nobody if running with full root privileges (EUID ==
	    UID == 0).	User user needs to be allowed to make outbound TCP  con-
	    nections,  and  in	some configurations, to also perform DNS resolu-
	    tion.  Dropping privileges enables privilege separation,  which  in-
	    curs  latency  for	certain options, such as separate per-connection
	    log files.	By using -u root, SSLproxy can be run  as  root  without
	    dropping privileges.  Due to an Apple bug, -u cannot be used with pf
	    proxyspecs on Mac OS X.

     -x engine
	    Use  the  OpenSSL engine with identifier engine as a default engine.
	    The engine must be available within the OpenSSL ecosystem under  the
	    specified  identifier,  that is, they must be loaded from the global
	    OpenSSL configuration.  If engine is an absolute path,  it	will  be
	    interpreted  as  path  to  an  engine dynamically linked library and
	    loaded by path, regardless of global  OpenSSL  configuration.   This
	    option  is only available if built against a version of OpenSSL with
	    engine support.

     -X pcapfile
	    Log connection content to pcapfile in  PCAP  format,  with	emulated
	    TCP, IP and Ethernet headers.  SIGHUP or SIGUSR1 will cause pcapfile
	    to	be  re-opened.	 Only one of -X, -Y and -y may be used (last one
	    wins).

     -Y pcapdir
	    Log connection content to separate PCAP files  under  pcapdir.   For
	    each  connection, a separate PCAP file will be written.  Only one of
	    -X, -Y and -y may be used (last one wins).

     -y pcapspec
	    Log connection content to separate PCAP files with	the  given  path
	    specification  (see LOG SPECIFICATIONS below).  For each connection,
	    a separate PCAP file will be written.  Only one of -X, -Y and -y may
	    be used (last one wins).

     -n     Enable split mode of operation for all proxyspecs, effectively  mak-
	    ing sslproxy behave like sslsplit.

     -V     Display version and compiled features information and exit.

     -w gendir
	    Write generated keys and certificates to individual files in gendir.
	    For  keys, the key identifier is used as filename, which consists of
	    the SHA-1 hash of the ASN.1 bit string of the public key, as  refer-
	    enced  by  the  subjectKeyIdentifier extension in certificates.  For
	    certificates, the SHA-1 fingerprints of the original  and  the  used
	    (forged)  certificate  are combined to form the filename.  Note that
	    only newly generated certificates are written to disk.

     -W gendir
	    Same as -w, but also write original  certificates  and  certificates
	    not newly generated, such as those loaded from -t.

     -Z     Disable  SSL/TLS  compression on all connections.  This is useful if
	    your limiting factor is CPU, not network bandwidth.  The  -Z  option
	    is only available if SSLproxy was built against a version of OpenSSL
	    which supports disabling compression.

PROXY SPECIFICATIONS
     SSLproxy  supports  two  types of proxy specifications: one line and struc-
     tured.  The structured proxy specifications provide more configuration  op-
     tions, but can only be defined in configuration files. See sslproxy.conf(5)
     and the sample configuration file in the sources for details.

     One  line proxy specifications (proxyspecs) consist of the connection type,
     listen address and program port. You can also specify  program  and  return
     addresses,  otherwise  they  default to the loopback address 127.0.0.1. The
     program and return address options help you divert packets to remote  loca-
     tions. However, beware that the diverted traffic is always unencrypted:

     https listenaddr port up:port
     https listenaddr port up:port ua:addr ra:addr
     pop3s listenaddr port up:port
     smtps listenaddr port up:port
     ssl   listenaddr port up:port
     http  listenaddr port up:port
     pop3  listenaddr port up:port
     smtp  listenaddr port up:port
     tcp   listenaddr port up:port

     https  SSL/TLS  interception with HTTP protocol decoding, including the re-
	    moval of HPKP, HSTS, Upgrade and Alternate Protocol  response  head-
	    ers.  This mode currently suppresses WebSockets and HTTP/2.

     pop3s  SSL/TLS interception with POP3 protocol decoding.

     smtps  SSL/TLS interception with SMTP protocol decoding.

     ssl    SSL/TLS  interception without any lower level protocol decoding; de-
	    crypted connection content is treated as opaque stream of bytes  and
	    not modified.

     http   Plain  TCP	connection without SSL/TLS, with HTTP protocol decoding,
	    including the removal of HPKP, HSTS, Upgrade and Alternate	Protocol
	    response  headers.	 This  mode  currently suppresses WebSockets and
	    HTTP/2.

     pop3   Plain POP3 connection without SSL/TLS and with POP3 protocol  decod-
	    ing.

     smtp   Plain  SMTP connection without SSL/TLS and with SMTP protocol decod-
	    ing.

     tcp    Plain TCP connection without SSL/TLS and  without  any  lower  level
	    protocol decoding; decrypted connection content is treated as opaque
	    stream of bytes and not modified.

     autossl
	    Plain TCP connection until a Client Hello SSL/TLS message appears in
	    the  byte  stream,	then  automatic upgrade to SSL/TLS interception.
	    This is generic, protocol-independent STARTTLS support, that may er-
	    roneously trigger on byte sequences that look like Client Hello mes-
	    sages even though there was no actual STARTTLS command issued.

     listenaddr port
	    IPv4 or IPv6 address and port or service name to listen on.  This is
	    the address and port where the NAT engine  should  redirect  connec-
	    tions to.

     up:port
	    Port  or service name that the program is listening for connections.
	    This is the port where the traffic should be diverted to.

     ua:addr
	    Address that the program is listening for connections.  This is  the
	    address  where the traffic should be diverted to.  If not specified,
	    defaults to 127.0.0.1.

     ra:addr
	    Address that the program should return packets to.	This is the  ad-
	    dress where SSLproxy is listening for returned packets from the pro-
	    gram.   This address is inserted into the SSLproxy header line along
	    with the dynamically assigned port number.	If  not  specified,  de-
	    faults to 127.0.0.1.

LOG SPECIFICATIONS
     Log  specifications  are  composed of zero or more printf-style directives;
     ordinary characters are included directly in  the	output	path.	SSLproxy
     current supports the following directives:

     %T     The initial connection time as an ISO 8601 UTC timestamp.

     %d     The  destination host and port, separated by a comma, IPv6 addresses
	    using underscore instead of colon.

     %D     The destination host, IPv6 addresses  using  underscore  instead  of
	    colon.

     %p     The destination port.

     %s     The source host and port, separated by a comma, IPv6 addresses using
	    underscore instead of colon.

     %S     The source host, IPv6 addresses using underscore instead of colon.

     %q     The source port.

     %x     The  name of the local process.  Requires -i to be used.  If process
	    information is unavailable, this directive will be omitted from  the
	    output path.

     %X     The  full  path  of  the local process.  Requires -i to be used.  If
	    process information is unavailable, this directive will  be  omitted
	    from the output path.

     %u     The username or numeric uid of the local process.  Requires -i to be
	    used.  If process information is unavailable, this directive will be
	    omitted from the output path.

     %g     The  group name or numeric gid of the local process.  Requires -i to
	    be used.  If process information is unavailable, this directive will
	    be omitted from the output path.

     %%     A literal '%' character.

NAT ENGINES
     SSLproxy currently supports the following NAT engines:

     pf     OpenBSD packet filter (pf) rdr/rdr-to NAT redirects, also  available
	    on	FreeBSD,  NetBSD and Mac OS X.	Fully supported, including IPv6.
	    Note that SSLproxy needs permission to  open  /dev/pf  for	reading,
	    which  by  default means that it needs to run under root privileges.
	    Assuming inbound interface em0, first in old (FreeBSD,  Mac  OS  X),
	    then in new (OpenBSD 4.7+) syntax:

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

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

     ipfw   FreeBSD  IP firewall (IPFW) divert sockets, also available on Mac OS
	    X.	Available on FreeBSD and OpenBSD using pf divert-to.  Fully sup-
	    ported on FreeBSD and OpenBSD, including IPv6.  Only  supports  IPv4
	    on	Mac  OS X due to the ancient version of IPFW included.	First in
	    IPFW, then in pf divert-to syntax:

	    ipfw add fwd       ::1,10080 tcp from 2001:db8::/64 to any	80
	    ipfw add fwd       ::1,10443 tcp from 2001:db8::/64 to any 443
	    ipfw add fwd 127.0.0.1,10080 tcp from 192.0.2.0/24	to any	80
	    ipfw add fwd 127.0.0.1,10443 tcp from 192.0.2.0/24	to any 443

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

     ipfilter
	    IPFilter (ipfilter,  ipf),	available  on  many  systems,  including
	    FreeBSD,  NetBSD,  Linux and Solaris.  Note that SSLproxy needs per-
	    mission to open /dev/ipnat for reading, which by default means  that
	    it	needs  to  run under root privileges.  Only supports IPv4 due to
	    limitations in the SIOCGNATL ioctl(2) interface.   Assuming  inbound
	    interface bge0:

	    rdr bge0 0.0.0.0/0 port  80 -> 127.0.0.1 port 10080
	    rdr bge0 0.0.0.0/0 port 443 -> 127.0.0.1 port 10443

     netfilter
	    Linux netfilter using the iptables REDIRECT target.  Fully supported
	    including  IPv6 since Linux v3.8-rc1; on older kernels only supports
	    IPv4 due to limitations in the SO_ORIGINAL_DST getsockopt(2)  inter-
	    face.

	    iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
		     -p tcp --dport  80 \
		     -j REDIRECT --to-ports 10080
	    iptables -t nat -A PREROUTING -s 192.0.2.0/24 \
		     -p tcp --dport 443 \
		     -j REDIRECT --to-ports 10443
	    # please contribute a tested ip6tables config

	    Note that SSLproxy is only able to accept incoming connections if it
	    binds  to  the  correct IP address (e.g. 192.0.2.1) or on all inter-
	    faces (0.0.0.0).  REDIRECT uses the local interface address  of  the
	    incoming  interface  as  target IP address, or 127.0.0.1 for locally
	    generated packets.

     tproxy
	    Linux netfilter using the iptables TPROXY target together with rout-
	    ing table magic to allow non-local traffic	to  originate  on  local
	    sockets.  Fully supported, including IPv6.

	    ip -f inet6 rule add fwmark 1 lookup 100
	    ip -f inet6 route add local default dev lo table 100
	    ip6tables -t mangle -N DIVERT
	    ip6tables -t mangle -A DIVERT -j MARK --set-mark 1
	    ip6tables -t mangle -A DIVERT -j ACCEPT
	    ip6tables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
	    ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
		      -p tcp --dport 80 \
		      -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
	    ip6tables -t mangle -A PREROUTING -s 2001:db8::/64 \
		      -p tcp --dport 443 \
		      -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443
	    ip -f inet rule add fwmark 1 lookup 100
	    ip -f inet route add local default dev lo table 100
	    iptables -t mangle -N DIVERT
	    iptables -t mangle -A DIVERT -j MARK --set-mark 1
	    iptables -t mangle -A DIVERT -j ACCEPT
	    iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
	    iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
		     -p tcp --dport 80 \
		     -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10080
	    iptables -t mangle -A PREROUTING -s 192.0.2.0/24 \
		     -p tcp --dport 443 \
		     -j TPROXY --tproxy-mark 0x1/0x1 --on-port 10443

	    Note  that	return	path filtering (rp_filter) also needs to be dis-
	    abled on interfaces which handle TPROXY redirected traffic.

SIGNALS
     A running sslproxy accepts SIGINT and SIGTERM for a clean shutdown and  SI-
     GUSR1  to	re-open  the single-file log files (such as -l, -L and -X).  The
     canonical way to rotate or post-process logs is to rename	the  active  log
     file,  send  SIGUSR1  to the PID in the PID file given by -p, give SSLproxy
     some time to flush buffers after closing  the  old  file,	and  then  post-
     process the renamed log file.  Per-connection log files (such as -S and -F)
     are not re-opened because their filename is specific to the connection.

EXIT STATUS
     The  sslproxy  process  will  exit  with  0  on  regular  shutdown (SIGINT,
     SIGTERM), and 128 + signal number on controlled shutdown based on receiving
     a different signal such as SIGHUP.  Exit status in the range  1..127  indi-
     cates error conditions.

EXAMPLES
     With configuration similar to the above NAT engine samples, intercept HTTPS
     and  POP3S  over  IPv4 using forged certificates with CA private key ca.key
     and certificate ca.crt, logging connections to connect.log  and  connection
     data into separate files under /tmp (add -e nat-engine to select the appro-
     priate engine if multiple engines are available on your system) and divert-
     ing  packets  to  a  program running on address 127.0.0.1 and port 8080 for
     HTTPS and to another program running on address 127.0.0.1 and port 8110 for
     POP3S:

     sslproxy -k ca.key -c ca.crt -l connect.log -L /tmp \
	      https 127.0.0.1 8443 up:8080 \
	      pop3s 127.0.0.1 8995 up:8110

     To generate a CA private key ca.key  and certificate ca.crt using OpenSSL:

     cat >x509v3ca.cnf <<'EOF'
     [ req ]
     distinguished_name = reqdn

     [ reqdn ]

     [ v3_ca ]
     basicConstraints	     = CA:TRUE
     subjectKeyIdentifier    = hash
     authorityKeyIdentifier  = keyid:always,issuer:always
     EOF

     openssl genrsa -out ca.key 2048
     openssl req -new -nodes -x509 -sha256 -out ca.crt -key ca.key \
	     -config x509v3ca.cnf -extensions v3_ca \
	     -subj '/O=SSLproxy Root CA/CN=SSLproxy Root CA/' \
	     -set_serial 0 -days 3650

NOTES
     SSLproxy is able to handle a relatively high number of listeners  and  con-
     nections  due  to	a  multithreaded,  event  based  architecture  based  on
     libevent, taking advantage of platform specific select() replacements  such
     as  kqueue.   The	main thread handles the listeners and signaling, while a
     number of worker threads equal to twice the number of CPU cores is used for
     handling the actual connections in separate event bases, including the CPU-
     intensive SSL/TLS handling.

     Care has been taken to choose well-performing data structures  for  caching
     certificates  and	SSL  sessions.	 Logging is implemented in separate disk
     writer threads to ensure that socket event handling threads don't	have  to
     block  on	disk  I/O.   DNS lookups are performed asynchronously.	SSLproxy
     uses SSL session caching on both ends to minimize the amount  of  full  SSL
     handshakes,  but even then, the limiting factor in handling SSL connections
     are the actual bignum computations.

     For high performance and low latency and when running SSLproxy as	root  or
     otherwise in a privilege separation mode, avoid using options which require
     a	privileged operation to be invoked through privilege separation for each
     connection.  These are currently all per-connection log types: content  log
     to  per-stream  file in dir or filespec (-F, -S), content log to per-stream
     PCAP in dir or filespec (-Y, -y), and  generated  or  all	certificates  to
     files in directory (-w, -W).  Instead, use the respective single-file vari-
     ants  where  available.   It is possible, albeit not recommended, to bypass
     the default privilege separation when run as root by using -u root, thereby
     bypassing privilege separation entirely.

SEE ALSO
     sslproxy.conf(5), openssl(1), ciphers(1), speed(1), pf(4),  ipfw(8),  ipta-
     bles(8),	ip6tables(8),	ip(8),	hostapd(8),  arpspoof(8),  parasite6(8),
     yersinia(8), https://www.roe.ch/SSLsplit, https://github.com/sonertari/SSL-
     proxy

AUTHORS
     SSLsplit was written by Daniel Roethlisberger <daniel@roe.ch>.  SSLsplit is
     currently maintained by Daniel Roethlisberger and Soner Tari.

     SSLproxy has been developed by Soner Tari <sonertari@gmail.com>.

     The following  individuals  have  contributed  code  or  documentation,  in
     chronological  order  of  their  first  contribution:  Steve  Wills, Landon
     Fuller, Wayne Jensen, Rory McNamara, Alexander Neumann, Adam Jacob  Muller,
     Richard  Poole, Maciej Kotowicz, Eun Soo Park, Christian Groschupp, Alexan-
     der Savchenkov, Soner Tari, Petr Vanek, Hilko Bengen, Philip  Duldig,  Lev-
     ente Polyak, Nick French and Cihan Komecoglu.

     SSLsplit contains work sponsored by HackerOne.

BUGS
     Use Github for submission of bug reports or patches:

	    https://github.com/droe/sslsplit

	    https://github.com/sonertari/sslproxy

v0.9.9				   09 Nov 2025			     sslproxy(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sslproxy&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help