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