1TLSPROXY(8)                 System Manager's Manual                TLSPROXY(8)
2
3
4

NAME

6       tlsproxy - Postfix TLS proxy
7

SYNOPSIS

9       tlsproxy [generic Postfix daemon options]
10

DESCRIPTION

12       The  tlsproxy(8)  server  implements a two-way TLS proxy. It is used by
13       the postscreen(8) server to talk SMTP-over-TLS with remote SMTP clients
14       that  are not whitelisted (including clients whose whitelist status has
15       expired), and by the smtp(8) client to support  TLS  connection  reuse,
16       but it should also work for non-SMTP protocols.
17
18       Although  one  tlsproxy(8)  process  can serve multiple sessions at the
19       same time, it is a good idea  to  allow  the  number  of  processes  to
20       increase with load, so that the service remains responsive.
21

PROTOCOL EXAMPLE

23       The  example  below  concerns  postscreen(8).  However, the tlsproxy(8)
24       server is agnostic of the application protocol, and the example is eas‐
25       ily adapted to other applications.
26
27       After  receiving  a  valid  remote  SMTP  client  STARTTLS command, the
28       postscreen(8) server sends the remote SMTP client endpoint string,  the
29       requested  role  (server),  and  the  requested timeout to tlsproxy(8).
30       postscreen(8)  then  receives  a  "TLS   available"   indication   from
31       tlsproxy(8).   If the TLS service is available, postscreen(8) sends the
32       remote SMTP client file descriptor to tlsproxy(8), and sends the plain‐
33       text 220 greeting to the remote SMTP client.  This triggers TLS negoti‐
34       ations between the remote SMTP client and tlsproxy(8).  Upon completion
35       of  the  TLS-level  handshake, tlsproxy(8) translates between plaintext
36       from/to postscreen(8) and ciphertext to/from the remote SMTP client.
37

SECURITY

39       The tlsproxy(8) server is moderately security-sensitive.  It  talks  to
40       untrusted  clients  on  the network. The process can be run chrooted at
41       fixed low privilege.
42

DIAGNOSTICS

44       Problems and transactions are logged to syslogd(8) or postlogd(8).
45

CONFIGURATION PARAMETERS

47       Changes to main.cf are not picked up automatically, as tlsproxy(8) pro‐
48       cesses  may run for a long time depending on mail server load.  Use the
49       command "postfix reload" to speed up a change.
50
51       The text below provides only a parameter summary. See  postconf(5)  for
52       more details including examples.
53

STARTTLS GLOBAL CONTROLS

55       The  following settings are global and therefore cannot be overruled by
56       information specified in a tlsproxy(8) client request.
57
58       tls_append_default_CA (no)
59              Append the system-supplied default Certification Authority  cer‐
60              tificates   to   the   ones   specified   with  *_tls_CApath  or
61              *_tls_CAfile.
62
63       tls_daemon_random_bytes (32)
64              The number of pseudo-random bytes that an  smtp(8)  or  smtpd(8)
65              process  requests from the tlsmgr(8) server in order to seed its
66              internal pseudo random number generator (PRNG).
67
68       tls_high_cipherlist (see 'postconf -d' output)
69              The OpenSSL cipherlist for "high" grade ciphers.
70
71       tls_medium_cipherlist (see 'postconf -d' output)
72              The OpenSSL cipherlist for "medium" or higher grade ciphers.
73
74       tls_low_cipherlist (see 'postconf -d' output)
75              The OpenSSL cipherlist for "low" or higher grade ciphers.
76
77       tls_export_cipherlist (see 'postconf -d' output)
78              The OpenSSL cipherlist for "export" or higher grade ciphers.
79
80       tls_null_cipherlist (eNULL:!aNULL)
81              The OpenSSL cipherlist for "NULL"  grade  ciphers  that  provide
82              authentication without encryption.
83
84       tls_eecdh_strong_curve (prime256v1)
85              The  elliptic curve used by the Postfix SMTP server for sensibly
86              strong ephemeral ECDH key exchange.
87
88       tls_eecdh_ultra_curve (secp384r1)
89              The elliptic curve used by the Postfix SMTP server for maximally
90              strong ephemeral ECDH key exchange.
91
92       tls_disable_workarounds (see 'postconf -d' output)
93              List or bit-mask of OpenSSL bug work-arounds to disable.
94
95       tls_preempt_cipherlist (no)
96              With SSLv3 and later, use the Postfix SMTP server's cipher pref‐
97              erence order instead of the remote  client's  cipher  preference
98              order.
99
100       Available in Postfix version 2.9 and later:
101
102       tls_legacy_public_key_fingerprints (no)
103              A  temporary  migration  aid for sites that use certificate pub‐
104              lic-key fingerprints with Postfix  2.9.0..2.9.5,  which  use  an
105              incorrect algorithm.
106
107       Available in Postfix version 2.11-3.1:
108
109       tls_dane_digest_agility (on)
110              Configure RFC7671 DANE TLSA digest algorithm agility.
111
112       tls_dane_trust_anchor_digest_enable (yes)
113              Enable support for RFC 6698 (DANE TLSA) DNS records that contain
114              digests of trust-anchors with certificate usage "2".
115
116       Available in Postfix version 2.11 and later:
117
118       tlsmgr_service_name (tlsmgr)
119              The name of the tlsmgr(8) service entry in master.cf.
120
121       Available in Postfix version 3.0 and later:
122
123       tls_session_ticket_cipher (Postfix >= 3.0: aes-256-cbc, Postfix <  3.0:
124       aes-128-cbc)
125              Algorithm used to encrypt RFC5077 TLS session tickets.
126
127       openssl_path (openssl)
128              The location of the OpenSSL command line program openssl(1).
129
130       Available in Postfix version 3.2 and later:
131
132       tls_eecdh_auto_curves (see 'postconf -d' output)
133              The prioritized list of elliptic curves supported by the Postfix
134              SMTP client and server.
135
136       Available in Postfix version 3.4 and later:
137
138       tls_server_sni_maps (empty)
139              Optional lookup tables that map names received from remote  SMTP
140              clients  via  the  TLS Server Name Indication (SNI) extension to
141              the appropriate keys and certificate chains.
142

STARTTLS SERVER CONTROLS

144       These settings are clones of Postfix SMTP server settings.  They  allow
145       tlsproxy(8) to load the same certificate and private key information as
146       the Postfix SMTP server, before dropping privileges, so  that  the  key
147       files  can be kept read-only for root. These settings can currently not
148       be overruled by information in a tlsproxy(8) client request,  but  that
149       limitation may be removed in a future version.
150
151       tlsproxy_tls_CAfile ($smtpd_tls_CAfile)
152              A  file  containing  (PEM  format)  CA  certificates of root CAs
153              trusted to sign either remote SMTP client certificates or inter‐
154              mediate CA certificates.
155
156       tlsproxy_tls_CApath ($smtpd_tls_CApath)
157              A  directory containing (PEM format) CA certificates of root CAs
158              trusted to sign either remote SMTP client certificates or inter‐
159              mediate CA certificates.
160
161       tlsproxy_tls_always_issue_session_ids     ($smtpd_tls_always_issue_ses‐
162       sion_ids)
163              Force the Postfix tlsproxy(8) server to issue a TLS session  id,
164              even when TLS session caching is turned off.
165
166       tlsproxy_tls_ask_ccert ($smtpd_tls_ask_ccert)
167              Ask a remote SMTP client for a client certificate.
168
169       tlsproxy_tls_ccert_verifydepth ($smtpd_tls_ccert_verifydepth)
170              The verification depth for remote SMTP client certificates.
171
172       tlsproxy_tls_cert_file ($smtpd_tls_cert_file)
173              File  with the Postfix tlsproxy(8) server RSA certificate in PEM
174              format.
175
176       tlsproxy_tls_ciphers ($smtpd_tls_ciphers)
177              The minimum TLS cipher grade that the Postfix tlsproxy(8) server
178              will use with opportunistic TLS encryption.
179
180       tlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)
181              File  with the Postfix tlsproxy(8) server DSA certificate in PEM
182              format.
183
184       tlsproxy_tls_dh1024_param_file ($smtpd_tls_dh1024_param_file)
185              File with DH parameters  that  the  Postfix  tlsproxy(8)  server
186              should use with non-export EDH ciphers.
187
188       tlsproxy_tls_dh512_param_file ($smtpd_tls_dh512_param_file)
189              File  with  DH  parameters  that  the Postfix tlsproxy(8) server
190              should use with export-grade EDH ciphers.
191
192       tlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)
193              File with the Postfix tlsproxy(8) server DSA private key in  PEM
194              format.
195
196       tlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)
197              File  with  the  Postfix tlsproxy(8) server ECDSA certificate in
198              PEM format.
199
200       tlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)
201              File with the Postfix tlsproxy(8) server ECDSA  private  key  in
202              PEM format.
203
204       tlsproxy_tls_eecdh_grade ($smtpd_tls_eecdh_grade)
205              The  Postfix  tlsproxy(8)  server  security  grade for ephemeral
206              elliptic-curve Diffie-Hellman (EECDH) key exchange.
207
208       tlsproxy_tls_exclude_ciphers ($smtpd_tls_exclude_ciphers)
209              List of ciphers or cipher types to exclude from the  tlsproxy(8)
210              server cipher list at all TLS security levels.
211
212       tlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)
213              The   message   digest   algorithm   to  construct  remote  SMTP
214              client-certificate fingerprints.
215
216       tlsproxy_tls_key_file ($smtpd_tls_key_file)
217              File with the Postfix tlsproxy(8) server RSA private key in  PEM
218              format.
219
220       tlsproxy_tls_loglevel ($smtpd_tls_loglevel)
221              Enable  additional  Postfix  tlsproxy(8)  server  logging of TLS
222              activity.
223
224       tlsproxy_tls_mandatory_ciphers ($smtpd_tls_mandatory_ciphers)
225              The minimum TLS cipher grade that the Postfix tlsproxy(8) server
226              will use with mandatory TLS encryption.
227
228       tlsproxy_tls_mandatory_exclude_ciphers               ($smtpd_tls_manda‐
229       tory_exclude_ciphers)
230              Additional list of ciphers or cipher types to exclude  from  the
231              tlsproxy(8) server cipher list at mandatory TLS security levels.
232
233       tlsproxy_tls_mandatory_protocols ($smtpd_tls_mandatory_protocols)
234              The SSL/TLS protocols accepted by the Postfix tlsproxy(8) server
235              with mandatory TLS encryption.
236
237       tlsproxy_tls_protocols ($smtpd_tls_protocols)
238              List of TLS protocols that the Postfix tlsproxy(8)  server  will
239              exclude or include with opportunistic TLS encryption.
240
241       tlsproxy_tls_req_ccert ($smtpd_tls_req_ccert)
242              With  mandatory  TLS  encryption,  require a trusted remote SMTP
243              client certificate in order to allow TLS connections to proceed.
244
245       tlsproxy_tls_security_level ($smtpd_tls_security_level)
246              The SMTP TLS security level for the Postfix tlsproxy(8)  server;
247              when a non-empty value is specified, this overrides the obsolete
248              parameters smtpd_use_tls and smtpd_enforce_tls.
249
250       tlsproxy_tls_chain_files ($smtpd_tls_chain_files)
251              Files with the Postfix tlsproxy(8) server keys  and  certificate
252              chains in PEM format.
253

STARTTLS CLIENT CONTROLS

255       These  settings are clones of Postfix SMTP client settings.  They allow
256       tlsproxy(8) to load the same certificate and private key information as
257       the  Postfix  SMTP  client, before dropping privileges, so that the key
258       files can be kept read-only for root. Some settings may be overruled by
259       information in a tlsproxy(8) client request.
260
261       Available in Postfix version 3.4 and later:
262
263       tlsproxy_client_CAfile ($smtp_tls_CAfile)
264              A  file  containing  CA certificates of root CAs trusted to sign
265              either remote TLS server certificates or  intermediate  CA  cer‐
266              tificates.
267
268       tlsproxy_client_CApath ($smtp_tls_CApath)
269              Directory  with  PEM format Certification Authority certificates
270              that the Postfix tlsproxy(8) client uses to verify a remote  TLS
271              server certificate.
272
273       tlsproxy_client_chain_files ($smtp_tls_chain_files)
274              Files  with  the Postfix tlsproxy(8) client keys and certificate
275              chains in PEM format.
276
277       tlsproxy_client_cert_file ($smtp_tls_cert_file)
278              File with the Postfix tlsproxy(8) client RSA certificate in  PEM
279              format.
280
281       tlsproxy_client_key_file ($smtp_tls_key_file)
282              File  with the Postfix tlsproxy(8) client RSA private key in PEM
283              format.
284
285       tlsproxy_client_dcert_file ($smtp_tls_dcert_file)
286              File with the Postfix tlsproxy(8) client DSA certificate in  PEM
287              format.
288
289       tlsproxy_client_dkey_file ($smtp_tls_dkey_file)
290              File  with the Postfix tlsproxy(8) client DSA private key in PEM
291              format.
292
293       tlsproxy_client_eccert_file ($smtp_tls_eccert_file)
294              File with the Postfix tlsproxy(8) client  ECDSA  certificate  in
295              PEM format.
296
297       tlsproxy_client_eckey_file ($smtp_tls_eckey_file)
298              File  with  the  Postfix tlsproxy(8) client ECDSA private key in
299              PEM format.
300
301       tlsproxy_client_fingerprint_digest ($smtp_tls_fingerprint_digest)
302              The message digest algorithm used to construct remote TLS server
303              certificate fingerprints.
304
305       tlsproxy_client_loglevel ($smtp_tls_loglevel)
306              Enable  additional  Postfix  tlsproxy(8)  client  logging of TLS
307              activity.
308
309       tlsproxy_client_loglevel_parameter (smtp_tls_loglevel)
310              The    name    of    the    parameter    that    provides    the
311              tlsproxy_client_loglevel value.
312
313       tlsproxy_client_scert_verifydepth ($smtp_tls_scert_verifydepth)
314              The verification depth for remote TLS server certificates.
315
316       tlsproxy_client_security_level ($smtp_tls_security_level)
317              The  default  TLS  security  level  for  the Postfix tlsproxy(8)
318              client.
319
320       tlsproxy_client_policy_maps ($smtp_tls_policy_maps)
321              Optional lookup tables with the Postfix tlsproxy(8)  client  TLS
322              security policy by next-hop destination.
323
324       tlsproxy_client_use_tls ($smtp_use_tls)
325              Opportunistic  mode:  use TLS when a remote server announces TLS
326              support.
327
328       tlsproxy_client_enforce_tls ($smtp_enforce_tls)
329              Enforcement mode: require that SMTP servers use TLS encryption.
330
331       tlsproxy_client_per_site ($smtp_tls_per_site)
332              Optional lookup tables with the Postfix tlsproxy(8)  client  TLS
333              usage  policy  by  next-hop destination and by remote TLS server
334              hostname.
335
336       Introduced with Postfix 3.4.6, 3.3.5, 3.2.10, and 3.1.13:
337
338       tls_fast_shutdown_enable (yes)
339              A workaround for implementations that hang Postfix while shuting
340              down a TLS session, until Postfix times out.
341

OBSOLETE STARTTLS SUPPORT CONTROLS

343       These  parameters  are supported for compatibility with smtpd(8) legacy
344       parameters.
345
346       tlsproxy_use_tls ($smtpd_use_tls)
347              Opportunistic TLS: announce  STARTTLS  support  to  remote  SMTP
348              clients, but do not require that clients use TLS encryption.
349
350       tlsproxy_enforce_tls ($smtpd_enforce_tls)
351              Mandatory TLS: announce STARTTLS support to remote SMTP clients,
352              and require that clients use TLS encryption.
353

RESOURCE CONTROLS

355       tlsproxy_watchdog_timeout (10s)
356              How much time a tlsproxy(8) process may take to process local or
357              remote I/O before it is terminated by a built-in watchdog timer.
358

MISCELLANEOUS CONTROLS

360       config_directory (see 'postconf -d' output)
361              The  default  location of the Postfix main.cf and master.cf con‐
362              figuration files.
363
364       process_id (read-only)
365              The process ID of a Postfix command or daemon process.
366
367       process_name (read-only)
368              The process name of a Postfix command or daemon process.
369
370       syslog_facility (mail)
371              The syslog facility of Postfix logging.
372
373       syslog_name (see 'postconf -d' output)
374              A prefix that  is  prepended  to  the  process  name  in  syslog
375              records, so that, for example, "smtpd" becomes "prefix/smtpd".
376
377       Available in Postfix 3.3 and later:
378
379       service_name (read-only)
380              The master.cf service name of a Postfix daemon process.
381

SEE ALSO

383       postscreen(8), Postfix zombie blocker
384       smtpd(8), Postfix SMTP server
385       postconf(5), configuration parameters
386       postlogd(8), Postfix logging
387       syslogd(8), system logging
388

LICENSE

390       The Secure Mailer license must be distributed with this software.
391

HISTORY

393       This service was introduced with Postfix version 2.8.
394

AUTHOR(S)

396       Wietse Venema
397       IBM T.J. Watson Research
398       P.O. Box 704
399       Yorktown Heights, NY 10598, USA
400
401       Wietse Venema
402       Google, Inc.
403       111 8th Avenue
404       New York, NY 10011, USA
405
406
407
408                                                                   TLSPROXY(8)
Impressum