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 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
17       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

PROTOCOL EXAMPLE

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
26       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

SECURITY

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

DIAGNOSTICS

43       Problems and transactions are logged to syslogd(8).
44

CONFIGURATION PARAMETERS

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
50       The  text  below provides only a parameter summary. See postconf(5) for
51       more details including examples.
52

STARTTLS SUPPORT CONTROLS

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
59       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
64       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
69       tlsproxy_tls_ask_ccert ($smtpd_tls_ask_ccert)
70              Ask a remote SMTP client for a client certificate.
71
72       tlsproxy_tls_ccert_verifydepth ($smtpd_tls_ccert_verifydepth)
73              The verification depth for remote SMTP client certificates.
74
75       tlsproxy_tls_cert_file ($smtpd_tls_cert_file)
76              File with the Postfix tlsproxy(8) server RSA certificate in  PEM
77              format.
78
79       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
83       tlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)
84              File with the Postfix tlsproxy(8) server DSA certificate in  PEM
85              format.
86
87       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
91       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
95       tlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)
96              File  with the Postfix tlsproxy(8) server DSA private key in PEM
97              format.
98
99       tlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)
100              File with the Postfix tlsproxy(8) server  ECDSA  certificate  in
101              PEM format.
102
103       tlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)
104              File  with  the  Postfix tlsproxy(8) server ECDSA private key in
105              PEM format.
106
107       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
111       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
115       tlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)
116              The  message  digest  algorithm   to   construct   remote   SMTP
117              client-certificate fingerprints.
118
119       tlsproxy_tls_key_file ($smtpd_tls_key_file)
120              File  with the Postfix tlsproxy(8) server RSA private key in PEM
121              format.
122
123       tlsproxy_tls_loglevel ($smtpd_tls_loglevel)
124              Enable additional Postfix  tlsproxy(8)  server  logging  of  TLS
125              activity.
126
127       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
131       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
136       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
140       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
144       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
148       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
153       Available in Postfix version 2.11 and later:
154
155       tlsmgr_service_name (tlsmgr)
156              The name of the tlsmgr(8) service entry in master.cf.
157

OBSOLETE STARTTLS SUPPORT CONTROLS

159       These  parameters  are supported for compatibility with smtpd(8) legacy
160       parameters.
161
162       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
166       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

RESOURCE CONTROLS

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

MISCELLANEOUS CONTROLS

176       config_directory (see 'postconf -d' output)
177              The  default  location of the Postfix main.cf and master.cf con‐
178              figuration files.
179
180       process_id (read-only)
181              The process ID of a Postfix command or daemon process.
182
183       process_name (read-only)
184              The process name of a Postfix command or daemon process.
185
186       syslog_facility (mail)
187              The syslog facility of Postfix logging.
188
189       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
193       Available in Postfix 3.3 and later:
194
195       service_name (read-only)
196              The master.cf service name of a Postfix daemon process.
197

SEE ALSO

199       postscreen(8), Postfix zombie blocker
200       smtpd(8), Postfix SMTP server
201       postconf(5), configuration parameters
202       syslogd(5), system logging
203

LICENSE

205       The Secure Mailer license must be distributed with this software.
206

HISTORY

208       This service was introduced with Postfix version 2.8.
209

AUTHOR(S)

211       Wietse Venema
212       IBM T.J. Watson Research
213       P.O. Box 704
214       Yorktown Heights, NY 10598, USA
215
216       Wietse Venema
217       Google, Inc.
218       111 8th Avenue
219       New York, NY 10011, USA
220
221
222
223                                                                   TLSPROXY(8)
Impressum