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 legacy 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 legacy TLS Support 17</h1> 18 19<hr> 20 21<h2> NOTE </h2> 22 23<p> This document describes an old TLS user interface that is based 24on a third-party TLS patch by Lutz Jänicke. As of Postfix 25version 2.3, the old user interface still exists to allow migration 26from earlier Postfix releases, but its functionality is frozen. </p> 27 28<h2> What Postfix TLS support does for you </h2> 29 30<p> Transport Layer Security (TLS, formerly called SSL) provides 31certificate-based authentication and encrypted sessions. An 32encrypted session protects the information that is transmitted with 33SMTP mail or with SASL authentication. 34 35<p> Postfix version 2.2 introduces support for TLS as described in 36RFC 3207. TLS Support for older Postfix versions was available as 37an add-on patch. The section "<a href="#compat">Compatibility with 38Postfix < 2.2 TLS support</a>" below discusses the differences 39between these implementations. </p> 40 41<p> Topics covered in this document: </p> 42 43<ul> 44 45<li><a href="#how">How Postfix TLS support works</a> 46 47<li><a href="#build_tls">Building Postfix with TLS support</a> 48 49<li><a href="#server_tls">SMTP Server specific settings</a> 50 51<li> <a href="#client_tls">SMTP Client specific settings</a> 52 53<li><a href="#tlsmgr_controls"> TLS manager specific settings </a> 54 55<li><a href="#problems"> Reporting problems </a> 56 57<li><a href="#compat">Compatibility with Postfix < 2.2 TLS support</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><-session-> </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><-session-> 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> To build Postfix with TLS support, first we need to generate 126the <tt>make(1)</tt> files with the necessary definitions. This is 127done by invoking the command "<tt>make makefiles</tt>" in the Postfix 128top-level directory and with arguments as shown next. </p> 129 130<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate 131a Postfix daemon process with exit status code 2, instead of allowing 132Postfix to 1) report the error to the maillog file, and to 2) provide 133plaintext service where this is appropriate. </b> </p> 134 135<ul> 136 137<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are 138in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries 139(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in 140directory <tt>/usr/lib</tt>: </p> 141 142<blockquote> 143<pre> 144% <b>make tidy</b> # if you have left-over files from a previous build 145% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b> 146</pre> 147</blockquote> 148 149<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are 150in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL 151libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) 152are in directory <tt>/usr/local/lib</tt>: </p> 153 154<blockquote> 155<pre> 156% <b>make tidy</b> # if you have left-over files from a previous build 157% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \ 158 AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b> 159</pre> 160</blockquote> 161 162<p> On Solaris, specify the <tt>-R</tt> option as shown below: 163 164<blockquote> 165<pre> 166% <b>make tidy</b> # if you have left-over files from a previous build 167% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \ 168 AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b> 169</pre> 170</blockquote> 171 172</ul> 173 174<p> If you need to apply other customizations (such as Berkeley DB 175databases, MySQL, PosgreSQL, LDAP or SASL), see the respective 176Postfix README documents, and combine their "<tt>make makefiles</tt>" 177instructions with the instructions above: </p> 178 179<blockquote> 180<pre> 181% <b>make tidy</b> # if you have left-over files from a previous build 182% <b>make makefiles CCARGS="-DUSE_TLS \ 183 <i>(other -D or -I options)</i>" \ 184 AUXLIBS="-lssl -lcrypto \ 185 <i>(other -l options for libraries in /usr/lib)</i> \ 186 <i>(-L/path/name + -l options for other libraries)</i>"</b> 187</pre> 188</blockquote> 189 190<p> To complete the build process, see the Postfix INSTALL 191instructions. Postfix has TLS support turned off by default, so 192you can start using Postfix as soon as it is installed. </p> 193 194<h2><a name="server_tls">SMTP Server specific settings</a></h2> 195 196<p> Topics covered in this section: </p> 197 198<ul> 199 200<li><a href="#server_cert_key">Server-side certificate and private 201key configuration </a> 202 203<li><a href="#server_logging"> Server-side TLS activity logging 204</a> 205 206<li><a href="#server_enable">Enabling TLS in the Postfix SMTP server </a> 207 208<li><a href="#server_vrfy_client">Client certificate verification</a> 209 210<li><a href="#server_tls_auth">Supporting AUTH over TLS only</a> 211 212<li><a href="#server_tls_cache">Server-side TLS session cache</a> 213 214<li><a href="#server_access">Server access control</a> 215 216<li><a href="#server_cipher">Server-side cipher controls</a> 217 218<li><a href="#server_misc"> Miscellaneous server controls</a> 219 220</ul> 221 222<h3><a name="server_cert_key">Server-side certificate and private 223key configuration </a> </h3> 224 225<p> In order to use TLS, the Postfix SMTP server needs a certificate 226and a private key. Both must be in "pem" format. The private key 227must not be encrypted, meaning: the key must be accessible without 228password. Both certificate and private key may be in the same 229file. </p> 230 231<p> Both RSA and DSA certificates are supported. Typically you will 232only have RSA certificates issued by a commercial CA. In addition, 233the tools supplied with OpenSSL will by default issue RSA certificates. 234You can have both at the same time, in which case the cipher used 235determines which certificate is presented. For Netscape and OpenSSL 236clients without special cipher choices, the RSA certificate is 237preferred. </p> 238 239<p> In order for remote SMTP clients to check the Postfix SMTP 240server certificates, the CA certificate (in case of a certificate 241chain, all CA certificates) must be available. You should add 242these certificates to the server certificate, the server certificate 243first, then the issuing CA(s). </p> 244 245<p> Example: the certificate for "server.dom.ain" was issued by 246"intermediate CA" which itself has a certificate issued by "root 247CA". Create the server.pem file with: </p> 248 249<blockquote> 250<pre> 251% <b>cat server_cert.pem intermediate_CA.pem > server.pem</b> 252</pre> 253</blockquote> 254 255<p> A Postfix SMTP server certificate supplied here must be usable 256as SSL server certificate and hence pass the "openssl verify -purpose 257sslserver ..." test. </p> 258 259<p> A client that trusts the root CA has a local copy of the root 260CA certificate, so it is not necessary to include the root CA 261certificate here. Leaving it out of the "server.pem" file reduces 262the overhead of the TLS exchange. </p> 263 264<p> If you want the Postfix SMTP server to accept remote SMTP client 265certificates issued by these CAs, append the root certificate to 266$smtpd_tls_CAfile or install it in the $smtpd_tls_CApath directory. When 267you configure trust in a root CA, it is not necessary to explicitly trust 268intermediary CAs signed by the root CA, unless $smtpd_tls_ccert_verifydepth 269is less than the number of CAs in the certificate chain for the clients 270of interest. With a verify depth of 1 you can only verify certificates 271directly signed by a trusted CA, and all trusted intermediary CAs need to 272be configured explicitly. With a verify depth of 2 you can verify clients 273signed by a root CA or a direct intermediary CA (so long as the client 274is correctly configured to supply its intermediate CA certificate). </p> 275 276<p> RSA key and certificate examples: </p> 277 278<blockquote> 279<pre> 280/etc/postfix/main.cf: 281 smtpd_tls_cert_file = /etc/postfix/server.pem 282 smtpd_tls_key_file = $smtpd_tls_cert_file 283</pre> 284</blockquote> 285 286<p> Their DSA counterparts: </p> 287 288<blockquote> 289<pre> 290/etc/postfix/main.cf: 291 smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem 292 smtpd_tls_dkey_file = $smtpd_tls_dcert_file 293</pre> 294</blockquote> 295 296<p> To verify a remote SMTP client certificate, the Postfix SMTP 297server needs to trust the certificates of the issuing certification 298authorities. These certificates in "pem" format can be stored in a 299single $smtpd_tls_CAfile or in multiple files, one CA per file in 300the $smtpd_tls_CApath directory. If you use a directory, don't forget 301to create the necessary "hash" links with: </p> 302 303<blockquote> 304<pre> 305# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b> 306</pre> 307</blockquote> 308 309<p> The $smtpd_tls_CAfile contains the CA certificates of one or 310more trusted CAs. The file is opened (with root privileges) before 311Postfix enters the optional chroot jail and so need not be accessible 312from inside the chroot jail. </p> 313 314<p> Additional trusted CAs can be specified via the $smtpd_tls_CApath 315directory, in which case the certificates are read (with $mail_owner 316privileges) from the files in the directory when the information 317is needed. Thus, the $smtpd_tls_CApath directory needs to be 318accessible inside the optional chroot jail. </p> 319 320<p> When you configure Postfix to request client certificates (by 321setting $smtpd_tls_ask_ccert = yes), any certificates in 322$smtpd_tls_CAfile are sent to the client, in order to allow it to 323choose an identity signed by a CA you trust. If no $smtpd_tls_CAfile 324is specified, no preferred CA list is sent, and the client is free 325to choose an identity signed by any CA. Many clients use a fixed 326identity regardless of the preferred CA list and you may be able 327to reduce TLS negotiation overhead by installing client CA certificates 328mostly or only in $smtpd_tls_CApath. In the latter case you need 329not specify a $smtpd_tls_CAfile. </p> 330 331<p> Note, that unless client certificates are used to allow greater 332access to TLS authenticated clients, it is best to not ask for 333client certificates at all, as in addition to increased overhead 334some clients (notably in some cases qmail) are unable to complete 335the TLS handshake when client certificates are requested. </p> 336 337<p> Example: </p> 338<blockquote> 339<pre> 340/etc/postfix/main.cf: 341 smtpd_tls_CAfile = /etc/postfix/CAcert.pem 342 smtpd_tls_CApath = /etc/postfix/certs 343</pre> 344</blockquote> 345 346<h3><a name="server_logging"> Server-side TLS activity logging </a> </h3> 347 348<p> To get additional information about Postfix SMTP server TLS 349activity you can increase the loglevel from 0..4. Each logging 350level also includes the information that is logged at a lower 351logging level. </p> 352 353<blockquote> 354 355<table> 356 357<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr> 358 359<tr> <td> 1 </td> <td> Log TLS handshake and certificate information. 360</td> </tr> 361 362<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td> 363</tr> 364 365<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS 366negotiation process </td> </tr> 367 368<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete 369transmission after STARTTLS </td> </tr> 370 371</table> 372 373</blockquote> 374 375<p> Use loglevel 3 only in case of problems. Use of loglevel 4 is 376strongly discouraged. </p> 377 378<p> Example: </p> 379 380<blockquote> 381<pre> 382/etc/postfix/main.cf: 383 smtpd_tls_loglevel = 0 384</pre> 385</blockquote> 386 387<p> To include information about the protocol and cipher used as 388well as the client and issuer CommonName into the "Received:" 389message header, set the smtpd_tls_received_header variable to true. 390The default is no, as the information is not necessarily authentic. 391Only information recorded at the final destination is reliable, 392since the headers may be changed by intermediate servers. </p> 393 394<p> Example: </p> 395 396<blockquote> 397<pre> 398/etc/postfix/main.cf: 399 smtpd_tls_received_header = yes 400</pre> 401</blockquote> 402 403<h3><a name="server_enable">Enabling TLS in the Postfix SMTP server </a> </h3> 404 405<p> By default, TLS is disabled in the Postfix SMTP server, so no 406difference to plain Postfix is visible. Explicitly switch it on 407using "smtpd_use_tls = yes". </p> 408 409<p> Example: </p> 410 411<blockquote> 412<pre> 413/etc/postfix/main.cf: 414 smtpd_use_tls = yes 415</pre> 416</blockquote> 417 418<p> With this, Postfix SMTP server announces STARTTLS support to 419SMTP clients, but does not require that clients use TLS encryption. 420</p> 421 422<p> Note: when an unprivileged user invokes "sendmail -bs", STARTTLS 423is never offered due to insufficient privileges to access the server 424private key. This is intended behavior. </p> 425 426<p> You can ENFORCE the use of TLS, so that the Postfix SMTP server 427announces STARTTLS and accepts no mail without TLS encryption, by 428setting "smtpd_enforce_tls = yes". According to RFC 2487 this MUST 429NOT be applied in case of a publicly-referenced Postfix SMTP server. 430This option is off by default and should only seldom be used. </p> 431 432<p> Example: </p> 433 434<blockquote> 435<pre> 436/etc/postfix/main.cf: 437 smtpd_enforce_tls = yes 438</pre> 439</blockquote> 440 441<p> TLS is sometimes used in the non-standard "wrapper" mode where 442a server always uses TLS, instead of announcing STARTTLS support 443and waiting for clients to request TLS service. Some clients, namely 444Outlook [Express] prefer the "wrapper" mode. This is true for OE 445(Win32 < 5.0 and Win32 >=5.0 when run on a port<>25 446and OE (5.01 Mac on all ports). </p> 447 448<p> It is strictly discouraged to use this mode from main.cf. If 449you want to support this service, enable a special port in master.cf 450and specify "-o smtpd_tls_wrappermode = yes" as an smtpd(8) command 451line option. Port 465 (smtps) was once chosen for this feature. 452</p> 453 454<p> Example: </p> 455 456<blockquote> 457<pre> 458/etc/postfix/master.cf: 459 smtps inet n - n - - smtpd 460 -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes 461</pre> 462</blockquote> 463 464<h3><a name="server_vrfy_client">Client certificate verification</a> </h3> 465 466<p> To receive a remote SMTP client certificate, the Postfix SMTP 467server must explicitly ask for one (any contents of $smtpd_tls_CAfile 468are also sent to the client as a hint for choosing a certificate 469from a suitable CA). Unfortunately, Netscape clients will either 470complain if no matching client certificate is available or will 471offer the user client a list of certificates to choose from. 472Additionally some MTAs (notably some versions of qmail) are unable 473to complete TLS negotiation when client certificates are requested, 474and abort the SMTP session. So this option is "off" by default. 475You will however need the certificate if you want to use certificate 476based relaying with, for example, the permit_tls_clientcerts 477feature. </p> 478 479<p> Example: </p> 480 481<blockquote> 482<pre> 483/etc/postfix/main.cf: 484 smtpd_tls_ask_ccert = no 485</pre> 486</blockquote> 487 488<p> You may also decide to REQUIRE a remote SMTP client certificate 489before allowing TLS connections. This feature is included for 490completeness, and implies "smtpd_tls_ask_ccert = yes". </p> 491 492<p> Please be aware, that this will inhibit TLS connections without 493a proper client certificate and that it makes sense only when 494non-TLS submission is disabled (smtpd_enforce_tls = yes). Otherwise, 495clients could bypass the restriction by simply not using STARTTLS 496at all. </p> 497 498<p> When TLS is not enforced, the connection will be handled as 499if only "smtpd_tls_ask_ccert = yes" is specified, and a warning is 500logged. </p> 501 502<p> Example: </p> 503 504<blockquote> 505<pre> 506/etc/postfix/main.cf: 507 smtpd_tls_req_ccert = no 508</pre> 509</blockquote> 510 511<p> A client certificate verification depth of 1 is sufficient if 512the certificate is directly issued by a CA listed in the CA file. 513The default value (5) should also suffice for longer chains (root 514CA issues special CA which then issues the actual certificate...) 515</p> 516 517<p> Example: </p> 518 519<blockquote> 520<pre> 521/etc/postfix/main.cf: 522 smtpd_tls_ccert_verifydepth = 5 523</pre> 524</blockquote> 525 526<h3><a name="server_tls_auth">Supporting AUTH over TLS only</a></h3> 527 528<p> Sending AUTH data over an unencrypted channel poses a security 529risk. When TLS layer encryption is required (smtpd_enforce_tls = 530yes), the Postfix SMTP server will announce and accept AUTH only 531after the TLS layer has been activated with STARTTLS. When TLS 532layer encryption is optional (smtpd_enforce_tls = no), it may 533however still be useful to only offer AUTH when TLS is active. To 534maintain compatibility with non-TLS clients, the default is to 535accept AUTH without encryption. In order to change this behavior, 536set "smtpd_tls_auth_only = yes". </p> 537 538<p> Example: </p> 539 540<blockquote> 541<pre> 542/etc/postfix/main.cf: 543 smtpd_tls_auth_only = no 544</pre> 545</blockquote> 546 547<h3><a name="server_tls_cache">Server-side TLS session cache</a> </h3> 548 549<p> The Postfix SMTP server and the remote SMTP client negotiate 550a session, which takes some computer time and network bandwidth. 551By default, this session information is cached only in the smtpd(8) 552process actually using this session and is lost when the process 553terminates. To share the session information between multiple 554smtpd(8) processes, a persistent session cache can be used. You 555can specify any database type that can store objects of several 556kbytes and that supports the sequence operator. DBM databases are 557not suitable because they can only store small objects. The cache 558is maintained by the tlsmgr(8) process, so there is no problem with 559concurrent access. Session caching is highly recommended, because 560the cost of repeatedly negotiating TLS session keys is high.</p> 561 562<p> Example: </p> 563 564<blockquote> 565<pre> 566/etc/postfix/main.cf: 567 smtpd_tls_session_cache_database = btree:/etc/postfix/smtpd_scache 568</pre> 569</blockquote> 570 571<p> As of version 2.5, Postfix will no longer maintain this file 572in a directory with non-Postfix ownership. As a migration aid, 573attempts to open such files are redirected to the Postfix-owned 574$data_directory, and a warning is logged. </p> 575 576<p> Cached Postfix SMTP server session information expires after 577a certain amount of time. Postfix/TLS does not use the OpenSSL 578default of 300s, but a longer time of 3600sec (=1 hour). RFC 2246 579recommends a maximum of 24 hours. </p> 580 581<p> Example: </p> 582 583<blockquote> 584<pre> 585/etc/postfix/main.cf: 586 smtpd_tls_session_cache_timeout = 3600s 587</pre> 588</blockquote> 589 590<h3><a name="server_access">Server access control</a> </h3> 591 592<p> Postfix TLS support introduces three additional features for 593Postfix SMTP server access control: </p> 594 595<blockquote> 596 597<dl> 598 599<dt> permit_tls_clientcerts </dt> <dd> <p> Allow the remote SMTP 600client SMTP request if the client certificate passes verification, 601and if its fingerprint is listed in the list of client certificates 602(see relay_clientcerts discussion below). </p> </dd> 603 604<dt> permit_tls_all_clientcerts </dt> <dd> <p> Allow the remote 605client SMTP request if the client certificate passes verification. 606</p> </dd> 607 608<dt> check_ccert_access type:table</dt> <dd> 609<p> If the client certificate passes verification, use its fingerprint 610as a key for the specified access(5) table. </p> </dd> 611 612</dl> 613 614</blockquote> 615 616<p> The permit_tls_all_clientcerts feature must be used with caution, 617because it can result in too many access permissions. Use this 618feature only if a special CA issues the client certificates, and 619only if this CA is listed as trusted CA. If other CAs are trusted, 620any owner of a valid client certificate would be authorized. 621The permit_tls_all_clientcerts feature can be practical for a 622specially created email relay server. </p> 623 624<p> It is however recommended to stay with the permit_tls_clientcerts 625feature and list all certificates via $relay_clientcerts, as 626permit_tls_all_clientcerts does not permit any control when a 627certificate must no longer be used (e.g. an employee leaving). </p> 628 629<p> Example: </p> 630 631<blockquote> 632<pre> 633/etc/postfix/main.cf: 634 smtpd_recipient_restrictions = 635 ... 636 permit_tls_clientcerts 637 reject_unauth_destination 638 ... 639</pre> 640</blockquote> 641 642<p> The Postfix list manipulation routines give special treatment 643to whitespace and some other characters, making the use of certificate 644names impractical. Instead we use the certificate fingerprints as 645they are difficult to fake but easy to use for lookup. Postfix 646lookup tables are in the form of (key, value) pairs. Since we only 647need the key, the value can be chosen freely, e.g. the name of 648the user or host.</p> 649 650<p> Example: </p> 651 652<blockquote> 653<pre> 654/etc/postfix/main.cf: 655 relay_clientcerts = hash:/etc/postfix/relay_clientcerts 656 657/etc/postfix/relay_clientcerts: 658 D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home 659</pre> 660</blockquote> 661 662<h3><a name="server_cipher">Server-side cipher controls</a> </h3> 663 664<p> To influence the Postfix SMTP server cipher selection scheme, 665you can give cipherlist string. A detailed description would go 666to far here; please refer to the OpenSSL documentation. If you 667don't know what to do with it, simply don't touch it and leave the 668(openssl-)compiled in default! </p> 669 670<p> DO NOT USE " to enclose the string, specify just the string!!! </p> 671 672<p> Example: </p> 673 674<blockquote> 675<pre> 676/etc/postfix/main.cf: 677 smtpd_tls_cipherlist = DEFAULT 678</pre> 679</blockquote> 680 681<p> If you want to take advantage of ciphers with EDH, DH parameters 682are needed. Instead of using the built-in DH parameters for both 6831024bit and 512bit, it is better to generate "own" parameters, 684since otherwise it would "pay" for a possible attacker to start a 685brute force attack against parameters that are used by everybody. 686For this reason, the parameters chosen are already different from 687those distributed with other TLS packages. </p> 688 689<p> To generate your own set of DH parameters, use: </p> 690 691<blockquote> 692<pre> 693% <b>openssl gendh -out /etc/postfix/dh_1024.pem -2 -rand /var/run/egd-pool 1024</b> 694% <b>openssl gendh -out /etc/postfix/dh_512.pem -2 -rand /var/run/egd-pool 512</b> 695</pre> 696</blockquote> 697 698<p> Examples: </p> 699 700<blockquote> 701<pre> 702/etc/postfix/main.cf: 703 smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem 704 smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem 705</pre> 706</blockquote> 707 708<h3><a name="server_misc"> Miscellaneous server controls</a> </h3> 709 710<p> The smtpd_starttls_timeout parameter limits the time of Postfix 711SMTP server write and read operations during TLS startup and shutdown 712handshake procedures. </p> 713 714<p> Example: </p> 715 716<blockquote> 717<pre> 718/etc/postfix/main.cf: 719 smtpd_starttls_timeout = 300s 720</pre> 721</blockquote> 722 723<h2> <a name="client_tls">SMTP Client specific settings</a> </h2> 724 725<p> Topics covered in this section: </p> 726 727<ul> 728 729<li><a href="#client_cert_key">Client-side certificate and private 730key configuration </a> 731 732<li><a href="#client_logging"> Client-side TLS activity logging 733</a> 734 735<li><a href="#client_tls_cache">Client-side TLS session cache</a> 736 737<li><a href="#client_tls_enable"> Enabling TLS in the Postfix SMTP client </a> 738 739<li><a href="#client_tls_require"> Requiring TLS encryption </a> 740 741<li><a href="#client_tls_nopeer"> Disabling server certificate verification </a> 742 743<li><a href="#client_tls_per_site"> Per-site TLS policies </a> 744 745<!-- 746<li><a href="#client_tls_obs"> Obsolete per-site TLS policy support </a> 747--> 748 749<li><a href="#client_tls_harden"> Closing a DNS loophole with <!-- legacy --> per-site TLS policies </a> 750 751<li><a href="#client_tls_discover"> Discovering servers that support TLS </a> 752 753<li><a href="#client_vrfy_server">Server certificate verification depth</a> 754 755<li> <a href="#client_cipher">Client-side cipher controls </a> 756 757<li> <a href="#client_misc"> Miscellaneous client controls </a> 758 759</ul> 760 761<h3><a name="client_cert_key">Client-side certificate and private 762key configuration </a> </h3> 763 764<p> During TLS startup negotiation the Postfix SMTP client may present 765a certificate to the remote SMTP server. The Netscape client is 766rather clever here and lets the user select between only those 767certificates that match CA certificates offered by the remote SMTP 768server. As the Postfix SMTP client uses the "SSL_connect()" function 769from the OpenSSL package, this is not possible and we have to choose 770just one certificate. So for now the default is to use _no_ 771certificate and key unless one is explicitly specified here. </p> 772 773<p> Both RSA and DSA certificates are supported. You can have both 774at the same time, in which case the cipher used determines which 775certificate is presented. </p> 776 777<p> It is possible for the Postfix SMTP client to use the same 778key/certificate pair as the Postfix SMTP server. If a certificate 779is to be presented, it must be in "pem" format. The private key 780must not be encrypted, meaning: it must be accessible without 781password. Both parts (certificate and private key) may be in the 782same file. </p> 783 784<p> In order for remote SMTP servers to verify the Postfix SMTP 785client certificates, the CA certificate (in case of a certificate 786chain, all CA certificates) must be available. You should add 787these certificates to the client certificate, the client certificate 788first, then the issuing CA(s). </p> 789 790<p> Example: the certificate for "client.example.com" was issued by 791"intermediate CA" which itself has a certificate of "root CA". 792Create the client.pem file with: </p> 793 794<blockquote> 795<pre> 796% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b> 797</pre> 798</blockquote> 799 800<p> A Postfix SMTP client certificate supplied here must be usable 801as SSL client certificate and hence pass the "openssl verify -purpose 802sslclient ..." test. </p> 803 804<p> A server that trusts the root CA has a local copy of the root 805CA certificate, so it is not necessary to include the root CA 806certificate here. Leaving it out of the "client.pem" file reduces 807the overhead of the TLS exchange. </p> 808 809<p> If you want the Postfix SMTP client to accept remote SMTP server 810certificates issued by these CAs, append the root certificate to 811$smtp_tls_CAfile or install it in the $smtp_tls_CApath directory. When 812you configure trust in a root CA, it is not necessary to explicitly trust 813intermediary CAs signed by the root CA, unless $smtp_tls_scert_verifydepth 814is less than the number of CAs in the certificate chain for the servers 815of interest. With a verify depth of 1 you can only verify certificates 816directly signed by a trusted CA, and all trusted intermediary CAs need to 817be configured explicitly. With a verify depth of 2 you can verify servers 818signed by a root CA or a direct intermediary CA (so long as the server 819is correctly configured to supply its intermediate CA certificate). </p> 820 821<p> RSA key and certificate examples: </p> 822 823<blockquote> 824<pre> 825/etc/postfix/main.cf: 826 smtp_tls_cert_file = /etc/postfix/client.pem 827 smtp_tls_key_file = $smtp_tls_cert_file 828</pre> 829</blockquote> 830 831<p> Their DSA counterparts: </p> 832 833<blockquote> 834<pre> 835/etc/postfix/main.cf: 836 smtp_tls_dcert_file = /etc/postfix/client-dsa.pem 837 smtp_tls_dkey_file = $smtp_tls_dcert_file 838</pre> 839</blockquote> 840 841<p> To verify a remote SMTP server certificate, the Postfix SMTP 842client needs to trust the certificates of the issuing certification 843authorities. These certificates in "pem" format can be stored in a 844single $smtp_tls_CAfile or in multiple files, one CA per file in 845the $smtp_tls_CApath directory. If you use a directory, don't forget 846to create the necessary "hash" links with: </p> 847 848<blockquote> 849<pre> 850# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b> 851</pre> 852</blockquote> 853 854<p> The $smtp_tls_CAfile contains the CA certificates of one or more 855trusted CAs. The file is opened (with root privileges) before Postfix 856enters the optional chroot jail and so need not be accessible from inside the 857chroot jail. </p> 858 859<p> Additional trusted CAs can be specified via the $smtp_tls_CApath 860directory, in which case the certificates are read (with $mail_owner 861privileges) from the files in the directory when the information 862is needed. Thus, the $smtp_tls_CApath directory needs to be accessible 863inside the optional chroot jail. </p> 864 865<p> The choice between $smtp_tls_CAfile and $smtp_tls_CApath is 866a space/time tradeoff. If there are many trusted CAs, the cost of 867preloading them all into memory may not pay off in reduced access time 868when the certificate is needed. </p> 869 870<p> Example: </p> 871 872<blockquote> 873<pre> 874/etc/postfix/main.cf: 875 smtp_tls_CAfile = /etc/postfix/CAcert.pem 876 smtp_tls_CApath = /etc/postfix/certs 877</pre> 878</blockquote> 879 880<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3> 881 882<p> To get additional information about Postfix SMTP client TLS 883activity you can increase the loglevel from 0..4. Each logging 884level also includes the information that is logged at a lower 885logging level. </p> 886 887<blockquote> 888 889<table> 890 891<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr> 892 893<tr> <td> 1 </td> <td> Log TLS handshake and certificate information. 894</td> </tr> 895 896<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td> 897</tr> 898 899<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS 900negotiation process </td> </tr> 901 902<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete 903transmission after STARTTLS </td> </tr> 904 905</table> 906 907</blockquote> 908 909<p> Example: </p> 910 911<blockquote> 912<pre> 913/etc/postfix/main.cf: 914 smtp_tls_loglevel = 0 915</pre> 916</blockquote> 917 918<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3> 919 920<p> The remote SMTP server and the Postfix SMTP client negotiate a 921session, which takes some computer time and network bandwidth. By 922default, this session information is cached only in the smtp(8) 923process actually using this session and is lost when the process 924terminates. To share the session information between multiple 925smtp(8) processes, a persistent session cache can be used. You 926can specify any database type that can store objects of several 927kbytes and that supports the sequence operator. DBM databases are 928not suitable because they can only store small objects. The cache 929is maintained by the tlsmgr(8) process, so there is no problem with 930concurrent access. Session caching is highly recommended, because 931the cost of repeatedly negotiating TLS session keys is high. Future 932Postfix SMTP servers may limit the number of sessions that a client 933is allowed to negotiate per unit time.</p> 934 935 936<p> Example: </p> 937 938<blockquote> 939<pre> 940/etc/postfix/main.cf: 941 smtp_tls_session_cache_database = btree:/etc/postfix/smtp_scache 942</pre> 943</blockquote> 944 945<p> As of version 2.5, Postfix will no longer maintain this file 946in a directory with non-Postfix ownership. As a migration aid, 947attempts to open such files are redirected to the Postfix-owned 948$data_directory, and a warning is logged. </p> 949 950<p> Cached Postfix SMTP client session information expires after 951a certain amount of time. Postfix/TLS does not use the OpenSSL 952default of 300s, but a longer time of 3600s (=1 hour). RFC 2246 953recommends a maximum of 24 hours. </p> 954 955<p> Example: </p> 956 957<blockquote> 958<pre> 959/etc/postfix/main.cf: 960 smtp_tls_session_cache_timeout = 3600s 961</pre> 962</blockquote> 963 964<h3><a name="client_tls_enable"> Enabling TLS in the Postfix SMTP 965client </a> </h3> 966 967<p> By default, TLS is disabled in the Postfix SMTP client, so no 968difference to plain Postfix is visible. If you enable TLS, the 969Postfix SMTP client will send STARTTLS when TLS support is announced 970by the remote SMTP server. </p> 971 972<p> When the server accepts the STARTTLS command, but the subsequent 973TLS handshake fails, and no other server is available, the Postfix SMTP 974client defers the delivery attempt, and the mail stays in the queue. After 975a handshake failure, the communications channel is in an indeterminate 976state and cannot be used for non-TLS deliveries. </p> 977 978<p> Example: </p> 979 980<blockquote> 981<pre> 982/etc/postfix/main.cf: 983 smtp_use_tls = yes 984</pre> 985</blockquote> 986 987<h3><a name="client_tls_require"> Requiring TLS encryption </a> 988</h3> 989 990<p> You can ENFORCE the use of TLS, so that the Postfix SMTP client 991will not deliver mail over unencrypted connections. In this mode, 992the remote SMTP server hostname must match the information in the 993remote server certificate, and the server certificate must be issued 994by a CA that is trusted by the Postfix SMTP client. If the remote 995server certificate doesn't verify or the remote SMTP server hostname 996doesn't match, and no other server is available, the delivery 997attempt is deferred and the mail stays in the queue. </p> 998 999<p> The remote SMTP server hostname is verified against all names 1000provided as dNSNames 1001in the SubjectAlternativeName. If no dNSNames are specified, the 1002CommonName is checked. Verification may be turned off with the 1003smtp_tls_enforce_peername option which is discussed below. </p> 1004 1005<p> Enforcing the use of TLS is useful if you know that you will 1006only 1007connect to servers that support RFC 2487 _and_ that present server 1008certificates that meet the above requirements. An example would 1009be a client only sends email to one specific mailhub that offers 1010the necessary STARTTLS support. </p> 1011 1012<p> Example: </p> 1013 1014<blockquote> 1015<pre> 1016/etc/postfix/main.cf: 1017 smtp_enforce_tls = yes 1018</pre> 1019</blockquote> 1020 1021<h3> <a name="client_tls_nopeer"> Disabling server certificate 1022verification </a> </h3> 1023 1024<p> As of RFC 2487 the requirements for hostname checking for MTA 1025clients are not set. When TLS is required (smtp_enforce_tls = yes), 1026the option smtp_tls_enforce_peername can be set to "no" to disable 1027strict remote SMTP server hostname checking. In this case, the mail 1028delivery will proceed regardless of the CommonName etc. listed in 1029the certificate. </p> 1030 1031<p> Despite the potential for eliminating "man-in-the-middle" and 1032other attacks, mandatory certificate/peername verification is not 1033viable as a default Internet mail delivery policy at this time. A 1034significant fraction of TLS enabled MTAs uses self-signed certificates, 1035or certificates that are signed by a private certificate authority. 1036On a machine that delivers mail to the Internet, if you set 1037smtp_enforce_tls = yes, you should probably also set 1038smtp_tls_enforce_peername = no. You can use the per-site TLS 1039policies (see below) to enable full peer verification for specific 1040destinations that are known to have verifiable TLS server certificates. 1041</p> 1042 1043<p> Example: </p> 1044 1045<blockquote> 1046<pre> 1047/etc/postfix/main.cf: 1048 smtp_enforce_tls = yes 1049 smtp_tls_enforce_peername = no 1050</pre> 1051</blockquote> 1052 1053<h3> <a name="client_tls_per_site"> Per-site TLS policies </a> </h3> 1054 1055<p> A small fraction of servers offer STARTTLS but the negotiation 1056consistently fails, leading to mail aging out of the queue and 1057bouncing back to the sender. In such cases, you can use the per-site 1058policies to disable TLS for the problem sites. Alternatively, you 1059can enable TLS for just a few specific sites and not enable it for 1060all sites. </p> 1061 1062<!-- insert new-style TLS policy mechanism here 1063 1064<h3> <a name="client_tls_obs"> Obsolete per-site TLS policy support 1065</a> </h3> 1066 1067<p> This section describes an obsolete per-site TLS policy mechanism. 1068Unlike the newer mechanism it supports TLS policy lookup by server 1069hostname, and lacks control over what names can appear in server 1070certificates. Because of this, the obsolete mechanism is vulnerable 1071to false DNS hostname information in MX or CNAME records. These 1072attacks can be eliminated only with great difficulty. </p> 1073 1074--> 1075 1076<p> The smtp_tls_per_site table is searched for a policy that matches 1077the following information: </p> 1078 1079<blockquote> 1080 1081<dl> 1082 1083<dt> remote SMTP server hostname </dt> <dd> This is simply the DNS 1084name of the server that the Postfix SMTP client connects to; this 1085name may be obtained from other DNS lookups, such as MX lookups or 1086CNAME lookups. </dd> 1087 1088<dt> next-hop destination </dt> <dd> This is normally the domain 1089portion of the recipient address, but it may be overruled by 1090information from the transport(5) table, from the relayhost parameter 1091setting, or from the relay_transport setting. When it's not the 1092recipient domain, the next-hop destination can have the Postfix-specific 1093form "<tt>[name]</tt>", <tt>[name]:port</tt>", "<tt>name</tt>" or 1094"<tt>name:port</tt>". </dd> 1095 1096</dl> 1097 1098</blockquote> 1099 1100<p> When both the hostname lookup and the next-hop lookup succeed, 1101the host policy does not automatically override the next-hop policy. 1102Instead, precedence is given to either the more specific or the 1103more secure per-site policy as described below. </p> 1104 1105<p> The smtp_tls_per_site table uses a simple "<i>name whitespace 1106value</i>" format. Specify host names or next-hop destinations on 1107the left-hand side; no wildcards are allowed. On the right hand 1108side specify one of the following keywords: </p> 1109 1110<blockquote> 1111 1112<dl> 1113 1114<dt> NONE </dt> <dd> Don't use TLS at all. This overrides a less 1115specific <b>MAY</b> lookup result from the alternate host or next-hop 1116lookup key, and overrides the global smtp_use_tls, smtp_enforce_tls, 1117and smtp_tls_enforce_peername settings. </dd> 1118 1119<dt> MAY </dt> <dd> Try to use TLS if the server announces support, 1120otherwise use the unencrypted connection. This has less precedence 1121than a more specific result (including <b>NONE</b>) from the alternate 1122host or next-hop lookup key, and has less precedence than the more 1123specific global "smtp_enforce_tls = yes" or "smtp_tls_enforce_peername 1124= yes". </dd> 1125 1126<dt> MUST_NOPEERMATCH </dt> <dd> Require TLS encryption, but do not 1127require that the remote SMTP server hostname matches the information 1128in the remote SMTP server certificate, or that the server certificate 1129was issued by a trusted CA. This overrides a less secure <b>NONE</b> 1130or a less specific <b>MAY</b> lookup result from the alternate host 1131or next-hop lookup key, and overrides the global smtp_use_tls, 1132smtp_enforce_tls and smtp_tls_enforce_peername settings. </dd> 1133 1134<dt> MUST </dt> <dd> Require TLS encryption, require that the remote 1135SMTP server hostname matches the information in the remote SMTP 1136server certificate, and require that the remote SMTP server certificate 1137was issued by a trusted CA. This overrides a less secure <b>NONE</b> 1138and <b>MUST_NOPEERMATCH</b> or a less specific <b>MAY</b> lookup 1139result from the alternate host or next-hop lookup key, and overrides 1140the global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername 1141settings. </dd> 1142 1143</dl> 1144 1145</blockquote> 1146 1147<p> The precedences between global (main.cf) and per-site TLS 1148policies can be summarized as follows: </p> 1149 1150<ul> 1151 1152<li> <p> When neither the remote SMTP server hostname nor the 1153next-hop destination are found in the smtp_tls_per_site table, the 1154policy is based on smtp_use_tls, smtp_enforce_tls and 1155smtp_tls_enforce_peername. Note: "smtp_enforce_tls = yes" and 1156"smtp_tls_enforce_peername = yes" imply "smtp_use_tls = yes". </p> 1157 1158<li> <p> When both hostname and next-hop destination lookups produce 1159a result, the more specific per-site policy (NONE, MUST, etc) 1160overrides the less specific one (MAY), and the more secure per-site 1161policy (MUST, etc) overrides the less secure one (NONE). </p> 1162 1163<li> <p> After the per-site policy lookups are combined, the result 1164generally overrides the global policy. The exception is the less 1165specific <b>MAY</b> per-site policy, which is overruled by the more 1166specific global "smtp_enforce_tls = yes" with server certificate 1167verification as specified with the smtp_tls_enforce_peername 1168parameter. </p> 1169 1170</ul> 1171 1172<h3> <a name="client_tls_harden"> Closing a DNS loophole with 1173<!-- legacy --> per-site TLS policies </a> </h3> 1174 1175<p> As long as no secure DNS lookup mechanism is available, false 1176hostnames in MX or CNAME responses can change the server hostname 1177that Postfix uses for TLS policy lookup and server certificate 1178verification. Even with a perfect match between the server hostname 1179and the server certificate, there is no guarantee that Postfix is 1180connected to the right server. To avoid this loophole take the 1181following steps: </p> 1182 1183<ul> 1184 1185<li> <p> Eliminate MX lookups. Specify local transport(5) table 1186entries for sensitive domains with explicit smtp:[<i>mailhost</i>] 1187or smtp:[<i>mailhost</i>]:<i>port</i> destinations (you can assure 1188security of this table unlike DNS); in the smtp_tls_per_site table 1189specify the value <b>MUST</b> for the key [<i>mailhost</i>] or 1190smtp:[<i>mailhost</i>]:<i>port</i>. This prevents false hostname 1191information in DNS MX records from changing the server hostname 1192that Postfix uses for TLS policy lookup and server certificate 1193verification. </p> 1194 1195<li> <p> Disallow CNAME hostname overrides. In main.cf specify 1196"smtp_cname_overrides_servername = no". This prevents false hostname 1197information in DNS CNAME records from changing the server hostname 1198that Postfix uses for TLS policy lookup and server certificate 1199verification. This feature requires Postfix 2.2.9 or later. </p> 1200 1201</ul> 1202 1203<p> Example: </p> 1204 1205<blockquote> <pre> 1206/etc/postfix/main.cf: 1207 smtp_tls_per_site = hash:/etc/postfix/tls_per_site 1208 relayhost = [msa.example.net]:587 1209 1210/etc/postfix/tls_per_site: 1211 # relayhost exact nexthop match 1212 [msa.example.net]:587 MUST 1213 1214 # TLS should not be used with the <i>example.org</i> MX hosts. 1215 example.org NONE 1216 1217 # TLS should not be used with the host <i>smtp.example.com</i>. 1218 smtp.example.com NONE 1219</pre> 1220</blockquote> 1221 1222<h3> <a name="client_tls_discover"> Discovering servers that support 1223TLS </a> </h3> 1224 1225<p> As we decide on a "per site" basis whether or not to use TLS, 1226it would be good to have a list of sites that offered "STARTTLS". 1227We can collect it ourselves with this option. </p> 1228 1229<p> If the smtp_tls_note_starttls_offer feature is enabled and a 1230server offers STARTTLS while TLS is not already enabled for that 1231server, the Postfix SMTP client logs a line as follows: </p> 1232 1233<blockquote> 1234<pre> 1235postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com] 1236</pre> 1237</blockquote> 1238 1239<p> Example: </p> 1240 1241<blockquote> 1242<pre> 1243/etc/postfix/main.cf: 1244 smtp_tls_note_starttls_offer = yes 1245</pre> 1246</blockquote> 1247 1248<h3><a name="client_vrfy_server">Server certificate verification depth</a> </h3> 1249 1250<p> When verifying a remote SMTP server certificate, a verification 1251depth of 1 is sufficient if the certificate is directly issued by 1252a CA specified with smtp_tls_CAfile or smtp_tls_CApath. The default 1253value of 5 should also suffice for longer chains (root CA issues 1254special CA which then issues the actual certificate...) </p> 1255 1256<p> Example: </p> 1257 1258<blockquote> 1259<pre> 1260/etc/postfix/main.cf: 1261 smtp_tls_scert_verifydepth = 5 1262</pre> 1263</blockquote> 1264 1265<h3> <a name="client_cipher">Client-side cipher controls </a> </h3> 1266 1267<p> To influence the Postfix SMTP client cipher selection scheme, 1268you can give cipherlist string. A detailed description would go 1269to far here; please refer to the OpenSSL documentation. If you 1270don't know what to do with it, simply don't touch it and leave the 1271(openssl-)compiled in default! </p> 1272 1273<p> DO NOT USE " to enclose the string, specify just the string!!! </p> 1274 1275<p> Example: </p> 1276 1277<blockquote> 1278<pre> 1279/etc/postfix/main.cf: 1280 smtp_tls_cipherlist = DEFAULT 1281</pre> 1282</blockquote> 1283 1284<h3> <a name="client_misc"> Miscellaneous client controls </a> </h3> 1285 1286<p> The smtp_starttls_timeout parameter limits the time of Postfix 1287SMTP client write and read operations during TLS startup and shutdown 1288handshake procedures. In case of problems the Postfix SMTP client 1289tries the next network address on the mail exchanger list, and 1290defers delivery if no alternative server is available. </p> 1291 1292<p> Example: </p> 1293 1294<blockquote> 1295<pre> 1296/etc/postfix/main.cf: 1297 smtp_starttls_timeout = 300s 1298</pre> 1299</blockquote> 1300 1301<h2><a name="tlsmgr_controls"> TLS manager specific settings </a> </h2> 1302 1303<p> The security of cryptographic software such as TLS depends 1304critically on the ability to generate unpredictable numbers for 1305keys and other information. To this end, the tlsmgr(8) process 1306maintains a Pseudo Random Number Generator (PRNG) pool. This is 1307queried by the smtp(8) and smtpd(8) processes when they initialize. 1308By default, these daemons request 32 bytes, the equivalent to 256 1309bits. This is more than sufficient to generate a 128bit (or 168bit) 1310session key. </p> 1311 1312<p> Example: </p> 1313 1314<blockquote> 1315<pre> 1316/etc/postfix/main.cf: 1317 tls_daemon_random_bytes = 32 1318</pre> 1319</blockquote> 1320 1321<p> In order to feed its in-memory PRNG pool, the tlsmgr(8) reads 1322entropy from an external source, both at startup and during run-time. 1323Specify a good entropy source, like EGD or /dev/urandom; be sure 1324to only use non-blocking sources (on OpenBSD, use /dev/arandom 1325when tlsmgr(8) complains about /dev/urandom timeout errors). 1326If the entropy source is not a 1327regular file, you must prepend the source type to the source name: 1328"dev:" for a device special file, or "egd:" for a source with EGD 1329compatible socket interface. </p> 1330 1331<p> Examples (specify only one in main.cf): </p> 1332 1333<blockquote> 1334<pre> 1335/etc/postfix/main.cf: 1336 tls_random_source = dev:/dev/urandom 1337 tls_random_source = egd:/var/run/egd-pool 1338</pre> 1339</blockquote> 1340 1341<p> By default, tlsmgr(8) reads 32 bytes from the external entropy 1342source at each seeding event. This amount (256bits) is more than 1343sufficient for generating a 128bit symmetric key. With EGD and 1344device entropy sources, the tlsmgr(8) limits the amount of data 1345read at each step to 255 bytes. If you specify a regular file as 1346entropy source, a larger amount of data can be read. </p> 1347 1348<p> Example: </p> 1349 1350<blockquote> 1351<pre> 1352/etc/postfix/main.cf: 1353 tls_random_bytes = 32 1354</pre> 1355</blockquote> 1356 1357<p> In order to update its in-memory PRNG pool, the tlsmgr(8) 1358queries the external entropy source again after a pseudo-random 1359amount of time. The time is calculated using the PRNG, and is 1360between 0 and the maximal time specified with tls_random_reseed_period. 1361The default maximal time interval is 1 hour. </p> 1362 1363<p> Example: </p> 1364 1365<blockquote> 1366<pre> 1367/etc/postfix/main.cf: 1368 tls_random_reseed_period = 3600s 1369</pre> 1370</blockquote> 1371 1372<p> The tlsmgr(8) process saves the PRNG state to a persistent 1373exchange file at regular times and when the process terminates, so 1374that it can recover the PRNG state the next time it starts up. 1375This file is created when it does not exist. Its default location 1376is under the Postfix configuration directory, which is not the 1377proper place for information that is modified by Postfix. Instead, 1378the file location should probably be on the /var partition (but 1379<b>not</b> inside the chroot jail). </p> 1380 1381<p> Examples: </p> 1382 1383<blockquote> 1384<pre> 1385/etc/postfix/main.cf: 1386 tls_random_exchange_name = /etc/postfix/prng_exch 1387 tls_random_prng_update_period = 3600s 1388</pre> 1389</blockquote> 1390 1391<h2><a name="quick-start">Getting started, quick and dirty</a></h2> 1392 1393<p> The following steps will get you started quickly. Because you 1394sign your own Postfix public key certificate, you get TLS encryption 1395but no TLS authentication. This is sufficient for testing, and 1396for exchanging email with sites that you have no trust relationship 1397with. For real authentication, your Postfix public key certificate 1398needs to be signed by a recognized Certificate Authority, and 1399Postfix needs to be configured with a list of public key certificates 1400of Certificate Authorities, so that Postfix can verify the public key 1401certificates of remote hosts. </p> 1402 1403<p> In the examples below, user input is shown in <b><tt>bold</tt></b> 1404font, and a "<tt>#</tt>" prompt indicates a super-user shell. </p> 1405 1406<ul> 1407 1408<li> <p> Become your own Certificate Authority, so that you can 1409sign your own public keys. This example uses the CA.pl script that 1410ships with OpenSSL. By default, OpenSSL installs this as 1411<tt>/usr/local/ssl/misc/CA.pl</tt>, but your mileage may vary. 1412The script creates a private key in <tt>./demoCA/private/cakey.pem</tt> 1413and a public key in <tt>./demoCA/cacert.pem</tt>.</p> 1414 1415<blockquote> 1416<pre> 1417% <b>/usr/local/ssl/misc/CA.pl -newca</b> 1418CA certificate filename (or enter to create) 1419 1420Making CA certificate ... 1421Using configuration from /etc/ssl/openssl.cnf 1422Generating a 1024 bit RSA private key 1423....................++++++ 1424.....++++++ 1425writing new private key to './demoCA/private/cakey.pem' 1426Enter PEM pass phrase:<b>whatever</b> 1427</pre> 1428</blockquote> 1429 1430<li> <p> Create an unpassworded private key for host FOO and create 1431an unsigned public key certificate. </p> 1432 1433<blockquote> 1434<pre> 1435% <b>openssl req -new -nodes -keyout FOO-key.pem -out FOO-req.pem -days 365</b> 1436Using configuration from /etc/ssl/openssl.cnf 1437Generating a 1024 bit RSA private key 1438........................................++++++ 1439....++++++ 1440writing new private key to 'FOO-key.pem' 1441----- 1442You are about to be asked to enter information that will be incorporated 1443into your certificate request. 1444What you are about to enter is what is called a Distinguished Name or a DN. 1445There are quite a few fields but you can leave some blank 1446For some fields there will be a default value, 1447If you enter '.', the field will be left blank. 1448----- 1449Country Name (2 letter code) [AU]:<b>US</b> 1450State or Province Name (full name) [Some-State]:<b>New York</b> 1451Locality Name (eg, city) []:<b>Westchester</b> 1452Organization Name (eg, company) [Internet Widgits Pty Ltd]:<b>Porcupine</b> 1453Organizational Unit Name (eg, section) []: 1454Common Name (eg, YOUR name) []:<b>FOO</b> 1455Email Address []:<b>wietse@porcupine.org</b> 1456 1457Please enter the following 'extra' attributes 1458to be sent with your certificate request 1459A challenge password []:<b>whatever</b> 1460An optional company name []: 1461</pre> 1462</blockquote> 1463 1464<li> <p> Sign the public key certificate for host FOO with the 1465Certification Authority private key that we created a few 1466steps ago. </p> 1467 1468<blockquote> 1469<pre> 1470% <b>openssl ca -out FOO-cert.pem -infiles FOO-req.pem</b> 1471Uing configuration from /etc/ssl/openssl.cnf 1472Enter PEM pass phrase:<b>whatever</b> 1473Check that the request matches the signature 1474Signature ok 1475The Subjects Distinguished Name is as follows 1476countryName :PRINTABLE:'US' 1477stateOrProvinceName :PRINTABLE:'New York' 1478localityName :PRINTABLE:'Westchester' 1479organizationName :PRINTABLE:'Porcupine' 1480commonName :PRINTABLE:'FOO' 1481emailAddress :IA5STRING:'wietse@porcupine.org' 1482Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days) 1483Sign the certificate? [y/n]:<b>y</b> 1484 1485 14861 out of 1 certificate requests certified, commit? [y/n]<b>y</b> 1487Write out database with 1 new entries 1488Data Base Updated 1489</pre> 1490</blockquote> 1491 1492<li> <p> Install the host private key, the host public key certificate, 1493and the Certification Authority certificate files. This requires 1494super-user privileges. </p> 1495 1496<blockquote> 1497<pre> 1498# <b>cp demoCA/cacert.pem FOO-key.pem FOO-cert.pem /etc/postfix</b> 1499# <b>chmod 644 /etc/postfix/FOO-cert.pem /etc/postfix/cacert.pem</b> 1500# <b>chmod 400 /etc/postfix/FOO-key.pem</b> 1501</pre> 1502</blockquote> 1503 1504<li> <p> Configure Postfix, by adding the following to 1505<tt>/etc/postfix/main.cf </tt>. </p> 1506 1507<blockquote> 1508<pre> 1509smtp_tls_CAfile = /etc/postfix/cacert.pem 1510smtp_tls_cert_file = /etc/postfix/FOO-cert.pem 1511smtp_tls_key_file = /etc/postfix/FOO-key.pem 1512smtp_tls_session_cache_database = btree:/var/run/smtp_tls_session_cache 1513smtp_use_tls = yes 1514smtpd_tls_CAfile = /etc/postfix/cacert.pem 1515smtpd_tls_cert_file = /etc/postfix/FOO-cert.pem 1516smtpd_tls_key_file = /etc/postfix/FOO-key.pem 1517smtpd_tls_received_header = yes 1518smtpd_tls_session_cache_database = btree:/var/run/smtpd_tls_session_cache 1519smtpd_use_tls = yes 1520tls_random_source = dev:/dev/urandom 1521</pre> 1522</blockquote> 1523 1524</ul> 1525 1526 1527<h2> <a name="problems"> Reporting problems </a> </h2> 1528 1529<p> When reporting a problem, please be thorough in the report. 1530Patches, when possible, are greatly appreciated too. </p> 1531 1532<p> Please differentiate when possible between: </p> 1533 1534<ul> 1535 1536<li> Problems in the TLS code: <postfix_tls@aet.tu-cottbus.de> 1537 1538<li> Problems in vanilla Postfix: <postfix-users@postfix.org> 1539 1540</ul> 1541 1542<h2><a name="compat">Compatibility with Postfix <2.2 TLS support</a></h2> 1543 1544<p> Postfix version 2.2 TLS support is based on the Postfix/TLS 1545patch by Lutz Jänicke, but differs in a few minor ways. </p> 1546 1547<ul> 1548 1549<li> <p> main.cf: Specify "btree" instead of "sdbm" for TLS 1550session cache databases. </p> 1551 1552<p> TLS session cache databases are now accessed only by the 1553tlsmgr(8) process, so there are no more concurrency issues. Although 1554Postfix has an sdbm client, the sdbm library (1000 1555lines of code) is not included with Postfix. </p> 1556 1557<p> TLS session caches can use any database that can store objects 1558of several kbytes or more, and that implements the sequence operation. 1559In most cases, btree databases should be adequate. </p> 1560 1561<p> NOTE: You cannot use dbm databases. TLS session objects 1562are too large. </p> 1563 1564<li> <p> master.cf: Specify "unix" instead of "fifo" as 1565the tlsmgr service type. </p> 1566 1567<p> The smtp(8) and smtpd(8) processes now use a client-server 1568protocol in order to access the tlsmgr(8) pseudo-random number 1569generation (PRNG) pool, and in order to access the TLS session 1570cache databases. Such a protocol cannot be run across fifos. </p> 1571 1572<li> <p> smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy 1573cannot override the global "smtp_tls_enforce_peername = yes" setting. 1574</p> 1575 1576<li> <p> smtp_tls_per_site: a combined (NONE + MAY) lookup result 1577for (hostname and next-hop destination) produces counter-intuitive 1578results for different main.cf settings. TLS is enabled with 1579"smtp_tls_enforce_peername = no", but it is disabled when both 1580"smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes". 1581</p> 1582 1583</ul> 1584 1585<p> The smtp_tls_per_site limitations were removed by the end of 1586the Postfix 2.2 support cycle. </p> 1587 1588<h2><a name="credits">Credits </a> </h2> 1589 1590<ul> 1591 1592<li> TLS support for Postfix was originally developed by Lutz 1593Jänicke at Cottbus Technical University. 1594 1595<li> Wietse Venema adopted the code, did some restructuring, and 1596compiled this part of the documentation from Lutz's documents. 1597 1598<li> Victor Duchovni was instrumental with the re-implementation 1599of the smtp_tls_per_site code in terms of enforcement levels, which 1600simplified the implementation greatly. 1601 1602</ul> 1603 1604</body> 1605 1606</html> 1607