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