This repository has been archived by the owner on Mar 1, 2021. It is now read-only.
/
titus.8
228 lines (224 loc) · 10.3 KB
/
titus.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
.TH "TITUS" "8" "2015-11-28" "" "Titus Manual"
.SH "NAME"
.LP
titus \- totally isolated TLS unwrapping server
.SH "SYNOPSIS"
.LP
\fBtitus\fR [ \fB\-\-\fIoption-name\fR\fB \fIoption-value\fR ... ]
.SH "DESCRIPTION"
.LP
\fBtitus\fR is a highly secure network proxy that terminates TLS (SSL) connections
and forwards the unencrypted traffic to some backend.
.LP
\fBtitus\fR 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.
.LP
\fBtitus\fR aims to be as transparent as possible to the backend application.
Changes to the connection state between the client and \fBtitus\fR are reflected
in the connection between \fBtitus\fR and the backend, and vice-versa.
This allows the backend to dictate throttling behavior, maximum connection behavior,
and so on.
.LP
On Linux, \fBtitus\fR 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).
.LP
\fBtitus\fR 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.
.SH "OPTIONS"
Options can be specified either on the command line or in a configuration
file. When specified on the command line, the syntax is \fB\-\-\fIoption-name\fR\fB \fIoption-value\fR.
When specified in a configuration file, the syntax is \fB\fIoption-name\fR\fB \fIoption-value\fR,
with one option per line.
.LP
The following options are supported:
.TP
.BI config \ \fIfilename\fR
Load additional configuration options from \fIfilename\fR, where each line corresponds
to one command line option, but with the leading '--' removed. Blank lines and lines
starting with '#' are ignored.
Config files can recursively include other config files via the \fBconfig\fR option.
.TP
.BI config-directory \ \fIpath\fR
Load additional configuration files from \fIpath\fR. Configuration files
are loaded in lexicographical order. Hidden files are ignored.
.TP
.BI daemon \ \fByes\fR\ |\ \fBno\fR
If set to "yes," daemonize after initialization is complete. Defaults to "no."
.TP
.BI pid-file \ \fIfilename\fR
After daemonizing, write PID to \fIfilename\fR.
.TP
.BI port \ \fIport\fR
Listen on the given TCP port.
.TP
.BI transparent \ \fByes\fR\ |\ \fBno\fR\ |\ \fBbackend-only\fR
(Linux only) Run \fBtitus\fR in transparent proxy mode. In this mode, \fBtitus\fR 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 \fBtitus\fR proxy.
This requires special configuration with iptables and advanced routing (see TRANSPARENT PROXY MODE below).
Specify \fBbackend-only\fR to use a transparent socket only when talking 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 \fBbackend\fR and \fBbackend-port\fR options.
.TP
.BI backend \ \fIhost\fR
.TP
.BI backend-port \ \fIport\fR
Connect to the backend on the given \fIhost\fR and \fIport\fR. Not applicable if \fBtransparent\fR is set to "yes"
(in which case the backend address is taken from the destination address of the TCP connection).
.TP
.BI min-spare-children \ \fInumber\fR
Keep at least \fInumber\fR child processes on standby ready to accept new connections.
.TP
.BI max-children \ \fInumber\fR
Run at most \fInumber\fR child processes at a given time. This is equivalent to the number of concurrent
connections you can service at a time.
.TP
.BI max-handshake-time \ \fIseconds\fR
Terminate the connection if the TLS handshake takes longer than \fIseconds\fR seconds.
.TP
.BI network-user \ \fIusername\fR
.TP
.BI network-group \ \fIgroupname\fR
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.
.TP
.BI keyserver-user \ \fIusername\fR
.TP
.BI keyserver-group \ \fIgroupname\fR
Run the processes that perform private key operations as the given user and group. For best security,
you should use a different user account from \fBnetwork-user\fR.
.TP
.BI chroot \ \fIpath\fR
Run titus in the given chroot. \fIpath\fR should be an empty directory that is not writable
by any of the users that titus runs as. This option only works if you start \fBtitus\fR as root.
.TP
.BI key \ \fIfilename\fR
Use the private key stored in \fIfilename\fR.
.TP
.BI cert \ \fIfilename\fR
Use the certificate stored in \fIfilename\fR. Intermediate certificate authority (aka chain) certificates
should be placed in this file following your certificate.
.TP
.BI ciphers \ \fIlist\fR
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.
.TP
.BI honor-client-cipher-order \ \fByes\fR\ |\ \fBno\fR
If set to "yes," the client dictates which cipher, among those listed in the \fBciphers\fR option,
is used. If set to "no," earlier ciphers listed in the \fBciphers\fR option are preferred. Defaults to "no."
.TP
.BI dhgroup \ \fIid\fR
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.
.TP
.BI ecdhcurve \ \fIname\fR
Use the given curve for the Elliptic Curve Diffie-Hellman handshake. 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.
.TP
.BI compression \ \fByes\fR\ |\ \fBno\fR
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 compression
is safe only when an attacker cannot inject chosen plaintext into the connection.
\fBNever enable TLS compression when proxying HTTPS\fR, since the browser security model makes
it trivial to inject chosen plaintext.
.TP
.BI sslv3 \ \fByes\fR\ |\ \fBno\fR
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 better.
.TP
.BI tlsv1 \ \fByes\fR\ |\ \fBno\fR
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 support anything
better than TLSv1, so you should not disable it unless you
do not need to support these clients.
.TP
.BI tlsv1.1 \ \fByes\fR\ |\ \fBno\fR
Enable/disable support for TLSv1.1, which is on by default.
.TP
.BI tlsv1.2 \ \fByes\fR\ |\ \fBno\fR
Enable/disable support for TLSv1.2, which is on by default.
.SH "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).
.LP
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
declaration continues until the first option that is not prefixed by a space.
Virtual hosts cannot be specified by command line arguments.
.LP
The following options can be specified for a virtual host:
.TP
.BI local-address \ \fIhost\fR
Use this virtual host if the local address of the connection matches
\fIhost\fR. If this option is omitted, the virtual host matches any
local address.
.TP
.BI local-port \ \fIport\fR
Use this virtual host if the local port number of the connection matches
\fIport\fR. If this option is omitted, the virtual host matches any
local port.
.TP
.BI sni-name \ \fIname\fR
Use this virtual host if the TLS server name (aka SNI) sent by the client matches \fIname\fR.
To match a client that does not send a server name (such as an older web browser), specify a literal
\fB""\fR for \fIname\fR. If this option is omitted, the virtual host matches any server name.
.LP
Virtual hosts are consulted in the order they are specified in the configuration 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.
.LP
The following options, described above, can be configured on a per-virtual host basis. If an option is not specified,
its value from the main part of the configuration is used instead.
.TP
.BI key \ \fIfilename\fR
.TP
.BI cert \ \fIfilename\fR
.TP
.BI backend \ \fIhost\fR
.TP
.BI backend-port \ \fIport\fR
.TP
.BI ciphers \ \fIlist\fR
.TP
.BI honor-client-cipher-order \ \fByes\fR\ |\ \fBno\fR
.TP
.BI dhgroup \ \fIid\fR
.TP
.BI ecdhcurve \ \fIname\fR
.TP
.BI compression \ \fByes\fR\ |\ \fBno\fR
.TP
.BI sslv3 \ \fByes\fR\ |\ \fBno\fR
.TP
.BI tlsv1 \ \fByes\fR\ |\ \fBno\fR
.TP
.BI tlsv1.1 \ \fByes\fR\ |\ \fBno\fR
.TP
.BI tlsv1.2 \ \fByes\fR\ |\ \fBno\fR
.SH "TRANSPARENT PROXY MODE"
To be written. For now, set "transparent yes" and follow the instructions
at https://www.kernel.org/doc/Documentation/networking/tproxy.txt
.SH "SEE ALSO"
.LP
openssl(1SSL), ciphers(1SSL), genrsa(1SSL), req(1SSL)