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