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. 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 applies to the key file only, and the certificate file may be 167"world-readable". </p> 168 169<p> Public Internet MX hosts without certificates signed by a "reputable" 170CA must generate, and be prepared to present to most clients, a 171self-signed or private-CA signed certificate. The remote SMTP client 172will generally not be 173able to authenticate the self-signed certificate, but unless the 174client is running Postfix or 175similar software, it will still insist on 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. 191Typically you will 192only have RSA certificates issued by a commercial CA. In addition, 193the tools supplied with OpenSSL will by default issue RSA certificates. 194You can configure all three at the same time, in which case the cipher used 195determines which certificate is presented. For Netscape and OpenSSL 196clients without special cipher choices, the RSA certificate is 197preferred. </p> 198 199<p> To enable a remote SMTP client to verify the Postfix SMTP server 200certificate, the issuing CA certificates must be made available to the 201client. You should include the required certificates in the server 202certificate file, the server certificate first, then the issuing 203CA(s) (bottom-up order). </p> 204 205<p> Example: the certificate for "server.example.com" was issued by 206"intermediate CA" which itself has a certificate issued by "root 207CA". Create the server.pem file with: </p> 208 209<blockquote> 210<pre> 211% <b>cat server_cert.pem intermediate_CA.pem > server.pem</b> 212</pre> 213</blockquote> 214 215<p> A Postfix SMTP server certificate supplied here must be usable 216as SSL server certificate and hence pass the "openssl verify -purpose 217sslserver ..." test. </p> 218 219<p> A client that trusts the root CA has a local copy of the root 220CA certificate, so it is not necessary to include the root CA 221certificate here. Leaving it out of the "server.pem" file reduces 222the overhead of the TLS exchange. </p> 223 224<p> If you want the Postfix SMTP server to accept remote SMTP client 225certificates issued by these CAs, append the root certificate to 226$smtpd_tls_CAfile or install it in the $smtpd_tls_CApath directory. </p> 227 228<p> RSA key and certificate examples: </p> 229 230<blockquote> 231<pre> 232/etc/postfix/main.cf: 233 smtpd_tls_cert_file = /etc/postfix/server.pem 234 smtpd_tls_key_file = $smtpd_tls_cert_file 235</pre> 236</blockquote> 237 238<p> Their DSA counterparts: </p> 239 240<blockquote> 241<pre> 242/etc/postfix/main.cf: 243 smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem 244 smtpd_tls_dkey_file = $smtpd_tls_dcert_file 245</pre> 246</blockquote> 247 248<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9): </p> 249 250<blockquote> 251<pre> 252/etc/postfix/main.cf: 253 # Most clients will not be ECDSA capable, so you will likely also need 254 # an RSA or DSA certificate and private key. 255 # 256 smtpd_tls_eccert_file = /etc/postfix/server-ecdsa.pem 257 smtpd_tls_eckey_file = $smtpd_tls_eccert_file 258</pre> 259</blockquote> 260 261<p> TLS without certificates for servers serving exclusively 262anonymous-cipher capable clients: </p> 263 264<blockquote> 265<pre> 266/etc/postfix/main.cf: 267 smtpd_tls_cert_file = none 268</pre> 269</blockquote> 270 271<p> To verify a remote SMTP client certificate, the Postfix SMTP 272server needs to trust the certificates of the issuing certification 273authorities. These certificates in "PEM" format can be stored in a 274single $smtpd_tls_CAfile or in multiple files, one CA per file in 275the $smtpd_tls_CApath directory. If you use a directory, don't forget 276to create the necessary "hash" links with: </p> 277 278<blockquote> 279<pre> 280# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b> 281</pre> 282</blockquote> 283 284<p> The $smtpd_tls_CAfile contains the CA certificates of one or 285more trusted CAs. The file is opened (with root privileges) before 286Postfix enters the optional chroot jail and so need not be accessible 287from inside the chroot jail. </p> 288 289<p> Additional trusted CAs can be specified via the $smtpd_tls_CApath 290directory, in which case the certificates are read (with $mail_owner 291privileges) from the files in the directory when the information 292is needed. Thus, the $smtpd_tls_CApath directory needs to be 293accessible inside the optional chroot jail. </p> 294 295<p> When you configure the Postfix SMTP server to request <a 296href="#server_vrfy_client">client certificates</a>, the DNs of certificate 297authorities in $smtpd_tls_CAfile are sent to the client, in order to allow 298it to choose an identity signed by a CA you trust. If no $smtpd_tls_CAfile 299is specified, no preferred CA list is sent, and the client is free to 300choose an identity signed by any CA. Many clients use a fixed identity 301regardless of the preferred CA list and you may be able to reduce TLS 302negotiation overhead by installing client CA certificates mostly or 303only in $smtpd_tls_CApath. In the latter case you need not specify a 304$smtpd_tls_CAfile. </p> 305 306<p> Note, that unless client certificates are used to allow greater 307access to TLS authenticated clients, it is best to not ask for 308client certificates at all, as in addition to increased overhead 309some clients (notably in some cases qmail) are unable to complete 310the TLS handshake when client certificates are requested. </p> 311 312<p> Example: </p> 313<blockquote> 314<pre> 315/etc/postfix/main.cf: 316 smtpd_tls_CAfile = /etc/postfix/CAcert.pem 317 smtpd_tls_CApath = /etc/postfix/certs 318</pre> 319</blockquote> 320 321<h3><a name="server_logging"> Server-side TLS activity logging </a> </h3> 322 323<p> To get additional information about Postfix SMTP server TLS 324activity you can increase the log level from 0..4. Each logging 325level also includes the information that is logged at a lower 326logging level. </p> 327 328<blockquote> 329 330<table border="1"> 331 332<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier 333releases. </th> </tr> 334 335<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary 336message on TLS handshake completion — no logging of client 337certificate trust-chain verification errors if client certificate 338verification is not required. </td> <td valign="top"> Disable logging 339of TLS activity.</td> </tr> 340 341<tr> <td valign="top"> 1 </td> <td valign="top"> Also log trust-chain 342verification errors and peer certificate summary information. </td> 343<td valign="top"> Also log TLS handshake and certificate information. 344</td> </tr> 345 346<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also 347log levels during TLS negotiation. </td> </tr> 348 349<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also 350log hexadecimal and ASCII dump of TLS negotiation process. </td> 351</tr> 352 353<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also 354log hexadecimal and ASCII dump of complete transmission after 355STARTTLS. </td></tr> 356 357</table> 358 359</blockquote> 360 361<p> Use log level 3 only in case of problems. Use of log level 4 is 362strongly discouraged. </p> 363 364<p> Example: </p> 365 366<blockquote> 367<pre> 368/etc/postfix/main.cf: 369 smtpd_tls_loglevel = 0 370</pre> 371</blockquote> 372 373<p> To include information about the protocol and cipher used as 374well as the client and issuer CommonName into the "Received:" 375message header, set the smtpd_tls_received_header variable to true. 376The default is no, as the information is not necessarily authentic. 377Only information recorded at the final destination is reliable, 378since the headers may be changed by intermediate servers. </p> 379 380<p> Example: </p> 381 382<blockquote> 383<pre> 384/etc/postfix/main.cf: 385 smtpd_tls_received_header = yes 386</pre> 387</blockquote> 388 389<h3><a name="server_enable">Enabling TLS in the Postfix SMTP server </a> </h3> 390 391<p> By default, TLS is disabled in the Postfix SMTP server, so no 392difference to plain Postfix is visible. Explicitly switch it on 393with "smtpd_tls_security_level = may". </p> 394 395<p> Example: </p> 396 397<blockquote> 398<pre> 399/etc/postfix/main.cf: 400 smtpd_tls_security_level = may 401</pre> 402</blockquote> 403 404<p> With this, the Postfix SMTP server announces STARTTLS support to 405remote SMTP clients, but does not require that clients use TLS encryption. 406</p> 407 408<p> Note: when an unprivileged user invokes "sendmail -bs", STARTTLS 409is never offered due to insufficient privileges to access the Postfix 410SMTP server 411private key. This is intended behavior. </p> 412 413<p> <a name="server_enforce">You can ENFORCE the use of TLS</a>, 414so that the Postfix SMTP server announces STARTTLS and accepts no 415mail without TLS encryption, by setting 416"smtpd_tls_security_level = encrypt". According to RFC 2487 this 417MUST NOT be applied in case 418of a publicly-referenced Postfix SMTP server. This option is off 419by default and should only seldom be used. </p> 420 421<p> Example: </p> 422 423<blockquote> 424<pre> 425/etc/postfix/main.cf: 426 smtpd_tls_security_level = encrypt 427</pre> 428</blockquote> 429 430<p> TLS is sometimes used in the non-standard "wrapper" mode where 431a server always uses TLS, instead of announcing STARTTLS support 432and waiting for remote SMTP clients to request TLS service. Some 433clients, namely 434Outlook [Express] prefer the "wrapper" mode. This is true for OE 435(Win32 < 5.0 and Win32 >=5.0 when run on a port<>25 436and OE (5.01 Mac on all ports). </p> 437 438<p> It is strictly discouraged to use this mode from main.cf. If 439you want to support this service, enable a special port in master.cf 440and specify "-o smtpd_tls_wrappermode=yes" (note: no space around 441the "=") as an smtpd(8) command line option. Port 465 (smtps) was 442once chosen for this feature. 443</p> 444 445<p> Example: </p> 446 447<blockquote> 448<pre> 449/etc/postfix/master.cf: 450 smtps inet n - n - - smtpd 451 -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes 452</pre> 453</blockquote> 454 455<h3><a name="server_vrfy_client">Client certificate verification</a> </h3> 456 457<p> To receive a remote SMTP client certificate, the Postfix SMTP 458server must explicitly ask for one (any contents of $smtpd_tls_CAfile 459are also sent to the client as a hint for choosing a certificate from 460a suitable CA). Unfortunately, Netscape clients will either complain 461if no matching client certificate is available or will offer the user 462client a list of certificates to choose from. Additionally some MTAs 463(notably some versions of qmail) are unable to complete TLS negotiation 464when client certificates are requested, and abort the SMTP session. So 465this option is "off" by default. You will however need the certificate 466if you want to use certificate based relaying with, for example, the 467permit_tls_clientcerts feature. A server that wants client certificates 468must first present its own certificate. While Postfix by default 469offers anonymous ciphers to remote SMTP clients, these are automatically 470suppressed 471when the Postfix SMTP server is configured to ask for client 472certificates. </p> 473 474<p> Example: </p> 475 476<blockquote> 477<pre> 478/etc/postfix/main.cf: 479 smtpd_tls_ask_ccert = yes 480 smtpd_tls_security_level = may 481</pre> 482</blockquote> 483 484<p> When TLS is <a href="#server_enforce">enforced</a> you may also decide 485to REQUIRE a remote SMTP client certificate for all TLS connections, 486by setting "smtpd_tls_req_ccert = yes". This feature implies 487"smtpd_tls_ask_ccert = yes". When TLS is not enforced, 488"smtpd_tls_req_ccert = yes" is ignored and a warning is 489logged. </p> 490 491<p> Example: </p> 492 493<blockquote> 494<pre> 495/etc/postfix/main.cf: 496 smtpd_tls_req_ccert = yes 497 smtpd_tls_security_level = encrypt 498</pre> 499</blockquote> 500 501<p> The client certificate verification depth is specified with the 502main.cf smtpd_tls_ccert_verifydepth parameter. The default verification 503depth is 9 (the OpenSSL default), for compatibility with Postfix 504versions before 2.5 where smtpd_tls_ccert_verifydepth was ignored. 505When you configure trust in a 506root CA, it is not necessary to explicitly trust intermediary CAs signed 507by the root CA, unless $smtpd_tls_ccert_verifydepth is less than the 508number of CAs in the certificate chain for the clients of interest. With 509a verify depth of 1 you can only verify certificates directly signed 510by a trusted CA, and all trusted intermediary CAs need to be configured 511explicitly. With a verify depth of 2 you can verify clients signed by a 512root CA or a direct intermediary CA (so long as the client is correctly 513configured to supply its intermediate CA certificate). </p> 514 515<p> Example: </p> 516 517<blockquote> 518<pre> 519/etc/postfix/main.cf: 520 smtpd_tls_ccert_verifydepth = 2 521</pre> 522</blockquote> 523 524<h3><a name="server_tls_auth">Supporting AUTH over TLS only</a></h3> 525 526<p> Sending AUTH data over an unencrypted channel poses a security 527risk. When TLS layer encryption is required 528("smtpd_tls_security_level = encrypt"), the Postfix SMTP server will 529announce and accept AUTH only after the TLS layer has been activated 530with STARTTLS. When TLS layer encryption is optional 531("smtpd_tls_security_level = may"), it may however still be useful 532to only offer AUTH when TLS is active. To maintain compatibility 533with non-TLS clients, the default is to accept AUTH without encryption. 534In order to change this behavior, set 535"smtpd_tls_auth_only = yes". </p> 536 537<p> Example: </p> 538 539<blockquote> 540<pre> 541/etc/postfix/main.cf: 542 smtpd_tls_auth_only = no 543</pre> 544</blockquote> 545 546<h3><a name="server_tls_cache">Server-side TLS session cache</a> </h3> 547 548<p> The Postfix SMTP server and the remote SMTP client negotiate 549a session, which takes some computer time and network bandwidth. 550By default, this session information is cached only in the smtpd(8) 551process actually using this session and is lost when the process 552terminates. To share the session information between multiple 553smtpd(8) processes, a persistent session cache can be used. You 554can specify any database type that can store objects of several 555kbytes and that supports the sequence operator. DBM databases are 556not suitable because they can only store small objects. The cache 557is maintained by the tlsmgr(8) process, so there is no problem with 558concurrent access. Session caching is highly recommended, because 559the cost of repeatedly negotiating TLS session keys is high.</p> 560 561<p> Example: </p> 562 563<blockquote> 564<pre> 565/etc/postfix/main.cf: 566 smtpd_tls_session_cache_database = btree:/var/db/postfix/smtpd_scache 567</pre> 568</blockquote> 569 570<p> Note: as of version 2.5, Postfix no longer uses root privileges 571when opening this file. The file should now be stored under the 572Postfix-owned data_directory. As a migration aid, an attempt to 573open the file under a non-Postfix directory is redirected to the 574Postfix-owned data_directory, and a warning is logged. </p> 575 576<p> Cached Postfix SMTP server session information expires after 577a certain amount of time. Postfix/TLS does not use the OpenSSL 578default of 300s, but a longer time of 3600sec (=1 hour). RFC 2246 579recommends a maximum of 24 hours. </p> 580 581<p> Example: </p> 582 583<blockquote> 584<pre> 585/etc/postfix/main.cf: 586 smtpd_tls_session_cache_timeout = 3600s 587</pre> 588</blockquote> 589 590<p> When the Postfix SMTP server does not save TLS sessions to an 591external cache database, client-side session caching is unlikely 592to be useful. To prevent such wastage, the Postfix SMTP server can 593be configured to not issue TLS session ids. By default the Postfix 594SMTP server always issues TLS session ids. This works around known 595interoperability issues with some MUAs, and prevents possible 596interoperability issues with other MTAs. </p> 597 598<p> Example: </p> 599 600<blockquote> 601<pre> 602 smtpd_tls_always_issue_session_ids = no 603</pre> 604</blockquote> 605 606<h3><a name="server_access">Server access control</a> </h3> 607 608<p> Postfix TLS support introduces three additional features for 609Postfix SMTP server access control: </p> 610 611<blockquote> 612 613<dl> 614 615<dt> permit_tls_clientcerts </dt> <dd> <p> Allow the remote SMTP 616client request if the client certificate fingerprint or certificate 617public key fingerprint (Postfix 2.9 and later) is listed in the 618client certificate table (see relay_clientcerts discussion below). 619</p> </dd> 620 621<dt> permit_tls_all_clientcerts </dt> <dd> <p> Allow the remote SMTP 622client request if the client certificate passes trust chain verification. 623Useful with private-label CAs that only issue certificates to trusted 624clients (and not otherwise). </p> </dd> 625 626<dt> check_ccert_access type:table</dt> <dd> <p> Use the remote 627SMTP client certificate fingerprint or public key fingerprint 628(Postfix 2.9 and later) as the lookup key for the specified access(5) 629table. </p> </dd> 630 631</dl> 632 633</blockquote> 634 635<p> The digest algorithm used to compute the client certificate 636fingerprints is specified with the main.cf smtpd_tls_fingerprint_digest 637parameter. The default is "md5", for compatibility with Postfix 638versions < 2.5. </p> 639 640<p> The permit_tls_all_clientcerts feature must be used with caution, 641because it can result in too many access permissions. Use this 642feature only if a special CA issues the client certificates, and 643only if this CA is listed as trusted CA. If other CAs are trusted, 644any owner of a valid client certificate would be authorized. 645The permit_tls_all_clientcerts feature can be practical for a 646specially created email relay server. </p> 647 648<p> It is however recommended to stay with the permit_tls_clientcerts 649feature and list all certificates via $relay_clientcerts, as 650permit_tls_all_clientcerts does not permit any control when a 651certificate must no longer be used (e.g. an employee leaving). </p> 652 653<p> Example: </p> 654 655<blockquote> 656<pre> 657/etc/postfix/main.cf: 658 smtpd_recipient_restrictions = 659 ... 660 permit_tls_clientcerts 661 reject_unauth_destination 662 ... 663</pre> 664</blockquote> 665 666<p> Example: Postfix lookup tables are in the form of (key, value) 667pairs. Since we only need the key, the value can be chosen freely, e.g. 668the name of the user or host:</p> 669 670<blockquote> 671<pre> 672/etc/postfix/main.cf: 673 relay_clientcerts = hash:/etc/postfix/relay_clientcerts 674 675/etc/postfix/relay_clientcerts: 676 D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home 677</pre> 678</blockquote> 679 680<h3><a name="server_cipher">Server-side cipher controls</a> </h3> 681 682<p> The Postfix SMTP server supports 5 distinct cipher security levels 683as specified by the smtpd_tls_mandatory_ciphers configuration parameter, 684which determines the cipher grade with mandatory TLS encryption. The 685default value is "medium" which is essentially 128-bit encryption or better. 686With opportunistic TLS encryption, the minimum accepted cipher grade is 687typically "export". The corresponding smtpd_tls_ciphers parameter 688(Postfix ≥ 2.6) controls the cipher grade used with opportunistic 689TLS. </p> 690 691<p> By default anonymous ciphers are enabled. They are automatically 692disabled when remote SMTP client certificates are requested. If 693clients are expected to always verify the Postfix SMTP 694server certificate you may want to disable anonymous ciphers 695by setting "smtpd_tls_mandatory_exclude_ciphers = aNULL" or 696"smtpd_tls_exclude_ciphers = aNULL", as appropriate. One can't force 697a remote SMTP client to check the server certificate, so excluding 698anonymous ciphers is generally unnecessary. </p> 699 700<p> The "smtpd_tls_ciphers" configuration parameter (Postfix ≥ 7012.6) provides control over the minimum cipher grade for opportunistic 702TLS. With 703Postfix < 2.6, the minimum opportunistic TLS cipher grade is always 704"export". </p> 705 706<p> With mandatory TLS encryption, the Postfix SMTP server will by 707default disable SSLv2. SSLv2 is used only when TLS encryption 708is optional. The mandatory TLS protocol list is specified via the 709smtpd_tls_mandatory_protocols configuration parameter. The 710corresponding smtpd_tls_protocols parameter (Postfix ≥ 2.6) 711controls the SSL/TLS protocols used with opportunistic TLS. </p> 712 713<p> Note that the OpenSSL library only supports protocol exclusion 714(not inclusion). For this reason, Postfix can exclude only protocols 715that are known at the time the Postfix software is written. If new 716protocols are added to the OpenSSL library, they cannot be excluded 717without corresponding changes to the Postfix source code. </p> 718 719<p> For a server that is not a public Internet MX host, Postfix 720supports configurations with no <a href="#server_cert_key">server 721certificates</a> that use <b>only</b> the anonymous ciphers. This is 722enabled by explicitly setting "smtpd_tls_cert_file = none" 723and not specifying an smtpd_tls_dcert_file or smtpd_tls_eccert_file. </p> 724 725<p> Example, MSA that requires TLSv1, not SSLv2 or SSLv3, with high grade 726ciphers: </p> 727 728<blockquote> 729<pre> 730/etc/postfix/main.cf: 731 smtpd_tls_cert_file = /etc/postfix/cert.pem 732 smtpd_tls_key_file = /etc/postfix/key.pem 733 smtpd_tls_mandatory_ciphers = high 734 smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5 735 smtpd_tls_security_level = encrypt 736 # Preferred form with Postfix ≥ 2.5: 737 smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3 738 # Alternative form. 739 smtpd_tls_mandatory_protocols = TLSv1 740</pre> 741</blockquote> 742 743<p> If you want to take advantage of ciphers with ephemeral Diffie-Hellman 744(EDH) key exchange (this offers "forward-secrecy"), DH parameters are 745needed. Instead of using the built-in DH parameters for both 1024-bit 746(non-export ciphers) and 512-bit (export ciphers), it is better to 747generate your own parameters, since otherwise it would "pay" for a 748possible attacker to start a brute force attack against parameters that 749are used by everybody. Postfix defaults to compiled-in parameters 750that are shared by all Postfix users who don't generate their own 751settings. </p> 752 753<p> To generate your own set of DH parameters, use: </p> 754 755<blockquote> 756<pre> 757% <b>openssl gendh -out /etc/postfix/dh_512.pem -2 512</b> 758% <b>openssl gendh -out /etc/postfix/dh_1024.pem -2 1024</b> 759</pre> 760</blockquote> 761 762<p> Support for elliptic curve cryptography is available with Postfix 7632.6 and OpenSSL 0.9.9 or later. To enable ephemeral elliptic curve 764Diffie-Hellman (EECDH) key-exchange, set "smtpd_tls_eecdh_grade = 765strong" or "smtpd_tls_eecdh_grade = ultra". The "ultra" setting is 766substantially more CPU intensive, and "strong" is sufficiently 767secure for most situations. </p> 768 769<p> Examples: </p> 770 771<blockquote> 772<pre> 773/etc/postfix/main.cf: 774 smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem 775 smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem 776 # Postfix ≥ 2.6: 777 smtpd_tls_eecdh_grade = strong 778</pre> 779</blockquote> 780 781<p> Postfix 2.8 and later, in combination with OpenSSL 0.9.7 and later 782allows TLS servers to preempt the TLS client's cipher preference list. 783This is possible only with SSLv3 and later, as in SSLv2 the client 784chooses the cipher from a list supplied by the server. </p> 785 786<p> By default, the OpenSSL server selects the client's most preferred 787cipher that the server supports. With SSLv3 and later, the server 788may choose its own most preferred cipher that is supported (offered) 789by the client. Setting "tls_preempt_cipherlist = yes" enables server 790cipher preferences. The default OpenSSL behaviour applies with 791"tls_preempt_cipherlist = no". </p> 792 793<p> While server cipher selection may in some cases lead to a more secure 794or performant cipher choice, there is some risk of interoperability 795issues. In the past, some SSL clients have listed lower priority ciphers 796that they did not implement correctly. If the server chooses a cipher 797that the client prefers less, it may select a cipher whose client 798implementation is flawed. </p> 799 800<h3><a name="server_misc"> Miscellaneous server controls</a> </h3> 801 802<p> The smtpd_starttls_timeout parameter limits the time of Postfix 803SMTP server write and read operations during TLS startup and shutdown 804handshake procedures. </p> 805 806<p> Example: </p> 807 808<blockquote> 809<pre> 810/etc/postfix/main.cf: 811 smtpd_starttls_timeout = 300s 812</pre> 813</blockquote> 814 815<p> With Postfix 2.8 and later, the tls_disable_workarounds parameter 816specifies a list or bit-mask of OpenSSL bug work-arounds to disable. This 817may be necessary if one of the work-arounds enabled by default in 818OpenSSL proves to pose a security risk, or introduces an unexpected 819interoperability issue. Some bug work-arounds known to be problematic 820are disabled in the default value of the parameter when linked with 821an OpenSSL library that could be vulnerable. </p> 822 823<p> Example: </p> 824 825<blockquote> 826<pre> 827/etc/postfix/main.cf: 828 tls_disable_workarounds = 0xFFFFFFFF 829 tls_disable_workarounds = CVE-2010-4180, LEGACY_SERVER_CONNECT 830</pre> 831</blockquote> 832 833<p> Note: Disabling LEGACY_SERVER_CONNECT is not wise at this 834time, lots of servers are still unpatched and Postfix is <a 835href="http://www.postfix.org/wip.html#tls-renegotiation">not 836significantly vulnerable</a> to the renegotiation issue in the TLS 837protocol. </p> 838 839<h2> <a name="client_tls">SMTP Client specific settings</a> </h2> 840 841<p> Topics covered in this section: </p> 842 843<ul> 844 845<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a> 846 847<li><a href="#client_logging"> Client-side TLS activity logging </a> 848 849<li><a href="#client_cert_key">Client-side certificate and private 850key configuration </a> 851 852<li><a href="#client_tls_cache">Client-side TLS session cache</a> 853 854<li><a href="#client_tls_limits"> Client TLS limitations </a> 855 856<li><a href="#client_tls_policy"> Per-destination TLS policy </a> 857 858<li><a href="#client_tls_discover"> Discovering servers that support TLS </a> 859 860<li><a href="#client_vrfy_server">Server certificate verification depth</a> 861 862<li> <a href="#client_cipher">Client-side cipher controls </a> 863 864<li> <a href="#client_smtps">Client-side SMTPS support </a> 865 866<li> <a href="#client_misc"> Miscellaneous client controls </a> 867 868</ul> 869 870<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a> 871</h3> 872 873<p> Similar to the Postfix SMTP server, the Postfix SMTP/LMTP client 874implements multiple TLS security levels. These levels are described 875in more detail in the sections that follow.</p> 876 877<dl> 878<dt><b>none</b></dt> 879<dd><a href="#client_tls_none">No TLS.</a></dd> 880<dt><b>may</b></dt> 881<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd> 882<dt><b>encrypt</b></dt> 883<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a> 884<dt><b>fingerprint</b></dt> 885<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a> 886<dt><b>verify</b></dt> 887<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a> 888<dt><b>secure</b></dt> 889<dd><a href="#client_tls_secure">Secure-channel TLS.</a> 890</dl> 891 892<h4><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a> </h4> 893 894<p> The smtp(8) and lmtp(8) delivery agents are implemented by a 895single dual-purpose program. Specifically, all the TLS features 896described below apply 897equally to SMTP and LMTP, after replacing the "smtp_" prefix of the each 898parameter name with "lmtp_". 899 900<p> The Postfix LMTP delivery agent can communicate with LMTP servers 901listening 902on UNIX-domain sockets. When server certificate verification is enabled 903and the server is listening on a UNIX-domain socket, the $myhostname 904parameter is used to set the TLS verification <i>nexthop</i> and 905<i>hostname</i>. </p> 906 907<p> NOTE: Opportunistic encryption of LMTP traffic over UNIX-domain 908sockets or loopback TCP connections is futile. TLS is only useful 909in this context when 910it is mandatory, typically to allow at least one of the server or the 911client to authenticate the other. The "null" cipher grade may be 912appropriate in this context, when available on both client and server. 913The "null" ciphers provide authentication without encryption. </p> 914 915<h4><a name="client_tls_none"> No TLS encryption </a> </h4> 916 917<p> At the "none" TLS security level, TLS encryption is 918disabled. This is the default security level, and 919can be configured explicitly by setting "smtp_tls_security_level = none". 920For LMTP, use the corresponding "lmtp_" parameter. </p> 921 922<p> Per-destination settings may override this default setting, in which case 923TLS is used selectively, only with destinations explicitly configured 924for TLS. </p> 925 926<p> You can disable TLS for a subset of destinations, while leaving 927it enabled for the rest. With the Postfix TLS <a 928href="#client_tls_policy">policy table</a>, specify the "none" 929security level. 930 931<h4><a name="client_tls_may"> Opportunistic TLS </a> </h4> 932 933<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>. 934The SMTP transaction is encrypted if the STARTTLS ESMTP feature 935is supported by the server. Otherwise, messages are sent in the clear. 936Opportunistic TLS can be configured by setting "smtp_tls_security_level = may". 937For LMTP, use the corresponding "lmtp_" parameter. </p> 938 939<p> Since sending in the clear is acceptable, demanding stronger 940than default TLS security mostly reduces inter-operability. If you 941must restrict TLS protocol or cipher selection even with opportunistic 942TLS, the "smtp_tls_ciphers" and "smtp_tls_protocols" configuration 943parameters (Postfix ≥ 2.6) provide control over the protocols 944and cipher grade 945used with opportunistic TLS. With earlier releases the opportunistic TLS 946cipher grade is always "export" and no protocols are disabled. </p> 947 948<p> With opportunistic TLS, mail delivery continues even if the 949server certificate is untrusted or bears the wrong name. 950When the TLS handshake fails for an opportunistic 951TLS session, rather than give up on mail delivery, the Postfix SMTP 952client retries the transaction 953with TLS disabled. Trying an unencrypted connection makes 954it possible to deliver mail to sites with non-interoperable server 955TLS implementations. </p> 956 957<p> Opportunistic encryption is never used for LMTP over UNIX-domain 958sockets. The communications channel is already confidential without 959TLS, so the only potential benefit of TLS is authentication. Do not 960configure opportunistic TLS for LMTP deliveries over UNIX-domain sockets. 961Only configure TLS for LMTP over UNIX-domain sockets at the 962<a href="#client_tls_encrypt">encrypt</a> security level or higher. 963Attempts to configure opportunistic encryption of LMTP sessions will 964be ignored with a warning written to the mail logs. </p> 965 966<p> You can enable opportunistic TLS just for selected destinations. With 967the Postfix TLS <a href="#client_tls_policy">policy table</a>, 968specify the "may" security level. </p> 969 970<p> This is the most common security level for TLS protected SMTP 971sessions, stronger security is not generally available and, if needed, 972is typically only configured on a per-destination basis. See the section 973on TLS <a href="#client_tls_limits">limitations</a> above. </p> 974 975<p> Example: </p> 976 977<blockquote> 978<pre> 979/etc/postfix/main.cf: 980 smtp_tls_security_level = may 981</pre> 982</blockquote> 983 984<h4><a name="client_tls_encrypt"> Mandatory TLS encryption </a> </h4> 985 986<p> At the "encrypt" TLS security level, messages are sent only 987over TLS encrypted sessions. The SMTP transaction is aborted unless 988the STARTTLS ESMTP feature is supported by the remote SMTP server. 989If no suitable 990servers are found, the message will be deferred. 991Mandatory TLS encryption can be configured by setting 992"smtp_tls_security_level = encrypt". Even though TLS 993encryption is always used, mail delivery continues even if the server 994certificate is untrusted or bears the wrong name. 995For LMTP, use the corresponding "lmtp_" parameter. </p> 996 997<p> At this security level and higher, the smtp_tls_mandatory_protocols 998and smtp_tls_mandatory_ciphers configuration parameters determine 999the list of sufficiently secure SSL protocol versions and the minimum 1000cipher strength. If the protocol or cipher requirements are not 1001met, the mail transaction is aborted. The documentation for these 1002parameters includes useful interoperability and security guidelines. 1003</p> 1004 1005<p> Despite the potential for eliminating passive eavesdropping attacks, 1006mandatory TLS encryption is not viable as a default security level for 1007mail delivery to the public Internet. Most MX hosts do not support TLS at 1008all, and some of those that do have broken implementations. On a host 1009that delivers mail to the Internet, you should not configure mandatory 1010TLS encryption as the default security level. </p> 1011 1012<p> You can enable mandatory TLS encryption just for specific destinations. 1013With the Postfix TLS <a href="#client_tls_policy">policy 1014table</a>, specify the "encrypt" security level. 1015</p> 1016 1017<p> Examples: </p> 1018 1019<p> In the example below, traffic to <i>example.com</i> and its sub-domains 1020via the corresponding MX hosts always uses TLS. The SSLv2 protocol 1021will be disabled (the default setting of smtp_tls_mandatory_protocols 1022excludes "SSLv2"). Only high- or medium-strength (i.e. 128 bit or 1023better) ciphers will be used by default for all "encrypt" security 1024level sessions. </p> 1025 1026<blockquote> 1027<pre> 1028/etc/postfix/main.cf: 1029 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy 1030 1031/etc/postfix/tls_policy: 1032 example.com encrypt 1033 .example.com encrypt 1034</pre> 1035</blockquote> 1036 1037<p> In the next example, secure message submission is configured 1038via the MSA "<tt>[example.net]:587</tt>". TLS sessions are encrypted 1039without authentication, because this MSA does not possess an acceptable 1040certificate. This MSA is known to be capable of "TLSv1" and "high" grade 1041ciphers, so these are selected via the <a href="#client_tls_policy">policy 1042table</a>. </p> 1043 1044<p><b>Note:</b> the policy table lookup key is the verbatim next-hop 1045specification from the recipient domain, transport(5) table or relayhost 1046parameter, with any enclosing square brackets and optional port. Take 1047care to be consistent: the suffixes ":smtp" or ":25" or no port suffix 1048result in different policy table lookup keys, even though they are 1049functionally equivalent nexthop specifications. Use at most one of these 1050forms for all destinations. Below, the policy table has multiple keys, 1051just in case the transport table entries are not specified consistently. </p> 1052 1053<blockquote> 1054<pre> 1055/etc/postfix/main.cf: 1056 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy 1057 1058/etc/services: 1059 submission 587/tcp msa # mail message submission 1060 1061/etc/postfix/tls_policy: 1062 [example.net]:587 encrypt protocols=TLSv1 ciphers=high 1063 [example.net]:msa encrypt protocols=TLSv1 ciphers=high 1064 [example.net]:submission encrypt protocols=TLSv1 ciphers=high 1065</pre> 1066</blockquote> 1067 1068<h4><a name="client_tls_fprint"> Certificate fingerprint verification </a> </h4> 1069 1070<p> Certificate fingerprint verification is available with Postfix 10712.5 and later. At this security level ("smtp_tls_security_level = 1072fingerprint"), no trusted certificate authorities are used or 1073required. The certificate trust chain, expiration date, ... are 1074not checked. Instead, the smtp_tls_fingerprint_cert_match parameter 1075or the "match" attribute in the <a href="#client_tls_policy">policy</a> 1076table lists the remote SMTP server certificate fingerprint or 1077public key fingerprint (Postfix 2.9 and later). 1078 1079<p> If certificate fingerprints are exchanged securely, this is the 1080strongest, and least scalable security level. The administrator needs 1081to securely collect the fingerprints of the X.509 certificates of each 1082peer server, store them into a local file, and update this local file 1083whenever the peer server's public certificate changes. If public key 1084fingerprints are used in place of fingerprints of the entire certificate, 1085the fingerprints remain valid even after the certificate is renewed, 1086<b>provided</b> that the same public/private keys are used to obtain 1087the new certificate. </p> 1088 1089<p> Fingerprint verification may be feasible for an SMTP "VPN" connecting 1090a small number of branch offices over the Internet, or for secure 1091connections to a central mail hub. It works poorly if the remote SMTP 1092server is managed by a third party, and its public certificate changes 1093periodically without prior coordination with the verifying site. </p> 1094 1095<p> The digest algorithm used to calculate the fingerprint is 1096selected by the <b>smtp_tls_fingerprint_digest</b> parameter. In the <a 1097href="#client_tls_policy">policy</a> table multiple fingerprints can be 1098combined with a "|" delimiter in a single match attribute, or multiple 1099match attributes can be employed. The ":" character is not used as a 1100delimiter as it occurs between each pair of fingerprint (hexadecimal) 1101digits. </p> 1102 1103<p> Example: fingerprint TLS security with an internal mailhub. 1104Two matching fingerprints are listed. The relayhost may be multiple 1105physical hosts behind a load-balancer, each with its own private/public 1106key and self-signed certificate. Alternatively, a single relayhost may 1107be in the process of switching from one set of private/public keys to 1108another, and both keys are trusted just prior to the transition. </p> 1109 1110<blockquote> 1111<pre> 1112 relayhost = [mailhub.example.com] 1113 smtp_tls_security_level = fingerprint 1114 smtp_tls_fingerprint_digest = md5 1115 smtp_tls_fingerprint_cert_match = 1116 3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 1117 EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 1118</pre> 1119</blockquote> 1120 1121<p> Example: Certificate fingerprint verification with selected destinations. 1122As in the example above, we show two matching fingerprints: </p> 1123<blockquote> 1124<pre> 1125/etc/postfix/main.cf: 1126 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy 1127 smtp_tls_fingerprint_digest = md5 1128</pre> 1129</blockquote> 1130<blockquote> 1131<pre> 1132/etc/postfix/tls_policy: 1133 example.com fingerprint 1134 match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 1135 match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 1136</pre> 1137</blockquote> 1138 1139<h4><a name="client_tls_verify"> Mandatory server certificate verification </a> </h4> 1140 1141<p> At the "verify" TLS security level, messages are sent only over 1142TLS encrypted sessions if the remote SMTP server certificate is 1143valid (not 1144expired or revoked, and signed by a trusted certificate authority) 1145and where the server certificate name matches a known pattern. 1146Mandatory 1147server certificate verification can be configured by setting 1148"smtp_tls_security_level = verify". The 1149smtp_tls_verify_cert_match parameter can override the default 1150"hostname" certificate name matching strategy. Fine-tuning the 1151matching strategy is generally only appropriate for <a 1152href="#client_tls_secure">secure-channel</a> destinations. 1153For LMTP use the corresponding "lmtp_" parameters. </p> 1154 1155<p> If the server certificate chain is trusted (see smtp_tls_CAfile 1156and smtp_tls_CApath), any DNS names in the SubjectAlternativeName 1157certificate extension are used to verify the remote SMTP server name. 1158If no 1159DNS names are specified, the certificate CommonName is checked. 1160If you want mandatory encryption without server certificate 1161verification, see <a href="#client_tls_encrypt">above</a>. </p> 1162 1163<p> Despite the potential for eliminating "man-in-the-middle" and other 1164attacks, mandatory certificate trust chain and subject name verification 1165is not viable as a default Internet mail delivery policy. Most MX hosts 1166do not support TLS at all, and a significant portion of TLS enabled 1167MTAs use self-signed certificates, or certificates that are signed by 1168a private certificate authority. On a machine that delivers mail to 1169the Internet, you should not configure mandatory server certificate 1170verification as a default policy. </p> 1171 1172<p> Mandatory server certificate verification as a default security 1173level may be appropriate if you know that you will only connect to 1174servers that support RFC 2487 <i>and</i> that present verifiable 1175server certificates. An example would be a client that sends all 1176email to a central mailhub that offers the necessary STARTTLS 1177support. In such cases, you can often use a <a 1178href="#client_tls_secure">secure-channel</a> configuration instead. 1179</p> 1180 1181<p> You can enable mandatory server certificate verification just 1182for specific destinations. With the Postfix TLS <a 1183href="#client_tls_policy">policy table</a>, specify the "verify" 1184security level. </p> 1185 1186<p> Example: </p> 1187 1188<p> In this example, the Postfix SMTP client encrypts all traffic to the 1189<i>example.com</i> domain. The peer hostname is verified, but 1190verification is vulnerable to DNS response forgery. Mail transmission 1191to <i>example.com</i> recipients uses "high" grade ciphers. </p> 1192 1193<blockquote> 1194<pre> 1195/etc/postfix/main.cf: 1196 indexed = ${default_database_type}:${config_directory}/ 1197 smtp_tls_CAfile = ${config_directory}/CAfile.pem 1198 smtp_tls_policy_maps = ${indexed}tls_policy 1199 1200/etc/postfix/tls_policy: 1201 example.com verify ciphers=high 1202</pre> 1203</blockquote> 1204 1205<h4><a name="client_tls_secure"> Secure server certificate verification </a> </h4> 1206 1207<p> At the <i>secure</i> TLS security level, messages are sent only over 1208<i>secure-channel</i> TLS sessions where DNS forgery resistant server 1209certificate verification succeeds. If no suitable servers are found, the 1210message will be deferred. Postfix secure-channels 1211can be configured by setting "smtp_tls_security_level = secure". 1212The smtp_tls_secure_cert_match parameter can override the default 1213"nexthop, dot-nexthop" certificate match strategy. 1214For LMTP, use the corresponding "lmtp_" parameters. </p> 1215 1216<p> If the server certificate chain is trusted (see smtp_tls_CAfile and 1217smtp_tls_CApath), any DNS names in the SubjectAlternativeName certificate 1218extension are used to verify the remote SMTP server name. If no DNS names 1219are 1220specified, the CommonName is checked. If you want mandatory encryption 1221without server certificate verification, see <a 1222href="#client_tls_encrypt">above</a>. </p> 1223 1224<p> Despite the potential for eliminating "man-in-the-middle" and other 1225attacks, mandatory secure server certificate verification is not 1226viable as a default Internet mail delivery policy. Most MX hosts 1227do not support TLS at all, and a significant portion of TLS enabled 1228MTAs use self-signed certificates, or certificates that are signed 1229by a private certificate authority. On a machine that delivers mail 1230to the Internet, you should not configure secure TLS verification 1231as a default policy. </p> 1232 1233<p> Mandatory secure server certificate verification as a default 1234security level may be appropriate if you know that you will only 1235connect to servers that support RFC 2487 <i>and</i> that present 1236verifiable server certificates. An example would be a client that 1237sends all email to a central mailhub that offers the necessary 1238STARTTLS support. </p> 1239 1240<p> You can enable secure TLS verification just for specific destinations. 1241With the Postfix TLS <a href="#client_tls_policy">policy table</a>, 1242specify the "secure" security level. </p> 1243 1244<p> Examples: </p> 1245 1246<ul> 1247 1248<li> <p> Secure-channel TLS without transport(5) table overrides: </p> 1249 1250<p> The Postfix SMTP client will encrypt all traffic and verify the 1251destination name 1252immune from forged DNS responses. MX lookups are still used to find 1253the hostnames of the SMTP servers for <i>example.com</i>, but these 1254hostnames are not used when 1255checking the names in the server certificate(s). Rather, the requirement 1256is that the MX hosts for <i>example.com</i> have trusted certificates 1257with a subject name of <i>example.com</i> or a sub-domain, see the 1258documentation for the smtp_tls_secure_cert_match parameter. </p> 1259 1260<p> The related domains <i>example.co.uk</i> and <i>example.co.jp</i> are 1261hosted on the same MX hosts as the primary <i>example.com</i> domain, and 1262traffic to these is secured by verifying the primary <i>example.com</i> 1263domain in the server certificates. This frees the server administrator 1264from needing the CA to sign certificates that list all the secondary 1265domains. The downside is that clients that want secure channels to the 1266secondary domains need explicit TLS <a href="#client_tls_policy">policy 1267table</a> entries. </p> 1268 1269<p> Note, there are two ways to handle related domains. The first is to 1270use the default routing for each domain, but add policy table entries 1271to override the expected certificate subject name. The second is to 1272override the next-hop in the transport table, and use a single policy 1273table entry for the common nexthop. We choose the first approach, 1274because it works better when domain ownership changes. With the second 1275approach we securely deliver mail to the wrong destination, with the 1276first approach, authentication fails and mail stays in the local queue, 1277the first approach is more appropriate in most cases. <p> 1278 1279<blockquote> 1280<pre> 1281/etc/postfix/main.cf: 1282 smtp_tls_CAfile = /etc/postfix/CAfile.pem 1283 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy 1284 1285/etc/postfix/transport: 1286 1287/etc/postfix/tls_policy: 1288 example.com secure 1289 example.co.uk secure match=example.com:.example.com 1290 example.co.jp secure match=example.com:.example.com 1291</pre> 1292</blockquote> 1293 1294<li> <p> Secure-channel TLS with transport(5) table overrides: <p> 1295 1296<p> In this case traffic to <i>example.com</i> and its related domains 1297is sent to a single logical gateway (to avoid a single point of failure, 1298its name may resolve to one or more load-balancer addresses, or to the 1299combined addresses of multiple physical hosts). All the physical hosts 1300reachable via the gateway's IP addresses have the logical gateway name 1301listed in their certificates. </p> 1302 1303<blockquote> 1304<pre> 1305/etc/postfix/main.cf: 1306 smtp_tls_CAfile = /etc/postfix/CAfile.pem 1307 transport_maps = hash:/etc/postfix/transport 1308 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy 1309 1310/etc/postfix/transport: 1311 example.com smtp:[tls.example.com] 1312 example.co.uk smtp:[tls.example.com] 1313 example.co.jp smtp:[tls.example.com] 1314 1315/etc/postfix/tls_policy: 1316 [tls.example.com] secure match=tls.example.com 1317</pre> 1318</blockquote> 1319 1320</ul> 1321 1322<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3> 1323 1324<p> To get additional information about Postfix SMTP client TLS 1325activity you can increase the loglevel from 0..4. Each logging 1326level also includes the information that is logged at a lower 1327logging level. </p> 1328 1329<blockquote> 1330 1331<table border="1"> 1332 1333<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier 1334releases. </th> </tr> 1335 1336<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary 1337message on TLS handshake completion — no logging of remote 1338SMTP server certificate trust-chain verification errors if server 1339certificate verification is not required. </td> <td valign="top"> 1340Disable logging of TLS activity.</td> </tr> 1341 1342<tr> <td valign="top"> 1 </td> <td valign="top"> Also log remote 1343SMTP server trust-chain verification errors and peer certificate 1344summary information. </td> <td valign="top"> Also log TLS handshake 1345and certificate information. </td> </tr> 1346 1347<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also 1348log levels during TLS negotiation. </td> </tr> 1349 1350<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also 1351log hexadecimal and ASCII dump of TLS negotiation process. </td> 1352</tr> 1353 1354<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also 1355log hexadecimal and ASCII dump of complete transmission after 1356STARTTLS. </td> </tr> 1357 1358</table> 1359 1360</blockquote> 1361 1362<p> Example: </p> 1363 1364<blockquote> 1365<pre> 1366/etc/postfix/main.cf: 1367 smtp_tls_loglevel = 0 1368</pre> 1369</blockquote> 1370 1371<h3><a name="client_cert_key">Client-side certificate and private 1372key configuration </a> </h3> 1373 1374<p> Do not configure Postfix SMTP client certificates unless you <b>must</b> 1375present 1376client TLS certificates to one or more servers. Client certificates are 1377not usually needed, and can cause problems in configurations that work 1378well without them. The recommended setting is to let the defaults stand: </p> 1379 1380<blockquote> 1381<pre> 1382 smtp_tls_cert_file = 1383 smtp_tls_dcert_file = 1384 smtp_tls_key_file = 1385 smtp_tls_dkey_file = 1386 # Postfix ≥ 2.6 1387 smtp_tls_eccert_file = 1388 smtp_tls_eckey_file = 1389</pre> 1390</blockquote> 1391 1392<p> The best way to use the default settings is to comment out the above 1393parameters in main.cf if present. </p> 1394 1395<p> During TLS startup negotiation the Postfix SMTP client may present 1396a certificate to the remote SMTP server. The Netscape client is 1397rather clever here and lets the user select between only those 1398certificates that match CA certificates offered by the remote SMTP 1399server. As the Postfix SMTP client uses the "SSL_connect()" function 1400from the OpenSSL package, this is not possible and we have to choose 1401just one certificate. So for now the default is to use _no_ 1402certificate and key unless one is explicitly specified here. </p> 1403 1404<p> RSA, DSA and ECDSA (Postfix ≥ 2.6) certificates are supported. 1405You can configure all three at the same time, in which case the 1406cipher used determines which certificate is presented. </p> 1407 1408<p> It is possible for the Postfix SMTP client to use the same 1409key/certificate pair as the Postfix SMTP server. If a certificate 1410is to be presented, it must be in "PEM" format. The private key 1411must not be encrypted, meaning: it must be accessible without 1412password. Both parts (certificate and private key) may be in the 1413same file. </p> 1414 1415<p> To enable remote SMTP servers to verify the Postfix SMTP client 1416certificate, the issuing CA certificates must be made available to the 1417server. You should include the required certificates in the client 1418certificate file, the client certificate first, then the issuing 1419CA(s) (bottom-up order). </p> 1420 1421<p> Example: the certificate for "client.example.com" was issued by 1422"intermediate CA" which itself has a certificate issued by "root CA". 1423Create the client.pem file with: </p> 1424 1425<blockquote> 1426<pre> 1427% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b> 1428</pre> 1429</blockquote> 1430 1431<p> A Postfix SMTP client certificate supplied here must be usable 1432as SSL client certificate and hence pass the "openssl verify -purpose 1433sslclient ..." test. </p> 1434 1435<p> A server that trusts the root CA has a local copy of the root 1436CA certificate, so it is not necessary to include the root CA 1437certificate here. Leaving it out of the "client.pem" file reduces 1438the overhead of the TLS exchange. </p> 1439 1440<p> If you want the Postfix SMTP client to accept remote SMTP server 1441certificates issued by these CAs, append the root certificate to 1442$smtp_tls_CAfile or install it in the $smtp_tls_CApath directory. </p> 1443 1444<p> RSA key and certificate examples: </p> 1445 1446<blockquote> 1447<pre> 1448/etc/postfix/main.cf: 1449 smtp_tls_cert_file = /etc/postfix/client.pem 1450 smtp_tls_key_file = $smtp_tls_cert_file 1451</pre> 1452</blockquote> 1453 1454<p> Their DSA counterparts: </p> 1455 1456<blockquote> 1457<pre> 1458/etc/postfix/main.cf: 1459 smtp_tls_dcert_file = /etc/postfix/client-dsa.pem 1460 smtp_tls_dkey_file = $smtp_tls_dcert_file 1461</pre> 1462</blockquote> 1463 1464<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9): </p> 1465 1466<blockquote> 1467<pre> 1468/etc/postfix/main.cf: 1469 smtp_tls_eccert_file = /etc/postfix/client-ecdsa.pem 1470 smtp_tls_eckey_file = $smtp_tls_eccert_file 1471</pre> 1472</blockquote> 1473 1474<p> To verify a remote SMTP server certificate, the Postfix SMTP 1475client needs to trust the certificates of the issuing certification 1476authorities. These certificates in "pem" format can be stored in a 1477single $smtp_tls_CAfile or in multiple files, one CA per file in 1478the $smtp_tls_CApath directory. If you use a directory, don't forget 1479to create the necessary "hash" links with: </p> 1480 1481<blockquote> 1482<pre> 1483# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b> 1484</pre> 1485</blockquote> 1486 1487<p> The $smtp_tls_CAfile contains the CA certificates of one or more 1488trusted CAs. The file is opened (with root privileges) before Postfix 1489enters the optional chroot jail and so need not be accessible from inside the 1490chroot jail. </p> 1491 1492<p> Additional trusted CAs can be specified via the $smtp_tls_CApath 1493directory, in which case the certificates are read (with $mail_owner 1494privileges) from the files in the directory when the information 1495is needed. Thus, the $smtp_tls_CApath directory needs to be accessible 1496inside the optional chroot jail. </p> 1497 1498<p> The choice between $smtp_tls_CAfile and $smtp_tls_CApath is 1499a space/time tradeoff. If there are many trusted CAs, the cost of 1500preloading them all into memory may not pay off in reduced access time 1501when the certificate is needed. </p> 1502 1503<p> Example: </p> 1504 1505<blockquote> 1506<pre> 1507/etc/postfix/main.cf: 1508 smtp_tls_CAfile = /etc/postfix/CAcert.pem 1509 smtp_tls_CApath = /etc/postfix/certs 1510</pre> 1511</blockquote> 1512 1513<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3> 1514 1515<p> The remote SMTP server and the Postfix SMTP client negotiate a 1516session, which takes some computer time and network bandwidth. By 1517default, this session information is cached only in the smtp(8) 1518process actually using this session and is lost when the process 1519terminates. To share the session information between multiple 1520smtp(8) processes, a persistent session cache can be used. You 1521can specify any database type that can store objects of several 1522kbytes and that supports the sequence operator. DBM databases are 1523not suitable because they can only store small objects. The cache 1524is maintained by the tlsmgr(8) process, so there is no problem with 1525concurrent access. Session caching is highly recommended, because 1526the cost of repeatedly negotiating TLS session keys is high. Future 1527Postfix SMTP servers may limit the number of sessions that a client 1528is allowed to negotiate per unit time.</p> 1529 1530 1531<p> Example: </p> 1532 1533<blockquote> 1534<pre> 1535/etc/postfix/main.cf: 1536 smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache 1537</pre> 1538</blockquote> 1539 1540<p> Note: as of version 2.5, Postfix no longer uses root privileges 1541when opening this file. The file should now be stored under the 1542Postfix-owned data_directory. As a migration aid, an attempt to 1543open the file under a non-Postfix directory is redirected to the 1544Postfix-owned data_directory, and a warning is logged. </p> 1545 1546<p> Cached Postfix SMTP client session information expires after 1547a certain amount of time. Postfix/TLS does not use the OpenSSL 1548default of 300s, but a longer time of 3600s (=1 hour). RFC 2246 1549recommends a maximum of 24 hours. </p> 1550 1551<p> Example: </p> 1552 1553<blockquote> 1554<pre> 1555/etc/postfix/main.cf: 1556 smtp_tls_session_cache_timeout = 3600s 1557</pre> 1558</blockquote> 1559 1560<h3><a name="client_tls_limits"> Client TLS limitations </a> 1561</h3> 1562 1563<p> The security properties of TLS communication channels are 1564application specific. While the TLS protocol can provide a confidential, 1565tamper-resistant, mutually authenticated channel between client 1566and server, not all of these security features are applicable to every 1567communication. </p> 1568 1569<p> For example, while mutual TLS authentication between browsers and web 1570servers is possible, it is not practical, or even useful, for web-servers 1571that serve the public to verify the identity of every potential user. In 1572practice, most HTTPS transactions are asymmetric: the browser verifies 1573the HTTPS server's identity, but the user remains anonymous. Much of 1574the security policy is up to the client. If the client chooses to not 1575verify the server's name, the server is not aware of this. There are many 1576interesting browser security topics, but we shall not dwell 1577on them here. Rather, our goal is to understand the security features 1578of TLS in conjunction with SMTP. </p> 1579 1580<p> An important SMTP-specific observation is that a public MX host is 1581even more at the mercy of the SMTP client than is an HTTPS server. Not only 1582can it not enforce due care in the client's use of TLS, but it cannot even 1583enforce the use of TLS, because TLS support in SMTP clients is still the 1584exception rather than the rule. One cannot, in practice, limit access to 1585one's MX hosts to just TLS-enabled clients. Such a policy would result 1586in a vast reduction in one's ability to communicate by email with the 1587world at large. </p> 1588 1589<p> One may be tempted to try enforcing TLS for mail from specific 1590sending organizations, but this, too, runs into obstacles. One such 1591obstacle is that we don't know who is (allegedly) sending mail until 1592we see the "MAIL FROM:" SMTP command, and at that point, if TLS 1593is not already in use, a potentially sensitive sender address (and 1594with SMTP PIPELINING one or more of the recipients) has (have) already been 1595leaked in the clear. Another obstacle is that mail from the sender to 1596the recipient may be forwarded, and the forwarding organization may not 1597have any security arrangements with the final destination. Bounces also 1598need to be protected. These can only be identified by the IP address and 1599HELO name of the connecting client, and it is difficult to keep track 1600of all the potential IP addresses or HELO names of the outbound email 1601servers of the sending organization. </p> 1602 1603<p> Consequently, TLS security for mail delivery to public MX hosts is 1604almost entirely the client's responsibility. The server is largely a 1605passive enabler of TLS security, the rest is up to the client. While the 1606server has a greater opportunity to mandate client security policy when 1607it is a dedicated MSA that only handles outbound mail from trusted clients, 1608below we focus on the client security policy. </p> 1609 1610<p> On the SMTP client, there are further complications. When delivering 1611mail to a given domain, in contrast to HTTPS, one rarely uses the domain 1612name directly as the target host of the SMTP session. More typically, 1613one uses MX lookups - these are usually unauthenticated - to obtain the domain's SMTP server 1614hostname(s). When, as is current practice, the client verifies the 1615insecurely obtained MX hostname, it is subject to a DNS man-in-the-middle 1616attack. </p> 1617 1618<p> If clients instead attempted to verify the recipient domain name, 1619an SMTP server for multiple domains would need to 1620list all its email domain names in its certificate, and generate a 1621new certificate each time a new domain were added. At least some CAs set 1622fairly low limits (20 for one prominent CA) on the number of names that 1623server certificates can contain. This approach is not consistent with 1624current practice and does not scale. </p> 1625 1626<p> It is regrettably the case that TLS <i>secure-channels</i> 1627(fully authenticated and immune to man-in-the-middle attacks) impose 1628constraints on the sending and receiving sites that preclude ubiquitous 1629deployment. One needs to manually configure this type of security for 1630each destination domain, and in many cases implement non-default TLS 1631<a href="#client_tls_policy">policy table</a> entries for additional 1632domains hosted at a common secured destination. For these reasons 1633secure-channel configurations 1634will never be the norm. For the generic domain with which you 1635have made no specific security arrangements, this security level is not 1636a good fit. </p> 1637 1638<p> Given that strong authentication is not generally possible, and that 1639verifiable certificates cost time and money, many servers that implement 1640TLS use self-signed certificates or private CAs. This further limits 1641the applicability of verified TLS on the public Internet. </p> 1642 1643<p> Historical note: while the documentation of these issues and many of the 1644related features were new with Postfix 2.3, the issue was well 1645understood before Postfix 1.0, when Lutz Jänicke was designing 1646the first unofficial Postfix TLS patch. See his original post <a 1647href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a> 1648and the first response <a 1649href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>. 1650The problem is not even unique to SMTP or even TLS, similar issues exist 1651for secure connections via aliases for HTTPS and Kerberos. SMTP merely 1652uses indirect naming (via MX records) more frequently. </p> 1653 1654<h3> <a name="client_tls_policy"> TLS policy table </a> 1655</h3> 1656 1657<p> A small fraction of servers offer STARTTLS but the negotiation 1658consistently fails. As long as encryption is not mandatory, the 1659Postfix SMTP client retries the delivery immediately with TLS 1660disabled, without any need to explicitly disable TLS for the problem 1661destinations. </p> 1662 1663<p> The policy table is specified via the smtp_tls_policy_maps 1664parameter. This lists optional lookup tables with the Postfix SMTP client 1665TLS security policy by next-hop destination. </p> 1666 1667<p> The TLS policy table is indexed by the full next-hop destination, 1668which is either the recipient domain, or the verbatim next-hop 1669specified in the transport table, $local_transport, $virtual_transport, 1670$relay_transport or $default_transport. This includes any enclosing 1671square brackets and any non-default destination server port suffix. The 1672<a href="#client_lmtp_tls">LMTP</a> socket type prefix (inet: or unix:) 1673is not included in the lookup key. </p> 1674 1675<p> Only the next-hop domain, or $myhostname with LMTP over UNIX-domain 1676sockets, is used as the nexthop name for certificate verification. The 1677port and any enclosing square brackets are used in the table lookup key, 1678but are not used for server name verification. </p> 1679 1680<p> When the lookup key is a domain name without enclosing square brackets 1681or any <i>:port</i> suffix (typically the recipient domain), and the full 1682domain is not found in the table, just as with the transport(5) table, 1683the parent domain starting with a leading "." is matched recursively. This 1684allows one to specify a security policy for a recipient domain and all 1685its sub-domains. </p> 1686 1687<p> The lookup result is a security level, followed by an optional 1688list of whitespace and/or comma separated name=value attributes 1689that override related main.cf settings. The TLS security <a 1690href="#client_tls_levels">levels</a> are described above. Below, we 1691describe the corresponding table syntax: </p> 1692 1693<dl> 1694 1695<dt><b>none</b></dt> <dd><a href="#client_tls_none">No TLS</a>. No 1696additional attributes are supported at this level. </dd> 1697 1698<dt><b>may</b></dt> <dd><a href="#client_tls_may">Opportunistic TLS</a>. 1699The optional "ciphers", "exclude" and "protocols" attributes 1700(available for opportunistic TLS with Postfix ≥ 2.6) override the 1701"smtp_tls_ciphers", "smtp_tls_exclude_ciphers" and "smtp_tls_protocols" 1702configuration parameters. </dd> 1703 1704<dt><b>encrypt</b></dt> <dd><a href="#client_tls_encrypt"> Mandatory encryption</a>. 1705Mail is delivered only if the remote SMTP server offers STARTTLS 1706and the TLS handshake succeeds. At this level and higher, the optional 1707"protocols" attribute overrides the main.cf smtp_tls_mandatory_protocols 1708parameter, the optional "ciphers" attribute overrides the 1709main.cf smtp_tls_mandatory_ciphers parameter, and the optional 1710"exclude" attribute (Postfix ≥ 2.6) overrides the main.cf 1711smtp_tls_mandatory_exclude_ciphers parameter. </dd> 1712 1713<dt><b>fingerprint</b></dt> <dd><a href="#client_tls_fprint">Certificate 1714fingerprint verification.</a> Available with Postfix 2.5 and 1715later. At this security level, there are no trusted certificate 1716authorities. The certificate trust chain, expiration date, ... are 1717not checked. Instead, the optional <b>match</b> attribute, or else 1718the main.cf <b>smtp_tls_fingerprint_cert_match</b> parameter, lists 1719the server certificate fingerprints or public key fingerprints 1720(Postfix 2.9 and later). The 1721digest algorithm used to calculate fingerprints is selected by the 1722<b>smtp_tls_fingerprint_digest</b> parameter. Multiple fingerprints can 1723be combined with a "|" delimiter in a single match attribute, or multiple 1724match attributes can be employed. The ":" character is not used as a 1725delimiter as it occurs between each pair of fingerprint (hexadecimal) 1726digits. </dd> 1727 1728<dt><b>verify</b></dt> <dd><a href="#client_tls_verify">Mandatory 1729server certificate verification</a>. Mail is delivered only if the 1730TLS handshake 1731succeeds, if the remote SMTP server certificate can be validated (not 1732expired or revoked, and signed by a trusted certificate authority), and 1733if the server certificate name matches the optional "match" attribute (or 1734the main.cf smtp_tls_verify_cert_match parameter value when no optional 1735"match" attribute is specified). </dd> 1736 1737<dt><b>secure</b></dt> <dd><a href="#client_tls_secure">Secure certificate 1738verification.</a> Mail is delivered only if the TLS handshake succeeds, 1739if the remote SMTP server certificate can be validated (not expired 1740or revoked, and signed by a trusted certificate authority), and if the 1741server certificate name matches the optional "match" attribute (or the 1742main.cf smtp_tls_secure_cert_match parameter value when no optional 1743"match" attribute is specified). </dd> 1744 1745</dl> 1746 1747<p> Notes: </p> 1748 1749<ul> 1750 1751<li> <p> The "match" attribute is especially useful to verify TLS 1752certificates for domains that are hosted on a shared server. In 1753that case, specify "match" rules for the shared server's name. 1754While secure verification can also be achieved with manual routing 1755overrides in Postfix transport(5) tables, that approach can deliver 1756mail to the wrong host when domains are assigned to new gateway 1757hosts. The "match" attribute approach avoids the problems of manual 1758routing overrides; mail is deferred if verification of a new MX 1759host fails. </p> 1760 1761<li> <p> When a policy table entry specifies multiple match patterns, 1762multiple match strategies, or multiple protocols, these must be 1763separated by colons. </p> 1764 1765<li> <p> The "exclude" attribute (Postfix ≥ 2.6) is used to disable 1766ciphers that cause handshake failures with a specific mandatory TLS 1767destination, without disabling the ciphers for all mandatory destinations. 1768Alternatively, you can exclude ciphers that cause issues with multiple 1769remote servers in main.cf, and selectively enable them on a per-destination 1770basis in the policy table by setting a shorter or empty exclusion list. The 1771per-destination "exclude" list preempts both the opportunistic and 1772mandatory security level exclusions, so that all excluded ciphers 1773can be enabled for known-good destinations. For non-mandatory TLS 1774destinations that exhibit cipher-specific problems, Postfix will fall 1775back to plain-text delivery. If plain-text is not acceptable make TLS 1776mandatory and exclude the problem ciphers. </p> 1777 1778</ul> 1779 1780<p> 1781Example: 1782</p> 1783 1784<blockquote> 1785<pre> 1786/etc/postfix/main.cf: 1787 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy 1788 # Postfix 2.5 and later 1789 smtp_tls_fingerprint_digest = md5 1790/etc/postfix/tls_policy: 1791 example.edu none 1792 example.mil may 1793 example.gov encrypt protocols=SSLv3:TLSv1 ciphers=high 1794 example.com verify 1795 match=hostname:dot-nexthop protocols=SSLv3:TLSv1 ciphers=high 1796 example.net secure 1797 .example.net secure match=.example.net:example.net 1798 [mail.example.org]:587 secure match=nexthop 1799 # Postfix 2.5 and later 1800 [thumb.example.org] fingerprint 1801 match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 1802 match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 1803 # Postfix 2.6 and later 1804 example.info may protocols=!SSLv2 ciphers=medium exclude=3DES 1805</pre> 1806</blockquote> 1807 1808<p> <b>Note:</b> The "hostname" strategy if listed in a non-default setting 1809of smtp_tls_secure_cert_match or in the "match" attribute in the policy 1810table can render the "secure" level vulnerable to DNS forgery. Do not use 1811the "hostname" strategy for <a href="#client_tls_secure">secure-channel</a> 1812configurations in environments where DNS security is not assured. </p> 1813 1814<h3> <a name="client_tls_discover"> Discovering servers that support 1815TLS </a> </h3> 1816 1817<p> As we decide on a "per site" basis whether or not to use TLS, 1818it would be good to have a list of sites that offered "STARTTLS". 1819We can collect it ourselves with this option. </p> 1820 1821<p> If the smtp_tls_note_starttls_offer feature is enabled and a 1822server offers STARTTLS while TLS is not already enabled for that 1823server, the Postfix SMTP client logs a line as follows: </p> 1824 1825<blockquote> 1826<pre> 1827postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com] 1828</pre> 1829</blockquote> 1830 1831<p> Example: </p> 1832 1833<blockquote> 1834<pre> 1835/etc/postfix/main.cf: 1836 smtp_tls_note_starttls_offer = yes 1837</pre> 1838</blockquote> 1839 1840<h3><a name="client_vrfy_server">Server certificate verification depth</a> </h3> 1841 1842<p> The server certificate verification depth is specified with the 1843main.cf smtp_tls_scert_verifydepth parameter. The default verification 1844depth is 9 (the OpenSSL default), for compatibility with Postfix 1845versions before 2.5 where smtp_tls_scert_verifydepth was ignored. 1846When you configure trust 1847in a root CA, it is not necessary to explicitly trust intermediary CAs 1848signed by the root CA, unless $smtp_tls_scert_verifydepth is less than the 1849number of CAs in the certificate chain for the servers of interest. With 1850a verify depth of 1 you can only verify certificates directly signed 1851by a trusted CA, and all trusted intermediary CAs need to be configured 1852explicitly. With a verify depth of 2 you can verify servers signed by a 1853root CA or a direct intermediary CA (so long as the server is correctly 1854configured to supply its intermediate CA certificate). </p> 1855 1856<p> Example: </p> 1857 1858<blockquote> 1859<pre> 1860/etc/postfix/main.cf: 1861 smtp_tls_scert_verifydepth = 2 1862</pre> 1863</blockquote> 1864 1865<h3> <a name="client_cipher">Client-side cipher controls </a> </h3> 1866 1867<p> The Postfix SMTP client supports 5 distinct cipher security levels 1868as specified by the smtp_tls_mandatory_ciphers configuration 1869parameter. This setting controls the minimum acceptable SMTP client 1870TLS cipher grade for use with mandatory TLS encryption. The default 1871value "medium" is suitable for most destinations with which you may 1872want to enforce TLS, and is beyond the reach of today's cryptanalytic 1873methods. See smtp_tls_policy_maps for information on how to configure 1874ciphers on a per-destination basis. </p> 1875 1876<p> By default anonymous ciphers are allowed, and automatically 1877disabled when remote SMTP server certificates are verified. If you 1878want to 1879disable anonymous ciphers even at the "encrypt" security level, set 1880"smtp_tls_mandatory_exclude_ciphers = aNULL"; and to 1881disable anonymous ciphers even with opportunistic TLS, set 1882"smtp_tls_exclude_ciphers = aNULL". There is generally 1883no need to take these measures. Anonymous ciphers save bandwidth 1884and TLS session cache space, if certificates are ignored, there is 1885little point in requesting them. </p> 1886 1887<p> The "smtp_tls_ciphers" configuration parameter (Postfix ≥ 2.6) 1888provides control over the minimum cipher grade for opportunistic TLS. With 1889Postfix < 2.6, the minimum opportunistic TLS cipher grade is always 1890"export". </p> 1891 1892<p> With mandatory TLS encryption, the Postfix SMTP client will by 1893default disable SSLv2. SSLv2 is used only when TLS encryption 1894is optional. The mandatory TLS protocol list is specified via the 1895smtp_tls_mandatory_protocols configuration parameter. The corresponding 1896smtp_tls_protocols parameter (Postfix ≥ 2.6) controls 1897the SSL/TLS protocols used with opportunistic TLS. </p> 1898 1899<p> Example: </p> 1900 1901<blockquote> 1902<pre> 1903/etc/postfix/main.cf: 1904 smtp_tls_mandatory_ciphers = medium 1905 smtp_tls_mandatory_exclude_ciphers = RC4, MD5 1906 smtp_tls_exclude_ciphers = aNULL 1907 # Preferred form with Postfix ≥ 2.5: 1908 smtp_tls_mandatory_protocols = !SSLv2 1909 # Alternative form. 1910 smtp_tls_mandatory_protocols = SSLv3, TLSv1 1911 # Also available with Postfix ≥ 2.6: 1912 smtp_tls_ciphers = export 1913 smtp_tls_protocols = !SSLv2 1914</pre> 1915</blockquote> 1916 1917<h3> <a name="client_smtps">Client-side SMTPS support </a> </h3> 1918 1919<p> Although the Postfix SMTP client by itself doesn't support TLS 1920wrapper mode, it is relatively easy to forward a connection through 1921the stunnel program if Postfix needs to deliver mail to some legacy 1922system that doesn't support STARTTLS. Use one of the following two 1923examples, to send only some remote mail, or to send all remote mail, 1924to an SMTPS server. </p> 1925 1926<h4> Sending all remote mail to an SMTPS server </h4> 1927 1928<p> The first example uses SMTPS to send all remote mail to a 1929provider's mail server called "mail.example.com". </p> 1930 1931<p> A minimal stunnel.conf file is sufficient to set up a tunnel 1932from local port 11125 to the remote destination "mail.example.com" 1933and port "smtps". Postfix will later use this tunnel to connect to 1934the remote server. </p> 1935 1936<blockquote> 1937<pre> 1938/path/to/stunnel.conf: 1939 [smtp-tls-wrapper] 1940 accept = 11125 1941 client = yes 1942 connect = mail.example.com:smtps 1943</pre> 1944</blockquote> 1945 1946<p> To test this tunnel, use: </p> 1947 1948<blockquote> 1949<pre> 1950$ telnet localhost 11125 1951</pre> 1952</blockquote> 1953 1954<p> This should produce the greeting from the remote SMTP server 1955at mail.example.com. </p> 1956 1957<p> On the Postfix side, the relayhost feature sends all remote 1958mail through the local stunnel listener on port 11125: </p> 1959 1960<blockquote> 1961<pre> 1962/etc/postfix/main.cf: 1963 relayhost = [127.0.0.1]:11125 1964</pre> 1965</blockquote> 1966 1967<p> Use "postfix reload" to make the change effective. </p> 1968 1969<h4> Sending only mail for a specific destination via SMTPS </h4> 1970 1971<p> The second example will use SMTPS to send only mail for 1972"example.com" via SMTPS. It uses the same stunnel configuration 1973file as the first example, so it won't be repeated here. </p> 1974 1975<p> This time, the Postfix side uses a transport map to direct only 1976mail for "example.com" through the tunnel: </p> 1977 1978<blockquote> 1979<pre> 1980/etc/postfix/main.cf: 1981 transport_maps = hash:/etc/postfix/transport 1982 1983/etc/postfix/transport: 1984 example.com relay:[127.0.0.1]:11125 1985</pre> 1986</blockquote> 1987 1988<p> Use "postmap hash:/etc/postfix/transport" and "postfix reload" 1989to make the change effective. </p> 1990 1991<h3> <a name="client_misc"> Miscellaneous client controls </a> </h3> 1992 1993<p> The smtp_starttls_timeout parameter limits the time of Postfix 1994SMTP client write and read operations during TLS startup and shutdown 1995handshake procedures. In case of problems the Postfix SMTP client 1996tries the next network address on the mail exchanger list, and 1997defers delivery if no alternative server is available. </p> 1998 1999<p> Example: </p> 2000 2001<blockquote> 2002<pre> 2003/etc/postfix/main.cf: 2004 smtp_starttls_timeout = 300s 2005</pre> 2006</blockquote> 2007 2008<h2><a name="tlsmgr_controls"> TLS manager specific settings </a> </h2> 2009 2010<p> The security of cryptographic software such as TLS depends 2011critically on the ability to generate unpredictable numbers for 2012keys and other information. To this end, the tlsmgr(8) process 2013maintains a Pseudo Random Number Generator (PRNG) pool. This is 2014queried by the smtp(8) and smtpd(8) processes when they initialize. 2015By default, these daemons request 32 bytes, the equivalent to 256 2016bits. This is more than sufficient to generate a 128bit (or 168bit) 2017session key. </p> 2018 2019<p> Example: </p> 2020 2021<blockquote> 2022<pre> 2023/etc/postfix/main.cf: 2024 tls_daemon_random_bytes = 32 2025</pre> 2026</blockquote> 2027 2028<p> In order to feed its in-memory PRNG pool, the tlsmgr(8) reads 2029entropy from an external source, both at startup and during run-time. 2030Specify a good entropy source, like EGD or /dev/urandom; be sure 2031to only use non-blocking sources (on OpenBSD, use /dev/arandom 2032when tlsmgr(8) complains about /dev/urandom timeout errors). 2033If the entropy source is not a 2034regular file, you must prepend the source type to the source name: 2035"dev:" for a device special file, or "egd:" for a source with EGD 2036compatible socket interface. </p> 2037 2038<p> Examples (specify only one in main.cf): </p> 2039 2040<blockquote> 2041<pre> 2042/etc/postfix/main.cf: 2043 tls_random_source = dev:/dev/urandom 2044 tls_random_source = egd:/var/run/egd-pool 2045</pre> 2046</blockquote> 2047 2048<p> By default, tlsmgr(8) reads 32 bytes from the external entropy 2049source at each seeding event. This amount (256bits) is more than 2050sufficient for generating a 128bit symmetric key. With EGD and 2051device entropy sources, the tlsmgr(8) limits the amount of data 2052read at each step to 255 bytes. If you specify a regular file as 2053entropy source, a larger amount of data can be read. </p> 2054 2055<p> Example: </p> 2056 2057<blockquote> 2058<pre> 2059/etc/postfix/main.cf: 2060 tls_random_bytes = 32 2061</pre> 2062</blockquote> 2063 2064<p> In order to update its in-memory PRNG pool, the tlsmgr(8) 2065queries the external entropy source again after a pseudo-random 2066amount of time. The time is calculated using the PRNG, and is 2067between 0 and the maximal time specified with tls_random_reseed_period. 2068The default maximal time interval is 1 hour. </p> 2069 2070<p> Example: </p> 2071 2072<blockquote> 2073<pre> 2074/etc/postfix/main.cf: 2075 tls_random_reseed_period = 3600s 2076</pre> 2077</blockquote> 2078 2079<p> The tlsmgr(8) process saves the PRNG state to a persistent 2080exchange file at regular times and when the process terminates, so 2081that it can recover the PRNG state the next time it starts up. 2082This file is created when it does not exist. </p> 2083 2084<p> Examples: </p> 2085 2086<blockquote> 2087<pre> 2088/etc/postfix/main.cf: 2089 tls_random_exchange_name = /var/db/postfix/prng_exch 2090 tls_random_prng_update_period = 3600s 2091</pre> 2092</blockquote> 2093 2094<p> As of version 2.5, Postfix no longer uses root privileges when 2095opening this file. The file should now be stored under the Postfix-owned 2096data_directory. As a migration aid, an attempt to open the file 2097under a non-Postfix directory is redirected to the Postfix-owned 2098data_directory, and a warning is logged. If you wish to continue 2099using a pre-existing PRNG state file, move it to the data_directory 2100and change the ownership to the account specified with the mail_owner 2101parameter. </p> 2102 2103<p> With earlier Postfix versions the default file location 2104is under the Postfix configuration directory, which is not the 2105proper place for information that is modified by Postfix. </p> 2106 2107<h2><a name="quick-start">Getting started, quick and dirty</a></h2> 2108 2109<p> The following steps will get you started quickly. Because you 2110sign your own Postfix public key certificate, you get TLS encryption 2111but no TLS authentication. This is sufficient for testing, and 2112for exchanging email with sites that you have no trust relationship 2113with. For real authentication, your Postfix public key certificate 2114needs to be signed by a recognized Certificate Authority, and 2115Postfix needs to be configured with a list of public key certificates 2116of Certificate Authorities, so that Postfix can verify the public key 2117certificates of remote hosts. </p> 2118 2119<p> In the examples below, user input is shown in <b><tt>bold</tt></b> 2120font, and a "<tt>#</tt>" prompt indicates a super-user shell. </p> 2121 2122<ul> 2123 2124<li> <p> Become your own Certificate Authority, so that you can 2125sign your own public keys. This example uses the CA.pl script that 2126ships with OpenSSL. By default, OpenSSL installs this as 2127<tt>/usr/local/ssl/misc/CA.pl</tt>, but your mileage may vary. 2128The script creates a private key in <tt>./demoCA/private/cakey.pem</tt> 2129and a public key in <tt>./demoCA/cacert.pem</tt>.</p> 2130 2131<blockquote> 2132<pre> 2133% <b>/usr/local/ssl/misc/CA.pl -newca</b> 2134CA certificate filename (or enter to create) 2135 2136Making CA certificate ... 2137Using configuration from /etc/ssl/openssl.cnf 2138Generating a 1024 bit RSA private key 2139....................++++++ 2140.....++++++ 2141writing new private key to './demoCA/private/cakey.pem' 2142Enter PEM pass phrase:<b>whatever</b> 2143</pre> 2144</blockquote> 2145 2146<li> <p> Create an unpassworded private key for host foo.porcupine.org and create 2147an unsigned public key certificate. </p> 2148 2149<blockquote> 2150<pre> 2151% <b>openssl req -new -nodes -keyout foo-key.pem -out foo-req.pem -days 365</b> 2152Using configuration from /etc/ssl/openssl.cnf 2153Generating a 1024 bit RSA private key 2154........................................++++++ 2155....++++++ 2156writing new private key to 'foo-key.pem' 2157----- 2158You are about to be asked to enter information that will be incorporated 2159into your certificate request. 2160What you are about to enter is what is called a Distinguished Name or a DN. 2161There are quite a few fields but you can leave some blank 2162For some fields there will be a default value, 2163If you enter '.', the field will be left blank. 2164----- 2165Country Name (2 letter code) [AU]:<b>US</b> 2166State or Province Name (full name) [Some-State]:<b>New York</b> 2167Locality Name (eg, city) []:<b>Westchester</b> 2168Organization Name (eg, company) [Internet Widgits Pty Ltd]:<b>Porcupine</b> 2169Organizational Unit Name (eg, section) []: 2170Common Name (eg, YOUR name) []:<b>foo.porcupine.org</b> 2171Email Address []:<b>wietse@porcupine.org</b> 2172 2173Please enter the following 'extra' attributes 2174to be sent with your certificate request 2175A challenge password []:<b>whatever</b> 2176An optional company name []: 2177</pre> 2178</blockquote> 2179 2180<li> <p> Sign the public key certificate for host foo.porcupine.org with the 2181Certification Authority private key that we created a few 2182steps ago. </p> 2183 2184<blockquote> 2185<pre> 2186% <b>openssl ca -out foo-cert.pem -infiles foo-req.pem</b> 2187Using configuration from /etc/ssl/openssl.cnf 2188Enter PEM pass phrase:<b>whatever</b> 2189Check that the request matches the signature 2190Signature ok 2191The Subjects Distinguished Name is as follows 2192countryName :PRINTABLE:'US' 2193stateOrProvinceName :PRINTABLE:'New York' 2194localityName :PRINTABLE:'Westchester' 2195organizationName :PRINTABLE:'Porcupine' 2196commonName :PRINTABLE:'foo.porcupine.org' 2197emailAddress :IA5STRING:'wietse@porcupine.org' 2198Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days) 2199Sign the certificate? [y/n]:<b>y</b> 2200 2201 22021 out of 1 certificate requests certified, commit? [y/n]<b>y</b> 2203Write out database with 1 new entries 2204Data Base Updated 2205</pre> 2206</blockquote> 2207 2208<li> <p> Install the host private key, the host public key certificate, 2209and the Certification Authority certificate files. This requires 2210super-user privileges. </p> 2211 2212<blockquote> 2213<pre> 2214# <b>cp demoCA/cacert.pem foo-key.pem foo-cert.pem /etc/postfix</b> 2215# <b>chmod 644 /etc/postfix/foo-cert.pem /etc/postfix/cacert.pem</b> 2216# <b>chmod 400 /etc/postfix/foo-key.pem</b> 2217</pre> 2218</blockquote> 2219 2220<li> <p> Configure Postfix, by adding the following to 2221<tt>/etc/postfix/main.cf </tt>. It is generally best to not configure 2222client certificates, unless there are servers which authenticate your mail 2223submission via client certificates. Often servers that perform TLS client 2224authentication will issue the required certificates signed by their own 2225CA. If you configure the client certificate and key incorrectly, you 2226will be unable to send mail to sites that request client certificate, 2227but don't require them from all clients. </p> 2228 2229<blockquote> 2230<pre> 2231/etc/postfix/main.cf: 2232 smtp_tls_CAfile = /etc/postfix/cacert.pem 2233 smtp_tls_session_cache_database = 2234 btree:/var/db/postfix/smtp_tls_session_cache 2235 smtp_tls_security_level = may 2236 smtpd_tls_CAfile = /etc/postfix/cacert.pem 2237 smtpd_tls_cert_file = /etc/postfix/foo-cert.pem 2238 smtpd_tls_key_file = /etc/postfix/foo-key.pem 2239 smtpd_tls_received_header = yes 2240 smtpd_tls_session_cache_database = 2241 btree:/var/db/postfix/smtpd_tls_session_cache 2242 tls_random_source = dev:/dev/urandom 2243 smtpd_tls_security_level = may 2244</pre> 2245</blockquote> 2246 2247</ul> 2248 2249 2250<h2><a name="build_tls">Building Postfix with TLS support</a></h2> 2251 2252<p> These instructions assume that you build Postfix from source 2253code as described in the INSTALL document. Some modification may 2254be required if you build Postfix from a vendor-specific source 2255package. </p> 2256 2257<p> To build Postfix with TLS support, first we need to generate 2258the <tt>make(1)</tt> files with the necessary definitions. This is 2259done by invoking the command "<tt>make makefiles</tt>" in the Postfix 2260top-level directory and with arguments as shown next. </p> 2261 2262<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate 2263a Postfix daemon process with exit status code 2, instead of allowing 2264Postfix to 1) report the error to the maillog file, and to 2) provide 2265plaintext service where this is appropriate. </b> </p> 2266 2267<ul> 2268 2269<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are 2270in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries 2271(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in 2272directory <tt>/usr/lib</tt>: </p> 2273 2274<blockquote> 2275<pre> 2276% <b>make tidy</b> # if you have left-over files from a previous build 2277% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b> 2278</pre> 2279</blockquote> 2280 2281<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are 2282in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL 2283libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) 2284are in directory <tt>/usr/local/lib</tt>: </p> 2285 2286<blockquote> 2287<pre> 2288% <b>make tidy</b> # if you have left-over files from a previous build 2289% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \ 2290 AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b> 2291</pre> 2292</blockquote> 2293 2294<p> On Solaris, specify the <tt>-R</tt> option as shown below: 2295 2296<blockquote> 2297<pre> 2298% <b>make tidy</b> # if you have left-over files from a previous build 2299% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \ 2300 AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b> 2301</pre> 2302</blockquote> 2303 2304</ul> 2305 2306<p> If you need to apply other customizations (such as Berkeley DB 2307databases, MySQL, PostgreSQL, LDAP or SASL), see the respective 2308Postfix README documents, and combine their "<tt>make makefiles</tt>" 2309instructions with the instructions above: </p> 2310 2311<blockquote> 2312<pre> 2313% <b>make tidy</b> # if you have left-over files from a previous build 2314% <b>make makefiles CCARGS="-DUSE_TLS \ 2315 <i>(other -D or -I options)</i>" \ 2316 AUXLIBS="-lssl -lcrypto \ 2317 <i>(other -l options for libraries in /usr/lib)</i> \ 2318 <i>(-L/path/name + -l options for other libraries)</i>"</b> 2319</pre> 2320</blockquote> 2321 2322<p> To complete the build process, see the Postfix INSTALL 2323instructions. Postfix has TLS support turned off by default, so 2324you can start using Postfix as soon as it is installed. </p> 2325 2326<h2> <a name="problems"> Reporting problems </a> </h2> 2327 2328<p> Problems are preferably reported via <postfix-users@postfix.org>. 2329See http://www.postfix.org/lists.html for subscription information. 2330When reporting a problem, please be thorough in the report. Patches, 2331when possible, are greatly appreciated too. </p> 2332 2333<h2><a name="credits">Credits </a> </h2> 2334 2335<ul> 2336 2337<li> TLS support for Postfix was originally developed by Lutz 2338Jänicke at Cottbus Technical University. 2339 2340<li> Wietse Venema adopted the code, did some restructuring, and 2341compiled this part of the documentation from Lutz's documents. 2342 2343<li> Victor Duchovni was instrumental with the re-implementation 2344of the smtp_tls_per_site code in terms of enforcement levels, which 2345simplified the implementation greatly. 2346 2347<li> Victor Duchovni implemented the fingerprint security level, 2348added more sanity checks, and separated TLS connection management 2349from security policy enforcement. The latter change simplified the 2350code that verifies certificate signatures, certificate names, and 2351certificate fingerprints. 2352 2353</ul> 2354 2355</body> 2356 2357</html> 2358
