1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
1 |
.TH TLSPROXY 8 |
2 |
.ad
|
|
3 |
.fi
|
|
4 |
.SH NAME |
|
5 |
tlsproxy |
|
6 |
\-
|
|
7 |
Postfix TLS proxy |
|
8 |
.SH "SYNOPSIS" |
|
9 |
.na
|
|
10 |
.nf
|
|
11 |
\fBtlsproxy\fR [generic Postfix daemon options] |
|
12 |
.SH DESCRIPTION |
|
13 |
.ad
|
|
14 |
.fi
|
|
15 |
The \fBtlsproxy\fR(8) server implements a server-side TLS |
|
16 |
proxy. It is used by \fBpostscreen\fR(8) to talk SMTP-over-TLS |
|
1.1.38
by LaMont Jones
Import upstream version 2.10.0 |
17 |
with remote SMTP clients that are not whitelisted (including |
18 |
clients whose whitelist status has expired), |
|
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
19 |
but it should also work for non-SMTP protocols. |
20 |
||
21 |
Although one \fBtlsproxy\fR(8) process can serve multiple |
|
22 |
sessions at the same time, it is a good idea to allow the |
|
23 |
number of processes to increase with load, so that the |
|
24 |
service remains responsive. |
|
25 |
.SH "PROTOCOL EXAMPLE" |
|
26 |
.na
|
|
27 |
.nf
|
|
28 |
.ad
|
|
29 |
.fi
|
|
30 |
The example below concerns \fBpostscreen\fR(8). However, |
|
31 |
the \fBtlsproxy\fR(8) server is agnostic of the application |
|
32 |
protocol, and the example is easily adapted to other |
|
33 |
applications. |
|
34 |
||
1.1.38
by LaMont Jones
Import upstream version 2.10.0 |
35 |
After receiving a valid remote SMTP client STARTTLS command, |
36 |
the \fBpostscreen\fR(8) server sends the remote SMTP client |
|
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
37 |
endpoint string, the requested role (server), and the |
38 |
requested timeout to \fBtlsproxy\fR(8). \fBpostscreen\fR(8) |
|
39 |
then receives a "TLS available" indication from \fBtlsproxy\fR(8). |
|
40 |
If the TLS service is available, \fBpostscreen\fR(8) sends |
|
41 |
the remote SMTP client file descriptor to \fBtlsproxy\fR(8), |
|
42 |
and sends the plaintext 220 greeting to the remote SMTP |
|
43 |
client. This triggers TLS negotiations between the remote |
|
44 |
SMTP client and \fBtlsproxy\fR(8). Upon completion of the |
|
45 |
TLS-level handshake, \fBtlsproxy\fR(8) translates between |
|
46 |
plaintext from/to \fBpostscreen\fR(8) and ciphertext to/from |
|
47 |
the remote SMTP client. |
|
48 |
.SH "SECURITY" |
|
49 |
.na
|
|
50 |
.nf
|
|
51 |
.ad
|
|
52 |
.fi
|
|
53 |
The \fBtlsproxy\fR(8) server is moderately security-sensitive. |
|
54 |
It talks to untrusted clients on the network. The process |
|
55 |
can be run chrooted at fixed low privilege. |
|
56 |
.SH DIAGNOSTICS |
|
57 |
.ad
|
|
58 |
.fi
|
|
59 |
Problems and transactions are logged to \fBsyslogd\fR(8). |
|
60 |
.SH "CONFIGURATION PARAMETERS" |
|
61 |
.na
|
|
62 |
.nf
|
|
63 |
.ad
|
|
64 |
.fi
|
|
65 |
Changes to \fBmain.cf\fR are not picked up automatically, |
|
66 |
as \fBtlsproxy\fR(8) processes may run for a long time |
|
67 |
depending on mail server load. Use the command "\fBpostfix
|
|
68 |
reload\fR" to speed up a change.
|
|
69 |
||
70 |
The text below provides only a parameter summary. See |
|
71 |
\fBpostconf\fR(5) for more details including examples. |
|
72 |
.SH "STARTTLS SUPPORT CONTROLS" |
|
73 |
.na
|
|
74 |
.nf
|
|
75 |
.ad
|
|
76 |
.fi
|
|
77 |
.IP "\fBtlsproxy_tls_CAfile ($smtpd_tls_CAfile)\fR" |
|
78 |
A file containing (PEM format) CA certificates of root CAs |
|
79 |
trusted to sign either remote SMTP client certificates or intermediate |
|
80 |
CA certificates. |
|
81 |
.IP "\fBtlsproxy_tls_CApath ($smtpd_tls_CApath)\fR" |
|
82 |
A directory containing (PEM format) CA certificates of root CAs |
|
83 |
trusted to sign either remote SMTP client certificates or intermediate |
|
84 |
CA certificates. |
|
85 |
.IP "\fBtlsproxy_tls_always_issue_session_ids ($smtpd_tls_always_issue_session_ids)\fR" |
|
86 |
Force the Postfix \fBtlsproxy\fR(8) server to issue a TLS session id, |
|
87 |
even when TLS session caching is turned off. |
|
88 |
.IP "\fBtlsproxy_tls_ask_ccert ($smtpd_tls_ask_ccert)\fR" |
|
89 |
Ask a remote SMTP client for a client certificate. |
|
90 |
.IP "\fBtlsproxy_tls_ccert_verifydepth ($smtpd_tls_ccert_verifydepth)\fR" |
|
91 |
The verification depth for remote SMTP client certificates. |
|
92 |
.IP "\fBtlsproxy_tls_cert_file ($smtpd_tls_cert_file)\fR" |
|
93 |
File with the Postfix \fBtlsproxy\fR(8) server RSA certificate in PEM |
|
94 |
format. |
|
95 |
.IP "\fBtlsproxy_tls_ciphers ($smtpd_tls_ciphers)\fR" |
|
96 |
The minimum TLS cipher grade that the Postfix \fBtlsproxy\fR(8) server |
|
97 |
will use with opportunistic TLS encryption. |
|
98 |
.IP "\fBtlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)\fR" |
|
99 |
File with the Postfix \fBtlsproxy\fR(8) server DSA certificate in PEM |
|
100 |
format. |
|
101 |
.IP "\fBtlsproxy_tls_dh1024_param_file ($smtpd_tls_dh1024_param_file)\fR" |
|
102 |
File with DH parameters that the Postfix \fBtlsproxy\fR(8) server |
|
1.1.41
by LaMont Jones
Import upstream version 2.11.0 |
103 |
should use with non-export EDH ciphers. |
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
104 |
.IP "\fBtlsproxy_tls_dh512_param_file ($smtpd_tls_dh512_param_file)\fR" |
105 |
File with DH parameters that the Postfix \fBtlsproxy\fR(8) server |
|
1.1.41
by LaMont Jones
Import upstream version 2.11.0 |
106 |
should use with export-grade EDH ciphers. |
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
107 |
.IP "\fBtlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)\fR" |
108 |
File with the Postfix \fBtlsproxy\fR(8) server DSA private key in PEM |
|
109 |
format. |
|
110 |
.IP "\fBtlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)\fR" |
|
111 |
File with the Postfix \fBtlsproxy\fR(8) server ECDSA certificate in |
|
112 |
PEM format. |
|
113 |
.IP "\fBtlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)\fR" |
|
114 |
File with the Postfix \fBtlsproxy\fR(8) server ECDSA private key in |
|
115 |
PEM format. |
|
116 |
.IP "\fBtlsproxy_tls_eecdh_grade ($smtpd_tls_eecdh_grade)\fR" |
|
117 |
The Postfix \fBtlsproxy\fR(8) server security grade for ephemeral |
|
118 |
elliptic-curve Diffie-Hellman (EECDH) key exchange. |
|
119 |
.IP "\fBtlsproxy_tls_exclude_ciphers ($smtpd_tls_exclude_ciphers)\fR" |
|
120 |
List of ciphers or cipher types to exclude from the \fBtlsproxy\fR(8) |
|
121 |
server cipher list at all TLS security levels. |
|
122 |
.IP "\fBtlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)\fR" |
|
1.1.34
by LaMont Jones
Import upstream version 2.9.1 |
123 |
The message digest algorithm to construct remote SMTP |
124 |
client-certificate |
|
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
125 |
fingerprints. |
126 |
.IP "\fBtlsproxy_tls_key_file ($smtpd_tls_key_file)\fR" |
|
127 |
File with the Postfix \fBtlsproxy\fR(8) server RSA private key in PEM |
|
128 |
format. |
|
129 |
.IP "\fBtlsproxy_tls_loglevel ($smtpd_tls_loglevel)\fR" |
|
130 |
Enable additional Postfix \fBtlsproxy\fR(8) server logging of TLS |
|
131 |
activity. |
|
132 |
.IP "\fBtlsproxy_tls_mandatory_ciphers ($smtpd_tls_mandatory_ciphers)\fR" |
|
133 |
The minimum TLS cipher grade that the Postfix \fBtlsproxy\fR(8) server |
|
134 |
will use with mandatory TLS encryption. |
|
135 |
.IP "\fBtlsproxy_tls_mandatory_exclude_ciphers ($smtpd_tls_mandatory_exclude_ciphers)\fR" |
|
136 |
Additional list of ciphers or cipher types to exclude from the |
|
137 |
\fBtlsproxy\fR(8) server cipher list at mandatory TLS security levels. |
|
138 |
.IP "\fBtlsproxy_tls_mandatory_protocols ($smtpd_tls_mandatory_protocols)\fR" |
|
139 |
The SSL/TLS protocols accepted by the Postfix \fBtlsproxy\fR(8) server |
|
140 |
with mandatory TLS encryption. |
|
141 |
.IP "\fBtlsproxy_tls_protocols ($smtpd_tls_protocols)\fR" |
|
142 |
List of TLS protocols that the Postfix \fBtlsproxy\fR(8) server will |
|
143 |
exclude or include with opportunistic TLS encryption. |
|
144 |
.IP "\fBtlsproxy_tls_req_ccert ($smtpd_tls_req_ccert)\fR" |
|
145 |
With mandatory TLS encryption, require a trusted remote SMTP |
|
146 |
client certificate in order to allow TLS connections to proceed. |
|
147 |
.IP "\fBtlsproxy_tls_security_level ($smtpd_tls_security_level)\fR" |
|
148 |
The SMTP TLS security level for the Postfix \fBtlsproxy\fR(8) server; |
|
149 |
when a non-empty value is specified, this overrides the obsolete |
|
150 |
parameters smtpd_use_tls and smtpd_enforce_tls. |
|
1.1.41
by LaMont Jones
Import upstream version 2.11.0 |
151 |
.PP
|
152 |
Available in Postfix version 2.11 and later: |
|
153 |
.IP "\fBtlsmgr_service_name (tlsmgr)\fR" |
|
154 |
The name of the \fBtlsmgr\fR(8) service entry in master.cf. |
|
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
155 |
.SH "OBSOLETE STARTTLS SUPPORT CONTROLS" |
156 |
.na
|
|
157 |
.nf
|
|
158 |
.ad
|
|
159 |
.fi
|
|
160 |
These parameters are supported for compatibility with |
|
161 |
\fBsmtpd\fR(8) legacy parameters. |
|
162 |
.IP "\fBtlsproxy_use_tls ($smtpd_use_tls)\fR" |
|
1.1.34
by LaMont Jones
Import upstream version 2.9.1 |
163 |
Opportunistic TLS: announce STARTTLS support to remote SMTP clients, |
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
164 |
but do not require that clients use TLS encryption. |
165 |
.IP "\fBtlsproxy_enforce_tls ($smtpd_enforce_tls)\fR" |
|
1.1.34
by LaMont Jones
Import upstream version 2.9.1 |
166 |
Mandatory TLS: announce STARTTLS support to remote SMTP clients, and |
1.1.27
by LaMont Jones
Import upstream version 2.8.0 |
167 |
require that clients use TLS encryption. |
168 |
.SH "RESOURCE CONTROLS" |
|
169 |
.na
|
|
170 |
.nf
|
|
171 |
.ad
|
|
172 |
.fi
|
|
173 |
.IP "\fBtlsproxy_watchdog_timeout (10s)\fR" |
|
174 |
How much time a \fBtlsproxy\fR(8) process may take to process local |
|
175 |
or remote I/O before it is terminated by a built-in watchdog timer. |
|
176 |
.SH "MISCELLANEOUS CONTROLS" |
|
177 |
.na
|
|
178 |
.nf
|
|
179 |
.ad
|
|
180 |
.fi
|
|
181 |
.IP "\fBconfig_directory (see 'postconf -d' output)\fR" |
|
182 |
The default location of the Postfix main.cf and master.cf |
|
183 |
configuration files. |
|
184 |
.IP "\fBprocess_id (read-only)\fR" |
|
185 |
The process ID of a Postfix command or daemon process. |
|
186 |
.IP "\fBprocess_name (read-only)\fR" |
|
187 |
The process name of a Postfix command or daemon process. |
|
188 |
.IP "\fBsyslog_facility (mail)\fR" |
|
189 |
The syslog facility of Postfix logging. |
|
190 |
.IP "\fBsyslog_name (see 'postconf -d' output)\fR" |
|
191 |
The mail system name that is prepended to the process name in syslog |
|
192 |
records, so that "smtpd" becomes, for example, "postfix/smtpd". |
|
193 |
.SH "SEE ALSO" |
|
194 |
.na
|
|
195 |
.nf
|
|
196 |
postscreen(8), Postfix zombie blocker |
|
197 |
smtpd(8), Postfix SMTP server |
|
198 |
postconf(5), configuration parameters |
|
199 |
syslogd(5), system logging |
|
200 |
.SH "LICENSE" |
|
201 |
.na
|
|
202 |
.nf
|
|
203 |
.ad
|
|
204 |
.fi
|
|
205 |
The Secure Mailer license must be distributed with this software. |
|
206 |
.SH "HISTORY" |
|
207 |
.na
|
|
208 |
.nf
|
|
209 |
.ad
|
|
210 |
.fi
|
|
211 |
This service was introduced with Postfix version 2.8. |
|
212 |
.SH "AUTHOR(S)" |
|
213 |
.na
|
|
214 |
.nf
|
|
215 |
Wietse Venema |
|
216 |
IBM T.J. Watson Research |
|
217 |
P.O. Box 704 |
|
218 |
Yorktown Heights, NY 10598, USA |