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 net-
       work traffic to other programs for deep SSL inspection

SYNOPSIS
       sslproxy	[-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab] -c pem proxyspecs [...]
       sslproxy	[-kCKqwWOPZdDgGsrRxeumjplLSFXYyTIMiab] -c pem -t dir prox-
       yspecs [...]
       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
       intended	to be used for decrypting and  diverting  network  traffic  to
       other programs, such as UTM services.

       SSLproxy	 is  designed  to transparently	terminate connections that are
       redirected to it	using a	network	address	translation engine.   SSLproxy
       then  terminates	 SSL/TLS and initiates a new SSL/TLS connection	to the
       original	destination address. Packets received on the client  side  are
       decrypted  and  sent  to	 a  program listening on the 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 order.

       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  con-
       nection	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.

       The  program  that  packets are diverted	to should support this mode of
       operation.  Specifically, it should be able to recognize	 the  SSLproxy
       address	in the first packet, and give the first	and subsequent packets
       back to SSLproxy	listening on that address, instead of sending them  to
       the  original destination as it normally	would. For an example, see the
       lp program under	the extra folder in the	sources.

       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 dynamically upgrade plain TCP	to SSL in order	to generically support
       SMTP  STARTTLS and similar upgrade mechanisms.  SSLproxy	fully supports
       Server Name Indication (SNI) and	is able	to  work  with	RSA,  DSA  and
       ECDSA  keys  and	DHE and	ECDHE cipher suites.  Depending	on the version
       of OpenSSL, SSLproxy supports SSL 3.0, TLS 1.0, TLS 1.1	and  TLS  1.2,
       and optionally SSL 2.0 as well.

       For  SSL/TLS  connections,  SSLproxy  generates and signs forged	X509v3
       certificates on-the-fly,	mimicking the  original	 server	 certificate's
       subject	DN,  subjectAltName extension and other	characteristics.  SSL-
       proxy has the ability to	use existing certificates of which the private
       key is available, 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.

       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  connec-
       tions, SSLproxy mangles headers to prevent server-instructed public key
       pinning (HPKP), avoid strict transport  security	 restrictions  (HSTS),
       avoid  Certificate  Transparency	 enforcement  (Expect-CT)  and prevent
       switching to QUIC/SPDY, HTTP/2 or WebSockets (Upgrade, Alternate	Proto-
       cols).  HTTP compression, encodings and keep-alive are disabled to make
       the logs	more readable.

       Another reason to disable persistent connections	is to reduce file  de-
       scriptor	usage. Accordingly, connections	are closed if they remain idle
       for a certain period of time. The default timeout is 120	seconds, which
       can be changed in configuration file.

       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  de-
       fault, including	self-signed ones.

       If enabled, the UserAuth	option requires	network	users to log in	to the
       system to use SSLproxy (this feature is currently available on  OpenBSD
       and  Linux  only). When users are logged	in, they should	be recorded on
       the users table in an SQLite3 database. SSLproxy	does not  create  this
       users  table by itself, so it should already exist in the SQLite3 data-
       base file 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) );

       When  SSLproxy accepts a	connection, it obtains the ethernet address of
       the client IP address from the arp cache	of the system,	then  compares
       it  with	the value in the users table. If the ethernet addresses	do not
       match, the connection is	redirected to the login	 page.	SSLproxy  also
       compares	 the  atime  value  in the users table with the	current	system
       time. If	the difference is larger than the configured value of the user
       timeout	option,	 then  the connection is redirected to the login page.
       The atime of the	IP address in the users	table is updated with the sys-
       tem time	while the connection is	being terminated. Since	this atime up-
       date is run using a privsep command, it is expensive. So, to reduce the
       frequency  of  such updates, it is deferred until the user idle time is
       more than half of the timeout period.

       If enabled, the ValidateProto option validates protocols	in proxy spec-
       ifications. If a	connection cannot pass protocol	validation, then it is
       terminated. This	feature	currently supports HTTP, POP3, and SMTP	proto-
       cols.

       PassSite	 option	 allows	 certain SSL sites to be excluded from SSL in-
       spection.  If a PassSite	matches	SNI or common names in	the  SSL  cer-
       tificate,  the connection is passed through the proxy without being di-
       verted to the listening program.	For example,  sites  requiring	client
       authentication  can  be	added as PassSite. Per site filters can	be de-
       fined using client IP addresses,	users, and description keywords.  Mul-
       tiple sites can be defined, one on each line.

       Logging	options	 include  traditional SSLproxy connect and content log
       files as	well as	PCAP files and mirroring decrypted traffic to  a  net-
       work  interface.	  Additionally,	certificates, master secrets and local
       process information can be logged.

       SSLproxy	does not automagically redirect	any network traffic.  To actu-
       ally  implement	a  proxy, you also need	to redirect the	traffic	to the
       system running 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,  ma-
       licious	VLAN  reconfiguration or route injection, /etc/hosts modifica-
       tion and	so on.

       As SSLproxy is based on SSLsplit, this is a modified SSLsplit man page.

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

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

       -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, otherwise 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
	      certificate  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
	      syslog instead of	standard error.

       -D level
	      Run in debug mode, log lots of debugging information to standard
	      error.  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  ex-
	      plicit  NAT engine, static destination address or	SNI mode.  en-
	      gine 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.

       -F logspec
	      Log connection content to	separate log files with	the given path
	      specification (see LOG SPECIFICATIONS below).  For each  connec-
	      tion, a log file will be written,	which will contain both	direc-
	      tions 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).

       -g pemfile
	      Use Diffie-Hellman group parameters from pemfile for  Ephemereal
	      Diffie-Hellman  (EDH/DHE)	 cipher	 suites.   If -g is not	given,
	      SSLproxy 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  connec-
	      tion.   This  makes process information such as pid, owner:group
	      and executable path for connections originating on the same sys-
	      tem as SSLproxy available	to the connect log and enables the re-
	      spective -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	avail-
	      able if SSLproxy was built without mirroring support.

       -j jaildir
	      Change the root directory	to jaildir using chroot(2) after open-
	      ing  files.  Note	that this has implications for sni proxyspecs.
	      Depending	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  documenta-
	      tion 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,  otherwise 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 for-
	      mat, including addresses and ports and some HTTP and SSL	infor-
	      mation,  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  segment.	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  decryp-
	      tion  of	SSL/TLS	 traffic  using	 Wireshark.   Note that	unlike
	      browsers implementing this feature,  setting  the	 SSLKEYLOGFILE
	      environment  variable  has no effect on SSLproxy.	 SIGHUP	or SI-
	      GUSR1 will cause logfile 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
	      tryLater,	causing	OCSP clients to	temporarily  accept  even  re-
	      voked certificates.  HTTP	requests are being treated as OCSP re-
	      quests 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 effective,	SSLproxy must be handling traffic des-
	      tined to the port	used by	the OCSP server.  In particular,  SSL-
	      proxy must be configured to receive traffic to all ports used by
	      OCSP servers of targeted certificates within the certdir	speci-
	      fied 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  certificate.   In	 these situations, passthrough with -P
	      results in uninterrupted service for the clients,	while dropping
	      is  the  more secure alternative if unmonitored connections must
	      be prevented.  Passthrough mode  currently  does	not  apply  to
	      SSL/TLS errors in	the connection from the	client,	since the con-
	      nection from the client cannot easily be retried.	 Specifically,
	      -P does not currently work for clients that do not accept	forged
	      certificates.

       -q crlurl
	      Set CRL distribution point (CDP) crlurl on forged	leaf  certifi-
	      cates.   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 in-
	      stead 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 op-
	      tions and	the version of OpenSSL that  is	 used,	the  following
	      values  for  proto  are  accepted:  ssl2,	ssl3, tls10, tls11 and
	      tls12.  Note that	SSL 2.0	support	is not built in	by default be-
	      cause  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 dis-
	      abling other protocol versions.  Disabling protocol versions  is
	      useful  when  analyzing traffic to a server that does not	handle
	      some protocol versions well, or to test behaviour	with different
	      protocol	versions.   Depending on build options and the version
	      of OpenSSL that is used, the following values for	proto are  ac-
	      cepted:  ssl2,  ssl3, tls10, tls11 and tls12.  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 cipher suites, not the fastest ones.  By	speci-
	      fying  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 connections 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  directions	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  re-
	      spective	certificates, instead of using certificates forged on-
	      the-fly.	A single PEM file must contain a single	private	key, a
	      single  certificate and optionally intermediate and root CA cer-
	      tificates	to use as certificate 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 ad-
	      dress  addr  on the interface given by -I.  Only IPv4 target ad-
	      dresses are currently supported.	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  ap-
	      propriate	 primary  and  ancillary  groups.  If -u is not	given,
	      SSLproxy will drop privileges to the stored UID if EUID  !=  UID
	      (setuid  bit  scenario),	or to nobody if	running	with full root
	      privileges (EUID == UID == 0).  User user	needs to be allowed to
	      make  outbound  TCP  connections,	and in some configurations, to
	      also perform DNS resolution.  Dropping privileges	enables	privi-
	      lege  separation,	which incurs latency for certain options, such
	      as separate per-connection log files.  By	using  -u  root,  SSL-
	      proxy 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  en-
	      gine.  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).

       -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 referenced by the	subjectKeyIdentifier extension in cer-
	      tificates.   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  certifi-
	      cates 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
       structured.   The structured proxy specifications provide more configu-
       ration options, 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 pack-
       ets to remote locations.	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
	      removal of HPKP, HSTS, Upgrade and Alternate  Protocol  response
	      headers.	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;
	      decrypted	connection content is  treated	as  opaque  stream  of
	      bytes and	not modified.

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

       pop3   Plain POP3 connection without SSL/TLS and	with POP3 protocol de-
	      coding.

       smtp   Plain SMTP connection without SSL/TLS and	with SMTP protocol de-
	      coding.

       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  ap-
	      pears  in	the byte stream, then automatic	upgrade	to SSL/TLS in-
	      terception.  This	is generic, protocol-independent STARTTLS sup-
	      port,  that  may erroneously trigger on byte sequences that look
	      like Client Hello	messages  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	 redi-
	      rect connections to.

       up:port
	      Port  or	service	name that the program is listening for connec-
	      tions.  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
	      address where SSLproxy is	listening for  returned	 packets  from
	      the  program.  This address is inserted into the SSLproxy	header
	      line along with the dynamically assigned port  number.   If  not
	      specified, defaults to 127.0.0.1.

LOG SPECIFICATIONS
       Log  specifications  are	 composed  of zero or more printf-style	direc-
       tives; 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 ad-
	      dresses 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 omit-
	      ted 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 omit-
	      ted 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	direc-
	      tive 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	direc-
	      tive 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	avail-
	      able on FreeBSD, NetBSD and Mac OS X.  Fully supported,  includ-
	      ing  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 supported on FreeBSD and OpenBSD,  including  IPv6.	  Only
	      supports IPv4 on Mac OS X	due to the ancient version of IPFW in-
	      cluded.  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
	      permission 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 sup-
	      ported including IPv6 since Linux	 v3.8-rc1;  on	older  kernels
	      only  supports  IPv4  due	 to limitations	in the SO_ORIGINAL_DST
	      getsockopt(2) interface.

	      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
	      interfaces (0.0.0.0).  REDIRECT uses the local interface address
	      of the incoming interface	as target IP address, or 127.0.0.1 for
	      locally generated	packets.

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

	      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
	      disabled on interfaces which handle TPROXY redirected traffic.

SIGNALS
       A  running sslproxy accepts SIGINT and SIGTERM for a clean shutdown and
       SIGUSR1 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 ac-
       tive 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 spe-
       cific 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 re-
       ceiving a different signal such as SIGHUP.  Exit	status	in  the	 range
       1..127 indicates	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 appropriate engine if	multiple engines are available on your
       system) and diverting 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
       connections due to a multithreaded, event based architecture  based  on
       libevent,  taking  advantage of platform	specific select() replacements
       such as kqueue.	The main thread	handles	the listeners  and  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 sepa-
       rate  disk  writer threads to ensure that socket	event handling threads
       don't have to block on disk  I/O.   DNS	lookups	 are  performed	 asyn-
       chronously.  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 separa-
       tion for	each connection.  These	are currently all  per-connection  log
       types: content log to per-stream	file in	dir or filespec	(-F, -S), con-
       tent 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 variants where available.	 It is	possible,  al-
       beit  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),
       iptables(8),  ip6tables(8),  ip(8),  hostapd(8),	  arpspoof(8),	 para-
       site6(8),	   yersinia(8),		  https://www.roe.ch/SSLsplit,
       https://github.com/sonertari/SSLproxy

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, Alexander Savchenkov,	Soner Tari, Petr Vanek,	Hilko  Bengen,
       Philip Duldig, Levente 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.7.0				  22 Jul 2019			   sslproxy(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PROXY SPECIFICATIONS | LOG SPECIFICATIONS | NAT ENGINES | SIGNALS | EXIT STATUS | EXAMPLES | NOTES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sslproxy&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help