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