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