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