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