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