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 client- 121 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 TLSPROXY(8) 217</pre> </body> </html> 218