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 non-export 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 export-grade 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
117 client-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 Available in Postfix version 2.11 and later:
154 tlsmgr_service_name (tlsmgr)
156 The name of the tlsmgr(8) service entry in master.cf.
157
159 These parameters are supported for compatibility with smtpd(8) legacy
160 parameters.
161 tlsproxy_use_tls ($smtpd_use_tls)
163 Opportunistic TLS: announce STARTTLS support to remote SMTP
164 clients, but do not require that clients use TLS encryption.
165 tlsproxy_enforce_tls ($smtpd_enforce_tls)
167 Mandatory TLS: announce STARTTLS support to remote SMTP clients,
168 and require that clients use TLS encryption.
169
171 tlsproxy_watchdog_timeout (10s)
172 How much time a tlsproxy(8) process may take to process local or
173 remote I/O before it is terminated by a built-in watchdog timer.
174
176 config_directory (see 'postconf -d' output)
177 The default location of the Postfix main.cf and master.cf con‐
178 figuration files.
179 process_id (read-only)
181 The process ID of a Postfix command or daemon process.
182 process_name (read-only)
184 The process name of a Postfix command or daemon process.
185 syslog_facility (mail)
187 The syslog facility of Postfix logging.
188 syslog_name (see 'postconf -d' output)
190 A prefix that is prepended to the process name in syslog
191 records, so that, for example, "smtpd" becomes "prefix/smtpd".
192 Available in Postfix 3.3 and later:
194 service_name (read-only)
196 The master.cf service name of a Postfix daemon process.
197
199 postscreen(8), Postfix zombie blocker
200 smtpd(8), Postfix SMTP server
201 postconf(5), configuration parameters
202 syslogd(5), system logging
203
205 The Secure Mailer license must be distributed with this software.
206
208 This service was introduced with Postfix version 2.8.
209
211 Wietse Venema
212 IBM T.J. Watson Research
213 P.O. Box 704
214 Yorktown Heights, NY 10598, USA
215 Wietse Venema
217 Google, Inc.
218 111 8th Avenue
219 New York, NY 10011, USA
220 TLSPROXY(8)