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

FreeBSD Manual Pages

  
 
  

home | help
TITUS(8)			 Titus Manual			      TITUS(8)

NAME
       titus - totally isolated	TLS unwrapping server

SYNOPSIS
       titus [ --option-name option-value ... ]

DESCRIPTION
       titus  is  a highly secure network proxy	that terminates	TLS (SSL) con-
       nections	and forwards the unencrypted traffic to	some backend.

       titus provides heightened security by  running  in  extreme  isolation.
       The  private  key is stored in a	dedicated process that doesn't talk to
       the network, and	all private key	operations take	place in this process.
       Furthermore,  every connection is handled by a new process that runs as
       an unprivileged user in an unwritable and empty root directory.	 These
       security	 features  ensure  that	if there is a vulnerability in the TLS
       processing code,	it is very, very unlikely that an attacker could steal
       your  private  key,  access  the	memory of your application, sniff data
       from other TLS connections, or otherwise	attack your system.

       titus aims to be	as transparent as possible to the backend application.
       Changes	to  the	 connection state between the client and titus are re-
       flected in the connection between titus	and  the  backend,  and	 vice-
       versa.  This allows the backend to dictate throttling behavior, maximum
       connection behavior, and	so on.

       On Linux, titus can operate in  transparent  proxy  mode	 so  that  the
       client  IP  address is preserved	when contacting	the backend.  This re-
       quires special configuration with iptables and  advanced	 routing  (see
       TRANSPARENT PROXY MODE below).

       titus  supports	the  Elliptic Curve Diffie-Hellman handshake, and also
       provides	advanced control over TLS settings, such as the	Diffie-Hellman
       modulus,	and the	curve used for Elliptic	Curve Diffie-Hellman.  This is
       handy if	your backend's built-in	TLS support is lacking.

OPTIONS
       Options can be specified	either on the command line or in a  configura-
       tion file.  When	specified on the command line, the syntax is --option-
       name option-value.  When	specified in a configuration file, the	syntax
       is option-name option-value, with one option per	line.

       The following options are supported:

       config filename
	      Load  additional configuration options from filename, where each
	      line corresponds to one command line option, but with the	 lead-
	      ing  '--'	 removed.  Blank lines and lines starting with '#' are
	      ignored.

	      Config files can recursively include other config	files via  the
	      config option.

       config-directory	path
	      Load  additional	configuration  files from path.	 Configuration
	      files are	loaded in lexicographical order.  Hidden files are ig-
	      nored.

       daemon yes | no
	      If  set  to  "yes,"  daemonize after initialization is complete.
	      Defaults to "no."

       pid-file	filename
	      After daemonizing, write PID to filename.

       port port
	      Listen on	the given TCP port.

       transparent yes | no | backend-only
	      (Linux only) Run titus in	transparent proxy mode.	 In this mode,
	      titus  preserves	both the destination and source	addresses when
	      proxying connections, allowing your backend to see the  client's
	      actual  IP address instead of the	IP address of the titus	proxy.
	      This requires special configuration with iptables	 and  advanced
	      routing (see TRANSPARENT PROXY MODE below).

	      Specify backend-only to use a transparent	socket only when talk-
	      ing to the backend, and not when talking to  the	client.	  This
	      preserves	 the  source address, but not the destination address,
	      so you'll	still need to specify the backend and backend-port op-
	      tions.

       backend host

       backend-port port
	      Connect to the backend on	the given host and port.  Not applica-
	      ble if transparent is set	to "yes" (in which  case  the  backend
	      address is taken from the	destination address of the TCP connec-
	      tion).

       min-spare-children number
	      Keep at least number child processes on standby ready to	accept
	      new connections.

       max-children number
	      Run  at  most  number  child processes at	a given	time.  This is
	      equivalent to the	number of concurrent connections you can  ser-
	      vice at a	time.

       max-handshake-time seconds
	      Terminate	 the connection	if the TLS handshake takes longer than
	      seconds seconds.

       network-user username

       network-group groupname
	      Run the processes	that talk to the network as the	given user and
	      group.  For best security, you should use	a user account that is
	      not used for any other purpose.

       keyserver-user username

       keyserver-group groupname
	      Run the processes	that perform private  key  operations  as  the
	      given  user and group.  For best security, you should use	a dif-
	      ferent user account from network-user.

       chroot path
	      Run titus	in the given chroot.  path should be an	 empty	direc-
	      tory  that  is  not writable by any of the users that titus runs
	      as.  This	option only works if you start titus as	root.

       key filename
	      Use the private key stored in filename.

       cert filename
	      Use the certificate stored in filename.	Intermediate  certifi-
	      cate authority (aka chain) certificates should be	placed in this
	      file following your certificate.

       ciphers list
	      Use the given OpenSSL cipher list.  See ciphers(1SSL) for	a  de-
	      scription	 of the	syntax.	 The default cipher list is the	Inter-
	      mediate Compatibility list from Mozilla's	Server Side TLS	guide,
	      as  of 2014-12-09.  This cipher list provides excellent security
	      for recent browsers, and acceptable security for older browsers.

       honor-client-cipher-order yes | no
	      If set to	"yes," the client dictates which cipher,  among	 those
	      listed  in the ciphers option, is	used.  If set to "no," earlier
	      ciphers listed in	the ciphers option are preferred.  Defaults to
	      "no."

       dhgroup id
	      Use  the	given  Diffie-Hellman  group  (from  RFC3526)  for the
	      Diffie-Hellman  handshake.   Supported  groups  are  "14"	 (2048
	      bits),  "15"  (3072 bits), and "16" (4096	bits).	The default is
	      group 14.

       ecdhcurve name
	      Use the given curve for the Elliptic Curve Diffie-Hellman	 hand-
	      shake.  The curve	must be	supported by OpenSSL (run 'openssl ec-
	      param -list_curves' for a	list) and be listed in	Section	 5.1.1
	      of  RFC  4492.   As  of 2014, only "prime256v1" (NIST P-256) and
	      "secp384r1" (NIST	P-384) are widely supported by web browsers.

	      The default is "prime256v1", which is a  good  choice  for  most
	      people.

	      Note:  elliptic  curve  names  are poorly	standardized.  For in-
	      stance, the curve	called "prime256v1" by OpenSSL	is  listed  as
	      "secp256r1" in RFC 4492.

       compression yes | no
	      Enable/disable  TLS  compression,	 which is off by default.  Use
	      extreme caution before enabling TLS compression, as it  can  en-
	      able  side  channel  attacks such	as CRIME.  Generally, TLS com-
	      pression is safe only when  an  attacker	cannot	inject	chosen
	      plaintext	 into  the  connection.	  Never	enable TLS compression
	      when proxying HTTPS, since the browser security model  makes  it
	      trivial to inject	chosen plaintext.

       sslv3 yes | no
	      Enable/disable  support  for  SSLv3,  which  is  off by default.
	      SSLv3 is insecure	and should  not	 be  enabled.	Unfortunately,
	      some  older  clients (notably, IE6) do not support anything bet-
	      ter.

       tlsv1 yes | no
	      Enable/disable support for TLSv1,	which is on by default.	 TLSv1
	      has  security issues, though they	are mostly mitigated in	recent
	      TLS implementations.  As of 2014,	many clients still do not sup-
	      port  anything  better  than TLSv1, so you should	not disable it
	      unless you do not	need to	support	these clients.

       tlsv1.1 yes | no
	      Enable/disable support for TLSv1.1, which	is on by default.

       tlsv1.2 yes | no
	      Enable/disable support for TLSv1.2, which	is on by default.

VIRTUAL	HOSTS
       Virtual hosts let you configure different settings depending on the lo-
       cal  address  of	 the connection	and the	server name sent by the	client
       (aka SNI).

       A virtual host declaration begins with the single  word	"vhost"	 on  a
       line  by	 itself	in the config file.  Options for that virtual host are
       specified on the	following lines, as described above,  prefixed	by  at
       least one whitespace character (tab or space).  The virtual host	decla-
       ration continues	until the first	option	that  is  not  prefixed	 by  a
       space.  Virtual hosts cannot be specified by command line arguments.

       The following options can be specified for a virtual host:

       local-address host
	      Use  this	 virtual  host	if the local address of	the connection
	      matches host.  If	this  option  is  omitted,  the	 virtual  host
	      matches any local	address.

       local-port port
	      Use this virtual host if the local port number of	the connection
	      matches port.  If	this  option  is  omitted,  the	 virtual  host
	      matches any local	port.

       sni-name	name
	      Use  this	 virtual host if the TLS server	name (aka SNI) sent by
	      the client matches name.	To match a client that does not	send a
	      server name (such	as an older web	browser), specify a literal ""
	      for name.	 If this option	is omitted, the	virtual	 host  matches
	      any server name.

       Virtual hosts are consulted in the order	they are specified in the con-
       figuration file,	and the	first matching virtual host, as	determined  by
       the above options, is used.  If no virtual host matches,	the connection
       is dropped.  If this is undesirable, you	can specify a virtual host  at
       the end of your config that matches any local address and SNI name.

       The following options, described	above, can be configured on a per-vir-
       tual host basis.	 If an option is not specified,	 its  value  from  the
       main part of the	configuration is used instead.

       key filename

       cert filename

       backend host

       backend-port port

       ciphers list

       honor-client-cipher-order yes | no

       dhgroup id

       ecdhcurve name

       compression yes | no

       sslv3 yes | no

       tlsv1 yes | no

       tlsv1.1 yes | no

       tlsv1.2 yes | no

TRANSPARENT PROXY MODE
       To  be written.	For now, set "transparent yes" and follow the instruc-
       tions at	https://www.kernel.org/doc/Documentation/networking/tproxy.txt

AUTHOR
       Andrew Ayer <agwa@andrewayer.name>

SEE ALSO
       openssl(1SSL), ciphers(1SSL), genrsa(1SSL), req(1SSL)

Andrew Ayer			  2015-11-28			      TITUS(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | VIRTUAL HOSTS | TRANSPARENT PROXY MODE | AUTHOR | SEE ALSO

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

home | help