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