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