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. It is used 17 by <a href="postscreen.8.html"><b>postscreen</b>(8)</a> to talk SMTP-over-TLS with remote SMTP clients that 18 are not whitelisted (including clients whose whitelist status has 19 expired), but it should also work for non-SMTP protocols. 20 21 Although one <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process can serve multiple sessions at the 22 same time, it is a good idea to allow the number of processes to 23 increase with load, so that the service remains responsive. 24 25<b>PROTOCOL EXAMPLE</b> 26 The example below concerns <a href="postscreen.8.html"><b>postscreen</b>(8)</a>. However, the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> 27 server is agnostic of the application protocol, and the example is eas- 28 ily adapted to other applications. 29 30 After receiving a valid remote SMTP client STARTTLS command, the 31 <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server sends the remote SMTP client endpoint string, the 32 requested role (server), and the requested timeout to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. 33 <a href="postscreen.8.html"><b>postscreen</b>(8)</a> then receives a "TLS available" indication from 34 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. If the TLS service is available, <a href="postscreen.8.html"><b>postscreen</b>(8)</a> sends the 35 remote SMTP client file descriptor to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>, and sends the plain- 36 text 220 greeting to the remote SMTP client. This triggers TLS negoti- 37 ations between the remote SMTP client and <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. Upon completion 38 of the TLS-level handshake, <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> translates between plaintext 39 from/to <a href="postscreen.8.html"><b>postscreen</b>(8)</a> and ciphertext to/from the remote SMTP client. 40 41<b>SECURITY</b> 42 The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server is moderately security-sensitive. It talks to 43 untrusted clients on the network. The process can be run chrooted at 44 fixed low privilege. 45 46<b>DIAGNOSTICS</b> 47 Problems and transactions are logged to <b>syslogd</b>(8). 48 49<b>CONFIGURATION PARAMETERS</b> 50 Changes to <a href="postconf.5.html"><b>main.cf</b></a> are not picked up automatically, as <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> pro- 51 cesses may run for a long time depending on mail server load. Use the 52 command "<b>postfix reload</b>" to speed up a change. 53 54 The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for 55 more details including examples. 56 57<b>STARTTLS SUPPORT CONTROLS</b> 58 <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> 59 A file containing (PEM format) CA certificates of root CAs 60 trusted to sign either remote SMTP client certificates or inter- 61 mediate CA certificates. 62 63 <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> 64 A directory containing (PEM format) CA certificates of root CAs 65 trusted to sign either remote SMTP client certificates or inter- 66 mediate CA certificates. 67 68 <b><a href="postconf.5.html#tlsproxy_tls_always_issue_session_ids">tlsproxy_tls_always_issue_session_ids</a> ($<a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_ses</a>-</b> 69 <b><a href="postconf.5.html#smtpd_tls_always_issue_session_ids">sion_ids</a>)</b> 70 Force the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server to issue a TLS session id, 71 even when TLS session caching is turned off. 72 73 <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> 74 Ask a remote SMTP client for a client certificate. 75 76 <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_verifydepth</a>)</b> 77 The verification depth for remote SMTP client certificates. 78 79 <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> 80 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA certificate in PEM 81 format. 82 83 <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> 84 The minimum TLS cipher grade that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server 85 will use with opportunistic TLS encryption. 86 87 <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> 88 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA certificate in PEM 89 format. 90 91 <b><a href="postconf.5.html#tlsproxy_tls_dh1024_param_file">tlsproxy_tls_dh1024_param_file</a> ($<a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a>)</b> 92 File with DH parameters that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server 93 should use with non-export EDH ciphers. 94 95 <b><a href="postconf.5.html#tlsproxy_tls_dh512_param_file">tlsproxy_tls_dh512_param_file</a> ($<a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a>)</b> 96 File with DH parameters that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server 97 should use with export-grade EDH ciphers. 98 99 <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> 100 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA private key in PEM 101 format. 102 103 <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> 104 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA certificate in 105 PEM format. 106 107 <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> 108 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA private key in 109 PEM format. 110 111 <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> 112 The Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server security grade for ephemeral 113 elliptic-curve Diffie-Hellman (EECDH) key exchange. 114 115 <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> 116 List of ciphers or cipher types to exclude from the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> 117 server cipher list at all TLS security levels. 118 119 <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_fingerprint_digest</a>)</b> 120 The message digest algorithm to construct remote SMTP 121 client-certificate fingerprints. 122 123 <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> 124 File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA private key in PEM 125 format. 126 127 <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> 128 Enable additional Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server logging of TLS 129 activity. 130 131 <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_mandatory_ciphers</a>)</b> 132 The minimum TLS cipher grade that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server 133 will use with mandatory TLS encryption. 134 135 <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> 136 <b><a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">tory_exclude_ciphers</a>)</b> 137 Additional list of ciphers or cipher types to exclude from the 138 <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server cipher list at mandatory TLS security levels. 139 140 <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_mandatory_protocols</a>)</b> 141 The SSL/TLS protocols accepted by the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server 142 with mandatory TLS encryption. 143 144 <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> 145 List of TLS protocols that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server will 146 exclude or include with opportunistic TLS encryption. 147 148 <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> 149 With mandatory TLS encryption, require a trusted remote SMTP 150 client certificate in order to allow TLS connections to proceed. 151 152 <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> 153 The SMTP TLS security level for the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server; 154 when a non-empty value is specified, this overrides the obsolete 155 parameters <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>. 156 157 Available in Postfix version 2.11 and later: 158 159 <b><a href="postconf.5.html#tlsmgr_service_name">tlsmgr_service_name</a> (tlsmgr)</b> 160 The name of the <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> service entry in <a href="master.5.html">master.cf</a>. 161 162<b>OBSOLETE STARTTLS SUPPORT CONTROLS</b> 163 These parameters are supported for compatibility with <a href="smtpd.8.html"><b>smtpd</b>(8)</a> legacy 164 parameters. 165 166 <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> 167 Opportunistic TLS: announce STARTTLS support to remote SMTP 168 clients, but do not require that clients use TLS encryption. 169 170 <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> 171 Mandatory TLS: announce STARTTLS support to remote SMTP clients, 172 and require that clients use TLS encryption. 173 174<b>RESOURCE CONTROLS</b> 175 <b><a href="postconf.5.html#tlsproxy_watchdog_timeout">tlsproxy_watchdog_timeout</a> (10s)</b> 176 How much time a <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process may take to process local or 177 remote I/O before it is terminated by a built-in watchdog timer. 178 179<b>MISCELLANEOUS CONTROLS</b> 180 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 181 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 182 figuration files. 183 184 <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> 185 The process ID of a Postfix command or daemon process. 186 187 <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> 188 The process name of a Postfix command or daemon process. 189 190 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 191 The syslog facility of Postfix logging. 192 193 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 194 The mail system name that is prepended to the process name in 195 syslog records, so that "smtpd" becomes, for example, "post- 196 fix/smtpd". 197 198<b>SEE ALSO</b> 199 <a href="postscreen.8.html">postscreen(8)</a>, Postfix zombie blocker 200 <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server 201 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 202 syslogd(5), system logging 203 204<b>LICENSE</b> 205 The Secure Mailer license must be distributed with this software. 206 207<b>HISTORY</b> 208 This service was introduced with Postfix version 2.8. 209 210<b>AUTHOR(S)</b> 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 TLSPROXY(8) 222</pre> </body> </html> 223