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