1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Postfix TLS Support </title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 11 12</head> 13 14<body> 15 16<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix TLS Support 17</h1> 18 19<hr> 20 21<h2> WARNING </h2> 22 23<p> By turning on TLS support in Postfix, you not only get the 24ability to encrypt mail and to authenticate remote SMTP clients or servers. 25You also turn on thousands and thousands of lines of OpenSSL library 26code. Assuming that OpenSSL is written as carefully as Wietse's 27own code, every 1000 lines introduce one additional bug into 28Postfix. </p> 29 30<h2> What Postfix TLS support does for you </h2> 31 32<p> Transport Layer Security (TLS, formerly called SSL) provides 33certificate-based authentication and encrypted sessions. An 34encrypted session protects the information that is transmitted with 35SMTP mail or with SASL authentication. </p> 36 37<blockquote> <p> <a name="client_tls_obs"></a> <a 38name="client_tls_harden"></a> NOTE: This document describes a TLS 39user interface that was introduced with Postfix version 2.3. Support 40for an older user interface is documented in <a href="TLS_LEGACY_README.html">TLS_LEGACY_README</a>, 41which also describes the differences between Postfix and the 42third-party patch on which Postfix version 2.2 TLS support was 43based. </p> </blockquote> 44 45<p> Topics covered in this document: </p> 46 47<ul> 48 49<li><a href="#how">How Postfix TLS support works</a> 50 51<li><a href="#server_tls">SMTP Server specific settings</a> 52 53<li> <a href="#client_tls">SMTP Client specific settings</a> 54 55<li><a href="#tlsmgr_controls"> TLS manager specific settings </a> 56 57<li><a href="#build_tls">Building Postfix with TLS support</a> 58 59<li><a href="#problems"> Reporting problems </a> 60 61<li><a href="#credits"> Credits </a> 62 63</ul> 64 65<p> And last but not least, for the impatient: </p> 66 67<ul> 68 69<li><a href="#quick-start">Getting started, quick and dirty</a> 70 71</ul> 72 73<h2><a name="how">How Postfix TLS support works</a></h2> 74 75<p> The diagram below shows the main elements of the Postfix TLS 76architecture and their relationships. Colored boxes with numbered 77names represent Postfix daemon programs. Other colored boxes 78represent storage elements. </p> 79 80<ul> 81 82<li> <p> The <a href="smtpd.8.html">smtpd(8)</a> server implements the SMTP over TLS server 83side. </p> 84 85<li> <p> The <a href="smtp.8.html">smtp(8)</a> client implements the SMTP (and LMTP) over TLS 86client side. </p> 87 88<li> <p> The <a href="tlsmgr.8.html">tlsmgr(8)</a> server maintains the pseudo-random number 89generator (PRNG) that seeds the TLS engines in the <a href="smtpd.8.html">smtpd(8)</a> server 90and <a href="smtp.8.html">smtp(8)</a> client processes, and maintains the TLS session key 91cache files. </p> 92 93</ul> 94 95<p> Not shown in the figure are the <a href="tlsproxy.8.html">tlsproxy(8)</a> server and the 96<a href="postscreen.8.html">postscreen(8)</a> server. These use TLS in the same manner as <a href="smtpd.8.html">smtpd(8)</a>. 97</p> 98 99<table> 100 101<tr> <td>Network<tt>-> </tt> </td> <td align="center" 102bgcolor="#f0f0ff"> <br> <a href="smtpd.8.html">smtpd(8)</a> <br> </td> <td colspan="2"> 103 104<tt> <---seed----<br><br><-key/cert-> </tt> </td> <td 105align="center" bgcolor="#f0f0ff"> <br> <a href="tlsmgr.8.html">tlsmgr(8)</a> <br> </td> 106<td colspan="3"> <tt> ----seed---><br> <br><-key/cert-> 107 108</tt> </td> <td align="center" bgcolor="#f0f0ff"> <br> <a href="smtp.8.html">smtp(8)</a> <br> 109 </td> <td> <tt> -></tt>Network </td> </tr> 110 111<tr> <td colspan="3"> </td> <td align="right"> <table> <tr> <td> 112 113</td> <td> / </td> </tr> <tr> <td> / </td> <td> </td> </tr> </table> 114</td> <td align="center"> |<br> |</td> <td align="left"> <table> 115 116<tr> <td> \ </td> <td> </td> </tr> <tr> <td> </td> <td> \ </td> 117</tr> </table> </td> <td colspan="3"> </td> </tr> 118 119<tr> <td colspan="2"> </td> <td align="center" bgcolor="#f0f0ff"> 120smtpd<br> session<br> key cache </td> <td> </td> <td align="center" 121bgcolor="#f0f0ff"> PRNG<br> state <br>file </td> <td> </td> <td 122align="center" bgcolor="#f0f0ff"> smtp<br> session<br> key cache 123</td> 124 125<td colspan="2"> </td> </tr> 126 127</table> 128 129<h2><a name="server_tls">SMTP Server specific settings</a></h2> 130 131<p> Topics covered in this section: </p> 132 133<ul> 134 135<li><a href="#server_cert_key">Server-side certificate and private 136key configuration </a> 137 138<li><a href="#server_logging"> Server-side TLS activity logging 139</a> 140 141<li><a href="#server_enable">Enabling TLS in the Postfix SMTP server </a> 142 143<li><a href="#server_vrfy_client">Client certificate verification</a> 144 145<li><a href="#server_tls_auth">Supporting AUTH over TLS only</a> 146 147<li><a href="#server_tls_cache">Server-side TLS session cache</a> 148 149<li><a href="#server_access">Server access control</a> 150 151<li><a href="#server_cipher">Server-side cipher controls</a> 152 153<li><a href="#server_misc"> Miscellaneous server controls</a> 154 155</ul> 156 157<h3><a name="server_cert_key">Server-side certificate and private 158key configuration </a> </h3> 159 160<p> In order to use TLS, the Postfix SMTP server generally needs 161a certificate and a private key. Both must be in "PEM" format. The 162private key must not be encrypted, meaning: the key must be accessible 163without a password. The certificate and private key may be in the same 164file, in which case the certificate file should be owned by "root" and 165not be readable by any other user. If the key is stored separately, 166this access restriction applies to the key file only, and the 167certificate file may be "world-readable". </p> 168 169<p> Public Internet MX hosts without certificates signed by a 170well-known public CA must still generate, and be prepared to present 171to most clients, a self-signed or private-CA signed certificate. 172The remote SMTP client will generally not be able to verify the 173self-signed certificate, but unless the client is running Postfix 174or similar software, it will only negotiate TLS ciphersuites that 175require a server certificate. </p> 176 177<p> For servers that are <b>not</b> public Internet MX hosts, Postfix 178supports configurations with no certificates. This entails the 179use of just the anonymous TLS ciphers, which are not supported by 180typical SMTP clients. Since such clients will not, as a rule, fall 181back to plain text after a TLS handshake failure, a certificate-less 182Postfix SMTP server will 183be unable to receive email from most TLS enabled clients. To avoid 184accidental configurations with no certificates, Postfix enables 185certificate-less operation only when the administrator explicitly sets 186"<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = none". This ensures that new Postfix 187SMTP server configurations will not accidentally run with no 188certificates. </p> 189 190<p> RSA, DSA and ECDSA (Postfix ≥ 2.6) certificates are supported. 191Most sites only have RSA certificates. You can configure all three 192at the same time, in which case the ciphersuite negotiated with the 193remote SMTP client determines which certificate is used. If your 194DNS zone is signed, and you want to publish <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> TLSA records, 195these must match any of the configured certificates. Since the 196best practice is to publish "3 1 1" certificate associations, create 197a separate TLSA record for each public-key certificate digest. </p> 198 199<h4> Creating the server certificate file </h4> 200 201<p> To verify the Postfix SMTP server certificate, the remote SMTP 202client must receive the issuing CA certificates via the TLS handshake 203or via public-key infrastructure. This means that the Postfix server 204public-key certificate file must include the server certificate 205first, then the issuing CA(s) (bottom-up order). The Postfix SMTP 206server certificate must be usable as SSL server certificate and 207hence pass the "<tt>openssl verify -purpose sslserver ...</tt>" test. 208</p> 209 210<p> The examples that follow show how to create a server certificate 211file. We assume that the certificate for "server.example.com" was 212issued by "intermediate CA" which itself has a certificate issued 213by "root CA". </p> 214 215<ul> 216 217<li> <p> With legacy public CA trust verification, you can omit the 218root certificate from the "server.pem" certificate file. If the 219client trusts the root CA, it will already have a local copy of the 220root CA certificate. Omitting the root CA certificate reduces the 221size of the server TLS handshake. </p> 222 223<blockquote> 224<pre> 225% <b>cat server_cert.pem intermediate_CA.pem > server.pem</b> 226</pre> 227</blockquote> 228 229<li> <p> If you publish <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> TLSA "2 0 1" or "2 1 1" records to 230specify root CA certificate digests, you must include the corresponding 231root CA certificates in the "server.pem" certificate file. See the 232documentation of the <a href="postconf.5.html#tls_dane_trust_anchor_digest_enable">tls_dane_trust_anchor_digest_enable</a> <a href="postconf.5.html">main.cf</a> 233parameter. </p> 234 235<blockquote> 236<pre> 237% <b>cat server_cert.pem intermediate_CA.pem root.pem > server.pem</b> 238</pre> 239</blockquote> 240 241<p> Remote SMTP clients will be able to use the TLSA record you 242publish (which only contains the certificate digest) only if they 243have access to the corresponding certificate. Failure to verify 244certificates per the server's published TLSA records will typically 245cause the SMTP client to defer mail delivery. The foregoing also 246applies to "2 0 2" and "2 1 2" TLSA records or any other digest of 247a CA certificate, but it is expected that SHA256 will be by far the 248most common digest for TLSA. </p> 249 250<p> As a best practice, publish either "3 0 1" or "3 1 1" TLSA 251associations that specify the SHA256 digest of the server certificate 252public key with the alias-expanded hostname of each STARTTLS capable 253SMTP server. These continue to work when a certificate is renewed 254with the same public/private key pair. </p> 255 256</ul> 257 258<p> For instructions on how to compute the digest of a certificate 259or its public key for use in TLSA records, see the documentation of 260the <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> <a href="postconf.5.html">main.cf</a> parameter. </p> 261 262<p> When a new key or certificate is generated, an additional TLSA 263record with the new digest must be published in advance of the 264actual deployment of the new key or certificate on the server. You 265must allow sufficient time for any TLSA RRsets with only the old 266digest to expire from DNS caches. The safest practice is to wait 267until the DNSSEC signature on the previous TLSA RRset expires, and 268only then switch the server to use new keys published in the updated 269TLSA RRset. Once the new certificate trust chain and private key 270are in effect, the DNS should be updated once again to remove the 271old digest from the TLSA RRset. </p> 272 273<p> If you want the Postfix SMTP server to accept remote SMTP client 274certificates issued by one or more root CAs, append the root 275certificate to $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> 276directory. </p> 277 278<h4> Configuring the server certificate and key files </h4> 279 280<p> RSA key and certificate examples: </p> 281 282<blockquote> 283<pre> 284/etc/postfix/<a href="postconf.5.html">main.cf</a>: 285 <a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/server.pem 286 <a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = $<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> 287</pre> 288</blockquote> 289 290<p> Their DSA counterparts: </p> 291 292<blockquote> 293<pre> 294/etc/postfix/<a href="postconf.5.html">main.cf</a>: 295 <a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a> = /etc/postfix/server-dsa.pem 296 <a href="postconf.5.html#smtpd_tls_dkey_file">smtpd_tls_dkey_file</a> = $<a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a> 297</pre> 298</blockquote> 299 300<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 1.0.0): </p> 301 302<blockquote> 303<pre> 304/etc/postfix/<a href="postconf.5.html">main.cf</a>: 305 # Most clients will not be ECDSA capable, so you will likely also need 306 # an RSA or DSA certificate and private key. 307 # 308 <a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> = /etc/postfix/server-ecdsa.pem 309 <a href="postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file</a> = $<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> 310</pre> 311</blockquote> 312 313<p> TLS without certificates for servers serving exclusively 314anonymous-cipher capable clients: </p> 315 316<blockquote> 317<pre> 318/etc/postfix/<a href="postconf.5.html">main.cf</a>: 319 <a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = none 320</pre> 321</blockquote> 322 323<p> To verify a remote SMTP client certificate, the Postfix SMTP 324server needs to trust the certificates of the issuing certification 325authorities. These certificates in "PEM" format can be stored in a 326single $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> or in multiple files, one CA per file in 327the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> directory. If you use a directory, don't forget 328to create the necessary "hash" links with: </p> 329 330<blockquote> 331<pre> 332# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b> 333</pre> 334</blockquote> 335 336<p> The $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> contains the CA certificates of one or 337more trusted CAs. The file is opened (with root privileges) before 338Postfix enters the optional chroot jail and so need not be accessible 339from inside the chroot jail. </p> 340 341<p> Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> 342directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a> 343privileges) from the files in the directory when the information 344is needed. Thus, the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> directory needs to be 345accessible inside the optional chroot jail. </p> 346 347<p> When you configure the Postfix SMTP server to request <a 348href="#server_vrfy_client">client certificates</a>, the DNs of certificate 349authorities in $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> are sent to the client, in order to allow 350it to choose an identity signed by a CA you trust. If no $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> 351is specified, no preferred CA list is sent, and the client is free to 352choose an identity signed by any CA. Many clients use a fixed identity 353regardless of the preferred CA list and you may be able to reduce TLS 354negotiation overhead by installing client CA certificates mostly or 355only in $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>. In the latter case you need not specify a 356$<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>. </p> 357 358<p> Note, that unless client certificates are used to allow greater 359access to TLS authenticated clients, it is best to not ask for 360client certificates at all, as in addition to increased overhead 361some clients (notably in some cases qmail) are unable to complete 362the TLS handshake when client certificates are requested. </p> 363 364<p> Example: </p> 365<blockquote> 366<pre> 367/etc/postfix/<a href="postconf.5.html">main.cf</a>: 368 <a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> = /etc/postfix/CAcert.pem 369 <a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> = /etc/postfix/certs 370</pre> 371</blockquote> 372 373<h3><a name="server_logging"> Server-side TLS activity logging </a> </h3> 374 375<p> To get additional information about Postfix SMTP server TLS 376activity you can increase the log level from 0..4. Each logging 377level also includes the information that is logged at a lower 378logging level. </p> 379 380<blockquote> 381 382<table border="1"> 383 384<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier 385releases. </th> </tr> 386 387<tr> <td valign="top"> 0 </td> <td valign="top" colspan="2"> Disable 388logging of TLS activity. </td> </tr> 389 390<tr> <td valign="top"> 1 </td> <td valign="top"> Log only a summary 391message on TLS handshake completion — no logging of client 392certificate trust-chain verification errors if client certificate 393verification is not required. </td> <td valign="top"> Log the summary 394message, peer certificate summary information and unconditionally log 395trust-chain verification errors. </td> </tr> 396 397<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also 398log levels during TLS negotiation. </td> </tr> 399 400<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also 401log hexadecimal and ASCII dump of TLS negotiation process. </td> 402</tr> 403 404<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also 405log hexadecimal and ASCII dump of complete transmission after 406STARTTLS. </td></tr> 407 408</table> 409 410</blockquote> 411 412<p> Use log level 3 only in case of problems. Use of log level 4 is 413strongly discouraged. </p> 414 415<p> Example: </p> 416 417<blockquote> 418<pre> 419/etc/postfix/<a href="postconf.5.html">main.cf</a>: 420 <a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 0 421</pre> 422</blockquote> 423 424<p> To include information about the protocol and cipher used as 425well as the client and issuer CommonName into the "Received:" 426message header, set the <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> variable to true. 427The default is no, as the information is not necessarily authentic. 428Only information recorded at the final destination is reliable, 429since the headers may be changed by intermediate servers. </p> 430 431<p> Example: </p> 432 433<blockquote> 434<pre> 435/etc/postfix/<a href="postconf.5.html">main.cf</a>: 436 <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = yes 437</pre> 438</blockquote> 439 440<h3><a name="server_enable">Enabling TLS in the Postfix SMTP server </a> </h3> 441 442<p> By default, TLS is disabled in the Postfix SMTP server, so no 443difference to plain Postfix is visible. Explicitly switch it on 444with "<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may". </p> 445 446<p> Example: </p> 447 448<blockquote> 449<pre> 450/etc/postfix/<a href="postconf.5.html">main.cf</a>: 451 <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may 452</pre> 453</blockquote> 454 455<p> With this, the Postfix SMTP server announces STARTTLS support to 456remote SMTP clients, but does not require that clients use TLS encryption. 457</p> 458 459<p> Note: when an unprivileged user invokes "sendmail -bs", STARTTLS 460is never offered due to insufficient privileges to access the Postfix 461SMTP server 462private key. This is intended behavior. </p> 463 464<p> <a name="server_enforce">You can ENFORCE the use of TLS</a>, 465so that the Postfix SMTP server announces STARTTLS and accepts no 466mail without TLS encryption, by setting 467"<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt". According to <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> this 468MUST NOT be applied in case 469of a publicly-referenced Postfix SMTP server. This option is off 470by default and should only seldom be used. </p> 471 472<p> Example: </p> 473 474<blockquote> 475<pre> 476/etc/postfix/<a href="postconf.5.html">main.cf</a>: 477 <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt 478</pre> 479</blockquote> 480 481<p> TLS is sometimes used in the non-standard "wrapper" mode where 482a server always uses TLS, instead of announcing STARTTLS support 483and waiting for remote SMTP clients to request TLS service. Some 484clients, namely 485Outlook [Express] prefer the "wrapper" mode. This is true for OE 486(Win32 < 5.0 and Win32 >=5.0 when run on a port<>25 487and OE (5.01 Mac on all ports). </p> 488 489<p> It is strictly discouraged to use this mode from <a href="postconf.5.html">main.cf</a>. If 490you want to support this service, enable a special port in <a href="master.5.html">master.cf</a> 491and specify "-o <a href="postconf.5.html#smtpd_tls_wrappermode">smtpd_tls_wrappermode</a>=yes" (note: no space around 492the "=") as an <a href="smtpd.8.html">smtpd(8)</a> command line option. Port 465 (smtps) was 493once chosen for this feature. 494</p> 495 496<p> Example: </p> 497 498<blockquote> 499<pre> 500/etc/postfix/<a href="master.5.html">master.cf</a>: 501 smtps inet n - n - - smtpd 502 -o <a href="postconf.5.html#smtpd_tls_wrappermode">smtpd_tls_wrappermode</a>=yes -o <a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a>=yes 503</pre> 504</blockquote> 505 506<h3><a name="server_vrfy_client">Client certificate verification</a> </h3> 507 508<p> To receive a remote SMTP client certificate, the Postfix SMTP 509server must explicitly ask for one (any contents of $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> 510are also sent to the client as a hint for choosing a certificate from 511a suitable CA). Unfortunately, Netscape clients will either complain 512if no matching client certificate is available or will offer the user 513client a list of certificates to choose from. Additionally some MTAs 514(notably some versions of qmail) are unable to complete TLS negotiation 515when client certificates are requested, and abort the SMTP session. So 516this option is "off" by default. You will however need the certificate 517if you want to use certificate based relaying with, for example, the 518<a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> feature. A server that wants client certificates 519must first present its own certificate. While Postfix by default 520offers anonymous ciphers to remote SMTP clients, these are automatically 521suppressed 522when the Postfix SMTP server is configured to ask for client 523certificates. </p> 524 525<p> Example: </p> 526 527<blockquote> 528<pre> 529/etc/postfix/<a href="postconf.5.html">main.cf</a>: 530 <a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes 531 <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may 532</pre> 533</blockquote> 534 535<p> When TLS is <a href="#server_enforce">enforced</a> you may also decide 536to REQUIRE a remote SMTP client certificate for all TLS connections, 537by setting "<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes". This feature implies 538"<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes". When TLS is not enforced, 539"<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes" is ignored and a warning is 540logged. </p> 541 542<p> Example: </p> 543 544<blockquote> 545<pre> 546/etc/postfix/<a href="postconf.5.html">main.cf</a>: 547 <a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes 548 <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt 549</pre> 550</blockquote> 551 552<p> The client certificate verification depth is specified with the 553<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> parameter. The default verification 554depth is 9 (the OpenSSL default), for compatibility with Postfix 555versions before 2.5 where <a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> was ignored. 556When you configure trust in a 557root CA, it is not necessary to explicitly trust intermediary CAs signed 558by the root CA, unless $<a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> is less than the 559number of CAs in the certificate chain for the clients of interest. With 560a verify depth of 1 you can only verify certificates directly signed 561by a trusted CA, and all trusted intermediary CAs need to be configured 562explicitly. With a verify depth of 2 you can verify clients signed by a 563root CA or a direct intermediary CA (so long as the client is correctly 564configured to supply its intermediate CA certificate). </p> 565 566<p> Example: </p> 567 568<blockquote> 569<pre> 570/etc/postfix/<a href="postconf.5.html">main.cf</a>: 571 <a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> = 2 572</pre> 573</blockquote> 574 575<h3><a name="server_tls_auth">Supporting AUTH over TLS only</a></h3> 576 577<p> Sending AUTH data over an unencrypted channel poses a security 578risk. When TLS layer encryption is required 579("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt"), the Postfix SMTP server will 580announce and accept AUTH only after the TLS layer has been activated 581with STARTTLS. When TLS layer encryption is optional 582("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may"), it may however still be useful 583to only offer AUTH when TLS is active. To maintain compatibility 584with non-TLS clients, the default is to accept AUTH without encryption. 585In order to change this behavior, set 586"<a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = yes". </p> 587 588<p> Example: </p> 589 590<blockquote> 591<pre> 592/etc/postfix/<a href="postconf.5.html">main.cf</a>: 593 <a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = no 594</pre> 595</blockquote> 596 597<h3><a name="server_tls_cache">Server-side TLS session cache</a> </h3> 598 599<p> The Postfix SMTP server and the remote SMTP client negotiate a 600session, which takes some computer time and network bandwidth. SSL 601protocol versions other than SSLv2 support resumption of cached 602sessions. Not only is this more CPU and bandwidth efficient, it 603also reduces latency as only one network round-trip is used to 604resume a session while it takes two round-trips to create a session 605from scratch. </p> 606 607<p> Since Postfix uses multiple <a href="smtpd.8.html">smtpd(8)</a> service processes, an 608in-memory cache is not sufficient for session re-use. Clients store 609at most one cached session per server and are very unlikely to 610repeatedly connect to the same server process. Thus session caching 611in the Postfix SMTP server generally requires a shared cache (an 612alternative available with Postfix ≥ 2.11 is described below). 613</p> 614 615<p> To share the session information between multiple 616<a href="smtpd.8.html">smtpd(8)</a> processes, a session cache database is used. You 617can specify any database type that can store objects of several 618kbytes and that supports the sequence operator. DBM databases are 619not suitable because they can only store small objects. The cache 620is maintained by the <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there is no problem with 621concurrent access. Session caching is highly recommended, because 622the cost of repeatedly negotiating TLS session keys is high.</p> 623 624<p> Starting with Postfix 2.11, linked with a compatible OpenSSL 625library (at least 0.9.8h, preferably 1.0.0 or later) the Postfix 626SMTP server supports <a href="http://tools.ietf.org/html/rfc5077">RFC 5077</a> TLS session resumption without 627server-side state when the remote SMTP client also supports <a href="http://tools.ietf.org/html/rfc5077">RFC</a> 628<a href="http://tools.ietf.org/html/rfc5077">5077</a>. The session is encrypted by the server in a <i>session 629ticket</i> returned to client for storage. When a client sends a 630valid session ticket, the server decrypts it and resumes the session, 631provided neither the ticket nor the session have expired. This 632makes it possible to resume cached sessions without allocating space 633for a shared database on the server. This feature can be disabled 634by setting the session cache timeout to zero, otherwise the timeout 635must be at least 2 minutes and at most 100 days. </p> 636 637<p> Note, session tickets can only be negotiated if the client 638disables SSLv2 and does not use the legacy SSLv2 compatible HELLO 639message. This is true by default with the Postfix ≥ 2.6 SMTP 640client. </p> 641 642<p> Example: </p> 643 644<blockquote> 645<pre> 646/etc/postfix/<a href="postconf.5.html">main.cf</a>: 647 <a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> = <a href="DATABASE_README.html#types">btree</a>:/var/db/postfix/smtpd_scache 648</pre> 649</blockquote> 650 651<p> Note: as of version 2.5, Postfix no longer uses root privileges 652when opening this file. The file should now be stored under the 653Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to 654open the file under a non-Postfix directory is redirected to the 655Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. </p> 656 657<p> Cached Postfix SMTP server session information expires after 658a certain amount of time. Postfix/TLS does not use the OpenSSL 659default of 300s, but a longer time of 3600sec (=1 hour). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a> 660recommends a maximum of 24 hours. </p> 661 662<p> Example: </p> 663 664<blockquote> 665<pre> 666/etc/postfix/<a href="postconf.5.html">main.cf</a>: 667 <a href="postconf.5.html#smtpd_tls_session_cache_timeout">smtpd_tls_session_cache_timeout</a> = 3600s 668</pre> 669</blockquote> 670 671<p> As of Postfix 2.11 this setting cannot exceed 100 days. If set 672≤ 0, session caching is disabled. If set to a positive value 673less than 2 minutes, the minimum value of 2 minutes is used instead. </p> 674 675<p> When the Postfix SMTP server does not save TLS sessions to an 676external cache database, client-side session caching is unlikely 677to be useful. To reduce waste of client resources, the Postfix SMTP server can 678be configured to not issue TLS session ids. By default the Postfix 679SMTP server always issues TLS session ids. This works around known 680interoperability issues with some MUAs, and prevents possible 681interoperability issues with other MTAs. </p> 682 683<p> Example: </p> 684 685<blockquote> 686<pre> 687 <a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_session_ids</a> = no 688</pre> 689</blockquote> 690 691<h3><a name="server_access">Server access control</a> </h3> 692 693<p> Postfix TLS support introduces three additional features for 694Postfix SMTP server access control: </p> 695 696<blockquote> 697 698<dl> 699 700<dt> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </dt> <dd> <p> Allow the remote SMTP 701client request if the client certificate fingerprint or certificate 702public key fingerprint (Postfix 2.9 and later) is listed in the 703client certificate table (see <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below). 704</p> </dd> 705 706<dt> <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> </dt> <dd> <p> Allow the remote SMTP 707client request if the client certificate passes trust chain verification. 708Useful with private-label CAs that only issue certificates to trusted 709clients (and not otherwise). </p> </dd> 710 711<dt> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd> <p> Use the remote 712SMTP client certificate fingerprint or public key fingerprint 713(Postfix 2.9 and later) as the lookup key for the specified <a href="access.5.html">access(5)</a> 714table. </p> </dd> 715 716</dl> 717 718</blockquote> 719 720<p> The digest algorithm used to compute the client certificate 721fingerprints is specified with the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> 722parameter. The default is "md5", for compatibility with Postfix 723versions < 2.5. </p> 724 725<p> The <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> feature must be used with caution, 726because it can result in too many access permissions. Use this 727feature only if a special CA issues the client certificates, and 728only if this CA is listed as trusted CA. If other CAs are trusted, 729any owner of a valid client certificate would be authorized. 730The <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> feature can be practical for a 731specially created email relay server. </p> 732 733<p> It is however recommended to stay with the <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> 734feature and list all certificates via $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>, as 735<a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> does not permit any control when a 736certificate must no longer be used (e.g. an employee leaving). </p> 737 738<p> Example: </p> 739 740<blockquote> 741<pre> 742# With Postfix 2.10 and later, the mail relay policy is 743# preferably specified under <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>. 744/etc/postfix/<a href="postconf.5.html">main.cf</a>: 745 <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> = 746 <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a> 747 <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> 748 <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> 749</pre> 750 751<pre> 752# Older configurations combine relay control and spam control under 753# <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a>. To use this example with Postfix ≥ 754# 2.10 specify "<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=". 755/etc/postfix/<a href="postconf.5.html">main.cf</a>: 756 <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = 757 <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a> 758 <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> 759 <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> 760 ...other rules... 761</pre> 762</blockquote> 763 764<p> Example: Postfix lookup tables are in the form of (key, value) 765pairs. Since we only need the key, the value can be chosen freely, e.g. 766the name of the user or host:</p> 767 768<blockquote> 769<pre> 770/etc/postfix/<a href="postconf.5.html">main.cf</a>: 771 <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/relay_clientcerts 772 773/etc/postfix/relay_clientcerts: 774 D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home 775</pre> 776</blockquote> 777 778<p> To extract the public key fingerprint from an X.509 certificate, 779you need to extract the public key from the certificate and compute 780the appropriate digest of its DER (ASN.1) encoding. With OpenSSL 781the "-pubkey" option of the "x509" command extracts the public 782key always in "PEM" format. We pipe the result to another OpenSSL 783command that converts the key to DER and then to the "dgst" command 784to compute the fingerprint. </p> 785 786<p> The actual command to transform the key to DER format depends 787on the version of OpenSSL used. With OpenSSL 1.0.0 and later, the 788"pkey" command supports all key types. With OpenSSL 0.9.8 and 789earlier, the key type is always RSA (nobody uses DSA, and EC 790keys are not fully supported by 0.9.8), so the "rsa" command is 791used. </p> 792<blockquote> 793<pre> 794# OpenSSL 1.0 with all certificates and SHA-1 fingerprints. 795$ openssl x509 -in cert.pem -noout -pubkey | 796 openssl pkey -pubin -outform DER | 797 openssl dgst -sha1 -c 798(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58 799 800# OpenSSL 0.9.8 with RSA certificates and MD5 fingerprints. 801$ openssl x509 -in cert.pem -noout -pubkey | 802 openssl rsa -pubin -outform DER | 803 openssl dgst -md5 -c 804(stdin)= f4:62:60:f6:12:8f:d5:8d:28:4d:13:a7:db:b2:ff:50 805</pre> 806</blockquote> 807<p> Note: Postfix 2.9.0–2.9.5 computed the public key 808fingerprint incorrectly. To use public-key fingerprints, upgrade 809to Postfix 2.9.6 or later. </p> 810 811<h3><a name="server_cipher">Server-side cipher controls</a> </h3> 812 813<p> The Postfix SMTP server supports 5 distinct cipher security levels 814as specified by the <a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a> configuration parameter, 815which determines the cipher grade with mandatory TLS encryption. The 816default value is "medium" which is essentially 128-bit encryption or better. 817With opportunistic TLS encryption, the minimum accepted cipher grade is 818typically "export". The corresponding <a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a> parameter 819(Postfix ≥ 2.6) controls the cipher grade used with opportunistic 820TLS. </p> 821 822<p> By default anonymous ciphers are enabled. They are automatically 823disabled when remote SMTP client certificates are requested. If 824clients are expected to always verify the Postfix SMTP 825server certificate you may want to disable anonymous ciphers 826by setting "<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL" or 827"<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> = aNULL", as appropriate. One can't force 828a remote SMTP client to check the server certificate, so excluding 829anonymous ciphers is generally unnecessary. </p> 830 831<p> The "<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a>" configuration parameter (Postfix ≥ 8322.6) provides control over the minimum cipher grade for opportunistic 833TLS. With 834Postfix < 2.6, the minimum opportunistic TLS cipher grade is always 835"export". </p> 836 837<p> With mandatory TLS encryption, the Postfix SMTP server will by 838default disable SSLv2. SSLv2 is used only when TLS encryption 839is optional. The mandatory TLS protocol list is specified via the 840<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> configuration parameter. The 841corresponding <a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a> parameter (Postfix ≥ 2.6) 842controls the SSL/TLS protocols used with opportunistic TLS. </p> 843 844<p> Note that the OpenSSL library only supports protocol exclusion 845(not inclusion). For this reason, Postfix can exclude only protocols 846that are known at the time the Postfix software is written. If new 847protocols are added to the OpenSSL library, they cannot be excluded 848without corresponding changes to the Postfix source code. </p> 849 850<p> For a server that is not a public Internet MX host, Postfix 851supports configurations with no <a href="#server_cert_key">server 852certificates</a> that use <b>only</b> the anonymous ciphers. This is 853enabled by explicitly setting "<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = none" 854and not specifying an <a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a> or <a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>. </p> 855 856<p> Example, MSA that requires TLSv1 or higher, not SSLv2 or SSLv3, 857with high grade ciphers: </p> 858 859<blockquote> 860<pre> 861/etc/postfix/<a href="postconf.5.html">main.cf</a>: 862 <a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/cert.pem 863 <a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = /etc/postfix/key.pem 864 <a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a> = high 865 <a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL, MD5 866 <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt 867 # Preferred syntax with Postfix ≥ 2.5: 868 <a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> = !SSLv2, !SSLv3 869 # Legacy syntax: 870 <a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> = TLSv1 871</pre> 872</blockquote> 873 874<p> If you want to take maximal advantage of ciphers that offer <a 875href="FORWARD_SECRECY_README.html#dfn_fs">forward secrecy</a> see 876the <a href="FORWARD_SECRECY_README.html#quick-start">Getting 877started</a> section of <a 878href="FORWARD_SECRECY_README.html">FORWARD_SECRECY_README</a>. The 879full document conveniently presents all information about Postfix 880"perfect" forward secrecy support in one place: what forward secrecy 881is, how to tweak settings, and what you can expect to see when 882Postfix uses ciphers with forward secrecy. </p> 883 884<p> Postfix 2.8 and later, in combination with OpenSSL 0.9.7 and later 885allows TLS servers to preempt the TLS client's cipher-suite preference list. 886This is possible only with SSLv3 and later, as in SSLv2 the client 887chooses the cipher-suite from a list supplied by the server. </p> 888 889<p> By default, the OpenSSL server selects the client's most preferred 890cipher-suite that the server supports. With SSLv3 and later, the server 891may choose its own most preferred cipher-suite that is supported (offered) 892by the client. Setting "<a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> = yes" enables server 893cipher-suite preferences. The default OpenSSL behavior applies with 894"<a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> = no". </p> 895 896<p> While server cipher-suite selection may in some cases lead to 897a more secure or performant cipher-suite choice, there is some risk 898of interoperability issues. In the past, some SSL clients have 899listed lower priority ciphers that they did not implement correctly. 900If the server chooses a cipher that the client prefers less, it may 901select a cipher whose client implementation is flawed. Most notably 902Windows 2003 Microsoft Exchange servers have flawed implementations 903of DES-CBC3-SHA, which OpenSSL considers stronger than RC4-SHA. 904Enabling server cipher-suite selection may create interoperability 905issues with Windows 2003 Microsoft Exchange clients. </p> 906 907<h3><a name="server_misc"> Miscellaneous server controls</a> </h3> 908 909<p> The <a href="postconf.5.html#smtpd_starttls_timeout">smtpd_starttls_timeout</a> parameter limits the time of Postfix 910SMTP server write and read operations during TLS startup and shutdown 911handshake procedures. </p> 912 913<p> Example: </p> 914 915<blockquote> 916<pre> 917/etc/postfix/<a href="postconf.5.html">main.cf</a>: 918 <a href="postconf.5.html#smtpd_starttls_timeout">smtpd_starttls_timeout</a> = 300s 919</pre> 920</blockquote> 921 922<p> With Postfix 2.8 and later, the <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> parameter 923specifies a list or bit-mask of OpenSSL bug work-arounds to disable. This 924may be necessary if one of the work-arounds enabled by default in 925OpenSSL proves to pose a security risk, or introduces an unexpected 926interoperability issue. Some bug work-arounds known to be problematic 927are disabled in the default value of the parameter when linked with 928an OpenSSL library that could be vulnerable. </p> 929 930<p> Example: </p> 931 932<blockquote> 933<pre> 934/etc/postfix/<a href="postconf.5.html">main.cf</a>: 935 <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = 0xFFFFFFFF 936 <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = CVE-2010-4180 937</pre> 938</blockquote> 939 940<p> With Postfix ≥ 2.11, the tls_ssl_options parameter specifies 941a list or bit-mask of OpenSSL options to enable. Specify one or 942more of the named options below, or a hexadecimal bitmask of options 943found in the ssl.h file corresponding to the run-time OpenSSL 944library. While it may be reasonable to turn off all bug workarounds 945(see above), it is not a good idea to attempt to turn on all features. 946</p> 947 948<dl> 949 950<dt><b>LEGACY_SERVER_CONNECT</b></dt> <dd>See SSL_CTX_set_options(3).</dd> 951 952<dt><b>NO_TICKET</b></dt> <dd>See SSL_CTX_set_options(3).</dd> 953 954<dt><b>NO_COMPRESSION</b></dt> <dd>Disable SSL compression even if 955supported by the OpenSSL library. Compression is CPU-intensive, 956and compression before encryption does not always improve security. </dd> 957 958</dl> 959 960<p> Example: </p> 961 962<blockquote> 963<pre> 964/etc/postfix/<a href="postconf.5.html">main.cf</a>: 965 tls_ssl_options = no_ticket, no_compression 966</pre> 967</blockquote> 968 969<p> You should only enable features via the hexadecimal mask when 970the need to control the feature is critical (to deal with a new 971vulnerability or a serious interoperability problem). Postfix DOES 972NOT promise backwards compatible behavior with respect to the mask 973bits. A feature enabled via the mask in one release may be enabled 974by other means in a later release, and the mask bit will then be 975ignored. Therefore, use of the hexadecimal mask is only a temporary 976measure until a new Postfix or OpenSSL release provides a better 977solution. </p> 978 979<h2> <a name="client_tls">SMTP Client specific settings</a> </h2> 980 981<p> Topics covered in this section: </p> 982 983<ul> 984 985<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a> 986 987<li><a href="#client_logging"> Client-side TLS activity logging </a> 988 989<li><a href="#client_cert_key">Client-side certificate and private 990key configuration </a> 991 992<li><a href="#client_tls_cache">Client-side TLS session cache</a> 993 994<li><a href="#client_tls_limits"> Client TLS limitations </a> 995 996<li><a href="#client_tls_policy"> Per-destination TLS policy </a> 997 998<li><a href="#client_tls_discover"> Discovering servers that support TLS </a> 999 1000<li><a href="#client_vrfy_server">Server certificate verification depth</a> 1001 1002<li> <a href="#client_cipher">Client-side cipher controls </a> 1003 1004<li> <a href="#client_smtps">Client-side SMTPS support </a> 1005 1006<li> <a href="#client_misc"> Miscellaneous client controls </a> 1007 1008</ul> 1009 1010<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a> 1011</h3> 1012 1013<p> Similar to the Postfix SMTP server, the Postfix SMTP/LMTP client 1014implements multiple TLS security levels. These levels are described 1015in more detail in the sections that follow.</p> 1016 1017<dl> 1018<dt><b>none</b></dt> 1019<dd><a href="#client_tls_none">No TLS.</a></dd> 1020<dt><b>may</b></dt> 1021<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd> 1022<dt><b>encrypt</b></dt> 1023<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a> 1024<dt><b>dane</b></dt> 1025<dd><a href="#client_tls_dane">Opportunistic DANE TLS.</a> 1026<dt><b>dane-only</b></dt> 1027<dd><a href="#client_tls_dane">Mandatory DANE TLS.</a> 1028<dt><b>fingerprint</b></dt> 1029<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a> 1030<dt><b>verify</b></dt> 1031<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a> 1032<dt><b>secure</b></dt> 1033<dd><a href="#client_tls_secure">Secure-channel TLS.</a> 1034</dl> 1035 1036<h4><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a> </h4> 1037 1038<p> The <a href="smtp.8.html">smtp(8)</a> and <a href="lmtp.8.html">lmtp(8)</a> delivery agents are implemented by a 1039single dual-purpose program. Specifically, all the TLS features 1040described below apply 1041equally to SMTP and LMTP, after replacing the "smtp_" prefix of the each 1042parameter name with "lmtp_". 1043 1044<p> The Postfix LMTP delivery agent can communicate with LMTP servers 1045listening 1046on UNIX-domain sockets. When server certificate verification is enabled 1047and the server is listening on a UNIX-domain socket, the $<a href="postconf.5.html#myhostname">myhostname</a> 1048parameter is used to set the TLS verification <i>nexthop</i> and 1049<i>hostname</i>. </p> 1050 1051<p> NOTE: Opportunistic encryption of LMTP traffic over UNIX-domain 1052sockets or loopback TCP connections is futile. TLS is only useful 1053in this context when 1054it is mandatory, typically to allow at least one of the server or the 1055client to authenticate the other. The "null" cipher grade may be 1056appropriate in this context, when available on both client and server. 1057The "null" ciphers provide authentication without encryption. </p> 1058 1059<h4><a name="client_tls_none"> No TLS encryption </a> </h4> 1060 1061<p> At the "none" TLS security level, TLS encryption is 1062disabled. This is the default security level, and 1063can be configured explicitly by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = none". 1064For LMTP, use the corresponding "lmtp_" parameter. </p> 1065 1066<p> Per-destination settings may override this default setting, in which case 1067TLS is used selectively, only with destinations explicitly configured 1068for TLS. </p> 1069 1070<p> You can disable TLS for a subset of destinations, while leaving 1071it enabled for the rest. With the Postfix TLS <a 1072href="#client_tls_policy">policy table</a>, specify the "none" 1073security level. 1074 1075<h4><a name="client_tls_may"> Opportunistic TLS </a> </h4> 1076 1077<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>. 1078The SMTP transaction is encrypted if the STARTTLS ESMTP feature 1079is supported by the server. Otherwise, messages are sent in the clear. 1080Opportunistic TLS can be configured by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may". 1081For LMTP, use the corresponding "lmtp_" parameter. </p> 1082 1083<p> Since sending in the clear is acceptable, demanding stronger 1084than default TLS security mostly reduces inter-operability. If you 1085must restrict TLS protocol or cipher selection even with opportunistic 1086TLS, the "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>" and "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>" configuration 1087parameters (Postfix ≥ 2.6) provide control over the protocols 1088and cipher grade 1089used with opportunistic TLS. With earlier releases the opportunistic TLS 1090cipher grade is always "export" and no protocols are disabled. </p> 1091 1092<p> With opportunistic TLS, mail delivery continues even if the 1093server certificate is untrusted or bears the wrong name. 1094When the TLS handshake fails for an opportunistic 1095TLS session, rather than give up on mail delivery, the Postfix SMTP 1096client retries the transaction 1097with TLS disabled. Trying an unencrypted connection makes 1098it possible to deliver mail to sites with non-interoperable server 1099TLS implementations. </p> 1100 1101<p> Opportunistic encryption is never used for LMTP over UNIX-domain 1102sockets. The communications channel is already confidential without 1103TLS, so the only potential benefit of TLS is authentication. Do not 1104configure opportunistic TLS for LMTP deliveries over UNIX-domain sockets. 1105Only configure TLS for LMTP over UNIX-domain sockets at the 1106<a href="#client_tls_encrypt">encrypt</a> security level or higher. 1107Attempts to configure opportunistic encryption of LMTP sessions will 1108be ignored with a warning written to the mail logs. </p> 1109 1110<p> You can enable opportunistic TLS just for selected destinations. With 1111the Postfix TLS <a href="#client_tls_policy">policy table</a>, 1112specify the "may" security level. </p> 1113 1114<p> This is the most common security level for TLS protected SMTP 1115sessions, stronger security is not generally available and, if needed, 1116is typically only configured on a per-destination basis. See the section 1117on TLS <a href="#client_tls_limits">limitations</a> above. </p> 1118 1119<p> Example: </p> 1120 1121<blockquote> 1122<pre> 1123/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1124 <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may 1125</pre> 1126</blockquote> 1127 1128<h4><a name="client_tls_encrypt"> Mandatory TLS encryption </a> </h4> 1129 1130<p> At the "encrypt" TLS security level, messages are sent only 1131over TLS encrypted sessions. The SMTP transaction is aborted unless 1132the STARTTLS ESMTP feature is supported by the remote SMTP server. 1133If no suitable 1134servers are found, the message will be deferred. 1135Mandatory TLS encryption can be configured by setting 1136"<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = encrypt". Even though TLS 1137encryption is always used, mail delivery continues even if the server 1138certificate is untrusted or bears the wrong name. 1139For LMTP, use the corresponding "lmtp_" parameter. </p> 1140 1141<p> At this security level and higher, the <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> 1142and <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> configuration parameters determine 1143the list of sufficiently secure SSL protocol versions and the minimum 1144cipher strength. If the protocol or cipher requirements are not 1145met, the mail transaction is aborted. The documentation for these 1146parameters includes useful interoperability and security guidelines. 1147</p> 1148 1149<p> Despite the potential for eliminating passive eavesdropping attacks, 1150mandatory TLS encryption is not viable as a default security level for 1151mail delivery to the public Internet. Most MX hosts do not support TLS at 1152all, and some of those that do have broken implementations. On a host 1153that delivers mail to the Internet, you should not configure mandatory 1154TLS encryption as the default security level. </p> 1155 1156<p> You can enable mandatory TLS encryption just for specific destinations. 1157With the Postfix TLS <a href="#client_tls_policy">policy 1158table</a>, specify the "encrypt" security level. 1159</p> 1160 1161<p> Examples: </p> 1162 1163<p> In the example below, traffic to <i>example.com</i> and its sub-domains 1164via the corresponding MX hosts always uses TLS. The SSLv2 protocol 1165will be disabled (the default setting of <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> 1166excludes "SSLv2"). Only high- or medium-strength (i.e. 128 bit or 1167better) ciphers will be used by default for all "encrypt" security 1168level sessions. </p> 1169 1170<blockquote> 1171<pre> 1172/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1173 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy 1174 1175/etc/postfix/tls_policy: 1176 example.com encrypt 1177 .example.com encrypt 1178</pre> 1179</blockquote> 1180 1181<p> In the next example, secure message submission is configured 1182via the MSA "<tt>[example.net]:587</tt>". TLS sessions are encrypted 1183without authentication, because this MSA does not possess an acceptable 1184certificate. This MSA is known to be capable of "TLSv1" and "high" grade 1185ciphers, so these are selected via the <a href="#client_tls_policy">policy 1186table</a>. </p> 1187 1188<p><b>Note:</b> the policy table lookup key is the verbatim next-hop 1189specification from the recipient domain, <a href="transport.5.html">transport(5)</a> table or <a href="postconf.5.html#relayhost">relayhost</a> 1190parameter, with any enclosing square brackets and optional port. Take 1191care to be consistent: the suffixes ":smtp" or ":25" or no port suffix 1192result in different policy table lookup keys, even though they are 1193functionally equivalent nexthop specifications. Use at most one of these 1194forms for all destinations. Below, the policy table has multiple keys, 1195just in case the transport table entries are not specified consistently. </p> 1196 1197<blockquote> 1198<pre> 1199/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1200 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy 1201 1202/etc/services: 1203 submission 587/tcp msa # mail message submission 1204 1205/etc/postfix/tls_policy: 1206 [example.net]:587 encrypt protocols=TLSv1 ciphers=high 1207 [example.net]:msa encrypt protocols=TLSv1 ciphers=high 1208 [example.net]:submission encrypt protocols=TLSv1 ciphers=high 1209</pre> 1210</blockquote> 1211 1212<h4><a name="client_tls_dane">DANE TLS authentication.</a> </h4> 1213 1214<p> The Postfix SMTP client supports two TLS security levels based 1215on <a href="http://tools.ietf.org/html/rfc6698">RFC6698</a> DANE TLSA records. The opportunistic "dane" level and 1216the mandatory "dane-only" level. </p> 1217 1218<p> The "dane" level is a stronger form of <a 1219href="#client_tls_may">opportunistic</a> TLS that is resistant to 1220man in the middle and downgrade attacks when the destination domain 1221uses DNSSEC to publish DANE TLSA records for its MX hosts. If a 1222remote SMTP server has "usable" (see <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a>) DANE TLSA records, 1223the server connection will be authenticated. When DANE authentication 1224fails, there is no fallback to unauthenticated or plaintext delivery. </p> 1225 1226<p> If TLSA records are published for a given remote SMTP server 1227(implying TLS support), but are all "unusable" due to unsupported 1228parameters or malformed data, the Postfix SMTP client will use <a 1229href="#client_tls_encrypt">mandatory</a> unauthenticated TLS. 1230Otherwise, when no TLSA records are published, the Postfix SMTP 1231client behavior is the same as with <a href="#client_tls_may">may</a>. </p> 1232 1233<p> TLSA records must be published in DNSSEC validated DNS zones. 1234Any TLSA records in DNS zones not protected via DNSSEC are ignored. 1235The Postfix SMTP client will not look for TLSA records associated 1236with MX hosts whose "A" or "AAAA" records lie in an "insecure" DNS 1237zone. Such lookups have been observed to cause interoperability 1238issues with poorly implemented DNS servers, and are in any case not 1239expected to ever yield "secure" results, since that would require 1240a very unlikely DLV DNS trust anchor configured between the host 1241record and the associated "_25._tcp" child TLSA record. </p> 1242 1243<p> The "dane-only" level is a form of <a 1244href="#client_tls_secure">secure-channel</a> TLS based on the DANE PKI. 1245If "usable" TLSA records are present these are used to authenticate the 1246remote SMTP server. Otherwise, or when server certificate verification 1247fails, delivery via the server in question tempfails. </p> 1248 1249<p> At both security levels, the TLS policy for the destination is 1250obtained via TLSA records validated with DNSSEC. For TLSA policy 1251to be in effect, the destination domain's containing DNS zone must 1252be signed and the Postfix SMTP client's operating system must be 1253configured to send its DNS queries to a recursive DNS nameserver 1254that is able to validate the signed records. Each MX host's DNS 1255zone needs to also be signed, and needs to publish DANE TLSA (<a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a>) 1256records that specify how that MX host's TLS certificate is to be 1257verified. </p> 1258 1259<p> TLSA records do not preempt the normal SMTP MX host 1260selection algorithm, if some MX hosts support TLSA and others do 1261not, TLS security will vary from delivery to delivery. It is up 1262to the domain owner to configure their MX hosts and their DNS 1263sensibly. To configure the Postfix SMTP client for DNSSEC lookups 1264see the documentation for the <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> <a href="postconf.5.html">main.cf</a> 1265parameter. The <a href="postconf.5.html#tls_dane_trust_anchor_digest_enable">tls_dane_trust_anchor_digest_enable</a> <a href="postconf.5.html">main.cf</a> parameter 1266controls support for trust-anchor digest TLSA records. The 1267<a href="postconf.5.html#tls_dane_digests">tls_dane_digests</a> and tls_dane_digest_agility parameters control 1268the list of supported digests and digest downgrade attack resistance. 1269</p> 1270 1271<p> DANE for SMTP MTAs deviates in some details from the baseline 1272DANE protocol in <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a>. Most notably, it is not expected that 1273SMTP MTAs can reasonably include every public CA that a remote SMTP 1274server's administrator may believe to be well-known. Nor is there 1275an interactive user to "click OK" when authentication fails. </p> 1276 1277<p> Therefore, certificate usages "0" and "1" from <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> which 1278are intended to "constrain" existing PKI trust, are not supported. 1279TLSA records with usage "0" are treated as "unusable". TLSA records 1280with usage "1" are instead treated as "trust assertions" and mapped 1281to usage "3". Specifically, with certificate usage "1", Postfix 1282will not require the remote SMTP server's certificate to be trusted 1283with respect to any locally defined public CAs, it is the domain 1284owner's responsibility to ensure that the certificate associations 1285in their TLSA records are appropriate to authenticate their SMTP 1286servers. </p> 1287 1288<p> The Postfix SMTP client supports only certificate usages "2" 1289and "3" (with "1" treated as though it were "3"). See 1290<a href="postconf.5.html#tls_dane_trust_anchor_digest_enable">tls_dane_trust_anchor_digest_enable</a> for usage "2" usability 1291considerations. Support for certificate usage "1" is an experiment, 1292it may be withdrawn in the future. Server operators SHOULD NOT 1293publish TLSA records with usage "1". </p> 1294 1295<p> When usable TLSA records are obtained for the remote SMTP server 1296the Postfix SMTP client sends the SNI TLS extension in its SSL 1297client hello message. This may help the remote SMTP server live 1298up to its promise to provide a certificate that matches its TLSA 1299records. </p> 1300 1301<p> For purposes of protocol and cipher selection, the "dane" 1302security level is treated like a "mandatory" TLS security level, 1303and weak ciphers and protocols are disabled. Since DANE authenticates 1304server certificates the "aNULL" cipher-suites are transparently 1305excluded at this level, no need to configure this manually. <a href="http://tools.ietf.org/html/rfc6698">RFC</a> 1306<a href="http://tools.ietf.org/html/rfc6698">6698</a> (DANE) TLS authentication is available with Postfix 2.11 and 1307later. </p> 1308 1309<p> When a DANE TLSA record specifies a trust-anchor (TA) certificate 1310(that is an issuing CA), the strategy used to verify the peername 1311of the server certificate is unconditionally "nexthop, hostname". 1312Both the nexthop domain and the hostname obtained from the 1313DNSSEC-validated MX lookup are safe from forgery and the server 1314certificate must contain at least one of these names. </p> 1315 1316<p> When a DANE TLSA record specifies an end-entity (EE) certificate, 1317(that is the actual server certificate), as with the fingerprint 1318security level below, no name checks or certificate expiration checks 1319are applied. The server certificate (or its public key) either matches 1320the DANE record or not. Server administrators should publish such 1321EE records in preference to all other types. </p> 1322 1323<p> The pre-requisites for DANE support in the Postfix SMTP client are: </p> 1324<ul> 1325<li> A <i>compile-time</i> OpenSSL library that supports the TLS SNI 1326extension and "SHA-2" message digests. 1327<li> A <i>compile-time</i> DNS resolver library that supports DNSSEC. 1328Postfix binaries built on an older system will not support DNSSEC even 1329if deployed on a system with an updated resolver library. 1330<li> The "<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>" must be set to "dnssec". 1331<li> The "<a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a>" parameter must include "dns". 1332<li> A DNSSEC-validating recursive resolver (see note below). 1333</ul> 1334<p> The above client pre-requisites do not apply to the Postfix SMTP server. 1335It will support DANE provided it supports TLSv1 and its TLSA records are 1336published in a DNSSEC signed zone. To receive DANE secured mail for multiple 1337domains, use the same hostname to add the server to each domain's MX 1338records. There are no plans to implement SNI in the Postfix SMTP server. </p> 1339 1340<p> Note: The Postfix SMTP client's internal stub DNS resolver is 1341DNSSEC-aware, but it does not itself validate DNSSEC records, rather 1342it delegates DNSSEC validation to the operating system's configured 1343recursive DNS nameserver. The Postfix DNS client relies on a secure 1344channel to the resolver's cache for DNSSEC integrity, but does not 1345support TSIG to protect the transmission channel between itself and 1346the nameserver. Therefore, it is strongly recommended (DANE security 1347guarantee void otherwise) that each MTA run a local DNSSEC-validating 1348recursive resolver ("unbound" from nlnetlabs.nl is a reasonable 1349choice) listening on the loopback interface, and that the system 1350be configured to use <i>only</i> this local nameserver. The local 1351nameserver may forward queries to an upstream recursive resolver 1352on another host if desired. </p> 1353 1354<p> Note: When the operating system's recursive nameserver is not 1355local, enabling EDNS0 expanded DNS packet sizes and turning on the 1356DNSSEC "DO" bit in the DNS request and/or the new DNSSEC-specific 1357records returned in the nameserver's replies may cause problems 1358with older or buggy firewall and DNS server implementations. 1359Therefore, Postfix does not enable DNSSEC by default. Since MX 1360lookups happen before the security level is determined, DANE support 1361is disabled for all destinations unless you set "<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> 1362= dnssec". To enable DNSSEC lookups selectively, define a new 1363dedicated transport with a "-o <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>=dnssec" 1364override in <a href="master.5.html">master.cf</a> and route selected domains to that transport. 1365If DNSSEC proves to be sufficiently reliable for these domains, you 1366can enable it for all destinations by changing the global 1367<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> in <a href="postconf.5.html">main.cf</a>. </p> 1368 1369<p><b>Example</b>: "dane" security for selected destinations, with 1370opportunistic TLS by default. This is the recommended configuration 1371for early adopters. <p> 1372<ul> 1373<li> <p> The "example.com" destination uses DANE, but if TLSA records 1374are not present or are unusable, mail is deferred. </p> 1375 1376<li> <p> The "example.org" destination uses DANE if possible, but if no TLSA 1377records are found opportunistic TLS is used. </p> 1378</ul> 1379 1380<blockquote> 1381<pre> 1382<a href="postconf.5.html">main.cf</a>: 1383 indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/ 1384 # 1385 # default: Opportunistic TLS with no DNSSEC lookups. 1386 # 1387 <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may 1388 <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> = enabled 1389 # 1390 # Per-destination TLS policy 1391 # 1392 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = ${indexed}tls_policy 1393 # 1394 # <a href="postconf.5.html#default_transport">default_transport</a> = smtp, but some destinations are special: 1395 # 1396 <a href="postconf.5.html#transport_maps">transport_maps</a> = ${indexed}transport 1397</pre> 1398</blockquote> 1399 1400<blockquote> 1401<pre> 1402transport: 1403 example.com dane 1404 example.org dane 1405</pre> 1406</blockquote> 1407 1408<blockquote> 1409<pre> 1410tls_policy: 1411 example.com dane-only 1412</pre> 1413</blockquote> 1414 1415<blockquote> 1416<pre> 1417<a href="master.5.html">master.cf</a>: 1418 dane unix - - n - - smtp 1419 -o <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>=dnssec 1420 -o <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>=dane 1421</pre> 1422</blockquote> 1423 1424<h4><a name="client_tls_fprint"> Certificate fingerprint verification </a> </h4> 1425 1426<p> At the <i>fingerprint</i> security level, no trusted certificate 1427authorities are used or required. The certificate trust chain, 1428expiration date, etc., are not checked. Instead, the 1429<a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter or the "match" attribute 1430in the <a href="#client_tls_policy">policy</a> table lists the 1431remote SMTP server certificate fingerprint or public key fingerprint. 1432Certificate fingerprint verification is available with Postfix 2.5 1433and later, public-key fingerprint support is available with Postfix 14342.9 and later. </p> 1435 1436<p> If certificate fingerprints are exchanged securely, this is the 1437strongest, and least scalable security level. The administrator needs 1438to securely collect the fingerprints of the X.509 certificates of each 1439peer server, store them into a local file, and update this local file 1440whenever the peer server's public certificate changes. If public key 1441fingerprints are used in place of fingerprints of the entire certificate, 1442the fingerprints remain valid even after the certificate is renewed, 1443<b>provided</b> that the same public/private keys are used to obtain 1444the new certificate. </p> 1445 1446<p> Fingerprint verification may be feasible for an SMTP "VPN" connecting 1447a small number of branch offices over the Internet, or for secure 1448connections to a central mail hub. It works poorly if the remote SMTP 1449server is managed by a third party, and its public certificate changes 1450periodically without prior coordination with the verifying site. </p> 1451 1452<p> The digest algorithm used to calculate the fingerprint is 1453selected by the <b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b> parameter. In the <a 1454href="#client_tls_policy">policy</a> table multiple fingerprints can be 1455combined with a "|" delimiter in a single match attribute, or multiple 1456match attributes can be employed. The ":" character is not used as a 1457delimiter as it occurs between each pair of fingerprint (hexadecimal) 1458digits. </p> 1459 1460<p> Example: fingerprint TLS security with an internal mailhub. 1461Two matching fingerprints are listed. The <a href="postconf.5.html#relayhost">relayhost</a> may be multiple 1462physical hosts behind a load-balancer, each with its own private/public 1463key and self-signed certificate. Alternatively, a single <a href="postconf.5.html#relayhost">relayhost</a> may 1464be in the process of switching from one set of private/public keys to 1465another, and both keys are trusted just prior to the transition. </p> 1466 1467<blockquote> 1468<pre> 1469 <a href="postconf.5.html#relayhost">relayhost</a> = [mailhub.example.com] 1470 <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = fingerprint 1471 <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = md5 1472 <a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> = 1473 3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 1474 EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 1475</pre> 1476</blockquote> 1477 1478<p> Example: Certificate fingerprint verification with selected destinations. 1479As in the example above, we show two matching fingerprints: </p> 1480<blockquote> 1481<pre> 1482/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1483 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy 1484 <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = md5 1485</pre> 1486</blockquote> 1487<blockquote> 1488<pre> 1489/etc/postfix/tls_policy: 1490 example.com fingerprint 1491 match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 1492 match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 1493</pre> 1494</blockquote> 1495 1496<p> To extract the public key fingerprint from an X.509 certificate, 1497you need to extract the public key from the certificate and compute 1498the appropriate digest of its DER (ASN.1) encoding. With OpenSSL 1499the "-pubkey" option of the "x509" command extracts the public 1500key always in "PEM" format. We pipe the result to another OpenSSL 1501command that converts the key to DER and then to the "dgst" command 1502to compute the fingerprint. </p> 1503 1504<p> The actual command to transform the key to DER format depends 1505on the version of OpenSSL used. With OpenSSL 1.0.0 and later, the 1506"pkey" command supports all key types. With OpenSSL 0.9.8 and 1507earlier, the key type is always RSA (nobody uses DSA, and EC 1508keys are not fully supported by 0.9.8), so the "rsa" command is 1509used. </p> 1510<blockquote> 1511<pre> 1512# OpenSSL 1.0 with all certificates and SHA-1 fingerprints. 1513$ openssl x509 -in cert.pem -noout -pubkey | 1514 openssl pkey -pubin -outform DER | 1515 openssl dgst -sha1 -c 1516(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58 1517 1518# OpenSSL 0.9.8 with RSA certificates and MD5 fingerprints. 1519$ openssl x509 -in cert.pem -noout -pubkey | 1520 openssl rsa -pubin -outform DER | 1521 openssl dgst -md5 -c 1522(stdin)= f4:62:60:f6:12:8f:d5:8d:28:4d:13:a7:db:b2:ff:50 1523</pre> 1524</blockquote> 1525<p> Note: Postfix 2.9.0–2.9.5 computed the public key 1526fingerprint incorrectly. To use public-key fingerprints, upgrade 1527to Postfix 2.9.6 or later. </p> 1528 1529<h4><a name="client_tls_verify"> Mandatory server certificate verification </a> </h4> 1530 1531<p> At the <i>verify</i> TLS security level, messages are sent only over 1532TLS encrypted sessions if the remote SMTP server certificate is 1533valid (not 1534expired or revoked, and signed by a trusted certificate authority) 1535and where the server certificate name matches a known pattern. 1536Mandatory 1537server certificate verification can be configured by setting 1538"<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = verify". The 1539<a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> parameter can override the default 1540"hostname" certificate name matching strategy. Fine-tuning the 1541matching strategy is generally only appropriate for <a 1542href="#client_tls_secure">secure-channel</a> destinations. 1543For LMTP use the corresponding "lmtp_" parameters. </p> 1544 1545<p> If the server certificate chain is trusted (see <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> 1546and <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>), any DNS names in the SubjectAlternativeName 1547certificate extension are used to verify the remote SMTP server name. 1548If no 1549DNS names are specified, the certificate CommonName is checked. 1550If you want mandatory encryption without server certificate 1551verification, see <a href="#client_tls_encrypt">above</a>. </p> 1552 1553<p> With Postfix ≥ 2.11 the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter 1554or more typically the corresponding per-destination "tafile" attribute 1555optionally modifies trust chain verification. If the parameter is 1556not empty the root CAs in CAfile and CApath are no longer trusted. 1557Rather, the Postfix SMTP client will only trust certificate-chains 1558signed by one of the trust-anchors contained in the chosen files. 1559The specified trust-anchor certificates and public keys are not 1560subject to expiration, and need not be (self-signed) root CAs. They 1561may, if desired, be intermediate certificates. Therefore, these 1562certificates also may be found "in the middle" of the trust chain 1563presented by the remote SMTP server, and any untrusted issuing 1564parent certificates will be ignored. </p> 1565 1566<p> Despite the potential for eliminating "man-in-the-middle" and other 1567attacks, mandatory certificate trust chain and subject name verification 1568is not viable as a default Internet mail delivery policy. Most MX hosts 1569do not support TLS at all, and a significant portion of TLS enabled 1570MTAs use self-signed certificates, or certificates that are signed by 1571a private certificate authority. On a machine that delivers mail to 1572the Internet, you should not configure mandatory server certificate 1573verification as a default policy. </p> 1574 1575<p> Mandatory server certificate verification as a default security 1576level may be appropriate if you know that you will only connect to 1577servers that support <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> <i>and</i> that present verifiable 1578server certificates. An example would be a client that sends all 1579email to a central mailhub that offers the necessary STARTTLS 1580support. In such cases, you can often use a <a 1581href="#client_tls_secure">secure-channel</a> configuration instead. 1582</p> 1583 1584<p> You can enable mandatory server certificate verification just 1585for specific destinations. With the Postfix TLS <a 1586href="#client_tls_policy">policy table</a>, specify the "verify" 1587security level. </p> 1588 1589<p> Example: </p> 1590 1591<p> In this example, the Postfix SMTP client encrypts all traffic to the 1592<i>example.com</i> domain. The peer hostname is verified, but 1593verification is vulnerable to DNS response forgery. Mail transmission 1594to <i>example.com</i> recipients uses "high" grade ciphers. </p> 1595 1596<blockquote> 1597<pre> 1598/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1599 indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/ 1600 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = ${<a href="postconf.5.html#config_directory">config_directory</a>}/CAfile.pem 1601 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = ${indexed}tls_policy 1602 1603/etc/postfix/tls_policy: 1604 example.com verify ciphers=high 1605</pre> 1606</blockquote> 1607 1608<h4><a name="client_tls_secure"> Secure server certificate verification </a> </h4> 1609 1610<p> At the <i>secure</i> TLS security level, messages are sent only over 1611<i>secure-channel</i> TLS sessions where DNS forgery resistant server 1612certificate verification succeeds. If no suitable servers are found, the 1613message will be deferred. Postfix secure-channels 1614can be configured by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = secure". 1615The <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> parameter can override the default 1616"nexthop, dot-nexthop" certificate match strategy. 1617For LMTP, use the corresponding "lmtp_" parameters. </p> 1618 1619<p> If the server certificate chain is trusted (see <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and 1620<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>), any DNS names in the SubjectAlternativeName certificate 1621extension are used to verify the remote SMTP server name. If no DNS names 1622are 1623specified, the CommonName is checked. If you want mandatory encryption 1624without server certificate verification, see <a 1625href="#client_tls_encrypt">above</a>. </p> 1626 1627<p> With Postfix ≥ 2.11 the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter 1628or more typically the corresponding per-destination "tafile" attribute 1629optionally modifies trust chain verification. If the parameter is 1630not empty the root CAs in CAfile and CApath are no longer trusted. 1631Rather, the Postfix SMTP client will only trust certificate-chains 1632signed by one of the trust-anchors contained in the chosen files. 1633The specified trust-anchor certificates and public keys are not 1634subject to expiration, and need not be (self-signed) root CAs. They 1635may, if desired, be intermediate certificates. Therefore, these 1636certificates also may be found "in the middle" of the trust chain 1637presented by the remote SMTP server, and any untrusted issuing 1638parent certificates will be ignored. </p> 1639 1640<p> Despite the potential for eliminating "man-in-the-middle" and other 1641attacks, mandatory secure server certificate verification is not 1642viable as a default Internet mail delivery policy. Most MX hosts 1643do not support TLS at all, and a significant portion of TLS enabled 1644MTAs use self-signed certificates, or certificates that are signed 1645by a private certificate authority. On a machine that delivers mail 1646to the Internet, you should not configure secure TLS verification 1647as a default policy. </p> 1648 1649<p> Mandatory secure server certificate verification as a default 1650security level may be appropriate if you know that you will only 1651connect to servers that support <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> <i>and</i> that present 1652verifiable server certificates. An example would be a client that 1653sends all email to a central mailhub that offers the necessary 1654STARTTLS support. </p> 1655 1656<p> You can enable secure TLS verification just for specific destinations. 1657With the Postfix TLS <a href="#client_tls_policy">policy table</a>, 1658specify the "secure" security level. </p> 1659 1660<p> Examples: </p> 1661 1662<ul> 1663 1664<li> <p> Secure-channel TLS without <a href="transport.5.html">transport(5)</a> table overrides: </p> 1665 1666<p> The Postfix SMTP client will encrypt all traffic and verify the 1667destination name 1668immune from forged DNS responses. MX lookups are still used to find 1669the hostnames of the SMTP servers for <i>example.com</i>, but these 1670hostnames are not used when 1671checking the names in the server certificate(s). Rather, the requirement 1672is that the MX hosts for <i>example.com</i> have trusted certificates 1673with a subject name of <i>example.com</i> or a sub-domain, see the 1674documentation for the <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> parameter. </p> 1675 1676<p> The related domains <i>example.co.uk</i> and <i>example.co.jp</i> are 1677hosted on the same MX hosts as the primary <i>example.com</i> domain, and 1678traffic to these is secured by verifying the primary <i>example.com</i> 1679domain in the server certificates. This frees the server administrator 1680from needing the CA to sign certificates that list all the secondary 1681domains. The downside is that clients that want secure channels to the 1682secondary domains need explicit TLS <a href="#client_tls_policy">policy 1683table</a> entries. </p> 1684 1685<p> Note, there are two ways to handle related domains. The first is to 1686use the default routing for each domain, but add policy table entries 1687to override the expected certificate subject name. The second is to 1688override the next-hop in the transport table, and use a single policy 1689table entry for the common nexthop. We choose the first approach, 1690because it works better when domain ownership changes. With the second 1691approach we securely deliver mail to the wrong destination, with the 1692first approach, authentication fails and mail stays in the local queue, 1693the first approach is more appropriate in most cases. <p> 1694 1695<blockquote> 1696<pre> 1697/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1698 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem 1699 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy 1700 1701/etc/postfix/transport: 1702 1703/etc/postfix/tls_policy: 1704 example.com secure 1705 example.co.uk secure match=example.com:.example.com 1706 example.co.jp secure match=example.com:.example.com 1707</pre> 1708</blockquote> 1709 1710<li> <p> Secure-channel TLS with <a href="transport.5.html">transport(5)</a> table overrides: <p> 1711 1712<p> In this case traffic to <i>example.com</i> and its related domains 1713is sent to a single logical gateway (to avoid a single point of failure, 1714its name may resolve to one or more load-balancer addresses, or to the 1715combined addresses of multiple physical hosts). All the physical hosts 1716reachable via the gateway's IP addresses have the logical gateway name 1717listed in their certificates. </p> 1718 1719<blockquote> 1720<pre> 1721/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1722 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem 1723 <a href="postconf.5.html#transport_maps">transport_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport 1724 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy 1725 1726/etc/postfix/transport: 1727 example.com <a href="smtp.8.html">smtp</a>:[tls.example.com] 1728 example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com] 1729 example.co.jp <a href="smtp.8.html">smtp</a>:[tls.example.com] 1730 1731/etc/postfix/tls_policy: 1732 [tls.example.com] secure match=tls.example.com 1733</pre> 1734</blockquote> 1735 1736</ul> 1737 1738<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3> 1739 1740<p> To get additional information about Postfix SMTP client TLS 1741activity you can increase the loglevel from 0..4. Each logging 1742level also includes the information that is logged at a lower 1743logging level. </p> 1744 1745<blockquote> 1746 1747<table border="1"> 1748 1749<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier 1750releases. </th> </tr> 1751 1752<tr> <td valign="top"> 0 </td> <td valign="top" colspan="2"> Disable 1753logging of TLS activity. </td> </tr> 1754 1755<tr> <td valign="top"> 1 </td> <td valign="top"> Log only a summary 1756message on TLS handshake completion — no logging of remote SMTP 1757server certificate trust-chain verification errors if server certificate 1758verification is not required. </td> <td valign="top"> Log the summary 1759message and unconditionally log trust-chain verification errors. 1760</td> </tr> 1761 1762<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also 1763log levels during TLS negotiation. </td> </tr> 1764 1765<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also 1766log hexadecimal and ASCII dump of TLS negotiation process. </td> 1767</tr> 1768 1769<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also 1770log hexadecimal and ASCII dump of complete transmission after 1771STARTTLS. </td> </tr> 1772 1773</table> 1774 1775</blockquote> 1776 1777<p> Example: </p> 1778 1779<blockquote> 1780<pre> 1781/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1782 <a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 0 1783</pre> 1784</blockquote> 1785 1786<h3><a name="client_cert_key">Client-side certificate and private 1787key configuration </a> </h3> 1788 1789<p> Do not configure Postfix SMTP client certificates unless you <b>must</b> 1790present 1791client TLS certificates to one or more servers. Client certificates are 1792not usually needed, and can cause problems in configurations that work 1793well without them. The recommended setting is to let the defaults stand: </p> 1794 1795<blockquote> 1796<pre> 1797 <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = 1798 <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = 1799 <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> = 1800 <a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = 1801 # Postfix ≥ 2.6 1802 <a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = 1803 <a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = 1804</pre> 1805</blockquote> 1806 1807<p> The best way to use the default settings is to comment out the above 1808parameters in <a href="postconf.5.html">main.cf</a> if present. </p> 1809 1810<p> During TLS startup negotiation the Postfix SMTP client may present 1811a certificate to the remote SMTP server. The Netscape client is 1812rather clever here and lets the user select between only those 1813certificates that match CA certificates offered by the remote SMTP 1814server. As the Postfix SMTP client uses the "SSL_connect()" function 1815from the OpenSSL package, this is not possible and we have to choose 1816just one certificate. So for now the default is to use _no_ 1817certificate and key unless one is explicitly specified here. </p> 1818 1819<p> RSA, DSA and ECDSA (Postfix ≥ 2.6) certificates are supported. 1820You can configure all three at the same time, in which case the 1821cipher used determines which certificate is presented. </p> 1822 1823<p> It is possible for the Postfix SMTP client to use the same 1824key/certificate pair as the Postfix SMTP server. If a certificate 1825is to be presented, it must be in "PEM" format. The private key 1826must not be encrypted, meaning: it must be accessible without 1827password. Both parts (certificate and private key) may be in the 1828same file. </p> 1829 1830<p> To enable remote SMTP servers to verify the Postfix SMTP client 1831certificate, the issuing CA certificates must be made available to the 1832server. You should include the required certificates in the client 1833certificate file, the client certificate first, then the issuing 1834CA(s) (bottom-up order). </p> 1835 1836<p> Example: the certificate for "client.example.com" was issued by 1837"intermediate CA" which itself has a certificate issued by "root CA". 1838Create the client.pem file with: </p> 1839 1840<blockquote> 1841<pre> 1842% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b> 1843</pre> 1844</blockquote> 1845 1846<p> A Postfix SMTP client certificate supplied here must be usable 1847as SSL client certificate and hence pass the "openssl verify -purpose 1848sslclient ..." test. </p> 1849 1850<p> A server that trusts the root CA has a local copy of the root 1851CA certificate, so it is not necessary to include the root CA 1852certificate here. Leaving it out of the "client.pem" file reduces 1853the overhead of the TLS exchange. </p> 1854 1855<p> If you want the Postfix SMTP client to accept remote SMTP server 1856certificates issued by these CAs, append the root certificate to 1857$<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. </p> 1858 1859<p> RSA key and certificate examples: </p> 1860 1861<blockquote> 1862<pre> 1863/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1864 <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem 1865 <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> = $<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> 1866</pre> 1867</blockquote> 1868 1869<p> Their DSA counterparts: </p> 1870 1871<blockquote> 1872<pre> 1873/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1874 <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem 1875 <a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = $<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> 1876</pre> 1877</blockquote> 1878 1879<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 1.0.0): </p> 1880 1881<blockquote> 1882<pre> 1883/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1884 <a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = /etc/postfix/client-ecdsa.pem 1885 <a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = $<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> 1886</pre> 1887</blockquote> 1888 1889<p> To verify a remote SMTP server certificate, the Postfix SMTP 1890client needs to trust the certificates of the issuing certification 1891authorities. These certificates in "pem" format can be stored in a 1892single $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in 1893the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. If you use a directory, don't forget 1894to create the necessary "hash" links with: </p> 1895 1896<blockquote> 1897<pre> 1898# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b> 1899</pre> 1900</blockquote> 1901 1902<p> The $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> contains the CA certificates of one or more 1903trusted CAs. The file is opened (with root privileges) before Postfix 1904enters the optional chroot jail and so need not be accessible from inside the 1905chroot jail. </p> 1906 1907<p> Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> 1908directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a> 1909privileges) from the files in the directory when the information 1910is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible 1911inside the optional chroot jail. </p> 1912 1913<p> The choice between $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> is 1914a space/time tradeoff. If there are many trusted CAs, the cost of 1915preloading them all into memory may not pay off in reduced access time 1916when the certificate is needed. </p> 1917 1918<p> Example: </p> 1919 1920<blockquote> 1921<pre> 1922/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1923 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem 1924 <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /etc/postfix/certs 1925</pre> 1926</blockquote> 1927 1928<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3> 1929 1930<p> The remote SMTP server and the Postfix SMTP client negotiate a 1931session, which takes some computer time and network bandwidth. By 1932default, this session information is cached only in the <a href="smtp.8.html">smtp(8)</a> 1933process actually using this session and is lost when the process 1934terminates. To share the session information between multiple 1935<a href="smtp.8.html">smtp(8)</a> processes, a persistent session cache can be used. You 1936can specify any database type that can store objects of several 1937kbytes and that supports the sequence operator. DBM databases are 1938not suitable because they can only store small objects. The cache 1939is maintained by the <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there is no problem with 1940concurrent access. Session caching is highly recommended, because 1941the cost of repeatedly negotiating TLS session keys is high. Future 1942Postfix SMTP servers may limit the number of sessions that a client 1943is allowed to negotiate per unit time.</p> 1944 1945 1946<p> Example: </p> 1947 1948<blockquote> 1949<pre> 1950/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1951 <a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = <a href="DATABASE_README.html#types">btree</a>:/var/db/postfix/smtp_scache 1952</pre> 1953</blockquote> 1954 1955<p> Note: as of version 2.5, Postfix no longer uses root privileges 1956when opening this file. The file should now be stored under the 1957Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to 1958open the file under a non-Postfix directory is redirected to the 1959Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. </p> 1960 1961<p> Cached Postfix SMTP client session information expires after 1962a certain amount of time. Postfix/TLS does not use the OpenSSL 1963default of 300s, but a longer time of 3600s (=1 hour). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a> 1964recommends a maximum of 24 hours. </p> 1965 1966<p> Example: </p> 1967 1968<blockquote> 1969<pre> 1970/etc/postfix/<a href="postconf.5.html">main.cf</a>: 1971 <a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s 1972</pre> 1973</blockquote> 1974 1975<p> As of Postfix 2.11 this setting cannot exceed 100 days. If set 1976≤ 0, session caching is disabled. If set to a positive value 1977less than 2 minutes, the minimum value of 2 minutes is used instead. </p> 1978 1979<h3><a name="client_tls_limits"> Client TLS limitations </a> 1980</h3> 1981 1982<p> The security properties of TLS communication channels are 1983application specific. While the TLS protocol can provide a confidential, 1984tamper-resistant, mutually authenticated channel between client 1985and server, not all of these security features are applicable to every 1986communication. </p> 1987 1988<p> For example, while mutual TLS authentication between browsers and web 1989servers is possible, it is not practical, or even useful, for web-servers 1990that serve the public to verify the identity of every potential user. In 1991practice, most HTTPS transactions are asymmetric: the browser verifies 1992the HTTPS server's identity, but the user remains anonymous. Much of 1993the security policy is up to the client. If the client chooses to not 1994verify the server's name, the server is not aware of this. There are many 1995interesting browser security topics, but we shall not dwell 1996on them here. Rather, our goal is to understand the security features 1997of TLS in conjunction with SMTP. </p> 1998 1999<p> An important SMTP-specific observation is that a public MX host is 2000even more at the mercy of the SMTP client than is an HTTPS server. Not only 2001can it not enforce due care in the client's use of TLS, but it cannot even 2002enforce the use of TLS, because TLS support in SMTP clients is still the 2003exception rather than the rule. One cannot, in practice, limit access to 2004one's MX hosts to just TLS-enabled clients. Such a policy would result 2005in a vast reduction in one's ability to communicate by email with the 2006world at large. </p> 2007 2008<p> One may be tempted to try enforcing TLS for mail from specific 2009sending organizations, but this, too, runs into obstacles. One such 2010obstacle is that we don't know who is (allegedly) sending mail until 2011we see the "MAIL FROM:" SMTP command, and at that point, if TLS 2012is not already in use, a potentially sensitive sender address (and 2013with SMTP PIPELINING one or more of the recipients) has (have) already been 2014leaked in the clear. Another obstacle is that mail from the sender to 2015the recipient may be forwarded, and the forwarding organization may not 2016have any security arrangements with the final destination. Bounces also 2017need to be protected. These can only be identified by the IP address and 2018HELO name of the connecting client, and it is difficult to keep track 2019of all the potential IP addresses or HELO names of the outbound email 2020servers of the sending organization. </p> 2021 2022<p> Consequently, TLS security for mail delivery to public MX hosts is 2023almost entirely the client's responsibility. The server is largely a 2024passive enabler of TLS security, the rest is up to the client. While the 2025server has a greater opportunity to mandate client security policy when 2026it is a dedicated MSA that only handles outbound mail from trusted clients, 2027below we focus on the client security policy. </p> 2028 2029<p> On the SMTP client, there are further complications. When 2030delivering mail to a given domain, in contrast to HTTPS, one rarely 2031uses the domain name directly as the target host of the SMTP session. 2032More typically, one uses MX lookups — these are usually 2033unauthenticated — to obtain the domain's SMTP server hostname(s). 2034When, as is current practice, the client verifies the insecurely 2035obtained MX hostname, it is subject to a DNS man-in-the-middle 2036attack. </p> 2037 2038<p> Adoption of DNSSEC and <a href="http://tools.ietf.org/html/rfc6698">RFC6698</a> (DANE) may gradually (as domains 2039implement DNSSEC and publish TLSA records for their MX hosts) address 2040the DNS man-in-the-middle risk and provide scalable key management 2041for SMTP with TLS. Postfix ≥ 2.11 supports the new <a 2042href="#client_tls_dane">dane</a> and <a href="#client_tls_dane">dane-only</a> 2043security levels that take advantage of these standards. </p> 2044 2045<p> If clients instead attempted to verify the recipient domain name, 2046an SMTP server for multiple domains would need to 2047list all its email domain names in its certificate, and generate a 2048new certificate each time a new domain were added. At least some CAs set 2049fairly low limits (20 for one prominent CA) on the number of names that 2050server certificates can contain. This approach is not consistent with 2051current practice and does not scale. </p> 2052 2053<p> It is regrettably the case that TLS <i>secure-channels</i> 2054(fully authenticated and immune to man-in-the-middle attacks) impose 2055constraints on the sending and receiving sites that preclude ubiquitous 2056deployment. One needs to manually configure this type of security for 2057each destination domain, and in many cases implement non-default TLS 2058<a href="#client_tls_policy">policy table</a> entries for additional 2059domains hosted at a common secured destination. For these reasons 2060secure-channel configurations 2061will never be the norm. For the generic domain with which you 2062have made no specific security arrangements, this security level is not 2063a good fit. </p> 2064 2065<p> Given that strong authentication is not generally possible, and that 2066verifiable certificates cost time and money, many servers that implement 2067TLS use self-signed certificates or private CAs. This further limits 2068the applicability of verified TLS on the public Internet. </p> 2069 2070<p> Historical note: while the documentation of these issues and many of the 2071related features were new with Postfix 2.3, the issue was well 2072understood before Postfix 1.0, when Lutz Jänicke was designing 2073the first unofficial Postfix TLS patch. See his original post <a 2074href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a> 2075and the first response <a 2076href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>. 2077The problem is not even unique to SMTP or even TLS, similar issues exist 2078for secure connections via aliases for HTTPS and Kerberos. SMTP merely 2079uses indirect naming (via MX records) more frequently. </p> 2080 2081<h3> <a name="client_tls_policy"> TLS policy table </a> 2082</h3> 2083 2084<p> A small fraction of servers offer STARTTLS but the negotiation 2085consistently fails. As long as encryption is not mandatory, the 2086Postfix SMTP client retries the delivery immediately with TLS 2087disabled, without any need to explicitly disable TLS for the problem 2088destinations. </p> 2089 2090<p> The policy table is specified via the <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> 2091parameter. This lists optional lookup tables with the Postfix SMTP client 2092TLS security policy by next-hop destination. </p> 2093 2094<p> The TLS policy table is indexed by the full next-hop destination, 2095which is either the recipient domain, or the verbatim next-hop 2096specified in the transport table, $<a href="postconf.5.html#local_transport">local_transport</a>, $<a href="postconf.5.html#virtual_transport">virtual_transport</a>, 2097$<a href="postconf.5.html#relay_transport">relay_transport</a> or $<a href="postconf.5.html#default_transport">default_transport</a>. This includes any enclosing 2098square brackets and any non-default destination server port suffix. The 2099<a href="#client_lmtp_tls">LMTP</a> socket type prefix (inet: or unix:) 2100is not included in the lookup key. </p> 2101 2102<p> Only the next-hop domain, or $<a href="postconf.5.html#myhostname">myhostname</a> with LMTP over UNIX-domain 2103sockets, is used as the nexthop name for certificate verification. The 2104port and any enclosing square brackets are used in the table lookup key, 2105but are not used for server name verification. </p> 2106 2107<p> When the lookup key is a domain name without enclosing square brackets 2108or any <i>:port</i> suffix (typically the recipient domain), and the full 2109domain is not found in the table, just as with the <a href="transport.5.html">transport(5)</a> table, 2110the parent domain starting with a leading "." is matched recursively. This 2111allows one to specify a security policy for a recipient domain and all 2112its sub-domains. </p> 2113 2114<p> The lookup result is a security level, followed by an optional 2115list of whitespace and/or comma separated name=value attributes 2116that override related <a href="postconf.5.html">main.cf</a> settings. The TLS security <a 2117href="#client_tls_levels">levels</a> are described above. Below, we 2118describe the corresponding table syntax: </p> 2119 2120<dl> 2121 2122<dt><b>none</b></dt> <dd><a href="#client_tls_none">No TLS</a>. No 2123additional attributes are supported at this level. </dd> 2124 2125<dt><b>may</b></dt> <dd><a href="#client_tls_may">Opportunistic TLS</a>. 2126The optional "ciphers", "exclude" and "protocols" attributes 2127(available for opportunistic TLS with Postfix ≥ 2.6) override the 2128"<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>", "<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a>" and "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>" 2129configuration parameters. </dd> 2130 2131<dt><b>encrypt</b></dt> <dd><a href="#client_tls_encrypt"> Mandatory encryption</a>. 2132Mail is delivered only if the remote SMTP server offers STARTTLS 2133and the TLS handshake succeeds. At this level and higher, the optional 2134"protocols" attribute overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> 2135parameter, the optional "ciphers" attribute overrides the 2136<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> parameter, and the optional 2137"exclude" attribute (Postfix ≥ 2.6) overrides the <a href="postconf.5.html">main.cf</a> 2138<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> parameter. </dd> 2139 2140<dt><b>dane</b></dt> <dd><a href="#client_tls_dane">Opportunistic DANE TLS</a>. 2141The TLS policy for the destination is obtained via TLSA records in 2142DNSSEC. If no TLSA records are found, the effective security level 2143used is <a href="#client_tls_may">may</a>. If TLSA records are 2144found, but none are usable, the effective security level is <a 2145href="#client_tls_encrypt">encrypt</a>. When usable TLSA records 2146are obtained for the remote SMTP server, SSLv2 is automatically 2147disabled (see <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>), and the server certificate 2148must match the TLSA records. <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> (DANE) TLS authentication 2149and DNSSEC support is available with Postfix 2.11 and later. </dd> 2150 2151<dt><b>dane-only</b></dt> <dd><a href="#client_tls_dane">Mandatory DANE TLS</a>. 2152The TLS policy for the destination is obtained via TLSA records in 2153DNSSEC. If no TLSA records are found, or none are usable, no 2154connection is made to the server. When usable TLSA records are 2155obtained for the remote SMTP server, SSLv2 is automatically disabled 2156(see <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>), and the server certificate must 2157match the TLSA records. <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> (DANE) TLS authentication and 2158DNSSEC support is available with Postfix 2.11 and later. </dd> 2159 2160<dt><b>fingerprint</b></dt> <dd><a href="#client_tls_fprint">Certificate 2161fingerprint verification.</a> Available with Postfix 2.5 and 2162later. At this security level, there are no trusted certificate 2163authorities. The certificate trust chain, expiration date, ... are 2164not checked. Instead, the optional <b>match</b> attribute, or else 2165the <a href="postconf.5.html">main.cf</a> <b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter, lists 2166the server certificate fingerprints or public key fingerprints 2167(Postfix 2.9 and later). The 2168digest algorithm used to calculate fingerprints is selected by the 2169<b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b> parameter. Multiple fingerprints can 2170be combined with a "|" delimiter in a single match attribute, or multiple 2171match attributes can be employed. The ":" character is not used as a 2172delimiter as it occurs between each pair of fingerprint (hexadecimal) 2173digits. </dd> 2174 2175<dt><b>verify</b></dt> <dd><a href="#client_tls_verify">Mandatory 2176server certificate verification</a>. Mail is delivered only if the 2177TLS handshake succeeds, if the remote SMTP server certificate can 2178be validated (not expired or revoked, and signed by a trusted 2179certificate authority), and if the server certificate name matches 2180the optional "match" attribute (or the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> 2181parameter value when no optional "match" attribute is specified). 2182With Postfix ≥ 2.11 the "tafile" attribute optionally modifies 2183trust chain verification in the same manner as the 2184"<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter. The "tafile" attribute 2185may be specified multiple times to load multiple trust-anchor 2186files. </dd> 2187 2188<dt><b>secure</b></dt> <dd><a href="#client_tls_secure">Secure certificate 2189verification.</a> Mail is delivered only if the TLS handshake succeeds, 2190if the remote SMTP server certificate can be validated (not expired 2191or revoked, and signed by a trusted certificate authority), and if the 2192server certificate name matches the optional "match" attribute (or the 2193<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> parameter value when no optional 2194"match" attribute is specified). With Postfix ≥ 2.11 the "tafile" 2195attribute optionally modifies trust chain verification in the same manner 2196as the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter. The "tafile" attribute 2197may be specified multiple times to load multiple trust-anchor 2198files. </dd> 2199 2200</dl> 2201 2202<p> Notes: </p> 2203 2204<ul> 2205 2206<li> <p> The "match" attribute is especially useful to verify TLS 2207certificates for domains that are hosted on a shared server. In 2208that case, specify "match" rules for the shared server's name. 2209While secure verification can also be achieved with manual routing 2210overrides in Postfix <a href="transport.5.html">transport(5)</a> tables, that approach can deliver 2211mail to the wrong host when domains are assigned to new gateway 2212hosts. The "match" attribute approach avoids the problems of manual 2213routing overrides; mail is deferred if verification of a new MX 2214host fails. </p> 2215 2216<li> <p> When a policy table entry specifies multiple match patterns, 2217multiple match strategies, or multiple protocols, these must be 2218separated by colons. </p> 2219 2220<li> <p> The "exclude" attribute (Postfix ≥ 2.6) is used to disable 2221ciphers that cause handshake failures with a specific mandatory TLS 2222destination, without disabling the ciphers for all mandatory destinations. 2223Alternatively, you can exclude ciphers that cause issues with multiple 2224remote servers in <a href="postconf.5.html">main.cf</a>, and selectively enable them on a per-destination 2225basis in the policy table by setting a shorter or empty exclusion list. The 2226per-destination "exclude" list preempts both the opportunistic and 2227mandatory security level exclusions, so that all excluded ciphers 2228can be enabled for known-good destinations. For non-mandatory TLS 2229destinations that exhibit cipher-specific problems, Postfix will fall 2230back to plain-text delivery. If plain-text is not acceptable make TLS 2231mandatory and exclude the problem ciphers. </p> 2232 2233</ul> 2234 2235<p> 2236Example: 2237</p> 2238 2239<blockquote> 2240<pre> 2241/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2242 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy 2243 # Postfix 2.5 and later 2244 <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = md5 2245/etc/postfix/tls_policy: 2246 example.edu none 2247 example.mil may 2248 example.gov encrypt ciphers=high 2249 example.com verify match=hostname:dot-nexthop ciphers=high 2250 example.net secure 2251 .example.net secure match=.example.net:example.net 2252 [mail.example.org]:587 secure match=nexthop 2253 # Postfix 2.5 and later 2254 [thumb.example.org] fingerprint 2255 match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 2256 match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 2257 # Postfix 2.6 and later 2258 example.info may protocols=!SSLv2 ciphers=medium exclude=3DES 2259</pre> 2260</blockquote> 2261 2262<p> <b>Note:</b> The "hostname" strategy if listed in a non-default setting 2263of <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> or in the "match" attribute in the policy 2264table can render the "secure" level vulnerable to DNS forgery. Do not use 2265the "hostname" strategy for <a href="#client_tls_secure">secure-channel</a> 2266configurations in environments where DNS security is not assured. </p> 2267 2268<h3> <a name="client_tls_discover"> Discovering servers that support 2269TLS </a> </h3> 2270 2271<p> As we decide on a "per site" basis whether or not to use TLS, 2272it would be good to have a list of sites that offered "STARTTLS". 2273We can collect it ourselves with this option. </p> 2274 2275<p> If the <a href="postconf.5.html#smtp_tls_note_starttls_offer">smtp_tls_note_starttls_offer</a> feature is enabled and a 2276server offers STARTTLS while TLS is not already enabled for that 2277server, the Postfix SMTP client logs a line as follows: </p> 2278 2279<blockquote> 2280<pre> 2281postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com] 2282</pre> 2283</blockquote> 2284 2285<p> Example: </p> 2286 2287<blockquote> 2288<pre> 2289/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2290 <a href="postconf.5.html#smtp_tls_note_starttls_offer">smtp_tls_note_starttls_offer</a> = yes 2291</pre> 2292</blockquote> 2293 2294<h3><a name="client_vrfy_server">Server certificate verification depth</a> </h3> 2295 2296<p> The server certificate verification depth is specified with the 2297<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> parameter. The default verification 2298depth is 9 (the OpenSSL default), for compatibility with Postfix 2299versions before 2.5 where <a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> was ignored. 2300When you configure trust 2301in a root CA, it is not necessary to explicitly trust intermediary CAs 2302signed by the root CA, unless $<a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> is less than the 2303number of CAs in the certificate chain for the servers of interest. With 2304a verify depth of 1 you can only verify certificates directly signed 2305by a trusted CA, and all trusted intermediary CAs need to be configured 2306explicitly. With a verify depth of 2 you can verify servers signed by a 2307root CA or a direct intermediary CA (so long as the server is correctly 2308configured to supply its intermediate CA certificate). </p> 2309 2310<p> Example: </p> 2311 2312<blockquote> 2313<pre> 2314/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2315 <a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> = 2 2316</pre> 2317</blockquote> 2318 2319<h3> <a name="client_cipher">Client-side cipher controls </a> </h3> 2320 2321<p> The Postfix SMTP client supports 5 distinct cipher security levels 2322as specified by the <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> configuration 2323parameter. This setting controls the minimum acceptable SMTP client 2324TLS cipher grade for use with mandatory TLS encryption. The default 2325value "medium" is suitable for most destinations with which you may 2326want to enforce TLS, and is beyond the reach of today's cryptanalytic 2327methods. See <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> for information on how to configure 2328ciphers on a per-destination basis. </p> 2329 2330<p> By default anonymous ciphers are allowed, and automatically 2331disabled when remote SMTP server certificates are verified. If you 2332want to 2333disable anonymous ciphers even at the "encrypt" security level, set 2334"<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = aNULL"; and to 2335disable anonymous ciphers even with opportunistic TLS, set 2336"<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a> = aNULL". There is generally 2337no need to take these measures. Anonymous ciphers save bandwidth 2338and TLS session cache space, if certificates are ignored, there is 2339little point in requesting them. </p> 2340 2341<p> The "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>" configuration parameter (Postfix ≥ 2.6) 2342provides control over the minimum cipher grade for opportunistic TLS. With 2343Postfix < 2.6, the minimum opportunistic TLS cipher grade is always 2344"export". </p> 2345 2346<p> With mandatory TLS encryption, the Postfix SMTP client will by 2347default disable SSLv2. SSLv2 is used only when TLS encryption 2348is optional. The mandatory TLS protocol list is specified via the 2349<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> configuration parameter. The corresponding 2350<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a> parameter (Postfix ≥ 2.6) controls 2351the SSL/TLS protocols used with opportunistic TLS. </p> 2352 2353<p> Example: </p> 2354 2355<blockquote> 2356<pre> 2357/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2358 <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> = medium 2359 <a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = RC4, MD5 2360 <a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a> = aNULL 2361 # Preferred form with Postfix ≥ 2.5: 2362 <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> = !SSLv2 2363 # Legacy form for Postfix < 2.5: 2364 <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> = SSLv3, TLSv1 2365 # Also available with Postfix ≥ 2.6: 2366 <a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a> = export 2367 <a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a> = !SSLv2 2368</pre> 2369</blockquote> 2370 2371<h3> <a name="client_smtps">Client-side SMTPS support </a> </h3> 2372 2373<p> Although the Postfix SMTP client by itself doesn't support TLS 2374wrapper mode, it is relatively easy to forward a connection through 2375the stunnel program if Postfix needs to deliver mail to some legacy 2376system that doesn't support STARTTLS. Use one of the following two 2377examples, to send only some remote mail, or to send all remote mail, 2378to an SMTPS server. </p> 2379 2380<h4> Sending all remote mail to an SMTPS server </h4> 2381 2382<p> The first example uses SMTPS to send all remote mail to a 2383provider's mail server called "mail.example.com". </p> 2384 2385<p> A minimal stunnel.conf file is sufficient to set up a tunnel 2386from local port 11125 to the remote destination "mail.example.com" 2387and port "smtps". Postfix will later use this tunnel to connect to 2388the remote server. </p> 2389 2390<blockquote> 2391<pre> 2392/path/to/stunnel.conf: 2393 [smtp-tls-wrapper] 2394 accept = 11125 2395 client = yes 2396 connect = mail.example.com:smtps 2397</pre> 2398</blockquote> 2399 2400<p> To test this tunnel, use: </p> 2401 2402<blockquote> 2403<pre> 2404$ telnet localhost 11125 2405</pre> 2406</blockquote> 2407 2408<p> This should produce the greeting from the remote SMTP server 2409at mail.example.com. </p> 2410 2411<p> On the Postfix side, the <a href="postconf.5.html#relayhost">relayhost</a> feature sends all remote 2412mail through the local stunnel listener on port 11125: </p> 2413 2414<blockquote> 2415<pre> 2416/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2417 <a href="postconf.5.html#relayhost">relayhost</a> = [127.0.0.1]:11125 2418</pre> 2419</blockquote> 2420 2421<p> Use "postfix reload" to make the change effective. </p> 2422 2423<h4> Sending only mail for a specific destination via SMTPS </h4> 2424 2425<p> The second example will use SMTPS to send only mail for 2426"example.com" via SMTPS. It uses the same stunnel configuration 2427file as the first example, so it won't be repeated here. </p> 2428 2429<p> This time, the Postfix side uses a transport map to direct only 2430mail for "example.com" through the tunnel: </p> 2431 2432<blockquote> 2433<pre> 2434/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2435 <a href="postconf.5.html#transport_maps">transport_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport 2436 2437/etc/postfix/transport: 2438 example.com relay:[127.0.0.1]:11125 2439</pre> 2440</blockquote> 2441 2442<p> Use "postmap <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport" and "postfix reload" 2443to make the change effective. </p> 2444 2445<h3> <a name="client_misc"> Miscellaneous client controls </a> </h3> 2446 2447<p> The <a href="postconf.5.html#smtp_starttls_timeout">smtp_starttls_timeout</a> parameter limits the time of Postfix 2448SMTP client write and read operations during TLS startup and shutdown 2449handshake procedures. In case of problems the Postfix SMTP client 2450tries the next network address on the mail exchanger list, and 2451defers delivery if no alternative server is available. </p> 2452 2453<p> Example: </p> 2454 2455<blockquote> 2456<pre> 2457/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2458 <a href="postconf.5.html#smtp_starttls_timeout">smtp_starttls_timeout</a> = 300s 2459</pre> 2460</blockquote> 2461 2462<p> With Postfix 2.8 and later, the <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> parameter 2463specifies a list or bit-mask of OpenSSL bug work-arounds to disable. This 2464may be necessary if one of the work-arounds enabled by default in 2465OpenSSL proves to pose a security risk, or introduces an unexpected 2466interoperability issue. Some bug work-arounds known to be problematic 2467are disabled in the default value of the parameter when linked with 2468an OpenSSL library that could be vulnerable. </p> 2469 2470<p> Example: </p> 2471 2472<blockquote> 2473<pre> 2474/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2475 <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = 0xFFFFFFFF 2476 <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = CVE-2010-4180, LEGACY_SERVER_CONNECT 2477</pre> 2478</blockquote> 2479 2480<p> Note: Disabling LEGACY_SERVER_CONNECT is not wise at this 2481time, lots of servers are still unpatched and Postfix is <a 2482href="http://www.postfix.org/wip.html#tls-renegotiation">not 2483significantly vulnerable</a> to the renegotiation issue in the TLS 2484protocol. </p> 2485 2486<p> With Postfix ≥ 2.11, the tls_ssl_options parameter specifies 2487a list or bit-mask of OpenSSL options to enable. Specify one or 2488more of the named options below, or a hexadecimal bitmask of options 2489found in the ssl.h file corresponding to the run-time OpenSSL 2490library. While it may be reasonable to turn off all bug workarounds 2491(see above), it is not a good idea to attempt to turn on all features. 2492</p> 2493 2494<p> A future version of OpenSSL may by default no longer allow 2495connections to servers that don't support secure renegotiation. 2496Since the exposure for SMTP is minimal, and some SMTP servers may 2497remain unpatched, you can add LEGACY_SERVER_CONNECT to the 2498options to restore the more permissive default of current OpenSSL 2499releases. </p> 2500 2501<p> Example: </p> 2502 2503<blockquote> 2504<pre> 2505/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2506 tls_ssl_options = NO_TICKET, NO_COMPRESSION, LEGACY_SERVER_CONNECT 2507</pre> 2508</blockquote> 2509 2510<p> You should only enable features via the hexadecimal mask when 2511the need to control the feature is critical (to deal with a new 2512vulnerability or a serious interoperability problem). Postfix DOES 2513NOT promise backwards compatible behavior with respect to the mask 2514bits. A feature enabled via the mask in one release may be enabled 2515by other means in a later release, and the mask bit will then be 2516ignored. Therefore, use of the hexadecimal mask is only a temporary 2517measure until a new Postfix or OpenSSL release provides a better 2518solution. </p> 2519 2520<h2><a name="tlsmgr_controls"> TLS manager specific settings </a> </h2> 2521 2522<p> The security of cryptographic software such as TLS depends 2523critically on the ability to generate unpredictable numbers for 2524keys and other information. To this end, the <a href="tlsmgr.8.html">tlsmgr(8)</a> process 2525maintains a Pseudo Random Number Generator (PRNG) pool. This is 2526queried by the <a href="smtp.8.html">smtp(8)</a> and <a href="smtpd.8.html">smtpd(8)</a> processes when they initialize. 2527By default, these daemons request 32 bytes, the equivalent to 256 2528bits. This is more than sufficient to generate a 128bit (or 168bit) 2529session key. </p> 2530 2531<p> Example: </p> 2532 2533<blockquote> 2534<pre> 2535/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2536 <a href="postconf.5.html#tls_daemon_random_bytes">tls_daemon_random_bytes</a> = 32 2537</pre> 2538</blockquote> 2539 2540<p> In order to feed its in-memory PRNG pool, the <a href="tlsmgr.8.html">tlsmgr(8)</a> reads 2541entropy from an external source, both at startup and during run-time. 2542Specify a good entropy source, like EGD or /dev/urandom; be sure 2543to only use non-blocking sources (on OpenBSD, use /dev/arandom 2544when <a href="tlsmgr.8.html">tlsmgr(8)</a> complains about /dev/urandom timeout errors). 2545If the entropy source is not a 2546regular file, you must prepend the source type to the source name: 2547"dev:" for a device special file, or "egd:" for a source with EGD 2548compatible socket interface. </p> 2549 2550<p> Examples (specify only one in <a href="postconf.5.html">main.cf</a>): </p> 2551 2552<blockquote> 2553<pre> 2554/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2555 <a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom 2556 <a href="postconf.5.html#tls_random_source">tls_random_source</a> = egd:/var/run/egd-pool 2557</pre> 2558</blockquote> 2559 2560<p> By default, <a href="tlsmgr.8.html">tlsmgr(8)</a> reads 32 bytes from the external entropy 2561source at each seeding event. This amount (256bits) is more than 2562sufficient for generating a 128bit symmetric key. With EGD and 2563device entropy sources, the <a href="tlsmgr.8.html">tlsmgr(8)</a> limits the amount of data 2564read at each step to 255 bytes. If you specify a regular file as 2565entropy source, a larger amount of data can be read. </p> 2566 2567<p> Example: </p> 2568 2569<blockquote> 2570<pre> 2571/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2572 <a href="postconf.5.html#tls_random_bytes">tls_random_bytes</a> = 32 2573</pre> 2574</blockquote> 2575 2576<p> In order to update its in-memory PRNG pool, the <a href="tlsmgr.8.html">tlsmgr(8)</a> 2577queries the external entropy source again after a pseudo-random 2578amount of time. The time is calculated using the PRNG, and is 2579between 0 and the maximal time specified with <a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a>. 2580The default maximal time interval is 1 hour. </p> 2581 2582<p> Example: </p> 2583 2584<blockquote> 2585<pre> 2586/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2587 <a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a> = 3600s 2588</pre> 2589</blockquote> 2590 2591<p> The <a href="tlsmgr.8.html">tlsmgr(8)</a> process saves the PRNG state to a persistent 2592exchange file at regular times and when the process terminates, so 2593that it can recover the PRNG state the next time it starts up. 2594This file is created when it does not exist. </p> 2595 2596<p> Examples: </p> 2597 2598<blockquote> 2599<pre> 2600/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2601 <a href="postconf.5.html#tls_random_exchange_name">tls_random_exchange_name</a> = /var/db/postfix/prng_exch 2602 <a href="postconf.5.html#tls_random_prng_update_period">tls_random_prng_update_period</a> = 3600s 2603</pre> 2604</blockquote> 2605 2606<p> As of version 2.5, Postfix no longer uses root privileges when 2607opening this file. The file should now be stored under the Postfix-owned 2608<a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to open the file 2609under a non-Postfix directory is redirected to the Postfix-owned 2610<a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. If you wish to continue 2611using a pre-existing PRNG state file, move it to the <a href="postconf.5.html#data_directory">data_directory</a> 2612and change the ownership to the account specified with the <a href="postconf.5.html#mail_owner">mail_owner</a> 2613parameter. </p> 2614 2615<p> With earlier Postfix versions the default file location 2616is under the Postfix configuration directory, which is not the 2617proper place for information that is modified by Postfix. </p> 2618 2619<h2><a name="quick-start">Getting started, quick and dirty</a></h2> 2620 2621<p> The following steps will get you started quickly. Because you 2622sign your own Postfix public key certificate, you get TLS encryption 2623but no TLS authentication. This is sufficient for testing, and 2624for exchanging email with sites that you have no trust relationship 2625with. For real authentication, your Postfix public key certificate 2626needs to be signed by a recognized Certificate Authority, and 2627Postfix needs to be configured with a list of public key certificates 2628of Certificate Authorities, so that Postfix can verify the public key 2629certificates of remote hosts. </p> 2630 2631<p> In the examples below, user input is shown in <b><tt>bold</tt></b> 2632font, and a "<tt>#</tt>" prompt indicates a super-user shell. </p> 2633 2634<ul> 2635 2636<li> <p> Become your own Certificate Authority, so that you can 2637sign your own public keys. This example uses the CA.pl script that 2638ships with OpenSSL. On some systems, OpenSSL installs this as 2639<tt>/usr/local/ssl/misc/CA.pl</tt>. Some systems install this as 2640part of a package named <tt>openssl-perl</tt> or something similar. 2641The script creates a private key in <tt>./demoCA/private/cakey.pem</tt> 2642and a public key in <tt>./demoCA/cacert.pem</tt>.</p> 2643 2644<blockquote> 2645<pre> 2646% <b>/usr/local/ssl/misc/CA.pl -newca</b> 2647CA certificate filename (or enter to create) 2648 2649Making CA certificate ... 2650Using configuration from /etc/ssl/openssl.cnf 2651Generating a 1024 bit RSA private key 2652....................++++++ 2653.....++++++ 2654writing new private key to './demoCA/private/cakey.pem' 2655Enter PEM pass phrase:<b>whatever</b> 2656</pre> 2657</blockquote> 2658 2659<li> <p> Create an unpassworded private key for host foo.porcupine.org and create 2660an unsigned public key certificate. </p> 2661 2662<blockquote> 2663<pre> 2664% <b>openssl req -new -nodes -keyout foo-key.pem -out foo-req.pem -days 365</b> 2665Using configuration from /etc/ssl/openssl.cnf 2666Generating a 1024 bit RSA private key 2667........................................++++++ 2668....++++++ 2669writing new private key to 'foo-key.pem' 2670----- 2671You are about to be asked to enter information that will be incorporated 2672into your certificate request. 2673What you are about to enter is what is called a Distinguished Name or a DN. 2674There are quite a few fields but you can leave some blank 2675For some fields there will be a default value, 2676If you enter '.', the field will be left blank. 2677----- 2678Country Name (2 letter code) [AU]:<b>US</b> 2679State or Province Name (full name) [Some-State]:<b>New York</b> 2680Locality Name (eg, city) []:<b>Westchester</b> 2681Organization Name (eg, company) [Internet Widgits Pty Ltd]:<b>Porcupine</b> 2682Organizational Unit Name (eg, section) []: 2683Common Name (eg, YOUR name) []:<b>foo.porcupine.org</b> 2684Email Address []:<b>wietse@porcupine.org</b> 2685 2686Please enter the following 'extra' attributes 2687to be sent with your certificate request 2688A challenge password []:<b>whatever</b> 2689An optional company name []: 2690</pre> 2691</blockquote> 2692 2693<li> <p> Sign the public key certificate for host foo.porcupine.org with the 2694Certification Authority private key that we created a few 2695steps ago. </p> 2696 2697<blockquote> 2698<pre> 2699% <b>openssl ca -out foo-cert.pem -infiles foo-req.pem</b> 2700Using configuration from /etc/ssl/openssl.cnf 2701Enter PEM pass phrase:<b>whatever</b> 2702Check that the request matches the signature 2703Signature ok 2704The Subjects Distinguished Name is as follows 2705countryName :PRINTABLE:'US' 2706stateOrProvinceName :PRINTABLE:'New York' 2707localityName :PRINTABLE:'Westchester' 2708organizationName :PRINTABLE:'Porcupine' 2709commonName :PRINTABLE:'foo.porcupine.org' 2710emailAddress :IA5STRING:'wietse@porcupine.org' 2711Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days) 2712Sign the certificate? [y/n]:<b>y</b> 2713 2714 27151 out of 1 certificate requests certified, commit? [y/n]<b>y</b> 2716Write out database with 1 new entries 2717Data Base Updated 2718</pre> 2719</blockquote> 2720 2721<li> <p> Install the host private key, the host public key certificate, 2722and the Certification Authority certificate files. This requires 2723super-user privileges. </p> 2724 2725<blockquote> 2726<pre> 2727# <b>cp demoCA/cacert.pem foo-key.pem foo-cert.pem /etc/postfix</b> 2728# <b>chmod 644 /etc/postfix/foo-cert.pem /etc/postfix/cacert.pem</b> 2729# <b>chmod 400 /etc/postfix/foo-key.pem</b> 2730</pre> 2731</blockquote> 2732 2733<li> <p> Configure Postfix, by adding the following to 2734<tt>/etc/postfix/<a href="postconf.5.html">main.cf</a> </tt>. It is generally best to not configure 2735client certificates, unless there are servers which authenticate your mail 2736submission via client certificates. Often servers that perform TLS client 2737authentication will issue the required certificates signed by their own 2738CA. If you configure the client certificate and key incorrectly, you 2739will be unable to send mail to sites that request client certificate, 2740but don't require them from all clients. </p> 2741 2742<blockquote> 2743<pre> 2744/etc/postfix/<a href="postconf.5.html">main.cf</a>: 2745 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/cacert.pem 2746 <a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = 2747 <a href="DATABASE_README.html#types">btree</a>:/var/db/postfix/smtp_tls_session_cache 2748 <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may 2749 <a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> = /etc/postfix/cacert.pem 2750 <a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/foo-cert.pem 2751 <a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = /etc/postfix/foo-key.pem 2752 <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = yes 2753 <a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> = 2754 <a href="DATABASE_README.html#types">btree</a>:/var/db/postfix/smtpd_tls_session_cache 2755 <a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom 2756 <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may 2757</pre> 2758</blockquote> 2759 2760</ul> 2761 2762 2763<h2><a name="build_tls">Building Postfix with TLS support</a></h2> 2764 2765<p> These instructions assume that you build Postfix from source 2766code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may 2767be required if you build Postfix from a vendor-specific source 2768package. </p> 2769 2770<p> To build Postfix with TLS support, first we need to generate 2771the <tt>make(1)</tt> files with the necessary definitions. This is 2772done by invoking the command "<tt>make makefiles</tt>" in the Postfix 2773top-level directory and with arguments as shown next. </p> 2774 2775<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate 2776a Postfix daemon process with exit status code 2, instead of allowing 2777Postfix to 1) report the error to the maillog file, and to 2) provide 2778plaintext service where this is appropriate. </b> </p> 2779 2780<ul> 2781 2782<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are 2783in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries 2784(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in 2785directory <tt>/usr/lib</tt>: </p> 2786 2787<blockquote> 2788<pre> 2789% <b>make tidy</b> # if you have left-over files from a previous build 2790% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b> 2791</pre> 2792</blockquote> 2793 2794<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are 2795in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL 2796libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) 2797are in directory <tt>/usr/local/lib</tt>: </p> 2798 2799<blockquote> 2800<pre> 2801% <b>make tidy</b> # if you have left-over files from a previous build 2802% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \ 2803 AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b> 2804</pre> 2805</blockquote> 2806 2807<p> On Solaris, specify the <tt>-R</tt> option as shown below: 2808 2809<blockquote> 2810<pre> 2811% <b>make tidy</b> # if you have left-over files from a previous build 2812% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \ 2813 AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b> 2814</pre> 2815</blockquote> 2816 2817</ul> 2818 2819<p> If you need to apply other customizations (such as Berkeley DB 2820databases, MySQL, PostgreSQL, LDAP or SASL), see the respective 2821Postfix README documents, and combine their "<tt>make makefiles</tt>" 2822instructions with the instructions above: </p> 2823 2824<blockquote> 2825<pre> 2826% <b>make tidy</b> # if you have left-over files from a previous build 2827% <b>make makefiles CCARGS="-DUSE_TLS \ 2828 <i>(other -D or -I options)</i>" \ 2829 AUXLIBS="-lssl -lcrypto \ 2830 <i>(other -l options for libraries in /usr/lib)</i> \ 2831 <i>(-L/path/name + -l options for other libraries)</i>"</b> 2832</pre> 2833</blockquote> 2834 2835<p> To complete the build process, see the Postfix <a href="INSTALL.html">INSTALL</a> 2836instructions. Postfix has TLS support turned off by default, so 2837you can start using Postfix as soon as it is installed. </p> 2838 2839<h2> <a name="problems"> Reporting problems </a> </h2> 2840 2841<p> Problems are preferably reported via <postfix-users@postfix.org>. 2842See <a href="http://www.postfix.org/lists.html">http://www.postfix.org/lists.html</a> for subscription information. 2843When reporting a problem, please be thorough in the report. Patches, 2844when possible, are greatly appreciated too. </p> 2845 2846<h2><a name="credits">Credits </a> </h2> 2847 2848<ul> 2849 2850<li> TLS support for Postfix was originally developed by Lutz 2851Jänicke at Cottbus Technical University. 2852 2853<li> Wietse Venema adopted the code, did some restructuring, and 2854compiled this part of the documentation from Lutz's documents. 2855 2856<li> Victor Duchovni was instrumental with the re-implementation 2857of the <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> code in terms of enforcement levels, which 2858simplified the implementation greatly. 2859 2860<li> Victor Duchovni implemented the fingerprint security level, 2861added more sanity checks, and separated TLS connection management 2862from security policy enforcement. The latter change simplified the 2863code that verifies certificate signatures, certificate names, and 2864certificate fingerprints. 2865 2866</ul> 2867 2868</body> 2869 2870</html> 2871
