external/ibm-public/postfix/dist/html/TLS_README.html

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