TITUS(8) Titus Manual TITUS(8)NAMEtitus - totally isolated TLS unwrapping server
SYNOPSIStitus [ --option-name option-value ... ]
DESCRIPTIONtitus 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
reflected 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
requires 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
ignored.
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
options.
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
description of the syntax. The default cipher list is the
Intermediate 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
ecparam -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
instance, 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
enable 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
local 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 ALSOopenssl(1SSL), ciphers(1SSL), genrsa(1SSL), req(1SSL)Andrew Ayer 2015-11-28 TITUS(8)
