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,	TLS  1.2,  and
       TLS 1.3,	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 greater 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  system  time  while	the connection is being	terminated. Since this
       atime update 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.

       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 Di-
       vertUsers,  if defined, are diverted to listening programs. Connections
       from users in PassUsers,	if defined, are	simply passed through to their
       original	destinations. Users not	listed in DivertUsers or PassUsers are
       blocked.	If no DivertUsers list is defined, only	users  not  listed  in
       PassUsers  are  diverted	to listening programs. These user lists	can be
       defined globally	or per-proxyspec.

       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.  -A pemfile Use private key, cer-
	      tificate 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  single  cer-
	      tificate and optionally intermediate and root CA certificates to
	      use as certificate chain.	 When using -t,	 SSLproxy  will	 first
	      attempt  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 certifi-
	      cate is used instead, taking  precedence	over  the  certificate
	      specified	with -A.

       -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. If	-T  is
	      omitted, the packets are blindly pushed to if.

       -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,	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  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,	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 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.8.2			       14 December 2020			   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&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help