1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 5<title> Postfix manual - tlsproxy(8) </title> 6</head> <body> <pre> 7TLSPROXY(8) TLSPROXY(8) 8 9<b>NAME</b> 10 tlsproxy - Postfix TLS proxy 11 12<b>SYNOPSIS</b> 13 <b>tlsproxy</b> [generic Postfix daemon options] 14 15<b>DESCRIPTION</b> 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 that are not whitelisted (including 19 clients whose whitelist status has expired), but it should 20 also work for non-SMTP protocols. 21 22 Although one <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process can serve multiple ses- 23 sions at the same time, it is a good idea to allow the 24 number of processes to increase with load, so that the 25 service remains responsive. 26 27<b>PROTOCOL EXAMPLE</b> 28 The example below concerns <a href="postscreen.8.html"><b>postscreen</b>(8)</a>. However, the 29 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server is agnostic of the application proto- 30 col, and the example is easily adapted to other applica- 31 tions. 32 33 After receiving a valid remote SMTP client STARTTLS com- 34 mand, the <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server sends the remote SMTP 35 client endpoint string, the requested role (server), and 36 the requested timeout to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. <a href="postscreen.8.html"><b>postscreen</b>(8)</a> then 37 receives a "TLS available" indication from <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. 38 If the TLS service is available, <a href="postscreen.8.html"><b>postscreen</b>(8)</a> sends the 39 remote SMTP client file descriptor to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>, and 40 sends the plaintext 220 greeting to the remote SMTP 41 client. This triggers TLS negotiations between the remote 42 SMTP client and <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. Upon completion of the TLS- 43 level handshake, <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> translates between plaintext 44 from/to <a href="postscreen.8.html"><b>postscreen</b>(8)</a> and ciphertext to/from the remote 45 SMTP client. 46 47<b>SECURITY</b> 48 The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server is moderately security-sensitive. 49 It talks to untrusted clients on the network. The process 50 can be run chrooted at fixed low privilege. 51 52<b>DIAGNOSTICS</b> 53 Problems and transactions are logged to <b>syslogd</b>(8). 54 55<b>CONFIGURATION PARAMETERS</b> 56 Changes to <a href="postconf.5.html"><b>main.cf</b></a> are not picked up automatically, as 57 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> processes may run for a long time depending on 58 mail server load. Use the command "<b>postfix reload</b>" to 59 speed up a change. 60 61 The text below provides only a parameter summary. See 62 <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples. 63 64<b>STARTTLS SUPPORT CONTROLS</b> 65 <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> 66 A file containing (PEM format) CA certificates of 67 root CAs trusted to sign either remote SMTP client 68 certificates or intermediate CA certificates. 69 70 <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> 71 A directory containing (PEM format) CA certificates 72 of root CAs trusted to sign either remote SMTP 73 client certificates or intermediate CA certifi- 74 cates. 75 76 <b><a href="postconf.5.html#tlsproxy_tls_always_issue_session_ids">tlsproxy_tls_always_issue_session_ids</a></b> 77 <b>($<a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_session_ids</a>)</b> 78 Force the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server to issue a TLS 79 session id, even when TLS session caching is turned 80 off. 81 82 <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> 83 Ask a remote SMTP client for a client certificate. 84 85 <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> 86 <b><a href="postconf.5.html#smtpd_tls_ccert_verifydepth">depth</a>)</b> 87 The verification depth for remote SMTP client cer- 88 tificates. 89 90 <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> 91 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA cer- 92 tificate in PEM format. 93 94 <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> 95 The minimum TLS cipher grade that the Postfix 96 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server will use with opportunistic TLS 97 encryption. 98 99 <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> 100 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA cer- 101 tificate in PEM format. 102 103 <b><a href="postconf.5.html#tlsproxy_tls_dh1024_param_file">tlsproxy_tls_dh1024_param_file</a></b> 104 <b>($<a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a>)</b> 105 File with DH parameters that the Postfix 106 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server should use with EDH ciphers. 107 108 <b><a href="postconf.5.html#tlsproxy_tls_dh512_param_file">tlsproxy_tls_dh512_param_file</a></b> 109 <b>($<a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a>)</b> 110 File with DH parameters that the Postfix 111 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server should use with EDH ciphers. 112 113 <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> 114 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA pri- 115 vate key in PEM format. 116 117 <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> 118 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA cer- 119 tificate in PEM format. 120 121 <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> 122 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA pri- 123 vate key in PEM format. 124 125 <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> 126 The Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server security grade for 127 ephemeral elliptic-curve Diffie-Hellman (EECDH) key 128 exchange. 129 130 <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> 131 List of ciphers or cipher types to exclude from the 132 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server cipher list at all TLS security 133 levels. 134 135 <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> 136 <b><a href="postconf.5.html#smtpd_tls_fingerprint_digest">print_digest</a>)</b> 137 The message digest algorithm to construct remote 138 SMTP client-certificate fingerprints. 139 140 <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> 141 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA pri- 142 vate key in PEM format. 143 144 <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> 145 Enable additional Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server log- 146 ging of TLS activity. 147 148 <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> 149 <b><a href="postconf.5.html#smtpd_tls_mandatory_ciphers">tory_ciphers</a>)</b> 150 The minimum TLS cipher grade that the Postfix 151 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server will use with mandatory TLS 152 encryption. 153 154 <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> 155 <b><a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">tory_exclude_ciphers</a>)</b> 156 Additional list of ciphers or cipher types to 157 exclude from the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server cipher list at 158 mandatory TLS security levels. 159 160 <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> 161 <b><a href="postconf.5.html#smtpd_tls_mandatory_protocols">tory_protocols</a>)</b> 162 The SSL/TLS protocols accepted by the Postfix 163 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server with mandatory TLS encryption. 164 165 <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> 166 List of TLS protocols that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> 167 server will exclude or include with opportunistic 168 TLS encryption. 169 170 <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> 171 With mandatory TLS encryption, require a trusted 172 remote SMTP client certificate in order to allow 173 TLS connections to proceed. 174 175 <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> 176 The SMTP TLS security level for the Postfix 177 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server; when a non-empty value is spec- 178 ified, this overrides the obsolete parameters 179 <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>. 180 181 <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> 182 <b><a href="postconf.5.html#smtpd_tls_session_cache_timeout">sion_cache_timeout</a>)</b> 183 The expiration time of Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server 184 TLS session cache information. 185 186<b>OBSOLETE STARTTLS SUPPORT CONTROLS</b> 187 These parameters are supported for compatibility with 188 <a href="smtpd.8.html"><b>smtpd</b>(8)</a> legacy parameters. 189 190 <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> 191 Opportunistic TLS: announce STARTTLS support to 192 remote SMTP clients, but do not require that 193 clients use TLS encryption. 194 195 <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> 196 Mandatory TLS: announce STARTTLS support to remote 197 SMTP clients, and require that clients use TLS 198 encryption. 199 200<b>RESOURCE CONTROLS</b> 201 <b><a href="postconf.5.html#tlsproxy_watchdog_timeout">tlsproxy_watchdog_timeout</a> (10s)</b> 202 How much time a <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process may take to 203 process local or remote I/O before it is terminated 204 by a built-in watchdog timer. 205 206<b>MISCELLANEOUS CONTROLS</b> 207 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 208 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and 209 <a href="master.5.html">master.cf</a> configuration files. 210 211 <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> 212 The process ID of a Postfix command or daemon 213 process. 214 215 <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> 216 The process name of a Postfix command or daemon 217 process. 218 219 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 220 The syslog facility of Postfix logging. 221 222 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 223 The mail system name that is prepended to the 224 process name in syslog records, so that "smtpd" 225 becomes, for example, "postfix/smtpd". 226 227<b>SEE ALSO</b> 228 <a href="postscreen.8.html">postscreen(8)</a>, Postfix zombie blocker 229 <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server 230 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 231 syslogd(5), system logging 232 233<b>LICENSE</b> 234 The Secure Mailer license must be distributed with this 235 software. 236 237<b>HISTORY</b> 238 This service was introduced with Postfix version 2.8. 239 240<b>AUTHOR(S)</b> 241 Wietse Venema 242 IBM T.J. Watson Research 243 P.O. Box 704 244 Yorktown Heights, NY 10598, USA 245 246 TLSPROXY(8) 247</pre> </body> </html> 248