1TLSPROXY(8) System Manager's Manual TLSPROXY(8)
2
6 tlsproxy - Postfix TLS proxy
7
9 tlsproxy [generic Postfix daemon options]
10
12 The tlsproxy(8) server implements a server-side TLS proxy. It is used
13 by postscreen(8) to talk SMTP-over-TLS with remote SMTP clients that
14 are not whitelisted (including clients whose whitelist status has
15 expired), but it should also work for non-SMTP protocols.
16 Although one tlsproxy(8) process can serve multiple sessions at the
18 same time, it is a good idea to allow the number of processes to
19 increase with load, so that the service remains responsive.
20
22 The example below concerns postscreen(8). However, the tlsproxy(8)
23 server is agnostic of the application protocol, and the example is eas‐
24 ily adapted to other applications.
25 After receiving a valid remote SMTP client STARTTLS command, the
27 postscreen(8) server sends the remote SMTP client endpoint string, the
28 requested role (server), and the requested timeout to tlsproxy(8).
29 postscreen(8) then receives a "TLS available" indication from
30 tlsproxy(8). If the TLS service is available, postscreen(8) sends the
31 remote SMTP client file descriptor to tlsproxy(8), and sends the plain‐
32 text 220 greeting to the remote SMTP client. This triggers TLS negoti‐
33 ations between the remote SMTP client and tlsproxy(8). Upon completion
34 of the TLS-level handshake, tlsproxy(8) translates between plaintext
35 from/to postscreen(8) and ciphertext to/from the remote SMTP client.
36
38 The tlsproxy(8) server is moderately security-sensitive. It talks to
39 untrusted clients on the network. The process can be run chrooted at
40 fixed low privilege.
41
43 Problems and transactions are logged to syslogd(8).
44
46 Changes to main.cf are not picked up automatically, as tlsproxy(8) pro‐
47 cesses may run for a long time depending on mail server load. Use the
48 command "postfix reload" to speed up a change.
49 The text below provides only a parameter summary. See postconf(5) for
51 more details including examples.
52
54 tlsproxy_tls_CAfile ($smtpd_tls_CAfile)
55 A file containing (PEM format) CA certificates of root CAs
56 trusted to sign either remote SMTP client certificates or inter‐
57 mediate CA certificates.
58 tlsproxy_tls_CApath ($smtpd_tls_CApath)
60 A directory containing (PEM format) CA certificates of root CAs
61 trusted to sign either remote SMTP client certificates or inter‐
62 mediate CA certificates.
63 tlsproxy_tls_always_issue_session_ids ($smtpd_tls_always_issue_ses‐
65 sion_ids)
66 Force the Postfix tlsproxy(8) server to issue a TLS session id,
67 even when TLS session caching is turned off.
68 tlsproxy_tls_ask_ccert ($smtpd_tls_ask_ccert)
70 Ask a remote SMTP client for a client certificate.
71 tlsproxy_tls_ccert_verifydepth ($smtpd_tls_ccert_verifydepth)
73 The verification depth for remote SMTP client certificates.
74 tlsproxy_tls_cert_file ($smtpd_tls_cert_file)
76 File with the Postfix tlsproxy(8) server RSA certificate in PEM
77 format.
78 tlsproxy_tls_ciphers ($smtpd_tls_ciphers)
80 The minimum TLS cipher grade that the Postfix tlsproxy(8) server
81 will use with opportunistic TLS encryption.
82 tlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)
84 File with the Postfix tlsproxy(8) server DSA certificate in PEM
85 format.
86 tlsproxy_tls_dh1024_param_file ($smtpd_tls_dh1024_param_file)
88 File with DH parameters that the Postfix tlsproxy(8) server
89 should use with EDH ciphers.
90 tlsproxy_tls_dh512_param_file ($smtpd_tls_dh512_param_file)
92 File with DH parameters that the Postfix tlsproxy(8) server
93 should use with EDH ciphers.
94 tlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)
96 File with the Postfix tlsproxy(8) server DSA private key in PEM
97 format.
98 tlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)
100 File with the Postfix tlsproxy(8) server ECDSA certificate in
101 PEM format.
102 tlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)
104 File with the Postfix tlsproxy(8) server ECDSA private key in
105 PEM format.
106 tlsproxy_tls_eecdh_grade ($smtpd_tls_eecdh_grade)
108 The Postfix tlsproxy(8) server security grade for ephemeral
109 elliptic-curve Diffie-Hellman (EECDH) key exchange.
110 tlsproxy_tls_exclude_ciphers ($smtpd_tls_exclude_ciphers)
112 List of ciphers or cipher types to exclude from the tlsproxy(8)
113 server cipher list at all TLS security levels.
114 tlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)
116 The message digest algorithm to construct remote SMTP client-
117 certificate fingerprints.
118 tlsproxy_tls_key_file ($smtpd_tls_key_file)
120 File with the Postfix tlsproxy(8) server RSA private key in PEM
121 format.
122 tlsproxy_tls_loglevel ($smtpd_tls_loglevel)
124 Enable additional Postfix tlsproxy(8) server logging of TLS
125 activity.
126 tlsproxy_tls_mandatory_ciphers ($smtpd_tls_mandatory_ciphers)
128 The minimum TLS cipher grade that the Postfix tlsproxy(8) server
129 will use with mandatory TLS encryption.
130 tlsproxy_tls_mandatory_exclude_ciphers ($smtpd_tls_manda‐
132 tory_exclude_ciphers)
133 Additional list of ciphers or cipher types to exclude from the
134 tlsproxy(8) server cipher list at mandatory TLS security levels.
135 tlsproxy_tls_mandatory_protocols ($smtpd_tls_mandatory_protocols)
137 The SSL/TLS protocols accepted by the Postfix tlsproxy(8) server
138 with mandatory TLS encryption.
139 tlsproxy_tls_protocols ($smtpd_tls_protocols)
141 List of TLS protocols that the Postfix tlsproxy(8) server will
142 exclude or include with opportunistic TLS encryption.
143 tlsproxy_tls_req_ccert ($smtpd_tls_req_ccert)
145 With mandatory TLS encryption, require a trusted remote SMTP
146 client certificate in order to allow TLS connections to proceed.
147 tlsproxy_tls_security_level ($smtpd_tls_security_level)
149 The SMTP TLS security level for the Postfix tlsproxy(8) server;
150 when a non-empty value is specified, this overrides the obsolete
151 parameters smtpd_use_tls and smtpd_enforce_tls.
152 tlsproxy_tls_session_cache_timeout ($smtpd_tls_session_cache_timeout)
154 The expiration time of Postfix tlsproxy(8) server TLS session
155 cache information.
156
158 These parameters are supported for compatibility with smtpd(8) legacy
159 parameters.
160 tlsproxy_use_tls ($smtpd_use_tls)
162 Opportunistic TLS: announce STARTTLS support to remote SMTP
163 clients, but do not require that clients use TLS encryption.
164 tlsproxy_enforce_tls ($smtpd_enforce_tls)
166 Mandatory TLS: announce STARTTLS support to remote SMTP clients,
167 and require that clients use TLS encryption.
168
170 tlsproxy_watchdog_timeout (10s)
171 How much time a tlsproxy(8) process may take to process local or
172 remote I/O before it is terminated by a built-in watchdog timer.
173
175 config_directory (see 'postconf -d' output)
176 The default location of the Postfix main.cf and master.cf con‐
177 figuration files.
178 process_id (read-only)
180 The process ID of a Postfix command or daemon process.
181 process_name (read-only)
183 The process name of a Postfix command or daemon process.
184 syslog_facility (mail)
186 The syslog facility of Postfix logging.
187 syslog_name (see 'postconf -d' output)
189 The mail system name that is prepended to the process name in
190 syslog records, so that "smtpd" becomes, for example, "post‐
191 fix/smtpd".
192
194 postscreen(8), Postfix zombie blocker
195 smtpd(8), Postfix SMTP server
196 postconf(5), configuration parameters
197 syslogd(5), system logging
198
200 The Secure Mailer license must be distributed with this software.
201
203 This service was introduced with Postfix version 2.8.
204
206 Wietse Venema
207 IBM T.J. Watson Research
208 P.O. Box 704
209 Yorktown Heights, NY 10598, USA
210 TLSPROXY(8)