1 <!doctype html public
"-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=us-ascii">
5 <title> Postfix manual - tlsproxy(
8)
</title>
7 TLSPROXY(
8) TLSPROXY(
8)
10 tlsproxy - Postfix TLS proxy
13 <b>tlsproxy
</b> [generic Postfix daemon options]
16 The
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server implements a server-side TLS proxy.
17 It is used by
<a href=
"postscreen.8.html"><b>postscreen
</b>(
8)
</a> to talk SMTP-over-TLS with
18 remote SMTP clients whose whitelist status has expired,
19 but it should also work for non-SMTP protocols.
21 Although one
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> process can serve multiple ses-
22 sions 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.
26 <b>PROTOCOL EXAMPLE
</b>
27 The example below concerns
<a href=
"postscreen.8.html"><b>postscreen
</b>(
8)
</a>. However, the
28 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server is agnostic of the application proto-
29 col, and the example is easily adapted to other applica-
32 The
<a href=
"postscreen.8.html"><b>postscreen
</b>(
8)
</a> server sends the remote SMTP client end-
33 point string, the requested role (server), and the
34 requested timeout to
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a>.
<a href=
"postscreen.8.html"><b>postscreen
</b>(
8)
</a> then
35 receives a
"TLS available" indication from
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a>.
36 If the TLS service is available,
<a href=
"postscreen.8.html"><b>postscreen
</b>(
8)
</a> sends the
37 remote SMTP client file descriptor to
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a>, and
38 sends the plaintext
220 greeting to the remote SMTP
39 client. This triggers TLS negotiations between the remote
40 SMTP client and
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a>. Upon completion of the TLS-
41 level handshake,
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> translates between plaintext
42 from/to
<a href=
"postscreen.8.html"><b>postscreen
</b>(
8)
</a> and ciphertext to/from the remote
46 The
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server is moderately security-sensitive.
47 It talks to untrusted clients on the network. The process
48 can be run chrooted at fixed low privilege.
51 Problems and transactions are logged to
<b>syslogd
</b>(
8).
53 <b>CONFIGURATION PARAMETERS
</b>
54 Changes to
<a href=
"postconf.5.html"><b>main.cf
</b></a> are not picked up automatically, as
55 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> processes may run for a long time depending on
56 mail server load. Use the command
"<b>postfix reload</b>" to
59 The text below provides only a parameter summary. See
60 <a href=
"postconf.5.html"><b>postconf
</b>(
5)
</a> for more details including examples.
62 <b>STARTTLS SUPPORT CONTROLS
</b>
63 <b><a href=
"postconf.5.html#tlsproxy_tls_CAfile">tlsproxy_tls_CAfile
</a> ($
<a href=
"postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile
</a>)
</b>
64 A file containing (PEM format) CA certificates of
65 root CAs trusted to sign either remote SMTP client
66 certificates or intermediate CA certificates.
68 <b><a href=
"postconf.5.html#tlsproxy_tls_CApath">tlsproxy_tls_CApath
</a> ($
<a href=
"postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath
</a>)
</b>
69 A directory containing (PEM format) CA certificates
70 of root CAs trusted to sign either remote SMTP
71 client certificates or intermediate CA certifi-
74 <b><a href=
"postconf.5.html#tlsproxy_tls_always_issue_session_ids">tlsproxy_tls_always_issue_session_ids
</a></b>
75 <b>($
<a href=
"postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_session_ids
</a>)
</b>
76 Force the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server to issue a TLS
77 session id, even when TLS session caching is turned
80 <b><a href=
"postconf.5.html#tlsproxy_tls_ask_ccert">tlsproxy_tls_ask_ccert
</a> ($
<a href=
"postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert
</a>)
</b>
81 Ask a remote SMTP client for a client certificate.
83 <b><a href=
"postconf.5.html#tlsproxy_tls_ccert_verifydepth">tlsproxy_tls_ccert_verifydepth
</a> ($
<a href=
"postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verify
</a>-
</b>
84 <b><a href=
"postconf.5.html#smtpd_tls_ccert_verifydepth">depth
</a>)
</b>
85 The verification depth for remote SMTP client cer-
88 <b><a href=
"postconf.5.html#tlsproxy_tls_cert_file">tlsproxy_tls_cert_file
</a> ($
<a href=
"postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file
</a>)
</b>
89 File with the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server RSA cer-
90 tificate in PEM format.
92 <b><a href=
"postconf.5.html#tlsproxy_tls_ciphers">tlsproxy_tls_ciphers
</a> ($
<a href=
"postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers
</a>)
</b>
93 The minimum TLS cipher grade that the Postfix
94 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server will use with opportunistic TLS
97 <b><a href=
"postconf.5.html#tlsproxy_tls_dcert_file">tlsproxy_tls_dcert_file
</a> ($
<a href=
"postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file
</a>)
</b>
98 File with the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server DSA cer-
99 tificate in PEM format.
101 <b><a href=
"postconf.5.html#tlsproxy_tls_dh1024_param_file">tlsproxy_tls_dh1024_param_file
</a></b>
102 <b>($
<a href=
"postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file
</a>)
</b>
103 File with DH parameters that the Postfix
104 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server should use with EDH ciphers.
106 <b><a href=
"postconf.5.html#tlsproxy_tls_dh512_param_file">tlsproxy_tls_dh512_param_file
</a></b>
107 <b>($
<a href=
"postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file
</a>)
</b>
108 File with DH parameters that the Postfix
109 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server should use with EDH ciphers.
111 <b><a href=
"postconf.5.html#tlsproxy_tls_dkey_file">tlsproxy_tls_dkey_file
</a> ($
<a href=
"postconf.5.html#smtpd_tls_dkey_file">smtpd_tls_dkey_file
</a>)
</b>
112 File with the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server DSA pri-
113 vate key in PEM format.
115 <b><a href=
"postconf.5.html#tlsproxy_tls_eccert_file">tlsproxy_tls_eccert_file
</a> ($
<a href=
"postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file
</a>)
</b>
116 File with the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server ECDSA cer-
117 tificate in PEM format.
119 <b><a href=
"postconf.5.html#tlsproxy_tls_eckey_file">tlsproxy_tls_eckey_file
</a> ($
<a href=
"postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file
</a>)
</b>
120 File with the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server ECDSA pri-
121 vate key in PEM format.
123 <b><a href=
"postconf.5.html#tlsproxy_tls_eecdh_grade">tlsproxy_tls_eecdh_grade
</a> ($
<a href=
"postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade
</a>)
</b>
124 The Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server security grade for
125 ephemeral elliptic-curve Diffie-Hellman (EECDH) key
128 <b><a href=
"postconf.5.html#tlsproxy_tls_exclude_ciphers">tlsproxy_tls_exclude_ciphers
</a> ($
<a href=
"postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers
</a>)
</b>
129 List of ciphers or cipher types to exclude from the
130 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server cipher list at all TLS security
133 <b><a href=
"postconf.5.html#tlsproxy_tls_fingerprint_digest">tlsproxy_tls_fingerprint_digest
</a> ($
<a href=
"postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_finger
</a>-
</b>
134 <b><a href=
"postconf.5.html#smtpd_tls_fingerprint_digest">print_digest
</a>)
</b>
135 The message digest algorithm used to construct
136 client-certificate fingerprints.
138 <b><a href=
"postconf.5.html#tlsproxy_tls_key_file">tlsproxy_tls_key_file
</a> ($
<a href=
"postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file
</a>)
</b>
139 File with the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server RSA pri-
140 vate key in PEM format.
142 <b><a href=
"postconf.5.html#tlsproxy_tls_loglevel">tlsproxy_tls_loglevel
</a> ($
<a href=
"postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel
</a>)
</b>
143 Enable additional Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server log-
144 ging of TLS activity.
146 <b><a href=
"postconf.5.html#tlsproxy_tls_mandatory_ciphers">tlsproxy_tls_mandatory_ciphers
</a> ($
<a href=
"postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_manda
</a>-
</b>
147 <b><a href=
"postconf.5.html#smtpd_tls_mandatory_ciphers">tory_ciphers
</a>)
</b>
148 The minimum TLS cipher grade that the Postfix
149 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server will use with mandatory TLS
152 <b><a href=
"postconf.5.html#tlsproxy_tls_mandatory_exclude_ciphers">tlsproxy_tls_mandatory_exclude_ciphers
</a> ($
<a href=
"postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_manda
</a>-
</b>
153 <b><a href=
"postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">tory_exclude_ciphers
</a>)
</b>
154 Additional list of ciphers or cipher types to
155 exclude from the
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server cipher list at
156 mandatory TLS security levels.
158 <b><a href=
"postconf.5.html#tlsproxy_tls_mandatory_protocols">tlsproxy_tls_mandatory_protocols
</a> ($
<a href=
"postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_manda
</a>-
</b>
159 <b><a href=
"postconf.5.html#smtpd_tls_mandatory_protocols">tory_protocols
</a>)
</b>
160 The SSL/TLS protocols accepted by the Postfix
161 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server with mandatory TLS encryption.
163 <b><a href=
"postconf.5.html#tlsproxy_tls_protocols">tlsproxy_tls_protocols
</a> ($
<a href=
"postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols
</a>)
</b>
164 List of TLS protocols that the Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a>
165 server will exclude or include with opportunistic
168 <b><a href=
"postconf.5.html#tlsproxy_tls_req_ccert">tlsproxy_tls_req_ccert
</a> ($
<a href=
"postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert
</a>)
</b>
169 With mandatory TLS encryption, require a trusted
170 remote SMTP client certificate in order to allow
171 TLS connections to proceed.
173 <b><a href=
"postconf.5.html#tlsproxy_tls_security_level">tlsproxy_tls_security_level
</a> ($
<a href=
"postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level
</a>)
</b>
174 The SMTP TLS security level for the Postfix
175 <a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server; when a non-empty value is spec-
176 ified, this overrides the obsolete parameters
177 <a href=
"postconf.5.html#smtpd_use_tls">smtpd_use_tls
</a> and
<a href=
"postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls
</a>.
179 <b><a href=
"postconf.5.html#tlsproxy_tls_session_cache_timeout">tlsproxy_tls_session_cache_timeout
</a> ($
<a href=
"postconf.5.html#smtpd_tls_session_cache_timeout">smtpd_tls_ses
</a>-
</b>
180 <b><a href=
"postconf.5.html#smtpd_tls_session_cache_timeout">sion_cache_timeout
</a>)
</b>
181 The expiration time of Postfix
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> server
182 TLS session cache information.
184 <b>OBSOLETE STARTTLS SUPPORT CONTROLS
</b>
185 These parameters are supported for compatibility with
186 <a href=
"smtpd.8.html"><b>smtpd
</b>(
8)
</a> legacy parameters.
188 <b><a href=
"postconf.5.html#tlsproxy_use_tls">tlsproxy_use_tls
</a> ($
<a href=
"postconf.5.html#smtpd_use_tls">smtpd_use_tls
</a>)
</b>
189 Opportunistic TLS: announce STARTTLS support to
190 SMTP clients, but do not require that clients use
193 <b><a href=
"postconf.5.html#tlsproxy_enforce_tls">tlsproxy_enforce_tls
</a> ($
<a href=
"postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls
</a>)
</b>
194 Mandatory TLS: announce STARTTLS support to SMTP
195 clients, and require that clients use TLS encryp-
198 <b>RESOURCE CONTROLS
</b>
199 <b><a href=
"postconf.5.html#tlsproxy_watchdog_timeout">tlsproxy_watchdog_timeout
</a> (
10s)
</b>
200 How much time a
<a href=
"tlsproxy.8.html"><b>tlsproxy
</b>(
8)
</a> process may take to
201 process local or remote I/O before it is terminated
202 by a built-in watchdog timer.
204 <b>MISCELLANEOUS CONTROLS
</b>
205 <b><a href=
"postconf.5.html#config_directory">config_directory
</a> (see 'postconf -d' output)
</b>
206 The default location of the Postfix
<a href=
"postconf.5.html">main.cf
</a> and
207 <a href=
"master.5.html">master.cf
</a> configuration files.
209 <b><a href=
"postconf.5.html#process_id">process_id
</a> (read-only)
</b>
210 The process ID of a Postfix command or daemon
213 <b><a href=
"postconf.5.html#process_name">process_name
</a> (read-only)
</b>
214 The process name of a Postfix command or daemon
217 <b><a href=
"postconf.5.html#syslog_facility">syslog_facility
</a> (mail)
</b>
218 The syslog facility of Postfix logging.
220 <b><a href=
"postconf.5.html#syslog_name">syslog_name
</a> (see 'postconf -d' output)
</b>
221 The mail system name that is prepended to the
222 process name in syslog records, so that
"smtpd"
223 becomes, for example,
"postfix/smtpd".
226 <a href=
"postscreen.8.html">postscreen(
8)
</a>, Postfix zombie blocker
227 <a href=
"smtpd.8.html">smtpd(
8)
</a>, Postfix SMTP server
228 <a href=
"postconf.5.html">postconf(
5)
</a>, configuration parameters
229 syslogd(
5), system logging
232 The Secure Mailer license must be distributed with this
236 This service was introduced with Postfix version
2.8.
240 IBM T.J. Watson Research
242 Yorktown Heights, NY
10598, USA
245 </pre> </body> </html>