postfix-master/TLS_LEGACY_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 legacy 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 legacy TLS Support
  17 </h1>
  18
  19 <hr>
  20
  21 <h2> NOTE </h2>
  22
  23 <p> This document describes an old TLS user interface that is based
  24 on a third-party TLS patch by Lutz J&auml;nicke.  As of Postfix
  25 version 2.3, the old user interface still exists to allow migration
  26 from earlier Postfix releases, but its functionality is frozen. </p>
  27
  28 <h2> What Postfix TLS support does for you </h2>
  29
  30 <p> Transport Layer Security (TLS, formerly called SSL) provides
  31 certificate-based authentication and encrypted sessions.  An
  32 encrypted session protects the information that is transmitted with
  33 SMTP mail or with SASL authentication.
  34
  35 <p> Postfix version 2.2 introduces support for TLS as described in
  36 <a href="http://tools.ietf.org/html/rfc3207">RFC 3207</a>.  TLS Support for older Postfix versions was available as
  37 an add-on patch.  The section "<a href="#compat">Compatibility with
  38 Postfix < 2.2 TLS support</a>" below discusses the differences
  39 between these implementations.  </p>
  40
  41 <p> Topics covered in this document: </p>
  42
  43 <ul>
  44
  45 <li><a href="#how">How Postfix TLS support works</a>
  46
  47 <li><a href="#build_tls">Building Postfix with TLS support</a>
  48
  49 <li><a href="#server_tls">SMTP Server specific settings</a>
  50
  51 <li> <a href="#client_tls">SMTP Client specific settings</a>
  52
  53 <li><a href="#tlsmgr_controls"> TLS manager specific settings </a>
  54
  55 <li><a href="#problems"> Reporting problems </a>
  56
  57 <li><a href="#compat">Compatibility with Postfix < 2.2 TLS support</a>
  58
  59 <li><a href="#credits"> Credits </a>
  60
  61 </ul>
  62
  63 <p> And last but not least, for the impatient: </p>
  64
  65 <ul>
  66
  67 <li><a href="#quick-start">Getting started, quick and dirty</a>
  68
  69 </ul>
  70
  71 <h2><a name="how">How Postfix TLS support works</a></h2>
  72
  73 <p> The diagram below shows the main elements of the Postfix TLS
  74 architecture and their relationships.  Colored boxes with numbered
  75 names represent Postfix daemon programs. Other colored boxes
  76 represent storage elements. </p>
  77
  78 <ul>
  79
  80 <li> <p> The <a href="smtpd.8.html">smtpd(8)</a> server implements the SMTP over TLS server
  81 side. </p>
  82
  83 <li> <p> The <a href="smtp.8.html">smtp(8)</a> client implements the SMTP over TLS client
  84 side. </p>
  85
  86 <li> <p> The <a href="tlsmgr.8.html">tlsmgr(8)</a> server maintains the pseudo-random number
  87 generator (PRNG) that seeds the TLS engines in the <a href="smtpd.8.html">smtpd(8)</a> server
  88 and <a href="smtp.8.html">smtp(8)</a> client processes, and maintains the TLS session key
  89 cache files. </p>
  90
  91 </ul>
  92
  93 <table>
  94
  95 <tr> <td>Network<tt>-&gt; </tt> </td> <td align="center"
  96 bgcolor="#f0f0ff"> <br> <a href="smtpd.8.html">smtpd(8)</a> <br> &nbsp; </td> <td colspan="2">
  97
  98 <tt> &lt;---seed---<br><br>&lt;-session-&gt; </tt> </td> <td
  99 align="center" bgcolor="#f0f0ff"> <br> <a href="tlsmgr.8.html">tlsmgr(8)</a> <br> &nbsp; </td>
 100 <td colspan="3"> <tt> ---seed---&gt;<br> <br>&lt;-session-&gt;
 101
 102 </tt> </td> <td align="center" bgcolor="#f0f0ff"> <br> <a href="smtp.8.html">smtp(8)</a> <br>
 103 &nbsp; </td> <td> <tt> -&gt;</tt>Network </td> </tr>
 104
 105 <tr> <td colspan="3"> </td> <td align="right"> <table> <tr> <td>
 106
 107 </td> <td> / </td> </tr> <tr> <td> / </td> <td> </td> </tr> </table>
 108 </td> <td align="center"> |<br> |</td> <td align="left"> <table>
 109
 110 <tr> <td> \ </td> <td> </td> </tr> <tr> <td> </td> <td> \ </td>
 111 </tr> </table> </td> <td colspan="3"> </td> </tr>
 112
 113 <tr> <td colspan="2"> </td> <td align="center" bgcolor="#f0f0ff">
 114 smtpd<br> session<br> key cache </td> <td> </td> <td align="center"
 115 bgcolor="#f0f0ff"> PRNG<br> state <br>file </td> <td> </td> <td
 116 align="center" bgcolor="#f0f0ff"> smtp<br> session<br> key cache
 117 </td>
 118
 119 <td colspan="2"> </td> </tr>
 120
 121 </table>
 122
 123 <h2><a name="build_tls">Building Postfix with TLS support</a></h2>
 124
 125 <p> To build Postfix with TLS support, first we need to generate
 126 the <tt>make(1)</tt> files with the necessary definitions. This is
 127 done by invoking the command "<tt>make makefiles</tt>" in the Postfix
 128 top-level directory and with arguments as shown next. </p>
 129
 130 <p> <b> NOTE: Do not use Gnu TLS.  It will spontaneously terminate
 131 a Postfix daemon process with exit status code 2, instead of allowing
 132 Postfix to 1) report the error to the maillog file, and to 2) provide
 133 plaintext service where this is appropriate.  </b> </p>
 134
 135 <ul>
 136
 137 <li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
 138 in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries
 139 (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in
 140 directory <tt>/usr/lib</tt>:  </p>
 141
 142 <blockquote>
 143 <pre>
 144 % <b>make tidy</b> # if you have left-over files from a previous build
 145 % <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b>
 146 </pre>
 147 </blockquote>
 148
 149 <li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
 150 in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL
 151 libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)
 152 are in directory <tt>/usr/local/lib</tt>:  </p>
 153
 154 <blockquote>
 155 <pre>
 156 % <b>make tidy</b> # if you have left-over files from a previous build
 157 % <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
 158     AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b>
 159 </pre>
 160 </blockquote>
 161
 162 <p> On Solaris, specify the <tt>-R</tt> option as shown below:
 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="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b>
 169 </pre>
 170 </blockquote>
 171
 172 </ul>
 173
 174 <p> If you need to apply other customizations (such as Berkeley DB
 175 databases, MySQL, PosgreSQL, LDAP or SASL), see the respective
 176 Postfix README documents, and combine their "<tt>make makefiles</tt>"
 177 instructions with the instructions above:  </p>
 178
 179 <blockquote>
 180 <pre>
 181 % <b>make tidy</b> # if you have left-over files from a previous build
 182 % <b>make makefiles CCARGS="-DUSE_TLS \
 183     <i>(other -D or -I options)</i>" \
 184     AUXLIBS="-lssl -lcrypto \
 185     <i>(other -l options for libraries in /usr/lib)</i> \
 186     <i>(-L/path/name + -l options for other libraries)</i>"</b>
 187 </pre>
 188 </blockquote>
 189
 190 <p> To complete the build process, see the Postfix <a href="INSTALL.html">INSTALL</a>
 191 instructions. Postfix has TLS support turned off by default, so
 192 you can start using Postfix as soon as it is installed.  </p>
 193
 194 <h2><a name="server_tls">SMTP Server specific settings</a></h2>
 195
 196 <p> Topics covered in this section: </p>
 197
 198 <ul>
 199
 200 <li><a href="#server_cert_key">Server-side certificate and private
 201 key configuration </a>
 202
 203 <li><a href="#server_logging"> Server-side TLS activity logging
 204 </a>
 205
 206 <li><a href="#server_enable">Enabling TLS in the Postfix SMTP server </a>
 207
 208 <li><a href="#server_vrfy_client">Client certificate verification</a>
 209
 210 <li><a href="#server_tls_auth">Supporting AUTH over TLS only</a>
 211
 212 <li><a href="#server_tls_cache">Server-side TLS session cache</a>
 213
 214 <li><a href="#server_access">Server access control</a>
 215
 216 <li><a href="#server_cipher">Server-side cipher controls</a>
 217
 218 <li><a href="#server_misc"> Miscellaneous server controls</a>
 219
 220 </ul>
 221
 222 <h3><a name="server_cert_key">Server-side certificate and private
 223 key configuration </a> </h3>
 224
 225 <p> In order to use TLS, the Postfix SMTP server needs a certificate
 226 and a private key. Both must be in "pem" format. The private key
 227 must not be encrypted, meaning:  the key must be accessible without
 228 password.  Both certificate and private key may be in the same
 229 file.  </p>
 230
 231 <p> Both RSA and DSA certificates are supported. Typically you will
 232 only have RSA certificates issued by a commercial CA. In addition,
 233 the tools supplied with OpenSSL will by default issue RSA certificates.
 234 You can have both at the same time, in which case the cipher used
 235 determines which certificate is presented. For Netscape and OpenSSL
 236 clients without special cipher choices, the RSA certificate is
 237 preferred. </p>
 238
 239 <p> In order for remote SMTP clients to check the Postfix SMTP
 240 server certificates, the CA certificate (in case of a certificate
 241 chain, all CA certificates) must be available.  You should add
 242 these certificates to the server certificate, the server certificate
 243 first, then the issuing CA(s).  </p>
 244
 245 <p> Example: the certificate for "server.dom.ain" was issued by
 246 "intermediate CA" which itself has a certificate issued by "root
 247 CA".  Create the server.pem file with: </p>
 248
 249 <blockquote>
 250 <pre>
 251 % <b>cat server_cert.pem intermediate_CA.pem &gt; server.pem</b>
 252 </pre>
 253 </blockquote>
 254
 255 <p> A Postfix SMTP server certificate supplied here must be usable
 256 as SSL server certificate and hence pass the "openssl verify -purpose
 257 sslserver ..." test. </p>
 258
 259 <p> A client that trusts the root CA has a local copy of the root
 260 CA certificate, so it is not necessary to include the root CA
 261 certificate here.  Leaving it out of the "server.pem" file reduces
 262 the overhead of the TLS exchange. </p>
 263
 264 <p> If you want the Postfix SMTP server to accept remote SMTP client
 265 certificates issued by these CAs, append the root certificate to
 266 $<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.  When
 267 you configure trust in a root CA, it is not necessary to explicitly trust
 268 intermediary CAs signed by the root CA, unless $<a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a>
 269 is less than the number of CAs in the certificate chain for the clients
 270 of interest. With a verify depth of 1 you can only verify certificates
 271 directly signed by a trusted CA, and all trusted intermediary CAs need to
 272 be configured explicitly. With a verify depth of 2 you can verify clients
 273 signed by a root CA or a direct intermediary CA (so long as the client
 274 is correctly configured to supply its intermediate CA certificate). </p>
 275
 276 <p> RSA key and certificate examples: </p>
 277
 278 <blockquote>
 279 <pre>
 280 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 281     <a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/server.pem
 282     <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>
 283 </pre>
 284 </blockquote>
 285
 286 <p> Their DSA counterparts: </p>
 287
 288 <blockquote>
 289 <pre>
 290 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 291     <a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a> = /etc/postfix/server-dsa.pem
 292     <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>
 293 </pre>
 294 </blockquote>
 295
 296 <p> To verify a remote SMTP client certificate, the Postfix SMTP
 297 server needs to trust the certificates of the issuing certification
 298 authorities. These certificates in "pem" format can be stored in a
 299 single $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> or in multiple files, one CA per file in
 300 the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> directory. If you use a directory, don't forget
 301 to create the necessary "hash" links with: </p>
 302
 303 <blockquote>
 304 <pre>
 305 # <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
 306 </pre>
 307 </blockquote>
 308
 309 <p> The $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> contains the CA certificates of one or
 310 more trusted CAs. The file is opened (with root privileges) before
 311 Postfix enters the optional chroot jail and so need not be accessible
 312 from inside the chroot jail. </p>
 313
 314 <p> Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>
 315 directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>
 316 privileges) from the files in the directory when the information
 317 is needed. Thus, the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> directory needs to be
 318 accessible inside the optional chroot jail. </p>
 319
 320 <p> When you configure Postfix to request client certificates (by
 321 setting $<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes), any certificates in
 322 $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> are sent to the client, in order to allow it to
 323 choose an identity signed by a CA you trust. If no $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>
 324 is specified, no preferred CA list is sent, and the client is free
 325 to choose an identity signed by any CA. Many clients use a fixed
 326 identity regardless of the preferred CA list and you may be able
 327 to reduce TLS negotiation overhead by installing client CA certificates
 328 mostly or only in $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>. In the latter case you need
 329 not specify a $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>. </p>
 330
 331 <p> Note, that unless client certificates are used to allow greater
 332 access to TLS authenticated clients, it is best to not ask for
 333 client certificates at all, as in addition to increased overhead
 334 some clients (notably in some cases qmail) are unable to complete
 335 the TLS handshake when client certificates are requested. </p>
 336
 337 <p> Example: </p>
 338 <blockquote>
 339 <pre>
 340 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 341     <a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> = /etc/postfix/CAcert.pem
 342     <a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> = /etc/postfix/certs
 343 </pre>
 344 </blockquote>
 345
 346 <h3><a name="server_logging"> Server-side TLS activity logging </a> </h3>
 347
 348 <p> To get additional information about Postfix SMTP server TLS
 349 activity you can increase the loglevel from 0..4. Each logging
 350 level also includes the information that is logged at a lower
 351 logging level. </p>
 352
 353 <blockquote>
 354
 355 <table>
 356
 357 <tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>
 358
 359 <tr> <td> 1 </td> <td> Log TLS handshake and certificate information.
 360 </td> </tr>
 361
 362 <tr> <td> 2 </td> <td> Log levels during TLS negotiation.  </td>
 363 </tr>
 364
 365 <tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS
 366 negotiation process </td> </tr>
 367
 368 <tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete
 369 transmission after STARTTLS </td> </tr>
 370
 371 </table>
 372
 373 </blockquote>
 374
 375 <p> Use loglevel 3 only in case of problems. Use of loglevel 4 is
 376 strongly discouraged. </p>
 377
 378 <p> Example: </p>
 379
 380 <blockquote>
 381 <pre>
 382 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 383     <a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 0
 384 </pre>
 385 </blockquote>
 386
 387 <p> To include information about the protocol and cipher used as
 388 well as the client and issuer CommonName into the "Received:"
 389 message header, set the <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> variable to true.
 390 The default is no, as the information is not necessarily authentic.
 391 Only information recorded at the final destination is reliable,
 392 since the headers may be changed by intermediate servers. </p>
 393
 394 <p> Example: </p>
 395
 396 <blockquote>
 397 <pre>
 398 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 399     <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = yes
 400 </pre>
 401 </blockquote>
 402
 403 <h3><a name="server_enable">Enabling TLS in the Postfix SMTP server </a> </h3>
 404
 405 <p> By default, TLS is disabled in the Postfix SMTP server, so no
 406 difference to plain Postfix is visible.  Explicitly switch it on
 407 using "<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> = yes". </p>
 408
 409 <p> Example: </p>
 410
 411 <blockquote>
 412 <pre>
 413 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 414     <a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> = yes
 415 </pre>
 416 </blockquote>
 417
 418 <p> With this, Postfix SMTP server announces STARTTLS support to
 419 SMTP clients, but does not require that clients use TLS encryption.
 420 </p>
 421
 422 <p> Note: when an unprivileged user invokes "sendmail -bs", STARTTLS
 423 is never offered due to insufficient privileges to access the server
 424 private key. This is intended behavior. </p>
 425
 426 <p> You can ENFORCE the use of TLS, so that the Postfix SMTP server
 427 announces STARTTLS and accepts no mail without TLS encryption, by
 428 setting "<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = yes". According to <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> this MUST
 429 NOT be applied in case of a publicly-referenced Postfix SMTP server.
 430 This option is off by default and should only seldom be used. </p>
 431
 432 <p> Example: </p>
 433
 434 <blockquote>
 435 <pre>
 436 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 437     <a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = yes
 438 </pre>
 439 </blockquote>
 440
 441 <p> TLS is sometimes used in the non-standard "wrapper" mode where
 442 a server always uses TLS, instead of announcing STARTTLS support
 443 and waiting for clients to request TLS service. Some clients, namely
 444 Outlook [Express] prefer the "wrapper" mode.  This is true for OE
 445 (Win32 &lt; 5.0 and Win32 &gt;=5.0 when run on a port&lt;&gt;25
 446 and OE (5.01 Mac on all ports). </p>
 447
 448 <p> It is strictly discouraged to use this mode from <a href="postconf.5.html">main.cf</a>. If
 449 you want to support this service, enable a special port in <a href="master.5.html">master.cf</a>
 450 and specify "-o <a href="postconf.5.html#smtpd_tls_wrappermode">smtpd_tls_wrappermode</a> = yes" as an <a href="smtpd.8.html">smtpd(8)</a> command
 451 line option.  Port 465 (smtps) was once chosen for this feature.
 452 </p>
 453
 454 <p> Example: </p>
 455
 456 <blockquote>
 457 <pre>
 458 /etc/postfix/<a href="master.5.html">master.cf</a>:
 459     smtps    inet  n       -       n       -       -       smtpd
 460       -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
 461 </pre>
 462 </blockquote>
 463
 464 <h3><a name="server_vrfy_client">Client certificate verification</a> </h3>
 465
 466 <p> To receive a remote SMTP client certificate, the Postfix SMTP
 467 server must explicitly ask for one (any contents of $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>
 468 are also sent to the client as a hint for choosing a certificate
 469 from a suitable CA). Unfortunately, Netscape clients will either
 470 complain if no matching client certificate is available or will
 471 offer the user client a list of certificates to choose from.
 472 Additionally some MTAs (notably some versions of qmail) are unable
 473 to complete TLS negotiation when client certificates are requested,
 474 and abort the SMTP session. So this option is "off" by default.
 475 You will however need the certificate if you want to use certificate
 476 based relaying with, for example, the <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
 477 feature.  </p>
 478
 479 <p> Example: </p>
 480
 481 <blockquote>
 482 <pre>
 483 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 484     <a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = no
 485 </pre>
 486 </blockquote>
 487
 488 <p> You may also decide to REQUIRE a remote SMTP client certificate
 489 before allowing TLS connections.  This feature is included for
 490 completeness, and implies "<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes".  </p>
 491
 492 <p> Please be aware, that this will inhibit TLS connections without
 493 a proper client certificate and that it makes sense only when
 494 non-TLS submission is disabled (<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = yes). Otherwise,
 495 clients could bypass the restriction by simply not using STARTTLS
 496 at all. </p>
 497
 498 <p> When TLS is not enforced, the connection will be handled as
 499 if only "<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes" is specified, and a warning is
 500 logged. </p>
 501
 502 <p> Example: </p>
 503
 504 <blockquote>
 505 <pre>
 506 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 507     <a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = no
 508 </pre>
 509 </blockquote>
 510
 511 <p> A client certificate verification depth of 1 is sufficient if
 512 the certificate is directly issued by a CA listed in the CA file.
 513 The default value (5) should also suffice for longer chains (root
 514 CA issues special CA which then issues the actual certificate...)
 515 </p>
 516
 517 <p> Example: </p>
 518
 519 <blockquote>
 520 <pre>
 521 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 522     <a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> = 5
 523 </pre>
 524 </blockquote>
 525
 526 <h3><a name="server_tls_auth">Supporting AUTH over TLS only</a></h3>
 527
 528 <p> Sending AUTH data over an unencrypted channel poses a security
 529 risk. When TLS layer encryption is required (<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> =
 530 yes), the Postfix SMTP server will announce and accept AUTH only
 531 after the TLS layer has been activated with STARTTLS. When TLS
 532 layer encryption is optional (<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = no), it may
 533 however still be useful to only offer AUTH when TLS is active. To
 534 maintain compatibility with non-TLS clients, the default is to
 535 accept AUTH without encryption. In order to change this behavior,
 536 set "<a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = yes". </p>
 537
 538 <p> Example: </p>
 539
 540 <blockquote>
 541 <pre>
 542 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 543     <a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = no
 544 </pre>
 545 </blockquote>
 546
 547 <h3><a name="server_tls_cache">Server-side TLS session cache</a> </h3>
 548
 549 <p> The Postfix SMTP server and the remote SMTP client negotiate
 550 a session, which takes some computer time and network bandwidth.
 551 By default, this session information is cached only in the <a href="smtpd.8.html">smtpd(8)</a>
 552 process actually using this session and is lost when the process
 553 terminates.  To share the session information between multiple
 554 <a href="smtpd.8.html">smtpd(8)</a> processes, a persistent session cache can be used. You
 555 can specify any database type that can store objects of several
 556 kbytes and that supports the sequence operator. DBM databases are
 557 not suitable because they can only store small objects. The cache
 558 is maintained by the <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there is no problem with
 559 concurrent access. Session caching is highly recommended, because
 560 the cost of repeatedly negotiating TLS session keys is high.</p>
 561
 562 <p> Example: </p>
 563
 564 <blockquote>
 565 <pre>
 566 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 567     <a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> = btree:/etc/postfix/smtpd_scache
 568 </pre>
 569 </blockquote>
 570
 571 <p> As of version 2.5, Postfix will no longer maintain this file
 572 in a directory with non-Postfix ownership. As a migration aid,
 573 attempts to open such files are redirected to the Postfix-owned
 574 $<a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. </p>
 575
 576 <p> Cached Postfix SMTP server session information expires after
 577 a certain amount of time.  Postfix/TLS does not use the OpenSSL
 578 default of 300s, but a longer time of 3600sec (=1 hour). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a>
 579 recommends a maximum of 24 hours.  </p>
 580
 581 <p> Example: </p>
 582
 583 <blockquote>
 584 <pre>
 585 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 586     <a href="postconf.5.html#smtpd_tls_session_cache_timeout">smtpd_tls_session_cache_timeout</a> = 3600s
 587 </pre>
 588 </blockquote>
 589
 590 <h3><a name="server_access">Server access control</a> </h3>
 591
 592 <p> Postfix TLS support introduces three additional features for
 593 Postfix SMTP server access control:  </p>
 594
 595 <blockquote>
 596
 597 <dl>
 598
 599 <dt> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </dt> <dd> <p> Allow the remote SMTP
 600 client SMTP request if the client certificate passes verification,
 601 and if its fingerprint is listed in the list of client certificates
 602 (see <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below). </p> </dd>
 603
 604 <dt> <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> </dt> <dd> <p> Allow the remote
 605 client SMTP request if the client certificate passes verification.
 606 </p> </dd>
 607
 608 <dt> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd>
 609 <p> If the client certificate passes verification, use its fingerprint
 610 as a key for the specified <a href="access.5.html">access(5)</a> table. </p> </dd>
 611
 612 </dl>
 613
 614 </blockquote>
 615
 616 <p> The <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> feature must be used with caution,
 617 because it can result in too many access permissions.  Use this
 618 feature only if a special CA issues the client certificates, and
 619 only if this CA is listed as trusted CA. If other CAs are trusted,
 620 any owner of a valid client certificate would be authorized.
 621 The <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> feature can be practical for a
 622 specially created email relay server.  </p>
 623
 624 <p> It is however recommended to stay with the <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
 625 feature and list all certificates via $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>, as
 626 <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> does not permit any control when a
 627 certificate must no longer be used (e.g. an employee leaving). </p>
 628
 629 <p> Example: </p>
 630
 631 <blockquote>
 632 <pre>
 633 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 634     <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
 635         ...
 636         <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
 637         <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
 638         ...
 639 </pre>
 640 </blockquote>
 641
 642 <p> The Postfix list manipulation routines give special treatment
 643 to whitespace and some other characters, making the use of certificate
 644 names impractical.  Instead we use the certificate fingerprints as
 645 they are difficult to fake but easy to use for lookup.  Postfix
 646 lookup tables are in the form of (key, value) pairs.  Since we only
 647 need the key, the value can be chosen freely, e.g.  the name of
 648 the user or host.</p>
 649
 650 <p> Example: </p>
 651
 652 <blockquote>
 653 <pre>
 654 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 655     <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> = hash:/etc/postfix/relay_clientcerts
 656
 657 /etc/postfix/relay_clientcerts:
 658     D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home
 659 </pre>
 660 </blockquote>
 661
 662 <h3><a name="server_cipher">Server-side cipher controls</a> </h3>
 663
 664 <p> To influence the Postfix SMTP server cipher selection scheme,
 665 you can give cipherlist string.  A detailed description would go
 666 to far here; please refer to the OpenSSL documentation.  If you
 667 don't know what to do with it, simply don't touch it and leave the
 668 (openssl-)compiled in default! </p>
 669
 670 <p> DO NOT USE " to enclose the string, specify just the string!!! </p>
 671
 672 <p> Example: </p>
 673
 674 <blockquote>
 675 <pre>
 676 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 677     <a href="postconf.5.html#smtpd_tls_cipherlist">smtpd_tls_cipherlist</a> = DEFAULT
 678 </pre>
 679 </blockquote>
 680
 681 <p> If you want to take advantage of ciphers with EDH, DH parameters
 682 are needed.  Instead of using the built-in DH parameters for both
 683 1024bit and 512bit, it is better to generate "own" parameters,
 684 since otherwise it would "pay" for a possible attacker to start a
 685 brute force attack against parameters that are used by everybody.
 686 For this reason, the parameters chosen are already different from
 687 those distributed with other TLS packages. </p>
 688
 689 <p> To generate your own set of DH parameters, use: </p>
 690
 691 <blockquote>
 692 <pre>
 693 % <b>openssl gendh -out /etc/postfix/dh_1024.pem -2 -rand /var/run/egd-pool 1024</b>
 694 % <b>openssl gendh -out /etc/postfix/dh_512.pem -2 -rand /var/run/egd-pool 512</b>
 695 </pre>
 696 </blockquote>
 697
 698 <p> Examples: </p>
 699
 700 <blockquote>
 701 <pre>
 702 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 703     <a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a> = /etc/postfix/dh_1024.pem
 704     <a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a> = /etc/postfix/dh_512.pem
 705 </pre>
 706 </blockquote>
 707
 708 <h3><a name="server_misc"> Miscellaneous server controls</a> </h3>
 709
 710 <p> The <a href="postconf.5.html#smtpd_starttls_timeout">smtpd_starttls_timeout</a> parameter limits the time of Postfix
 711 SMTP server write and read operations during TLS startup and shutdown
 712 handshake procedures.  </p>
 713
 714 <p> Example: </p>
 715
 716 <blockquote>
 717 <pre>
 718 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 719     <a href="postconf.5.html#smtpd_starttls_timeout">smtpd_starttls_timeout</a> = 300s
 720 </pre>
 721 </blockquote>
 722
 723 <h2> <a name="client_tls">SMTP Client specific settings</a> </h2>
 724
 725 <p> Topics covered in this section: </p>
 726
 727 <ul>
 728
 729 <li><a href="#client_cert_key">Client-side certificate and private
 730 key configuration </a>
 731
 732 <li><a href="#client_logging"> Client-side TLS activity logging
 733 </a>
 734
 735 <li><a href="#client_tls_cache">Client-side TLS session cache</a>
 736
 737 <li><a href="#client_tls_enable"> Enabling TLS in the Postfix SMTP client </a>
 738
 739 <li><a href="#client_tls_require"> Requiring TLS encryption </a>
 740
 741 <li><a href="#client_tls_nopeer"> Disabling server certificate verification </a>
 742
 743 <li><a href="#client_tls_per_site"> Per-site TLS policies </a>
 744
 745 <!--
 746 <li><a href="#client_tls_obs"> Obsolete per-site TLS policy support </a>
 747 -->
 748
 749 <li><a href="#client_tls_harden"> Closing a DNS loophole with <!-- legacy --> per-site TLS policies </a>
 750
 751 <li><a href="#client_tls_discover"> Discovering servers that support TLS </a>
 752
 753 <li><a href="#client_vrfy_server">Server certificate verification depth</a>
 754
 755 <li> <a href="#client_cipher">Client-side cipher controls </a>
 756
 757 <li> <a href="#client_misc"> Miscellaneous client controls </a>
 758
 759 </ul>
 760
 761 <h3><a name="client_cert_key">Client-side certificate and private
 762 key configuration </a> </h3>
 763
 764 <p> During TLS startup negotiation the Postfix SMTP client may present
 765 a certificate to the remote SMTP server.  The Netscape client is
 766 rather clever here and lets the user select between only those
 767 certificates that match CA certificates offered by the remote SMTP
 768 server. As the Postfix SMTP client uses the "SSL_connect()" function
 769 from the OpenSSL package, this is not possible and we have to choose
 770 just one certificate.  So for now the default is to use _no_
 771 certificate and key unless one is explicitly specified here. </p>
 772
 773 <p> Both RSA and DSA certificates are supported.  You can have both
 774 at the same time, in which case the cipher used determines which
 775 certificate is presented.  </p>
 776
 777 <p> It is possible for the Postfix SMTP client to use the same
 778 key/certificate pair as the Postfix SMTP server.  If a certificate
 779 is to be presented, it must be in "pem" format. The private key
 780 must not be encrypted, meaning: it must be accessible without
 781 password. Both parts (certificate and private key) may be in the
 782 same file. </p>
 783
 784 <p> In order for remote SMTP servers to verify the Postfix SMTP
 785 client certificates, the CA certificate (in case of a certificate
 786 chain, all CA certificates) must be available.  You should add
 787 these certificates to the client certificate, the client certificate
 788 first, then the issuing CA(s). </p>
 789
 790 <p> Example: the certificate for "client.example.com" was issued by
 791 "intermediate CA" which itself has a certificate of "root CA".
 792 Create the client.pem file with: </p>
 793
 794 <blockquote>
 795 <pre>
 796 % <b>cat client_cert.pem intermediate_CA.pem &gt; client.pem </b>
 797 </pre>
 798 </blockquote>
 799
 800 <p> A Postfix SMTP client certificate supplied here must be usable
 801 as SSL client certificate and hence pass the "openssl verify -purpose
 802 sslclient ..." test. </p>
 803
 804 <p> A server that trusts the root CA has a local copy of the root
 805 CA certificate, so it is not necessary to include the root CA
 806 certificate here. Leaving it out of the "client.pem" file reduces
 807 the overhead of the TLS exchange. </p>
 808
 809 <p> If you want the Postfix SMTP client to accept remote SMTP server
 810 certificates issued by these CAs, append the root certificate to
 811 $<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.  When
 812 you configure trust in a root CA, it is not necessary to explicitly trust
 813 intermediary CAs signed by the root CA, unless $<a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a>
 814 is less than the number of CAs in the certificate chain for the servers
 815 of interest. With a verify depth of 1 you can only verify certificates
 816 directly signed by a trusted CA, and all trusted intermediary CAs need to
 817 be configured explicitly. With a verify depth of 2 you can verify servers
 818 signed by a root CA or a direct intermediary CA (so long as the server
 819 is correctly configured to supply its intermediate CA certificate). </p>
 820
 821 <p> RSA key and certificate examples: </p>
 822
 823 <blockquote>
 824 <pre>
 825 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 826     <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem
 827     <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>
 828 </pre>
 829 </blockquote>
 830
 831 <p> Their DSA counterparts: </p>
 832
 833 <blockquote>
 834 <pre>
 835 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 836     <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem
 837     <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>
 838 </pre>
 839 </blockquote>
 840
 841 <p> To verify a remote SMTP server certificate, the Postfix SMTP
 842 client needs to trust the certificates of the issuing certification
 843 authorities. These certificates in "pem" format can be stored in a
 844 single $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in
 845 the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. If you use a directory, don't forget
 846 to create the necessary "hash" links with: </p>
 847
 848 <blockquote>
 849 <pre>
 850 # <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
 851 </pre>
 852 </blockquote>
 853
 854 <p> The $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> contains the CA certificates of one or more
 855 trusted CAs. The file is opened (with root privileges) before Postfix
 856 enters the optional chroot jail and so need not be accessible from inside the
 857 chroot jail. </p>
 858
 859 <p> Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>
 860 directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>
 861 privileges) from the files in the directory when the information
 862 is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible
 863 inside the optional chroot jail.  </p>
 864
 865 <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
 866 a space/time tradeoff. If there are many trusted CAs, the cost of
 867 preloading them all into memory may not pay off in reduced access time
 868 when the certificate is needed.  </p>
 869
 870 <p> Example: </p>
 871
 872 <blockquote>
 873 <pre>
 874 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 875     <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem
 876     <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /etc/postfix/certs
 877 </pre>
 878 </blockquote>
 879
 880 <h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>
 881
 882 <p> To get additional information about Postfix SMTP client TLS
 883 activity you can increase the loglevel from 0..4. Each logging
 884 level also includes the information that is logged at a lower
 885 logging level. </p>
 886
 887 <blockquote>
 888
 889 <table>
 890
 891 <tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>
 892
 893 <tr> <td> 1 </td> <td> Log TLS handshake and certificate information.
 894 </td> </tr>
 895
 896 <tr> <td> 2 </td> <td> Log levels during TLS negotiation.  </td>
 897 </tr>
 898
 899 <tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS
 900 negotiation process </td> </tr>
 901
 902 <tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete
 903 transmission after STARTTLS </td> </tr>
 904
 905 </table>
 906
 907 </blockquote>
 908
 909 <p> Example: </p>
 910
 911 <blockquote>
 912 <pre>
 913 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 914     <a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 0
 915 </pre>
 916 </blockquote>
 917
 918 <h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>
 919
 920 <p> The remote SMTP server and the Postfix SMTP client negotiate a
 921 session, which takes some computer time and network bandwidth.  By
 922 default, this session information is cached only in the <a href="smtp.8.html">smtp(8)</a>
 923 process actually using this session and is lost when the process
 924 terminates.  To share the session information between multiple
 925 <a href="smtp.8.html">smtp(8)</a> processes, a persistent session cache can be used. You
 926 can specify any database type that can store objects of several
 927 kbytes and that supports the sequence operator. DBM databases are
 928 not suitable because they can only store small objects. The cache
 929 is maintained by the <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there is no problem with
 930 concurrent access. Session caching is highly recommended, because
 931 the cost of repeatedly negotiating TLS session keys is high.  Future
 932 Postfix SMTP servers may limit the number of sessions that a client
 933 is allowed to negotiate per unit time.</p>
 934
 935
 936 <p> Example: </p>
 937
 938 <blockquote>
 939 <pre>
 940 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 941     <a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = btree:/etc/postfix/smtp_scache
 942 </pre>
 943 </blockquote>
 944
 945 <p> As of version 2.5, Postfix will no longer maintain this file
 946 in a directory with non-Postfix ownership. As a migration aid,
 947 attempts to open such files are redirected to the Postfix-owned
 948 $<a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. </p>
 949
 950 <p> Cached Postfix SMTP client session information expires after
 951 a certain amount of time.  Postfix/TLS does not use the OpenSSL
 952 default of 300s, but a longer time of 3600s (=1 hour). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a>
 953 recommends a maximum of 24 hours.  </p>
 954
 955 <p> Example: </p>
 956
 957 <blockquote>
 958 <pre>
 959 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 960     <a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s
 961 </pre>
 962 </blockquote>
 963
 964 <h3><a name="client_tls_enable"> Enabling TLS in the Postfix SMTP
 965 client </a> </h3>
 966
 967 <p> By default, TLS is disabled in the Postfix SMTP client, so no
 968 difference to plain Postfix is visible.  If you enable TLS, the
 969 Postfix SMTP client will send STARTTLS when TLS support is announced
 970 by the remote SMTP server. </p>
 971
 972 <p> When the server accepts the STARTTLS command, but the subsequent
 973 TLS handshake fails, and no other server is available, the Postfix SMTP
 974 client defers the delivery attempt, and the mail stays in the queue. After
 975 a handshake failure, the communications channel is in an indeterminate
 976 state and cannot be used for non-TLS deliveries. </p>
 977
 978 <p> Example: </p>
 979
 980 <blockquote>
 981 <pre>
 982 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 983     <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes
 984 </pre>
 985 </blockquote>
 986
 987 <h3><a name="client_tls_require"> Requiring TLS encryption </a>
 988 </h3>
 989
 990 <p> You can ENFORCE the use of TLS, so that the Postfix SMTP client
 991 will not deliver mail over unencrypted connections.  In this mode,
 992 the remote SMTP server hostname must match the information in the
 993 remote server certificate, and the server certificate must be issued
 994 by a CA that is trusted by the Postfix SMTP client.  If the remote
 995 server certificate doesn't verify or the remote SMTP server hostname
 996 doesn't match, and no other server is available, the delivery
 997 attempt is deferred and the mail stays in the queue.  </p>
 998
 999 <p> The remote SMTP server hostname is verified against all names
1000 provided as dNSNames
1001 in the SubjectAlternativeName. If no dNSNames are specified, the
1002 CommonName is checked.  Verification may be turned off with the
1003 <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> option which is discussed below. </p>
1004
1005 <p> Enforcing the use of TLS is useful if you know that you will
1006 only
1007 connect to servers that support <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> _and_ that present server
1008 certificates that meet the above requirements.  An example would
1009 be a client only sends email to one specific mailhub that offers
1010 the necessary STARTTLS support.  </p>
1011
1012 <p> Example: </p>
1013
1014 <blockquote>
1015 <pre>
1016 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1017     <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes
1018 </pre>
1019 </blockquote>
1020
1021 <h3> <a name="client_tls_nopeer"> Disabling server certificate
1022 verification </a> </h3>
1023
1024 <p> As of <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> the requirements for hostname checking for MTA
1025 clients are not set. When TLS is required (<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes),
1026 the option <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> can be set to "no" to disable
1027 strict remote SMTP server hostname checking. In this case, the mail
1028 delivery will proceed regardless of the CommonName etc. listed in
1029 the certificate. </p>
1030
1031 <p>  Despite the potential for eliminating "man-in-the-middle" and
1032 other attacks, mandatory certificate/peername verification is not
1033 viable as a default Internet mail delivery policy at this time.  A
1034 significant fraction of TLS enabled MTAs uses self-signed certificates,
1035 or certificates that are signed by a private certificate authority.
1036 On a machine that delivers mail to the Internet, if you set
1037 <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes, you should probably also set
1038 <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = no.  You can use the per-site TLS
1039 policies (see below) to enable full peer verification for specific
1040 destinations that are known to have verifiable TLS server certificates.
1041 </p>
1042
1043 <p> Example: </p>
1044
1045 <blockquote>
1046 <pre>
1047 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1048     <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes
1049     <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = no
1050 </pre>
1051 </blockquote>
1052
1053 <h3> <a name="client_tls_per_site"> Per-site TLS policies </a> </h3>
1054
1055 <p> A small fraction of servers offer STARTTLS but the negotiation
1056 consistently fails, leading to mail aging out of the queue and
1057 bouncing back to the sender. In such cases, you can use the per-site
1058 policies to disable TLS for the problem sites.  Alternatively, you
1059 can enable TLS for just a few specific sites and not enable it for
1060 all sites. </p>
1061
1062 <!-- insert new-style TLS policy mechanism here
1063
1064 <h3> <a name="client_tls_obs"> Obsolete per-site TLS policy support
1065 </a> </h3>
1066
1067 <p> This section describes an obsolete per-site TLS policy mechanism.
1068 Unlike the newer mechanism it supports TLS policy lookup by server
1069 hostname, and lacks control over what names can appear in server
1070 certificates.  Because of this, the obsolete mechanism is vulnerable
1071 to false DNS hostname information in MX or CNAME records.  These
1072 attacks can be eliminated only with great difficulty.  </p>
1073
1074 -->
1075
1076 <p> The <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> table is searched for a policy that matches
1077 the following information:  </p>
1078
1079 <blockquote>
1080
1081 <dl>
1082
1083 <dt> remote SMTP server hostname </dt> <dd> This is simply the DNS
1084 name of the server that the Postfix SMTP client connects to; this
1085 name may be obtained from other DNS lookups, such as MX lookups or
1086 CNAME lookups. </dd>
1087
1088 <dt> next-hop destination </dt> <dd> This is normally the domain
1089 portion of the recipient address, but it may be overruled by
1090 information from the <a href="transport.5.html">transport(5)</a> table, from the <a href="postconf.5.html#relayhost">relayhost</a> parameter
1091 setting, or from the <a href="postconf.5.html#relay_transport">relay_transport</a> setting. When it's not the
1092 recipient domain, the next-hop destination can have the Postfix-specific
1093 form "<tt>[name]</tt>", <tt>[name]:port</tt>", "<tt>name</tt>" or
1094 "<tt>name:port</tt>".  </dd>
1095
1096 </dl>
1097
1098 </blockquote>
1099
1100 <p> When both the hostname lookup and the next-hop lookup succeed,
1101 the host policy does not automatically override the next-hop policy.
1102 Instead, precedence is given to either the more specific or the
1103 more secure per-site policy as described below.  </p>
1104
1105 <p> The <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> table uses a simple "<i>name whitespace
1106 value</i>" format. Specify host names or next-hop destinations on
1107 the left-hand side; no wildcards are allowed.  On the right hand
1108 side specify one of the following keywords:  </p>
1109
1110 <blockquote>
1111
1112 <dl>
1113
1114 <dt> NONE </dt> <dd> Don't use TLS at all. This overrides a less
1115 specific <b>MAY</b> lookup result from the alternate host or next-hop
1116 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>,
1117 and <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> settings. </dd>
1118
1119 <dt> MAY </dt> <dd> Try to use TLS if the server announces support,
1120 otherwise use the unencrypted connection. This has less precedence
1121 than a more specific result (including <b>NONE</b>) from the alternate
1122 host or next-hop lookup key, and has less precedence than the more
1123 specific global "<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>
1124 = yes".  </dd>
1125
1126 <dt> MUST_NOPEERMATCH </dt> <dd> Require TLS encryption, but do not
1127 require that the remote SMTP server hostname matches the information
1128 in the remote SMTP server certificate, or that the server certificate
1129 was issued by a trusted CA. This overrides a less secure <b>NONE</b>
1130 or a less specific <b>MAY</b> lookup result from the alternate host
1131 or next-hop lookup key, and overrides the global <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>,
1132 <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.  </dd>
1133
1134 <dt> MUST </dt> <dd> Require TLS encryption, require that the remote
1135 SMTP server hostname matches the information in the remote SMTP
1136 server certificate, and require that the remote SMTP server certificate
1137 was issued by a trusted CA. This overrides a less secure <b>NONE</b>
1138 and <b>MUST_NOPEERMATCH</b> or a less specific <b>MAY</b> lookup
1139 result from the alternate host or next-hop lookup key, and overrides
1140 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>
1141 settings.  </dd>
1142
1143 </dl>
1144
1145 </blockquote>
1146
1147 <p> The precedences between global (<a href="postconf.5.html">main.cf</a>) and per-site TLS
1148 policies can be summarized as follows: </p>
1149
1150 <ul>
1151
1152 <li> <p> When neither the remote SMTP server hostname nor the
1153 next-hop destination are found in the <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> table, the
1154 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
1155 <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
1156 "<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>
1157
1158 <li> <p> When both hostname and next-hop destination lookups produce
1159 a result, the more specific per-site policy (NONE, MUST, etc)
1160 overrides the less specific one (MAY), and the more secure per-site
1161 policy (MUST, etc) overrides the less secure one (NONE).  </p>
1162
1163 <li> <p> After the per-site policy lookups are combined, the result
1164 generally overrides the global policy. The exception is the less
1165 specific <b>MAY</b> per-site policy, which is overruled by the more
1166 specific global "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes" with server certificate
1167 verification as specified with the <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>
1168 parameter.  </p>
1169
1170 </ul>
1171
1172 <h3> <a name="client_tls_harden"> Closing a DNS loophole with
1173 <!-- legacy --> per-site TLS policies </a> </h3>
1174
1175 <p> As long as no secure DNS lookup mechanism is available, false
1176 hostnames in MX or CNAME responses can change the server hostname
1177 that Postfix uses for TLS policy lookup and server certificate
1178 verification. Even with a perfect match between the server hostname
1179 and the server certificate, there is no guarantee that Postfix is
1180 connected to the right server.  To avoid this loophole take the
1181 following steps: </p>
1182
1183 <ul>
1184
1185 <li> <p> Eliminate MX lookups. Specify local <a href="transport.5.html">transport(5)</a> table
1186 entries for sensitive domains with explicit <a href="smtp.8.html">smtp</a>:[<i>mailhost</i>]
1187 or <a href="smtp.8.html">smtp</a>:[<i>mailhost</i>]:<i>port</i> destinations (you can assure
1188 security of this table unlike DNS); in the <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> table
1189 specify the value <b>MUST</b> for the key [<i>mailhost</i>] or
1190 <a href="smtp.8.html">smtp</a>:[<i>mailhost</i>]:<i>port</i>. This prevents false hostname
1191 information in DNS MX records from changing the server hostname
1192 that Postfix uses for TLS policy lookup and server certificate
1193 verification. </p>
1194
1195 <li> <p> Disallow CNAME hostname overrides. In <a href="postconf.5.html">main.cf</a> specify
1196 "<a href="postconf.5.html#smtp_cname_overrides_servername">smtp_cname_overrides_servername</a> = no". This prevents false hostname
1197 information in DNS CNAME records from changing the server hostname
1198 that Postfix uses for TLS policy lookup and server certificate
1199 verification. This feature requires Postfix 2.2.9 or later.  </p>
1200
1201 </ul>
1202
1203 <p> Example: </p>
1204
1205 <blockquote> <pre>
1206 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1207     <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = hash:/etc/postfix/tls_per_site
1208     <a href="postconf.5.html#relayhost">relayhost</a> = [msa.example.net]:587
1209
1210 /etc/postfix/tls_per_site:
1211     # <a href="postconf.5.html#relayhost">relayhost</a> exact nexthop match
1212     [msa.example.net]:587       MUST
1213
1214     # TLS should not be used with the <i>example.org</i> MX hosts.
1215     example.org                 NONE
1216
1217     # TLS should not be used with the host <i>smtp.example.com</i>.
1218     smtp.example.com             NONE
1219 </pre>
1220 </blockquote>
1221
1222 <h3> <a name="client_tls_discover"> Discovering servers that support
1223 TLS </a> </h3>
1224
1225 <p> As we decide on a "per site" basis whether or not to use TLS,
1226 it would be good to have a list of sites that offered "STARTTLS".
1227 We can collect it ourselves with this option. </p>
1228
1229 <p> If the <a href="postconf.5.html#smtp_tls_note_starttls_offer">smtp_tls_note_starttls_offer</a> feature is enabled and a
1230 server offers STARTTLS while TLS is not already enabled for that
1231 server, the Postfix SMTP client logs a line as follows: </p>
1232
1233 <blockquote>
1234 <pre>
1235 postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com]
1236 </pre>
1237 </blockquote>
1238
1239 <p> Example: </p>
1240
1241 <blockquote>
1242 <pre>
1243 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1244     <a href="postconf.5.html#smtp_tls_note_starttls_offer">smtp_tls_note_starttls_offer</a> = yes
1245 </pre>
1246 </blockquote>
1247
1248 <h3><a name="client_vrfy_server">Server certificate verification depth</a> </h3>
1249
1250 <p> When verifying a remote SMTP server certificate, a verification
1251 depth of 1 is sufficient if the certificate is directly issued by
1252 a CA specified with <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>.  The default
1253 value of 5 should also suffice for longer chains (root CA issues
1254 special CA which then issues the actual certificate...) </p>
1255
1256 <p> Example: </p>
1257
1258 <blockquote>
1259 <pre>
1260 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1261     <a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> = 5
1262 </pre>
1263 </blockquote>
1264
1265 <h3> <a name="client_cipher">Client-side cipher controls </a> </h3>
1266
1267 <p> To influence the Postfix SMTP client cipher selection scheme,
1268 you can give cipherlist string.  A detailed description would go
1269 to far here; please refer to the OpenSSL documentation.  If you
1270 don't know what to do with it, simply don't touch it and leave the
1271 (openssl-)compiled in default! </p>
1272
1273 <p> DO NOT USE " to enclose the string, specify just the string!!! </p>
1274
1275 <p> Example: </p>
1276
1277 <blockquote>
1278 <pre>
1279 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1280     <a href="postconf.5.html#smtp_tls_cipherlist">smtp_tls_cipherlist</a> = DEFAULT
1281 </pre>
1282 </blockquote>
1283
1284 <h3> <a name="client_misc"> Miscellaneous client controls </a> </h3>
1285
1286 <p> The <a href="postconf.5.html#smtp_starttls_timeout">smtp_starttls_timeout</a> parameter limits the time of Postfix
1287 SMTP client write and read operations during TLS startup and shutdown
1288 handshake procedures.  In case of problems the Postfix SMTP client
1289 tries the next network address on the mail exchanger list, and
1290 defers delivery if no alternative server is available. </p>
1291
1292 <p> Example: </p>
1293
1294 <blockquote>
1295 <pre>
1296 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1297     <a href="postconf.5.html#smtp_starttls_timeout">smtp_starttls_timeout</a> = 300s
1298 </pre>
1299 </blockquote>
1300
1301 <h2><a name="tlsmgr_controls"> TLS manager specific settings </a> </h2>
1302
1303 <p> The security of cryptographic software such as TLS depends
1304 critically on the ability to generate unpredictable numbers for
1305 keys and other information. To this end, the <a href="tlsmgr.8.html">tlsmgr(8)</a> process
1306 maintains a Pseudo Random Number Generator (PRNG) pool.  This is
1307 queried by the <a href="smtp.8.html">smtp(8)</a> and <a href="smtpd.8.html">smtpd(8)</a> processes when they initialize.
1308 By default, these daemons request 32 bytes, the equivalent to 256
1309 bits. This is more than sufficient to generate a 128bit (or 168bit)
1310 session key.  </p>
1311
1312 <p> Example: </p>
1313
1314 <blockquote>
1315 <pre>
1316 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1317     <a href="postconf.5.html#tls_daemon_random_bytes">tls_daemon_random_bytes</a> = 32
1318 </pre>
1319 </blockquote>
1320
1321 <p> In order to feed its in-memory PRNG pool, the <a href="tlsmgr.8.html">tlsmgr(8)</a> reads
1322 entropy from an external source, both at startup and during run-time.
1323 Specify a good entropy source, like EGD or /dev/urandom; be sure
1324 to only use non-blocking sources (on OpenBSD, use /dev/arandom
1325 when <a href="tlsmgr.8.html">tlsmgr(8)</a> complains about /dev/urandom timeout errors).
1326 If the entropy source is not a
1327 regular file, you must prepend the source type to the source name:
1328 "dev:" for a device special file, or "egd:" for a source with EGD
1329 compatible socket interface.  </p>
1330
1331 <p> Examples (specify only one in <a href="postconf.5.html">main.cf</a>): </p>
1332
1333 <blockquote>
1334 <pre>
1335 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1336     <a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom
1337     <a href="postconf.5.html#tls_random_source">tls_random_source</a> = egd:/var/run/egd-pool
1338 </pre>
1339 </blockquote>
1340
1341 <p> By default, <a href="tlsmgr.8.html">tlsmgr(8)</a> reads 32 bytes from the external entropy
1342 source at each seeding event.  This amount (256bits) is more than
1343 sufficient for generating a 128bit symmetric key.  With EGD and
1344 device entropy sources, the <a href="tlsmgr.8.html">tlsmgr(8)</a> limits the amount of data
1345 read at each step to 255 bytes. If you specify a regular file as
1346 entropy source, a larger amount of data can be read.  </p>
1347
1348 <p> Example: </p>
1349
1350 <blockquote>
1351 <pre>
1352 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1353     <a href="postconf.5.html#tls_random_bytes">tls_random_bytes</a> = 32
1354 </pre>
1355 </blockquote>
1356
1357 <p> In order to update its in-memory PRNG pool, the <a href="tlsmgr.8.html">tlsmgr(8)</a>
1358 queries the external entropy source again after a pseudo-random
1359 amount of time. The time is calculated using the PRNG, and is
1360 between 0 and the maximal time specified with <a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a>.
1361 The default maximal time interval is 1 hour. </p>
1362
1363 <p> Example: </p>
1364
1365 <blockquote>
1366 <pre>
1367 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1368     <a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a> = 3600s
1369 </pre>
1370 </blockquote>
1371
1372 <p> The <a href="tlsmgr.8.html">tlsmgr(8)</a> process saves the PRNG state to a persistent
1373 exchange file at regular times and when the process terminates, so
1374 that it can recover the PRNG state the next time it starts up.
1375 This file is created when it does not exist. Its default location
1376 is under the Postfix configuration directory, which is not the
1377 proper place for information that is modified by Postfix.  Instead,
1378 the file location should probably be on the /var partition (but
1379 <b>not</b> inside the chroot jail).  </p>
1380
1381 <p> Examples: </p>
1382
1383 <blockquote>
1384 <pre>
1385 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
1386     <a href="postconf.5.html#tls_random_exchange_name">tls_random_exchange_name</a> = /etc/postfix/prng_exch
1387     <a href="postconf.5.html#tls_random_prng_update_period">tls_random_prng_update_period</a> = 3600s
1388 </pre>
1389 </blockquote>
1390
1391 <h2><a name="quick-start">Getting started, quick and dirty</a></h2>
1392
1393 <p> The following steps will get you started quickly. Because you
1394 sign your own Postfix public key certificate, you get TLS encryption
1395 but no TLS authentication.  This is sufficient for testing, and
1396 for exchanging email with sites that you have no trust relationship
1397 with.  For real authentication, your Postfix public key certificate
1398 needs to be signed by a recognized Certificate Authority, and
1399 Postfix needs to be configured with a list of public key certificates
1400 of Certificate Authorities, so that Postfix can verify the public key
1401 certificates of remote hosts. </p>
1402
1403 <p> In the examples below, user input is shown in <b><tt>bold</tt></b>
1404 font, and a "<tt>#</tt>" prompt indicates a super-user shell. </p>
1405
1406 <ul>
1407
1408 <li> <p> Become your own Certificate Authority, so that you can
1409 sign your own public keys. This example uses the CA.pl script that
1410 ships with OpenSSL.  By default, OpenSSL installs this as
1411 <tt>/usr/local/ssl/misc/CA.pl</tt>, but your mileage may vary.
1412 The script creates a private key in <tt>./demoCA/private/cakey.pem</tt>
1413 and a public key in <tt>./demoCA/cacert.pem</tt>.</p>
1414
1415 <blockquote>
1416 <pre>
1417 % <b>/usr/local/ssl/misc/CA.pl -newca</b>
1418 CA certificate filename (or enter to create)
1419
1420 Making CA certificate ...
1421 Using configuration from /etc/ssl/openssl.cnf
1422 Generating a 1024 bit RSA private key
1423 ....................++++++
1424 .....++++++
1425 writing new private key to './demoCA/private/cakey.pem'
1426 Enter PEM pass phrase:<b>whatever</b>
1427 </pre>
1428 </blockquote>
1429
1430 <li> <p> Create an unpassworded private key for host FOO and create
1431 an unsigned public key certificate. </p>
1432
1433 <blockquote>
1434 <pre>
1435 % <b>openssl req -new -nodes -keyout FOO-key.pem -out FOO-req.pem -days 365</b>
1436 Using configuration from /etc/ssl/openssl.cnf
1437 Generating a 1024 bit RSA private key
1438 ........................................++++++
1439 ....++++++
1440 writing new private key to 'FOO-key.pem'
1441 -----
1442 You are about to be asked to enter information that will be incorporated
1443 into your certificate request.
1444 What you are about to enter is what is called a Distinguished Name or a DN.
1445 There are quite a few fields but you can leave some blank
1446 For some fields there will be a default value,
1447 If you enter '.', the field will be left blank.
1448 -----
1449 Country Name (2 letter code) [AU]:<b>US</b>
1450 State or Province Name (full name) [Some-State]:<b>New York</b>
1451 Locality Name (eg, city) []:<b>Westchester</b>
1452 Organization Name (eg, company) [Internet Widgits Pty Ltd]:<b>Porcupine</b>
1453 Organizational Unit Name (eg, section) []:
1454 Common Name (eg, YOUR name) []:<b>FOO</b>
1455 Email Address []:<b>wietse@porcupine.org</b>
1456
1457 Please enter the following 'extra' attributes
1458 to be sent with your certificate request
1459 A challenge password []:<b>whatever</b>
1460 An optional company name []:
1461 </pre>
1462 </blockquote>
1463
1464 <li> <p> Sign the public key certificate for host FOO with the
1465 Certification Authority private key that we created a few
1466 steps ago. </p>
1467
1468 <blockquote>
1469 <pre>
1470 % <b>openssl ca -out FOO-cert.pem -infiles FOO-req.pem</b>
1471 Uing configuration from /etc/ssl/openssl.cnf
1472 Enter PEM pass phrase:<b>whatever</b>
1473 Check that the request matches the signature
1474 Signature ok
1475 The Subjects Distinguished Name is as follows
1476 countryName           :PRINTABLE:'US'
1477 stateOrProvinceName   :PRINTABLE:'New York'
1478 localityName          :PRINTABLE:'Westchester'
1479 organizationName      :PRINTABLE:'Porcupine'
1480 commonName            :PRINTABLE:'FOO'
1481 emailAddress          :IA5STRING:'wietse@porcupine.org'
1482 Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days)
1483 Sign the certificate? [y/n]:<b>y</b>
1484
1485
1486 1 out of 1 certificate requests certified, commit? [y/n]<b>y</b>
1487 Write out database with 1 new entries
1488 Data Base Updated
1489 </pre>
1490 </blockquote>
1491
1492 <li> <p> Install the host private key, the host public key certificate,
1493 and the Certification Authority certificate files.  This requires
1494 super-user privileges. </p>
1495
1496 <blockquote>
1497 <pre>
1498 # <b>cp demoCA/cacert.pem FOO-key.pem FOO-cert.pem /etc/postfix</b>
1499 # <b>chmod 644 /etc/postfix/FOO-cert.pem /etc/postfix/cacert.pem</b>
1500 # <b>chmod 400 /etc/postfix/FOO-key.pem</b>
1501 </pre>
1502 </blockquote>
1503
1504 <li> <p> Configure Postfix, by adding the following to
1505 <tt>/etc/postfix/<a href="postconf.5.html">main.cf</a> </tt>. </p>
1506
1507 <blockquote>
1508 <pre>
1509 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/cacert.pem
1510 <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/FOO-cert.pem
1511 <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> = /etc/postfix/FOO-key.pem
1512 <a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = btree:/var/run/smtp_tls_session_cache
1513 <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes
1514 <a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> = /etc/postfix/cacert.pem
1515 <a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/FOO-cert.pem
1516 <a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = /etc/postfix/FOO-key.pem
1517 <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = yes
1518 <a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> = btree:/var/run/smtpd_tls_session_cache
1519 <a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> = yes
1520 <a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom
1521 </pre>
1522 </blockquote>
1523
1524 </ul>
1525
1526
1527 <h2> <a name="problems"> Reporting problems </a> </h2>
1528
1529 <p> When reporting a problem, please be thorough in the report.
1530 Patches, when possible, are greatly appreciated too. </p>
1531
1532 <p> Please differentiate when possible between: </p>
1533
1534 <ul>
1535
1536 <li> Problems in the TLS code: &lt;postfix_tls@aet.tu-cottbus.de&gt;
1537
1538 <li> Problems in vanilla Postfix: &lt;postfix-users@postfix.org&gt;
1539
1540 </ul>
1541
1542 <h2><a name="compat">Compatibility with Postfix <2.2 TLS support</a></h2>
1543
1544 <p> Postfix version 2.2 TLS support is based on the Postfix/TLS
1545 patch by Lutz J&auml;nicke, but differs in a few minor ways. </p>
1546
1547 <ul>
1548
1549 <li> <p> <a href="postconf.5.html">main.cf</a>: Specify "btree" instead of "sdbm" for TLS
1550 session cache databases. </p>
1551
1552 <p> TLS session cache databases are now accessed only by the
1553 <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there are no more concurrency issues. Although
1554 Postfix has an sdbm client, the sdbm library (1000
1555 lines of code) is not included with Postfix. </p>
1556
1557 <p> TLS session caches can use any database that can store objects
1558 of several kbytes or more, and that implements the sequence operation.
1559 In most cases, btree databases should be adequate.  </p>
1560
1561 <p> NOTE:  You cannot use dbm databases. TLS session objects
1562 are too large. </p>
1563
1564 <li> <p> <a href="master.5.html">master.cf</a>: Specify "unix" instead of "fifo" as
1565 the tlsmgr service type. </p>
1566
1567 <p> The <a href="smtp.8.html">smtp(8)</a> and <a href="smtpd.8.html">smtpd(8)</a> processes now use a client-server
1568 protocol in order to access the <a href="tlsmgr.8.html">tlsmgr(8)</a> pseudo-random number
1569 generation (PRNG) pool, and in order to access the TLS session
1570 cache databases. Such a protocol cannot be run across fifos. </p>
1571
1572 <li> <p> <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a>: the MUST_NOPEERMATCH per-site policy
1573 cannot override the global "<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = yes" setting.
1574 </p>
1575
1576 <li> <p> <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a>: a combined (NONE + MAY) lookup result
1577 for (hostname and next-hop destination) produces counter-intuitive
1578 results for different <a href="postconf.5.html">main.cf</a> settings.  TLS is enabled with
1579 "<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = no", but it is disabled when both
1580 "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes" and "<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = yes".
1581 </p>
1582
1583 </ul>
1584
1585 <p> The <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> limitations were removed by the end of
1586 the Postfix 2.2 support cycle. </p>
1587
1588 <h2><a name="credits">Credits </a> </h2>
1589
1590 <ul>
1591
1592 <li> TLS support for Postfix was originally developed by  Lutz
1593 J&auml;nicke at Cottbus Technical University.
1594
1595 <li> Wietse Venema adopted the code, did some restructuring, and
1596 compiled this part of the documentation from Lutz's documents.
1597
1598 <li> Victor Duchovni was instrumental with the re-implementation
1599 of the <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> code in terms of enforcement levels, which
1600 simplified the implementation greatly.
1601
1602 </ul>
1603
1604 </body>
1605
1606 </html>