summaryrefslogtreecommitdiffstats
path: root/proto/TLS_README.html
diff options
context:
space:
mode:
Diffstat (limited to 'proto/TLS_README.html')
-rw-r--r--proto/TLS_README.html3259
1 files changed, 3259 insertions, 0 deletions
diff --git a/proto/TLS_README.html b/proto/TLS_README.html
new file mode 100644
index 0000000..040fdfd
--- /dev/null
+++ b/proto/TLS_README.html
@@ -0,0 +1,3259 @@
+<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+
+<head>
+
+<title>Postfix TLS Support </title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+
+</head>
+
+<body>
+
+<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix TLS Support
+</h1>
+
+<hr>
+
+<h2> What Postfix TLS support does for you </h2>
+
+<p> Transport Layer Security (TLS, formerly called SSL) provides
+certificate-based authentication and encrypted sessions. An
+encrypted session protects the information that is transmitted with
+SMTP mail or with SASL authentication. </p>
+
+<p> NOTE: By turning on TLS support in Postfix, you not only get
+the ability to encrypt mail and to authenticate remote SMTP clients
+or servers. You also turn on hundreds of thousands of lines of
+OpenSSL library code. Assuming that OpenSSL is written as carefully
+as Wietse's own code, every 1000 lines introduce one additional bug
+into Postfix. </p>
+
+<p> Topics covered in this document: </p>
+
+<ul>
+
+<li><a href="#how">How Postfix TLS support works</a>
+
+<li><a href="#server_tls">SMTP Server specific settings</a>
+
+<li> <a href="#client_tls">SMTP Client specific settings</a>
+
+<li><a href="#tlsmgr_controls"> TLS manager specific settings </a>
+
+<li><a href="#build_tls">Building Postfix with TLS support</a>
+
+<li><a href="#problems"> Reporting problems </a>
+
+<li><a href="#credits"> Credits </a>
+
+</ul>
+
+<p> And last but not least, for the impatient: </p>
+
+<ul>
+
+<li><a href="#quick-start">Getting started, quick and dirty</a>
+
+</ul>
+
+<h2><a name="how">How Postfix TLS support works</a></h2>
+
+<p> The diagram below shows the main elements of the Postfix TLS
+architecture and their relationships. Colored boxes with numbered
+names represent Postfix daemon programs. Other colored boxes
+represent storage elements. </p>
+
+<ul>
+
+<li> <p> The smtpd(8) server implements the SMTP over TLS server
+side. </p>
+
+<li> <p> The smtp(8) client implements the SMTP (and LMTP) over TLS
+client side. </p>
+
+<li> <p> The tlsmgr(8) server maintains the pseudo-random number
+generator (PRNG) that seeds the TLS engines in the smtpd(8) server
+and smtp(8) client processes, and maintains the TLS session key
+cache files. </p>
+
+</ul>
+
+<p> Not shown in the figure are the tlsproxy(8) server and the
+postscreen(8) server. These use TLS in the same manner as smtpd(8).
+</p>
+
+<table>
+
+<tr> <td>Network<tt>-&gt; </tt> </td> <td align="center"
+bgcolor="#f0f0ff"> <br> <a href="smtpd.8.html">smtpd(8)</a> <br> &nbsp; </td> <td colspan="2">
+
+<tt> &lt;---seed----<br><br>&lt;-key/cert-&gt; </tt> </td> <td
+align="center" bgcolor="#f0f0ff"> <br> <a href="tlsmgr.8.html">tlsmgr(8)</a> <br> &nbsp; </td>
+<td colspan="3"> <tt> ----seed---&gt;<br> <br>&lt;-key/cert-&gt;
+
+</tt> </td> <td align="center" bgcolor="#f0f0ff"> <br> <a href="smtp.8.html">smtp(8)</a> <br>
+&nbsp; </td> <td> <tt> -&gt;</tt>Network </td> </tr>
+
+<tr> <td colspan="3"> </td> <td align="right"> <table> <tr> <td>
+
+</td> <td> / </td> </tr> <tr> <td> / </td> <td> </td> </tr> </table>
+</td> <td align="center"> |<br> |</td> <td align="left"> <table>
+
+<tr> <td> \ </td> <td> </td> </tr> <tr> <td> </td> <td> \ </td>
+</tr> </table> </td> <td colspan="3"> </td> </tr>
+
+<tr> <td colspan="2"> </td> <td align="center" bgcolor="#f0f0ff">
+smtpd<br> session<br> key cache </td> <td> </td> <td align="center"
+bgcolor="#f0f0ff"> PRNG<br> state <br>file </td> <td> </td> <td
+align="center" bgcolor="#f0f0ff"> smtp<br> session<br> key cache
+</td>
+
+<td colspan="2"> </td> </tr>
+
+</table>
+
+<h2><a name="server_tls">SMTP Server specific settings</a></h2>
+
+<p> Topics covered in this section: </p>
+
+<ul>
+
+<li><a href="#server_cert_key">Server-side certificate and private
+key configuration </a>
+
+<li><a href="#server_pfs">Server-side forward-secrecy configuration </a>
+
+<li><a href="#server_logging"> Server-side TLS activity logging
+</a>
+
+<li><a href="#server_enable">Enabling TLS in the Postfix SMTP server </a>
+
+<li><a href="#server_vrfy_client">Client certificate verification</a>
+
+<li><a href="#server_tls_auth">Supporting AUTH over TLS only</a>
+
+<li><a href="#server_tls_cache">Server-side TLS session cache</a>
+
+<li><a href="#server_access">Server access control</a>
+
+<li><a href="#server_cipher">Server-side cipher controls</a>
+
+<li><a href="#server_misc"> Miscellaneous server controls</a>
+
+</ul>
+
+<h3><a name="server_cert_key">Server-side certificate and private
+key configuration </a> </h3>
+
+<p> In order to use TLS, the Postfix SMTP server generally needs
+a certificate and a private key. Both must be in "PEM" format. The
+private key must not be encrypted, meaning: the key must be accessible
+without a password. The certificate and private key may be in the same
+file, in which case the certificate file should be owned by "root" and
+not be readable by any other user. If the key is stored separately,
+this access restriction applies to the key file only, and the
+certificate file may be "world-readable". </p>
+
+<p> Public Internet MX hosts without certificates signed by a
+well-known public CA must still generate, and be prepared to present
+to most clients, a self-signed or private-CA signed certificate.
+The remote SMTP client will generally not be able to verify the
+self-signed certificate, but unless the client is running Postfix
+or similar software, it will only negotiate TLS ciphersuites that
+require a server certificate. </p>
+
+<p> For servers that are <b>not</b> public Internet MX hosts, Postfix
+supports configurations with no certificates. This entails the use of
+just the anonymous TLS ciphers, which are not supported by typical SMTP
+clients. Since some clients may not fall back to plain text after a TLS
+handshake failure, a certificate-less Postfix SMTP server will be unable
+to receive email from some TLS-enabled clients. To avoid accidental
+configurations with no certificates, Postfix enables certificate-less
+operation only when the administrator explicitly sets
+"smtpd_tls_cert_file = none". This ensures that new Postfix SMTP server
+configurations will not accidentally enable TLS without certificates. </p>
+
+<p> Note that server certificates are <b>not</b> optional in TLS 1.3. To
+run without certificates you'd have to disable the TLS 1.3 protocol by
+including '!TLSv1.3' in "smtpd_tls_protocols" and perhaps also
+"smtpd_tls_mandatory_protocols". It is simpler instead to just
+configure a certificate chain. Certificate-less operation is not
+recommended. <p>
+
+<p> RSA, DSA and ECDSA (Postfix &ge; 2.6) certificates are supported.
+Most sites only have RSA certificates. You can configure all three
+at the same time, in which case the ciphersuite negotiated with the
+remote SMTP client determines which certificate is used. If your
+DNS zone is signed, and you want to publish DANE TLSA (RFC 6698,
+RFC 7671, RFC 7672) records, these must match all of the configured
+certificate chains. Since the best practice is to publish "3 1 1"
+certificate associations, create a separate TLSA record to match
+each public-key certificate digest. </p>
+
+<h4> Creating the server certificate file </h4>
+
+<p> To verify the Postfix SMTP server certificate, the remote SMTP
+client must receive the issuing CA certificates via the TLS handshake
+or via public-key infrastructure. This means that the Postfix server
+public-key certificate file must include the server certificate
+first, then the issuing CA(s) (bottom-up order). The Postfix SMTP
+server certificate must be usable as SSL server certificate and
+hence pass the "<tt>openssl verify -purpose sslserver ...</tt>" test.
+</p>
+
+<p> The examples that follow show how to create a server certificate
+file. We assume that the certificate for "server.example.com" was
+issued by "intermediate CA" which itself has a certificate issued
+by "root CA". </p>
+
+<ul>
+
+<li> <p> With legacy public CA trust verification, you can omit the
+root certificate from the "server.pem" certificate file. If the
+client trusts the root CA, it will already have a local copy of the
+root CA certificate. Omitting the root CA certificate reduces the
+size of the server TLS handshake. </p>
+
+<blockquote>
+<pre>
+% <b>cat server_cert.pem intermediate_CA.pem &gt; server.pem</b>
+</pre>
+</blockquote>
+
+<li> <p> If you publish DANE TLSA (RFC 6698, RFC 7671, RFC 7672)
+"2 0 1" or "2 1 1" records to specify root CA certificate digests,
+you must include the corresponding root CA certificates in the
+"server.pem" certificate file. </p>
+
+<blockquote>
+<pre>
+% <b>cat server_cert.pem intermediate_CA.pem root.pem &gt; server.pem</b>
+</pre>
+</blockquote>
+
+<p> Remote SMTP clients will be able to use the TLSA record you
+publish (which only contains the certificate digest) only if they
+have access to the corresponding certificate. Failure to verify
+certificates per the server's published TLSA records will typically
+cause the SMTP client to defer mail delivery. The foregoing also
+applies to "2 0 2" and "2 1 2" TLSA records or any other digest of
+a CA certificate, but it is expected that SHA256 will be by far the
+most common digest for TLSA. </p>
+
+<p> As a best practice, publish "3 1 1" TLSA associations that specify
+the SHA256 digest of the server's public key. These continue to work
+unmodified when a certificate is renewed with the same public/private
+key pair. </p>
+
+</ul>
+
+<p> For instructions on how to compute the digest of a certificate
+or its public key for use in TLSA records, see the documentation of
+the smtpd_tls_fingerprint_digest main.cf parameter. </p>
+
+<p> When a new key or certificate is generated, an additional TLSA
+record with the new digest must be published in advance of the
+actual deployment of the new key or certificate on the server. You
+must allow sufficient time for any TLSA RRsets with only the old
+digest to expire from DNS caches. The safest practice is to wait
+until the DNSSEC signature on the previous TLSA RRset expires, and
+only then switch the server to use new keys published in the updated
+TLSA RRset. Once the new certificate trust chain and private key
+are in effect, the DNS should be updated once again to remove the
+old digest from the TLSA RRset. </p>
+
+<p> If you want the Postfix SMTP server to accept remote SMTP client
+certificates issued by one or more root CAs, append the root
+certificate to $smtpd_tls_CAfile or install it in the $smtpd_tls_CApath
+directory. </p>
+
+<h4> Configuring the server certificate and key files </h4>
+
+<p> Example: Postfix &ge; 3.4 all-in-one chain file(s). One or more
+chain files that start with a key that is immediately followed by the
+corresponding certificate and any additional issuer certificates. A
+single file can hold multiple <i>(key, cert, [chain])</i> sequences, one
+per algorithm. It is typically simpler to keep the chain for each
+algorithm in its own file. Most users are likely to deploy just a
+single RSA chain, but with OpenSSL 1.1.1, it is possible to deploy up to
+five chains, one each for RSA, ECDSA, ED25519, ED448 and even the
+obsolete DSA. </p>
+
+<blockquote>
+<pre>
+ # Postfix &ge; 3.4. Preferred configuration interface. Each file
+ # starts with the private key, followed by the corresponding
+ # certificate, and any intermediate issuer certificates. The root CA
+ # cert may also be needed when published as a DANE trust anchor.
+ #
+ smtpd_tls_chain_files =
+ /etc/postfix/rsa.pem,
+ /etc/postfix/ecdsa.pem,
+ /etc/postfix/ed25519.pem,
+ /etc/postfix/ed448.pem
+</pre>
+</blockquote>
+
+<p> You can also store the keys separately from their certificates, again
+provided each is listed before the corresponding certificate chain. Storing a
+key and its associated certificate chain in separate files is not recommended,
+because this is prone to race conditions during key rollover, as there is no
+way to update multiple files atomically. </p>
+
+<blockquote>
+<pre>
+ # Postfix &ge; 3.4.
+ # Storing keys separately from the associated certificates is not
+ # recommended.
+ smtpd_tls_chain_files =
+ /etc/postfix/rsakey.pem,
+ /etc/postfix/rsacerts.pem,
+ /etc/postfix/ecdsakey.pem,
+ /etc/postfix/ecdsacerts.pem
+</pre>
+</blockquote>
+
+<p> The below examples show the legacy algorithm-specific configurations
+for Postfix 3.3 and older. With Postfix &le; 3.3, even if the key is
+stored in the same file as the certificate, the file is read twice and a
+(brief) race condition still exists during key rollover. While Postfix
+&ge; 3.4 avoids the race when the key and certificate are in the same
+file, you should use the new "smtpd_tls_chain_files" interface shown
+above. <p>
+
+<p> RSA key and certificate examples: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_cert_file = /etc/postfix/server.pem
+ smtpd_tls_key_file = $smtpd_tls_cert_file
+</pre>
+</blockquote>
+
+<p> Their DSA counterparts: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem
+ smtpd_tls_dkey_file = $smtpd_tls_dcert_file
+</pre>
+</blockquote>
+
+<p> Their ECDSA counterparts (Postfix &ge; 2.6 + OpenSSL &ge; 1.0.0): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ # Some clients will not be ECDSA capable, so you will likely still need
+ # an RSA certificate and private key.
+ #
+ smtpd_tls_eccert_file = /etc/postfix/server-ecdsa.pem
+ smtpd_tls_eckey_file = $smtpd_tls_eccert_file
+</pre>
+</blockquote>
+
+<p> TLS without certificates for servers serving exclusively
+anonymous-cipher capable clients: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ # Not recommended: breaks TLS 1.3 and clients that don't support
+ # anonymous cipher suites.
+ smtpd_tls_cert_file = none
+</pre>
+</blockquote>
+
+<p> To verify a remote SMTP client certificate, the Postfix SMTP
+server needs to trust the certificates of the issuing Certification
+Authorities. These certificates in "PEM" format can be stored in a
+single $smtpd_tls_CAfile or in multiple files, one CA per file in
+the $smtpd_tls_CApath directory. If you use a directory, don't forget
+to create the necessary "hash" links with: </p>
+
+<blockquote>
+<pre>
+# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
+</pre>
+</blockquote>
+
+<p> The $smtpd_tls_CAfile contains the CA certificates of one or
+more trusted CAs. The file is opened (with root privileges) before
+Postfix enters the optional chroot jail and so need not be accessible
+from inside the chroot jail. </p>
+
+<p> Additional trusted CAs can be specified via the $smtpd_tls_CApath
+directory, in which case the certificates are read (with $mail_owner
+privileges) from the files in the directory when the information
+is needed. Thus, the $smtpd_tls_CApath directory needs to be
+accessible inside the optional chroot jail. </p>
+
+<p> When you configure the Postfix SMTP server to request <a
+href="#server_vrfy_client">client certificates</a>, the DNs of Certification
+Authorities in $smtpd_tls_CAfile are sent to the client, in order to allow
+it to choose an identity signed by a CA you trust. If no $smtpd_tls_CAfile
+is specified, no preferred CA list is sent, and the client is free to
+choose an identity signed by any CA. Many clients use a fixed identity
+regardless of the preferred CA list and you may be able to reduce TLS
+negotiation overhead by installing client CA certificates mostly or
+only in $smtpd_tls_CApath. In the latter case you need not specify a
+$smtpd_tls_CAfile. </p>
+
+<p> Note, that unless client certificates are used to allow greater
+access to TLS authenticated clients, it is best to not ask for
+client certificates at all, as in addition to increased overhead
+some clients (notably in some cases qmail) are unable to complete
+the TLS handshake when client certificates are requested. </p>
+
+<p> Example: </p>
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_CAfile = /etc/postfix/CAcert.pem
+ smtpd_tls_CApath = /etc/postfix/certs
+</pre>
+</blockquote>
+
+<h3><a name="server_pfs"> Server-side forward-secrecy configuration </a> </h3>
+
+<p> If you want to take maximal advantage of ciphers that offer <a
+href="FORWARD_SECRECY_README.html#dfn_fs">forward secrecy</a> see
+the <a href="FORWARD_SECRECY_README.html#quick-start">Getting
+started</a> section of <a
+href="FORWARD_SECRECY_README.html">FORWARD_SECRECY_README</a>. The
+full document conveniently presents all information about Postfix
+forward secrecy support in one place: what forward secrecy is, how
+to tweak settings, and what you can expect to see when Postfix uses
+ciphers with forward secrecy. </p>
+
+<h3><a name="server_logging"> Server-side TLS activity logging </a> </h3>
+
+<p> To get additional information about Postfix SMTP server TLS
+activity you can increase the log level from 0..4. Each logging
+level also includes the information that is logged at a lower
+logging level. </p>
+
+<blockquote>
+
+<table border="1">
+
+<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier
+releases. </th> </tr>
+
+<tr> <td valign="top"> 0 </td> <td valign="top" colspan="2"> Disable
+logging of TLS activity. </td> </tr>
+
+<tr> <td valign="top"> 1 </td> <td valign="top"> Log only a summary
+message on TLS handshake completion &mdash; no logging of client
+certificate trust-chain verification errors if client certificate
+verification is not required. </td> <td valign="top"> Log the summary
+message, peer certificate summary information and unconditionally log
+trust-chain verification errors. </td> </tr>
+
+<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also
+log levels during TLS negotiation. </td> </tr>
+
+<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of TLS negotiation process. </td>
+</tr>
+
+<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of complete transmission after
+STARTTLS. </td></tr>
+
+</table>
+
+</blockquote>
+
+<p> Use log level 3 only in case of problems. Use of log level 4 is
+strongly discouraged. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_loglevel = 0
+</pre>
+</blockquote>
+
+<p> To include information about the protocol and cipher used as
+well as the client and issuer CommonName into the "Received:"
+message header, set the smtpd_tls_received_header variable to true.
+The default is no, as the information is not necessarily authentic.
+Only information recorded at the final destination is reliable,
+since the headers may be changed by intermediate servers. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_received_header = yes
+</pre>
+</blockquote>
+
+<h3><a name="server_enable">Enabling TLS in the Postfix SMTP server </a> </h3>
+
+<p> By default, TLS is disabled in the Postfix SMTP server, so no
+difference to plain Postfix is visible. Explicitly switch it on
+with "smtpd_tls_security_level = may". </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_security_level = may
+</pre>
+</blockquote>
+
+<p> With this, the Postfix SMTP server announces STARTTLS support to
+remote SMTP clients, but does not require that clients use TLS encryption.
+</p>
+
+<p> Note: when an unprivileged user invokes "sendmail -bs", STARTTLS
+is never offered due to insufficient privileges to access the Postfix
+SMTP server
+private key. This is intended behavior. </p>
+
+<p> <a name="server_enforce">You can ENFORCE the use of TLS</a>,
+so that the Postfix SMTP server announces STARTTLS and accepts no
+mail without TLS encryption, by setting
+"smtpd_tls_security_level = encrypt". According to RFC 2487 this
+MUST NOT be applied in case
+of a publicly-referenced Postfix SMTP server. This option is off
+by default and should only seldom be used. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_security_level = encrypt
+</pre>
+</blockquote>
+
+<p> TLS is sometimes used in the non-standard "wrapper" mode where
+a server always uses TLS, instead of announcing STARTTLS support
+and waiting for remote SMTP clients to request TLS service. Some
+clients, namely
+Outlook [Express] prefer the "wrapper" mode. This is true for OE
+(Win32 &lt; 5.0 and Win32 &gt;=5.0 when run on a port&lt;&gt;25
+and OE (5.01 Mac on all ports). </p>
+
+<p> It is strictly discouraged to use this mode from main.cf. If
+you want to support this service, enable a special port in master.cf
+and specify "-o smtpd_tls_wrappermode=yes" (note: no space around
+the "=") as an smtpd(8) command line option. Port 465 (smtps) was
+once chosen for this feature.
+</p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/master.cf:
+ smtps inet n - n - - smtpd
+ -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes
+</pre>
+</blockquote>
+
+<h3><a name="server_vrfy_client">Client certificate verification</a> </h3>
+
+<p> To receive a remote SMTP client certificate, the Postfix SMTP
+server must explicitly ask for one (any contents of $smtpd_tls_CAfile
+are also sent to the client as a hint for choosing a certificate from
+a suitable CA). Unfortunately, Netscape clients will either complain
+if no matching client certificate is available or will offer the user
+client a list of certificates to choose from. Additionally some MTAs
+(notably some versions of qmail) are unable to complete TLS negotiation
+when client certificates are requested, and abort the SMTP session. So
+this option is "off" by default. You will however need the certificate
+if you want to use certificate based relaying with, for example, the
+permit_tls_clientcerts feature. A server that wants client certificates
+must first present its own certificate. While Postfix by default
+offers anonymous ciphers to remote SMTP clients, these are automatically
+suppressed
+when the Postfix SMTP server is configured to ask for client
+certificates. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_ask_ccert = yes
+ smtpd_tls_security_level = may
+</pre>
+</blockquote>
+
+<p> When TLS is <a href="#server_enforce">enforced</a> you may also decide
+to REQUIRE a remote SMTP client certificate for all TLS connections,
+by setting "smtpd_tls_req_ccert = yes". This feature implies
+"smtpd_tls_ask_ccert = yes". When TLS is not enforced,
+"smtpd_tls_req_ccert = yes" is ignored and a warning is
+logged. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_req_ccert = yes
+ smtpd_tls_security_level = encrypt
+</pre>
+</blockquote>
+
+<p> The client certificate verification depth is specified with the
+main.cf smtpd_tls_ccert_verifydepth parameter. The default verification
+depth is 9 (the OpenSSL default), for compatibility with Postfix
+versions before 2.5 where smtpd_tls_ccert_verifydepth was ignored.
+When you configure trust in a
+root CA, it is not necessary to explicitly trust intermediary CAs signed
+by the root CA, unless $smtpd_tls_ccert_verifydepth is less than the
+number of CAs in the certificate chain for the clients of interest. With
+a verify depth of 1 you can only verify certificates directly signed
+by a trusted CA, and all trusted intermediary CAs need to be configured
+explicitly. With a verify depth of 2 you can verify clients signed by a
+root CA or a direct intermediary CA (so long as the client is correctly
+configured to supply its intermediate CA certificate). </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_ccert_verifydepth = 2
+</pre>
+</blockquote>
+
+<h3><a name="server_tls_auth">Supporting AUTH over TLS only</a></h3>
+
+<p> Sending AUTH data over an unencrypted channel poses a security
+risk. When TLS layer encryption is required
+("smtpd_tls_security_level = encrypt"), the Postfix SMTP server will
+announce and accept AUTH only after the TLS layer has been activated
+with STARTTLS. When TLS layer encryption is optional
+("smtpd_tls_security_level = may"), it may however still be useful
+to only offer AUTH when TLS is active. To maintain compatibility
+with non-TLS clients, the default is to accept AUTH without encryption.
+In order to change this behavior, set
+"smtpd_tls_auth_only = yes". </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_auth_only = no
+</pre>
+</blockquote>
+
+<h3><a name="server_tls_cache">Server-side TLS session cache</a> </h3>
+
+<p> The Postfix SMTP server and the remote SMTP client negotiate a
+session, which takes some computer time and network bandwidth. SSL
+protocol versions other than SSLv2 support resumption of cached
+sessions. Not only is this more CPU and bandwidth efficient, it
+also reduces latency as only one network round-trip is used to
+resume a session while it takes two round-trips to create a session
+from scratch. </p>
+
+<p> Since Postfix uses multiple smtpd(8) service processes, an
+in-memory cache is not sufficient for session re-use. Clients store
+at most one cached session per server and are very unlikely to
+repeatedly connect to the same server process. Thus session caching
+in the Postfix SMTP server generally requires a shared cache (an
+alternative available with Postfix &ge; 2.11 is described below).
+</p>
+
+<p> To share the session information between multiple
+smtpd(8) processes, a session cache database is used. You
+can specify any database type that can store objects of several
+kbytes and that supports the sequence operator. DBM databases are
+not suitable because they can only store small objects. The cache
+is maintained by the tlsmgr(8) process, so there is no problem with
+concurrent access. Session caching is highly recommended, because
+the cost of repeatedly negotiating TLS session keys is high.</p>
+
+<p> Starting with Postfix 2.11, linked with a compatible OpenSSL
+library (at least 0.9.8h, preferably 1.0.0 or later) the Postfix
+SMTP server supports RFC 5077 TLS session resumption without
+server-side state when the remote SMTP client also supports RFC
+5077. The session is encrypted by the server in a <i>session
+ticket</i> returned to client for storage. When a client sends a
+valid session ticket, the server decrypts it and resumes the session,
+provided neither the ticket nor the session have expired. This
+makes it possible to resume cached sessions without allocating space
+for a shared database on the server. Consequently, for Postfix
+&ge; 2.11 the smtpd_tls_session_cache_database parameter should
+generally be left empty. Session caching can be disabled by setting
+the session cache timeout to zero, otherwise the timeout must be
+at least 2 minutes and at most 100 days. </p>
+
+<p> Note, session tickets can only be negotiated if the client
+disables SSLv2 and does not use the legacy SSLv2 compatible HELLO
+message. This is true by default with the Postfix &ge; 2.6 SMTP
+client. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_session_cache_database = btree:/var/lib/postfix/smtpd_scache
+</pre>
+</blockquote>
+
+<p> Note: as of version 2.5, Postfix no longer uses root privileges
+when opening this file. The file should now be stored under the
+Postfix-owned data_directory. As a migration aid, an attempt to
+open the file under a non-Postfix directory is redirected to the
+Postfix-owned data_directory, and a warning is logged. </p>
+
+<p> Cached Postfix SMTP server session information expires after
+a certain amount of time. Postfix/TLS does not use the OpenSSL
+default of 300s, but a longer time of 3600sec (=1 hour). RFC 2246
+recommends a maximum of 24 hours. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_session_cache_timeout = 3600s
+</pre>
+</blockquote>
+
+<p> As of Postfix 2.11 this setting cannot exceed 100 days. If set
+&le; 0, session caching is disabled. If set to a positive value
+less than 2 minutes, the minimum value of 2 minutes is used instead. </p>
+
+<p> When the Postfix SMTP server does not save TLS sessions to an
+external cache database, client-side session caching is unlikely
+to be useful. To reduce waste of client resources, the Postfix SMTP server can
+be configured to not issue TLS session ids. By default the Postfix
+SMTP server always issues TLS session ids. This works around known
+interoperability issues with some MUAs, and prevents possible
+interoperability issues with other MTAs. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+ smtpd_tls_always_issue_session_ids = no
+</pre>
+</blockquote>
+
+<h3><a name="server_access">Server access control</a> </h3>
+
+<p> Postfix TLS support introduces three additional features for
+Postfix SMTP server access control: </p>
+
+<blockquote>
+
+<dl>
+
+<dt> permit_tls_clientcerts </dt> <dd> <p> Allow the remote SMTP
+client request if the client certificate fingerprint or certificate
+public key fingerprint (Postfix 2.9 and later) is listed in the
+client certificate table (see relay_clientcerts discussion below).
+</p> </dd>
+
+<dt> permit_tls_all_clientcerts </dt> <dd> <p> Allow the remote SMTP
+client request if the client certificate passes trust chain verification.
+Useful with private-label CAs that only issue certificates to trusted
+clients (and not otherwise). </p> </dd>
+
+<dt> check_ccert_access type:table</dt> <dd> <p> Use the remote
+SMTP client certificate fingerprint or public key fingerprint
+(Postfix 2.9 and later) as the lookup key for the specified access(5)
+table. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<p> The digest algorithm used to compute the client certificate
+fingerprints is specified with the main.cf smtpd_tls_fingerprint_digest
+parameter. The default is "md5", for compatibility with Postfix
+versions &lt; 2.5. </p>
+
+<p> The permit_tls_all_clientcerts feature must be used with caution,
+because it can result in too many access permissions. Use this
+feature only if a special CA issues the client certificates, and
+only if this CA is listed as trusted CA. If other CAs are trusted,
+any owner of a valid client certificate would be authorized.
+The permit_tls_all_clientcerts feature can be practical for a
+specially created email relay server. </p>
+
+<p> It is however recommended to stay with the permit_tls_clientcerts
+feature and list all certificates via $relay_clientcerts, as
+permit_tls_all_clientcerts does not permit any control when a
+certificate must no longer be used (e.g. an employee leaving). </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+# With Postfix 2.10 and later, the mail relay policy is
+# preferably specified under smtpd_relay_restrictions.
+/etc/postfix/main.cf:
+ smtpd_relay_restrictions =
+ permit_mynetworks
+ permit_tls_clientcerts
+ reject_unauth_destination
+</pre>
+
+<pre>
+# Older configurations combine relay control and spam control under
+# smtpd_recipient_restrictions. To use this example with Postfix &ge;
+# 2.10 specify "smtpd_relay_restrictions=".
+/etc/postfix/main.cf:
+ smtpd_recipient_restrictions =
+ permit_mynetworks
+ permit_tls_clientcerts
+ reject_unauth_destination
+ ...other rules...
+</pre>
+</blockquote>
+
+<p> Example: Postfix lookup tables are in the form of (key, value)
+pairs. Since we only need the key, the value can be chosen freely, e.g.
+the name of the user or host:</p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ relay_clientcerts = hash:/etc/postfix/relay_clientcerts
+
+/etc/postfix/relay_clientcerts:
+ D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home
+</pre>
+</blockquote>
+
+<p> To extract the public key fingerprint from an X.509 certificate,
+you need to extract the public key from the certificate and compute
+the appropriate digest of its DER (ASN.1) encoding. With OpenSSL
+the "-pubkey" option of the "x509" command extracts the public
+key always in "PEM" format. We pipe the result to another OpenSSL
+command that converts the key to DER and then to the "dgst" command
+to compute the fingerprint. </p>
+
+<p> The actual command to transform the key to DER format depends
+on the version of OpenSSL used. With OpenSSL 1.0.0 and later, the
+"pkey" command supports all key types. With OpenSSL 0.9.8 and
+earlier, the key type is always RSA (nobody uses DSA, and EC
+keys are not fully supported by 0.9.8), so the "rsa" command is
+used. </p>
+<blockquote>
+<pre>
+# OpenSSL 1.0 with all certificates and SHA-1 fingerprints.
+$ openssl x509 -in cert.pem -noout -pubkey |
+ openssl pkey -pubin -outform DER |
+ openssl dgst -sha1 -c
+(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58
+
+# OpenSSL 0.9.8 with RSA certificates and MD5 fingerprints.
+$ openssl x509 -in cert.pem -noout -pubkey |
+ openssl rsa -pubin -outform DER |
+ openssl dgst -md5 -c
+(stdin)= f4:62:60:f6:12:8f:d5:8d:28:4d:13:a7:db:b2:ff:50
+</pre>
+</blockquote>
+<p> Note: Postfix 2.9.0&ndash;2.9.5 computed the public key
+fingerprint incorrectly. To use public-key fingerprints, upgrade
+to Postfix 2.9.6 or later. </p>
+
+<h3><a name="server_cipher">Server-side cipher controls</a> </h3>
+
+<p> The Postfix SMTP server supports 5 distinct cipher grades as
+specified by the smtpd_tls_mandatory_ciphers configuration parameter,
+which determines the minimum cipher grade with mandatory TLS
+encryption. The default minimum cipher grade for mandatory TLS is
+"medium" which is essentially 128-bit encryption or better. The
+smtpd_tls_ciphers parameter (Postfix &ge; 2.6) controls the minimum
+cipher grade used with opportunistic TLS. Here, the default minimum
+cipher grade is "medium" for Postfix releases after the middle of
+2015, "export" for older Postfix releases. With Postfix &lt; 2.6,
+the minimum opportunistic TLS cipher grade is always "export". </p>
+
+<p> By default anonymous ciphers are enabled. They are automatically
+disabled when remote SMTP client certificates are requested. If
+clients are expected to always verify the Postfix SMTP
+server certificate you may want to disable anonymous ciphers
+by setting "smtpd_tls_mandatory_exclude_ciphers = aNULL" or
+"smtpd_tls_exclude_ciphers = aNULL", as appropriate. One can't force
+a remote SMTP client to check the server certificate, so excluding
+anonymous ciphers is generally unnecessary. </p>
+
+<p> With mandatory and opportunistic TLS encryption, the Postfix
+SMTP server by default disables SSLv2 and SSLv3 with Postfix releases
+after the middle of 2015; older releases only disable SSLv2 for
+mandatory TLS. The mandatory TLS protocol list is specified via the
+smtpd_tls_mandatory_protocols configuration parameter. The
+smtpd_tls_protocols parameter (Postfix &ge; 2.6)
+controls the SSL/TLS protocols used with opportunistic TLS. </p>
+
+<p> Note that the OpenSSL library only supports protocol exclusion
+(not inclusion). For this reason, Postfix can exclude only protocols
+that are known at the time the Postfix software is written. If new
+protocols are added to the OpenSSL library, they cannot be excluded
+without corresponding changes to the Postfix source code. </p>
+
+<p> For a server that is not a public Internet MX host, Postfix
+supports configurations with no <a href="#server_cert_key">server
+certificates</a> that use <b>only</b> the anonymous ciphers. This is
+enabled by explicitly setting "smtpd_tls_cert_file = none"
+and not specifying an smtpd_tls_dcert_file or smtpd_tls_eccert_file.
+Such configurations may not interoperate with some clients, and require
+that TLSv1.3 be explicitly disabled. Therefore, they are not
+recommended, it is better and simpler to just configure a suitable
+certificate. </p>
+
+<p> Example, MSA that requires TLSv1 or higher, not SSLv2 or SSLv3,
+with high grade ciphers: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_cert_file = /etc/postfix/cert.pem
+ smtpd_tls_key_file = /etc/postfix/key.pem
+ smtpd_tls_mandatory_ciphers = high
+ smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5
+ smtpd_tls_security_level = encrypt
+ # Preferred syntax with Postfix &ge; 2.5:
+ smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3
+ # Legacy syntax:
+ smtpd_tls_mandatory_protocols = TLSv1
+</pre>
+</blockquote>
+
+<p> With Postfix &ge; 3.4, specify instead a single file that holds the
+key followed by the corresponding certificate and any associated issuing
+certificates, leaving the "smtpd_tls_cert_file" and "smtpd_tls_key_file"
+and related DSA and ECDSA parameters empty. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_chain_files = /etc/postfix/rsachain.pem
+ smtpd_tls_cert_file =
+ smtpd_tls_key_file =
+ ...
+</pre>
+</blockquote>
+
+<p> If you want to take maximal advantage of ciphers that offer <a
+href="FORWARD_SECRECY_README.html#dfn_fs">forward secrecy</a> see
+the <a href="FORWARD_SECRECY_README.html#quick-start">Getting
+started</a> section of <a
+href="FORWARD_SECRECY_README.html">FORWARD_SECRECY_README</a>. The
+full document conveniently presents all information about Postfix
+forward secrecy support in one place: what forward secrecy is, how
+to tweak settings, and what you can expect to see when Postfix uses
+ciphers with forward secrecy. </p>
+
+<p> Postfix 2.8 and later, in combination with OpenSSL 0.9.7 and later
+allows TLS servers to preempt the TLS client's cipher-suite preference list.
+This is possible only with SSLv3 and later, as in SSLv2 the client
+chooses the cipher-suite from a list supplied by the server. </p>
+
+<p> By default, the OpenSSL server selects the client's most preferred
+cipher-suite that the server supports. With SSLv3 and later, the server
+may choose its own most preferred cipher-suite that is supported (offered)
+by the client. Setting "tls_preempt_cipherlist = yes" enables server
+cipher-suite preferences. The default OpenSSL behavior applies with
+"tls_preempt_cipherlist = no". </p>
+
+<p> While server cipher-suite selection may in some cases lead to
+a more secure or performant cipher-suite choice, there is some risk
+of interoperability issues. In the past, some SSL clients have
+listed lower priority ciphers that they did not implement correctly.
+If the server chooses a cipher that the client prefers less, it may
+select a cipher whose client implementation is flawed. Most notably
+Windows 2003 Microsoft Exchange servers have flawed implementations
+of DES-CBC3-SHA, which OpenSSL considers stronger than RC4-SHA.
+Enabling server cipher-suite selection may create interoperability
+issues with Windows 2003 Microsoft Exchange clients. </p>
+
+<h3><a name="server_misc"> Miscellaneous server controls</a> </h3>
+
+<p> The smtpd_starttls_timeout parameter limits the time of Postfix
+SMTP server write and read operations during TLS startup and shutdown
+handshake procedures. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_starttls_timeout = 300s
+</pre>
+</blockquote>
+
+<p> With Postfix 2.8 and later, the tls_disable_workarounds parameter
+specifies a list or bit-mask of default-enabled OpenSSL bug
+work-arounds to disable. This may be necessary if one of the
+work-arounds enabled by default in OpenSSL proves to pose a security
+risk, or introduces an unexpected interoperability issue. The list
+of enabled bug work-arounds is OpenSSL-release-specific. See the
+tls_disable_workarounds parameter documentation for the list of
+supported values.</p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_disable_workarounds = 0xFFFFFFFF
+ tls_disable_workarounds = CVE-2010-4180
+</pre>
+</blockquote>
+
+<p> With Postfix &ge; 2.11, the tls_ssl_options parameter specifies
+a list or bit-mask of OpenSSL options to enable. Specify one or
+more of the named options below, or a hexadecimal bitmask of options
+found in the ssl.h file corresponding to the run-time OpenSSL
+library. While it may be reasonable to turn off all bug workarounds
+(see above), it is not a good idea to attempt to turn on all features.
+See the tls_ssl_options parameter documentation for the list of
+supported values. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_ssl_options = no_ticket, no_compression
+</pre>
+</blockquote>
+
+<p> You should only enable features via the hexadecimal mask when
+the need to control the feature is critical (to deal with a new
+vulnerability or a serious interoperability problem). Postfix DOES
+NOT promise backwards compatible behavior with respect to the mask
+bits. A feature enabled via the mask in one release may be enabled
+by other means in a later release, and the mask bit will then be
+ignored. Therefore, use of the hexadecimal mask is only a temporary
+measure until a new Postfix or OpenSSL release provides a better
+solution. </p>
+
+<h2> <a name="client_tls">SMTP Client specific settings</a> </h2>
+
+<p> Topics covered in this section: </p>
+
+<ul>
+
+<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
+
+<li><a href="#client_logging"> Client-side TLS activity logging </a>
+
+<li><a href="#client_cert_key">Client-side certificate and private
+key configuration </a>
+
+<li><a href="#client_tls_reuse">Client-side TLS connection reuse</a>
+
+<li><a href="#client_tls_cache">Client-side TLS session cache</a>
+
+<li><a href="#client_tls_limits"> Client TLS limitations </a>
+
+<li><a href="#client_tls_policy"> Per-destination TLS policy </a>
+
+<li><a href="#client_tls_discover"> Discovering servers that support TLS </a>
+
+<li><a href="#client_vrfy_server">Server certificate verification depth</a>
+
+<li> <a href="#client_cipher">Client-side cipher controls </a>
+
+<li> <a href="#client_smtps">Client-side SMTPS support </a>
+
+<li> <a href="#client_misc"> Miscellaneous client controls </a>
+
+</ul>
+
+<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
+</h3>
+
+<p> Similar to the Postfix SMTP server, the Postfix SMTP/LMTP client
+implements multiple TLS security levels. These levels are described
+in more detail in the sections that follow.</p>
+
+<dl>
+<dt><b>none</b></dt>
+<dd><a href="#client_tls_none">No TLS.</a></dd>
+<dt><b>may</b></dt>
+<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd>
+<dt><b>encrypt</b></dt>
+<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a>
+<dt><b>dane</b></dt>
+<dd><a href="#client_tls_dane">Opportunistic DANE TLS.</a>
+<dt><b>dane-only</b></dt>
+<dd><a href="#client_tls_dane">Mandatory DANE TLS.</a>
+<dt><b>fingerprint</b></dt>
+<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a>
+<dt><b>verify</b></dt>
+<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a>
+<dt><b>secure</b></dt>
+<dd><a href="#client_tls_secure">Secure-channel TLS.</a>
+</dl>
+
+<h4><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a> </h4>
+
+<p> The smtp(8) and lmtp(8) delivery agents are implemented by a
+single dual-purpose program. Specifically, all the TLS features
+described below apply
+equally to SMTP and LMTP, after replacing the "smtp_" prefix of the each
+parameter name with "lmtp_".
+
+<p> The Postfix LMTP delivery agent can communicate with LMTP servers
+listening
+on UNIX-domain sockets. When server certificate verification is enabled
+and the server is listening on a UNIX-domain socket, the $myhostname
+parameter is used to set the TLS verification <i>nexthop</i> and
+<i>hostname</i>. </p>
+
+<p> NOTE: Opportunistic encryption of LMTP traffic over UNIX-domain
+sockets or loopback TCP connections is futile. TLS is only useful
+in this context when
+it is mandatory, typically to allow at least one of the server or the
+client to authenticate the other. The "null" cipher grade may be
+appropriate in this context, when available on both client and server.
+The "null" ciphers provide authentication without encryption. </p>
+
+<h4><a name="client_tls_none"> No TLS encryption </a> </h4>
+
+<p> At the "none" TLS security level, TLS encryption is
+disabled. This is the default security level, and
+can be configured explicitly by setting "smtp_tls_security_level = none".
+For LMTP, use the corresponding "lmtp_" parameter. </p>
+
+<p> Per-destination settings may override this default setting, in which case
+TLS is used selectively, only with destinations explicitly configured
+for TLS. </p>
+
+<p> You can disable TLS for a subset of destinations, while leaving
+it enabled for the rest. With the Postfix TLS <a
+href="#client_tls_policy">policy table</a>, specify the "none"
+security level.
+
+<h4><a name="client_tls_may"> Opportunistic TLS </a> </h4>
+
+<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>.
+The SMTP transaction is encrypted if the STARTTLS ESMTP feature
+is supported by the server. Otherwise, messages are sent in the clear.
+Opportunistic TLS can be configured by setting "smtp_tls_security_level = may".
+For LMTP, use the corresponding "lmtp_" parameter. </p>
+
+<p> The "smtp_tls_ciphers" and "smtp_tls_protocols" configuration
+parameters (Postfix &ge; 2.6) provide control over the cipher grade
+and protocols used with opportunistic TLS. With earlier Postfix
+releases, opportunistic TLS always uses the cipher grade "export"
+and enables all protocols. </p>
+
+<p> With opportunistic TLS, mail delivery continues even if the
+server certificate is untrusted or bears the wrong name.
+When the TLS handshake fails for an opportunistic
+TLS session, rather than give up on mail delivery, the Postfix SMTP
+client retries the transaction
+with TLS disabled. Trying an unencrypted connection makes
+it possible to deliver mail to sites with non-interoperable server
+TLS implementations. </p>
+
+<p> Opportunistic encryption is never used for LMTP over UNIX-domain
+sockets. The communications channel is already confidential without
+TLS, so the only potential benefit of TLS is authentication. Do not
+configure opportunistic TLS for LMTP deliveries over UNIX-domain sockets.
+Only configure TLS for LMTP over UNIX-domain sockets at the
+<a href="#client_tls_encrypt">encrypt</a> security level or higher.
+Attempts to configure opportunistic encryption of LMTP sessions will
+be ignored with a warning written to the mail logs. </p>
+
+<p> You can enable opportunistic TLS just for selected destinations. With
+the Postfix TLS <a href="#client_tls_policy">policy table</a>,
+specify the "may" security level. </p>
+
+<p> This is the most common security level for TLS protected SMTP
+sessions, stronger security is not generally available and, if needed,
+is typically only configured on a per-destination basis. See the section
+on TLS <a href="#client_tls_limits">limitations</a> above. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_security_level = may
+</pre>
+</blockquote>
+
+<h4><a name="client_tls_encrypt"> Mandatory TLS encryption </a> </h4>
+
+<p> At the "encrypt" TLS security level, messages are sent only
+over TLS encrypted sessions. The SMTP transaction is aborted unless
+the STARTTLS ESMTP feature is supported by the remote SMTP server.
+If no suitable
+servers are found, the message will be deferred.
+Mandatory TLS encryption can be configured by setting
+"smtp_tls_security_level = encrypt". Even though TLS
+encryption is always used, mail delivery continues even if the server
+certificate is untrusted or bears the wrong name.
+For LMTP, use the corresponding "lmtp_" parameter. </p>
+
+<p> At this security level and higher, the smtp_tls_mandatory_protocols
+and smtp_tls_mandatory_ciphers configuration parameters determine
+the list of sufficiently secure SSL protocol versions and the minimum
+cipher strength. If the protocol or cipher requirements are not
+met, the mail transaction is aborted. The documentation for these
+parameters includes useful interoperability and security guidelines.
+</p>
+
+<p> Despite the potential for eliminating passive eavesdropping attacks,
+mandatory TLS encryption is not viable as a default security level for
+mail delivery to the public Internet. Some MX hosts do not support TLS at
+all, and some of those that do have broken implementations. On a host
+that delivers mail to the Internet, you should not configure mandatory
+TLS encryption as the default security level. </p>
+
+<p> You can enable mandatory TLS encryption just for specific destinations.
+With the Postfix TLS <a href="#client_tls_policy">policy
+table</a>, specify the "encrypt" security level.
+</p>
+
+<p> Examples: </p>
+
+<p> In the example below, traffic to <i>example.com</i> and its sub-domains
+via the corresponding MX hosts always uses TLS. The SSLv2 protocol
+will be disabled (the default setting of smtp_tls_mandatory_protocols
+excludes SSLv2+3). Only high- or medium-strength (i.e. 128 bit or
+better) ciphers will be used by default for all "encrypt" security
+level sessions. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
+
+/etc/postfix/tls_policy:
+ example.com encrypt
+ .example.com encrypt
+</pre>
+</blockquote>
+
+<p> In the next example, secure message submission is configured
+via the MSA "<tt>[example.net]:587</tt>". TLS sessions are encrypted
+without authentication, because this MSA does not possess an acceptable
+certificate. This MSA is known to be capable of "TLSv1" and "high" grade
+ciphers, so these are selected via the <a href="#client_tls_policy">policy
+table</a>. </p>
+
+<p><b>Note:</b> the policy table lookup key is the verbatim next-hop
+specification from the recipient domain, transport(5) table or relayhost
+parameter, with any enclosing square brackets and optional port. Take
+care to be consistent: the suffixes ":smtp" or ":25" or no port suffix
+result in different policy table lookup keys, even though they are
+functionally equivalent nexthop specifications. Use at most one of these
+forms for all destinations. Below, the policy table has multiple keys,
+just in case the transport table entries are not specified consistently. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
+
+/etc/services:
+ submission 587/tcp msa # mail message submission
+
+/etc/postfix/tls_policy:
+ [example.net]:587 encrypt protocols=TLSv1 ciphers=high
+ [example.net]:msa encrypt protocols=TLSv1 ciphers=high
+ [example.net]:submission encrypt protocols=TLSv1 ciphers=high
+</pre>
+</blockquote>
+
+<h4><a name="client_tls_dane">DANE TLS authentication.</a> </h4>
+
+<p> The Postfix SMTP client supports two TLS security levels based
+on DANE TLSA (RFC 6698, RFC 7671, RFC 7672) records. The opportunistic
+"dane" level and the mandatory "dane-only" level. </p>
+
+<p> The "dane" level is a stronger form of <a
+href="#client_tls_may">opportunistic</a> TLS that is resistant to
+man in the middle and downgrade attacks when the destination domain
+uses DNSSEC to publish DANE TLSA records for its MX hosts. If a
+remote SMTP server has "usable" (see section 3 of RFC 7672) DANE
+TLSA records, the server connection will be authenticated. When
+DANE authentication fails, there is no fallback to unauthenticated
+or plaintext delivery. </p>
+
+<p> If TLSA records are published for a given remote SMTP server
+(implying TLS support), but are all "unusable" due to unsupported
+parameters or malformed data, the Postfix SMTP client will use <a
+href="#client_tls_encrypt">mandatory</a> unauthenticated TLS.
+Otherwise, when no TLSA records are published, the Postfix SMTP
+client behavior is the same as with <a href="#client_tls_may">may</a>. </p>
+
+<p> TLSA records must be published in DNSSEC validated DNS zones.
+Any TLSA records in DNS zones not protected via DNSSEC are ignored.
+The Postfix SMTP client will not look for TLSA records associated
+with MX hosts whose "A" or "AAAA" records lie in an "insecure" DNS
+zone. Such lookups have been observed to cause interoperability
+issues with poorly implemented DNS servers, and are in any case not
+expected to ever yield "secure" results, since that would require
+a very unlikely DLV DNS trust anchor configured between the host
+record and the associated "_25._tcp" child TLSA record. </p>
+
+<p> The "dane-only" level is a form of <a
+href="#client_tls_secure">secure-channel</a> TLS based on the DANE PKI.
+If "usable" TLSA records are present these are used to authenticate the
+remote SMTP server. Otherwise, or when server certificate verification
+fails, delivery via the server in question tempfails. </p>
+
+<p> At both security levels, the TLS policy for the destination is
+obtained via TLSA records validated with DNSSEC. For TLSA policy
+to be in effect, the destination domain's containing DNS zone must
+be signed and the Postfix SMTP client's operating system must be
+configured to send its DNS queries to a recursive DNS nameserver
+that is able to validate the signed records. Each MX host's DNS
+zone needs to also be signed, and needs to publish DANE TLSA (see
+section 3 of RFC 7672) records that specify how that MX host's TLS
+certificate is to be verified. </p>
+
+<p> TLSA records do not preempt the normal SMTP MX host
+selection algorithm, if some MX hosts support TLSA and others do
+not, TLS security will vary from delivery to delivery. It is up
+to the domain owner to configure their MX hosts and their DNS
+sensibly. To configure the Postfix SMTP client for DNSSEC lookups
+see the documentation for the smtp_dns_support_level main.cf
+parameter. The tls_dane_digests parameter controls the list of
+supported digests. </p>
+
+<p> As explained in section 3 of RFC 7672, certificate usages "0"
+and "1", which are intended to "constrain" existing Web-PKI trust,
+are not supported with MTA-to-MTA SMTP. Rather, TLSA records with
+usages "0" and "1" are treated as "unusable". </p>
+
+<p> The Postfix SMTP client supports only certificate usages "2"
+and "3". Experimental support for silently mapping certificate
+usage "1" to "3" has been withdrawn starting with Postfix 3.2. </p>
+
+<p> When usable TLSA records are obtained for the remote SMTP server
+the Postfix SMTP client sends the SNI TLS extension in its SSL
+client hello message. This may help the remote SMTP server live
+up to its promise to provide a certificate that matches its TLSA
+records. </p>
+
+<p> For purposes of protocol and cipher selection, the "dane"
+security level is treated like a "mandatory" TLS security level,
+and weak ciphers and protocols are disabled. Since DANE authenticates
+server certificates the "aNULL" cipher-suites are transparently
+excluded at this level, no need to configure this manually. RFC
+7672 (DANE) TLS authentication is available with Postfix 2.11 and
+later. </p>
+
+<p> When a DANE TLSA record specifies a trust-anchor (TA) certificate
+(that is an issuing CA), the strategy used to verify the peername
+of the server certificate is unconditionally "nexthop, hostname".
+Both the nexthop domain and the hostname obtained from the
+DNSSEC-validated MX lookup are safe from forgery and the server
+certificate must contain at least one of these names. </p>
+
+<p> When a DANE TLSA record specifies an end-entity (EE) certificate,
+(that is the actual server certificate), as with the fingerprint
+security level below, no name checks or certificate expiration checks
+are applied. The server certificate (or its public key) either matches
+the DANE record or not. Server administrators should publish such
+EE records in preference to all other types. </p>
+
+<p> The pre-requisites for DANE support in the Postfix SMTP client are: </p>
+<ul>
+<li> A <i>compile-time</i> OpenSSL library that supports the TLS SNI
+extension and "SHA-2" message digests.
+<li> A <i>compile-time</i> DNS resolver library that supports DNSSEC.
+Postfix binaries built on an older system will not support DNSSEC even
+if deployed on a system with an updated resolver library.
+<li> The "smtp_dns_support_level" must be set to "dnssec".
+<li> The "smtp_host_lookup" parameter must include "dns".
+<li> A DNSSEC-validating recursive resolver (see note below).
+</ul>
+<p> The above client pre-requisites do not apply to the Postfix SMTP server.
+It will support DANE provided it supports TLSv1 and its TLSA records are
+published in a DNSSEC signed zone. To receive DANE secured mail for multiple
+domains, use the same hostname to add the server to each domain's MX
+records. There are no plans to implement SNI in the Postfix SMTP server. </p>
+
+<p> Note: The Postfix SMTP client's internal stub DNS resolver is
+DNSSEC-aware, but it does not itself validate DNSSEC records, rather
+it delegates DNSSEC validation to the operating system's configured
+recursive DNS nameserver. The Postfix DNS client relies on a secure
+channel to the resolver's cache for DNSSEC integrity, but does not
+support TSIG to protect the transmission channel between itself and
+the nameserver. Therefore, it is strongly recommended (DANE security
+guarantee void otherwise) that each MTA run a local DNSSEC-validating
+recursive resolver ("unbound" from nlnetlabs.nl is a reasonable
+choice) listening on the loopback interface, and that the system
+be configured to use <i>only</i> this local nameserver. The local
+nameserver may forward queries to an upstream recursive resolver
+on another host if desired. </p>
+
+<p> Note: When the operating system's recursive nameserver is not
+local, enabling EDNS0 expanded DNS packet sizes and turning on the
+DNSSEC "DO" bit in the DNS request and/or the new DNSSEC-specific
+records returned in the nameserver's replies may cause problems
+with older or buggy firewall and DNS server implementations.
+Therefore, Postfix does not enable DNSSEC by default. Since MX
+lookups happen before the security level is determined, DANE support
+is disabled for all destinations unless you set "smtp_dns_support_level
+= dnssec". To enable DNSSEC lookups selectively, define a new
+dedicated transport with a "-o smtp_dns_support_level=dnssec"
+override in master.cf and route selected domains to that transport.
+If DNSSEC proves to be sufficiently reliable for these domains, you
+can enable it for all destinations by changing the global
+smtp_dns_support_level in main.cf. </p>
+
+<p><b>Example</b>: "dane" security for selected destinations, with
+opportunistic TLS by default. This is the recommended configuration
+for early adopters. <p>
+<ul>
+<li> <p> The "example.com" destination uses DANE, but if TLSA records
+are not present or are unusable, mail is deferred. </p>
+
+<li> <p> The "example.org" destination uses DANE if possible, but if no TLSA
+records are found opportunistic TLS is used. </p>
+</ul>
+
+<blockquote>
+<pre>
+main.cf:
+ indexed = ${default_database_type}:${config_directory}/
+ #
+ # default: Opportunistic TLS with no DNSSEC lookups.
+ #
+ smtp_tls_security_level = may
+ smtp_dns_support_level = enabled
+ #
+ # Per-destination TLS policy
+ #
+ smtp_tls_policy_maps = ${indexed}tls_policy
+ #
+ # default_transport = smtp, but some destinations are special:
+ #
+ transport_maps = ${indexed}transport
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+transport:
+ example.com dane
+ example.org dane
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+tls_policy:
+ example.com dane-only
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+master.cf:
+ dane unix - - n - - smtp
+ -o smtp_dns_support_level=dnssec
+ -o smtp_tls_security_level=dane
+</pre>
+</blockquote>
+
+<h4><a name="client_tls_fprint"> Certificate fingerprint verification </a> </h4>
+
+<p> At the <i>fingerprint</i> security level, no trusted Certification
+Authorities are used or required. The certificate trust chain,
+expiration date, etc., are not checked. Instead, the
+smtp_tls_fingerprint_cert_match parameter or the "match" attribute
+in the <a href="#client_tls_policy">policy</a> table lists the
+remote SMTP server certificate fingerprint or public key fingerprint.
+Certificate fingerprint verification is available with Postfix 2.5
+and later, public-key fingerprint support is available with Postfix
+2.9 and later. </p>
+
+<p> If certificate fingerprints are exchanged securely, this is the
+strongest, and least scalable security level. The administrator needs
+to securely collect the fingerprints of the X.509 certificates of each
+peer server, store them into a local file, and update this local file
+whenever the peer server's public certificate changes. If public key
+fingerprints are used in place of fingerprints of the entire certificate,
+the fingerprints remain valid even after the certificate is renewed,
+<b>provided</b> that the same public/private keys are used to obtain
+the new certificate. </p>
+
+<p> Fingerprint verification may be feasible for an SMTP "VPN" connecting
+a small number of branch offices over the Internet, or for secure
+connections to a central mail hub. It works poorly if the remote SMTP
+server is managed by a third party, and its public certificate changes
+periodically without prior coordination with the verifying site. </p>
+
+<p> The digest algorithm used to calculate the fingerprint is
+selected by the <b>smtp_tls_fingerprint_digest</b> parameter. In the <a
+href="#client_tls_policy">policy</a> table multiple fingerprints can be
+combined with a "|" delimiter in a single match attribute, or multiple
+match attributes can be employed. The ":" character is not used as a
+delimiter as it occurs between each pair of fingerprint (hexadecimal)
+digits. </p>
+
+<p> Example: fingerprint TLS security with an internal mailhub.
+Two matching fingerprints are listed. The relayhost may be multiple
+physical hosts behind a load-balancer, each with its own private/public
+key and self-signed certificate. Alternatively, a single relayhost may
+be in the process of switching from one set of private/public keys to
+another, and both keys are trusted just prior to the transition. </p>
+
+<blockquote>
+<pre>
+ relayhost = [mailhub.example.com]
+ smtp_tls_security_level = fingerprint
+ smtp_tls_fingerprint_digest = md5
+ smtp_tls_fingerprint_cert_match =
+ 3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1
+ EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35
+</pre>
+</blockquote>
+
+<p> Example: Certificate fingerprint verification with selected destinations.
+As in the example above, we show two matching fingerprints: </p>
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
+ smtp_tls_fingerprint_digest = md5
+</pre>
+</blockquote>
+<blockquote>
+<pre>
+/etc/postfix/tls_policy:
+ example.com fingerprint
+ match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1
+ match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35
+</pre>
+</blockquote>
+
+<p> To extract the public key fingerprint from an X.509 certificate,
+you need to extract the public key from the certificate and compute
+the appropriate digest of its DER (ASN.1) encoding. With OpenSSL
+the "-pubkey" option of the "x509" command extracts the public
+key always in "PEM" format. We pipe the result to another OpenSSL
+command that converts the key to DER and then to the "dgst" command
+to compute the fingerprint. </p>
+
+<p> The actual command to transform the key to DER format depends
+on the version of OpenSSL used. With OpenSSL 1.0.0 and later, the
+"pkey" command supports all key types. With OpenSSL 0.9.8 and
+earlier, the key type is always RSA (nobody uses DSA, and EC
+keys are not fully supported by 0.9.8), so the "rsa" command is
+used. </p>
+<blockquote>
+<pre>
+# OpenSSL 1.0 with all certificates and SHA-1 fingerprints.
+$ openssl x509 -in cert.pem -noout -pubkey |
+ openssl pkey -pubin -outform DER |
+ openssl dgst -sha1 -c
+(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58
+
+# OpenSSL 0.9.8 with RSA certificates and MD5 fingerprints.
+$ openssl x509 -in cert.pem -noout -pubkey |
+ openssl rsa -pubin -outform DER |
+ openssl dgst -md5 -c
+(stdin)= f4:62:60:f6:12:8f:d5:8d:28:4d:13:a7:db:b2:ff:50
+</pre>
+</blockquote>
+<p> Note: Postfix 2.9.0&ndash;2.9.5 computed the public key
+fingerprint incorrectly. To use public-key fingerprints, upgrade
+to Postfix 2.9.6 or later. </p>
+
+<h4><a name="client_tls_verify"> Mandatory server certificate verification </a> </h4>
+
+<p> At the <i>verify</i> TLS security level, messages are sent only over
+TLS encrypted sessions if the remote SMTP server certificate is
+valid (not
+expired or revoked, and signed by a trusted Certification Authority)
+and where the server certificate name matches a known pattern.
+Mandatory
+server certificate verification can be configured by setting
+"smtp_tls_security_level = verify". The
+smtp_tls_verify_cert_match parameter can override the default
+"hostname" certificate name matching strategy. Fine-tuning the
+matching strategy is generally only appropriate for <a
+href="#client_tls_secure">secure-channel</a> destinations.
+For LMTP use the corresponding "lmtp_" parameters. </p>
+
+<p> If the server certificate chain is trusted (see smtp_tls_CAfile
+and smtp_tls_CApath), any DNS names in the SubjectAlternativeName
+certificate extension are used to verify the remote SMTP server name.
+If no
+DNS names are specified, the certificate CommonName is checked.
+If you want mandatory encryption without server certificate
+verification, see <a href="#client_tls_encrypt">above</a>. </p>
+
+<p> With Postfix &ge; 2.11 the "smtp_tls_trust_anchor_file" parameter
+or more typically the corresponding per-destination "tafile" attribute
+optionally modifies trust chain verification. If the parameter is
+not empty the root CAs in CAfile and CApath are no longer trusted.
+Rather, the Postfix SMTP client will only trust certificate-chains
+signed by one of the trust-anchors contained in the chosen files.
+The specified trust-anchor certificates and public keys are not
+subject to expiration, and need not be (self-signed) root CAs. They
+may, if desired, be intermediate certificates. Therefore, these
+certificates also may be found "in the middle" of the trust chain
+presented by the remote SMTP server, and any untrusted issuing
+parent certificates will be ignored. </p>
+
+<p> Despite the potential for eliminating "man-in-the-middle" and other
+attacks, mandatory certificate trust chain and subject name verification
+is not viable as a default Internet mail delivery policy. Some MX hosts
+do not support TLS at all, and a significant portion of TLS-enabled
+MTAs use self-signed certificates, or certificates that are signed by
+a private Certification Authority. On a machine that delivers mail to
+the Internet, you should not configure mandatory server certificate
+verification as a default policy. </p>
+
+<p> Mandatory server certificate verification as a default security
+level may be appropriate if you know that you will only connect to
+servers that support RFC 2487 <i>and</i> that present verifiable
+server certificates. An example would be a client that sends all
+email to a central mailhub that offers the necessary STARTTLS
+support. In such cases, you can often use a <a
+href="#client_tls_secure">secure-channel</a> configuration instead.
+</p>
+
+<p> You can enable mandatory server certificate verification just
+for specific destinations. With the Postfix TLS <a
+href="#client_tls_policy">policy table</a>, specify the "verify"
+security level. </p>
+
+<p> Example: </p>
+
+<p> In this example, the Postfix SMTP client encrypts all traffic to the
+<i>example.com</i> domain. The peer hostname is verified, but
+verification is vulnerable to DNS response forgery. Mail transmission
+to <i>example.com</i> recipients uses "high" grade ciphers. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ indexed = ${default_database_type}:${config_directory}/
+ smtp_tls_CAfile = ${config_directory}/CAfile.pem
+ smtp_tls_policy_maps = ${indexed}tls_policy
+
+/etc/postfix/tls_policy:
+ example.com verify ciphers=high
+</pre>
+</blockquote>
+
+<h4><a name="client_tls_secure"> Secure server certificate verification </a> </h4>
+
+<p> At the <i>secure</i> TLS security level, messages are sent only over
+<i>secure-channel</i> TLS sessions where DNS forgery resistant server
+certificate verification succeeds. If no suitable servers are found, the
+message will be deferred. Postfix secure-channels
+can be configured by setting "smtp_tls_security_level = secure".
+The smtp_tls_secure_cert_match parameter can override the default
+"nexthop, dot-nexthop" certificate match strategy.
+For LMTP, use the corresponding "lmtp_" parameters. </p>
+
+<p> If the server certificate chain is trusted (see smtp_tls_CAfile and
+smtp_tls_CApath), any DNS names in the SubjectAlternativeName certificate
+extension are used to verify the remote SMTP server name. If no DNS names
+are
+specified, the CommonName is checked. If you want mandatory encryption
+without server certificate verification, see <a
+href="#client_tls_encrypt">above</a>. </p>
+
+<p> With Postfix &ge; 2.11 the "smtp_tls_trust_anchor_file" parameter
+or more typically the corresponding per-destination "tafile" attribute
+optionally modifies trust chain verification. If the parameter is
+not empty the root CAs in CAfile and CApath are no longer trusted.
+Rather, the Postfix SMTP client will only trust certificate-chains
+signed by one of the trust-anchors contained in the chosen files.
+The specified trust-anchor certificates and public keys are not
+subject to expiration, and need not be (self-signed) root CAs. They
+may, if desired, be intermediate certificates. Therefore, these
+certificates also may be found "in the middle" of the trust chain
+presented by the remote SMTP server, and any untrusted issuing
+parent certificates will be ignored. </p>
+
+<p> Despite the potential for eliminating "man-in-the-middle" and other
+attacks, mandatory secure server certificate verification is not
+viable as a default Internet mail delivery policy. Some MX hosts
+do not support TLS at all, and a significant portion of TLS-enabled
+MTAs use self-signed certificates, or certificates that are signed
+by a private Certification Authority. On a machine that delivers mail
+to the Internet, you should not configure secure TLS verification
+as a default policy. </p>
+
+<p> Mandatory secure server certificate verification as a default
+security level may be appropriate if you know that you will only
+connect to servers that support RFC 2487 <i>and</i> that present
+verifiable server certificates. An example would be a client that
+sends all email to a central mailhub that offers the necessary
+STARTTLS support. </p>
+
+<p> You can enable secure TLS verification just for specific destinations.
+With the Postfix TLS <a href="#client_tls_policy">policy table</a>,
+specify the "secure" security level. </p>
+
+<p> Examples: </p>
+
+<ul>
+
+<li> <p> Secure-channel TLS without transport(5) table overrides: </p>
+
+<p> The Postfix SMTP client will encrypt all traffic and verify the
+destination name
+immune from forged DNS responses. MX lookups are still used to find
+the hostnames of the SMTP servers for <i>example.com</i>, but these
+hostnames are not used when
+checking the names in the server certificate(s). Rather, the requirement
+is that the MX hosts for <i>example.com</i> have trusted certificates
+with a subject name of <i>example.com</i> or a sub-domain, see the
+documentation for the smtp_tls_secure_cert_match parameter. </p>
+
+<p> The related domains <i>example.co.uk</i> and <i>example.co.jp</i> are
+hosted on the same MX hosts as the primary <i>example.com</i> domain, and
+traffic to these is secured by verifying the primary <i>example.com</i>
+domain in the server certificates. This frees the server administrator
+from needing the CA to sign certificates that list all the secondary
+domains. The downside is that clients that want secure channels to the
+secondary domains need explicit TLS <a href="#client_tls_policy">policy
+table</a> entries. </p>
+
+<p> Note, there are two ways to handle related domains. The first is to
+use the default routing for each domain, but add policy table entries
+to override the expected certificate subject name. The second is to
+override the next-hop in the transport table, and use a single policy
+table entry for the common nexthop. We choose the first approach,
+because it works better when domain ownership changes. With the second
+approach we securely deliver mail to the wrong destination, with the
+first approach, authentication fails and mail stays in the local queue,
+the first approach is more appropriate in most cases. <p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_CAfile = /etc/postfix/CAfile.pem
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
+
+/etc/postfix/transport:
+
+/etc/postfix/tls_policy:
+ example.com secure
+ example.co.uk secure match=example.com:.example.com
+ example.co.jp secure match=example.com:.example.com
+</pre>
+</blockquote>
+
+<li> <p> Secure-channel TLS with transport(5) table overrides: <p>
+
+<p> In this case traffic to <i>example.com</i> and its related domains
+is sent to a single logical gateway (to avoid a single point of failure,
+its name may resolve to one or more load-balancer addresses, or to the
+combined addresses of multiple physical hosts). All the physical hosts
+reachable via the gateway's IP addresses have the logical gateway name
+listed in their certificates. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_CAfile = /etc/postfix/CAfile.pem
+ transport_maps = hash:/etc/postfix/transport
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
+
+/etc/postfix/transport:
+ example.com smtp:[tls.example.com]
+ example.co.uk smtp:[tls.example.com]
+ example.co.jp smtp:[tls.example.com]
+
+/etc/postfix/tls_policy:
+ [tls.example.com] secure match=tls.example.com
+</pre>
+</blockquote>
+
+</ul>
+
+<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>
+
+<p> To get additional information about Postfix SMTP client TLS
+activity you can increase the loglevel from 0..4. Each logging
+level also includes the information that is logged at a lower
+logging level. </p>
+
+<blockquote>
+
+<table border="1">
+
+<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier
+releases. </th> </tr>
+
+<tr> <td valign="top"> 0 </td> <td valign="top" colspan="2"> Disable
+logging of TLS activity. </td> </tr>
+
+<tr> <td valign="top"> 1 </td> <td valign="top"> Log only a summary
+message on TLS handshake completion &mdash; no logging of remote SMTP
+server certificate trust-chain verification errors if server certificate
+verification is not required. </td> <td valign="top"> Log the summary
+message and unconditionally log trust-chain verification errors.
+</td> </tr>
+
+<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also
+log levels during TLS negotiation. </td> </tr>
+
+<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of TLS negotiation process. </td>
+</tr>
+
+<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of complete transmission after
+STARTTLS. </td> </tr>
+
+</table>
+
+</blockquote>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_loglevel = 0
+</pre>
+</blockquote>
+
+<h3><a name="client_cert_key">Client-side certificate and private
+key configuration </a> </h3>
+
+<p> Do not configure Postfix SMTP client certificates unless you <b>must</b>
+present
+client TLS certificates to one or more servers. Client certificates are
+not usually needed, and can cause problems in configurations that work
+well without them. The recommended setting is to let the defaults stand: </p>
+
+<blockquote>
+<pre>
+ smtp_tls_cert_file =
+ smtp_tls_dcert_file =
+ smtp_tls_key_file =
+ smtp_tls_dkey_file =
+ # Postfix &ge; 2.6
+ smtp_tls_eccert_file =
+ smtp_tls_eckey_file =
+ # Postfix &ge; 3.4
+ smtp_tls_chain_files =
+</pre>
+</blockquote>
+
+<p> The best way to use the default settings is to comment out the above
+parameters in main.cf if present. </p>
+
+<p> During TLS startup negotiation the Postfix SMTP client may present a
+certificate to the remote SMTP server. Browsers typically let the user
+select among the certificates that match the CA names indicated by the
+remote SMTP server. The Postfix SMTP client does not yet have a mechanism
+to select from multiple candidate certificates on the fly, and supports a
+single set of certificates (at most one per public key algorithm). </p>
+
+<p> RSA, DSA and ECDSA (Postfix &ge; 2.6) certificates are supported.
+You can configure all three at the same time, in which case the
+cipher used determines which certificate is presented. </p>
+
+<p> It is possible for the Postfix SMTP client to use the same
+key/certificate pair as the Postfix SMTP server. If a certificate
+is to be presented, it must be in "PEM" format. The private key
+must not be encrypted, meaning: it must be accessible without
+password. Both parts (certificate and private key) may be in the
+same file. </p>
+
+<p> With OpenSSL 1.1.1 and Postfix &ge; 3.4 it is also possible to
+configure Ed25519 and Ed448 certificates. Rather than add two more
+pairs of key and certificate parameters, Postfix 3.4 introduces a new
+"smtp_tls_chain_files" parameter which specifies all the configured
+certificates at once, and handles files that hold both the key and the
+associated certificates in one pass, thereby avoiding potential race
+conditions during key rollover. </p>
+
+<p> To enable remote SMTP servers to verify the Postfix SMTP client
+certificate, the issuing CA certificates must be made available to the
+server. You should include the required certificates in the client
+certificate file, the client certificate first, then the issuing
+CA(s) (bottom-up order). </p>
+
+<p> Example: the certificate for "client.example.com" was issued by
+"intermediate CA" which itself has a certificate issued by "root CA".
+As the "root" super-user create the client.pem file with: </p>
+
+<blockquote>
+<pre>
+# <b>umask 077</b>
+# <b>cat client_key.pem client_cert.pem intermediate_CA.pem &gt; chain.pem </b>
+</pre>
+</blockquote>
+
+<p> A Postfix SMTP client certificate supplied here must be usable
+as SSL client certificate and hence pass the "openssl verify -purpose
+sslclient ..." test. </p>
+
+<p> A server that trusts the root CA has a local copy of the root
+CA certificate, so it is not necessary to include the root CA
+certificate here. Leaving it out of the "chain.pem" file reduces
+the overhead of the TLS exchange. </p>
+
+<p> If you want the Postfix SMTP client to accept remote SMTP server
+certificates issued by these CAs, append the root certificate to
+$smtp_tls_CAfile or install it in the $smtp_tls_CApath directory. </p>
+
+<p> Example: Postfix &ge; 3.4 all-in-one chain file(s). One or more
+chain files that start with a key that is immediately followed by the
+corresponding certificate and any additional issuer certificates. A
+single file can hold multiple <i>(key, cert, [chain])</i> sequences, one
+per algorithm. It is typically simpler to keep the chain for each
+algorithm in its own file. Most users are likely to deploy at most a
+single RSA chain, but with OpenSSL 1.1.1, it is possible to deploy up
+five chains, one each for RSA, ECDSA, ED25519, ED448 and even the
+obsolete DSA. </p>
+
+<blockquote>
+<pre>
+ # Postfix &ge; 3.4. Preferred configuration interface. Each file
+ # starts with the private key, followed by the corresponding
+ # certificate, and any intermediate issuer certificates.
+ #
+ smtp_tls_chain_files =
+ /etc/postfix/rsa.pem,
+ /etc/postfix/ecdsa.pem,
+ /etc/postfix/ed25519.pem,
+ /etc/postfix/ed448.pem
+</pre>
+</blockquote>
+
+<p> You can also store the keys separately from their certificates, again
+provided each is listed before the corresponding certificate chain. Storing a
+key and its associated certificate chain in separate files is not recommended,
+because this is prone to race conditions during key rollover, as there is no
+way to update multiple files atomically. </p>
+
+<blockquote>
+<pre>
+ # Postfix &ge; 3.4.
+ # Storing keys separately from the associated certificates is not
+ # recommended.
+ smtp_tls_chain_files =
+ /etc/postfix/rsakey.pem,
+ /etc/postfix/rsacerts.pem,
+ /etc/postfix/ecdsakey.pem,
+ /etc/postfix/ecdsacerts.pem
+</pre>
+</blockquote>
+
+<p> The below examples show the legacy algorithm-specific configurations
+for Postfix 3.3 and older. With Postfix &le; 3.3, even if the key is
+stored in the same file as the certificate, the file is read twice and a
+(brief) race condition still exists during key rollover. While Postfix
+&ge; 3.4 avoids the race when the key and certificate are in the same
+file, you should use the new "smtp_tls_chain_files" interface shown
+above. <p>
+
+<p> RSA key and certificate examples: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_cert_file = /etc/postfix/client.pem
+ smtp_tls_key_file = $smtp_tls_cert_file
+</pre>
+</blockquote>
+
+<p> Their DSA counterparts: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
+ smtp_tls_dkey_file = $smtp_tls_dcert_file
+</pre>
+</blockquote>
+
+<p> Their ECDSA counterparts (Postfix &ge; 2.6 + OpenSSL &ge; 1.0.0): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_eccert_file = /etc/postfix/client-ecdsa.pem
+ smtp_tls_eckey_file = $smtp_tls_eccert_file
+</pre>
+</blockquote>
+
+<p> To verify a remote SMTP server certificate, the Postfix SMTP
+client needs to trust the certificates of the issuing Certification
+Authorities. These certificates in "pem" format can be stored in a
+single $smtp_tls_CAfile or in multiple files, one CA per file in
+the $smtp_tls_CApath directory. If you use a directory, don't forget
+to create the necessary "hash" links with: </p>
+
+<blockquote>
+<pre>
+# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
+</pre>
+</blockquote>
+
+<p> The $smtp_tls_CAfile contains the CA certificates of one or more
+trusted CAs. The file is opened (with root privileges) before Postfix
+enters the optional chroot jail and so need not be accessible from inside the
+chroot jail. </p>
+
+<p> Additional trusted CAs can be specified via the $smtp_tls_CApath
+directory, in which case the certificates are read (with $mail_owner
+privileges) from the files in the directory when the information
+is needed. Thus, the $smtp_tls_CApath directory needs to be accessible
+inside the optional chroot jail. </p>
+
+<p> The choice between $smtp_tls_CAfile and $smtp_tls_CApath is
+a space/time tradeoff. If there are many trusted CAs, the cost of
+preloading them all into memory may not pay off in reduced access time
+when the certificate is needed. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_CAfile = /etc/postfix/CAcert.pem
+ smtp_tls_CApath = /etc/postfix/certs
+</pre>
+</blockquote>
+
+<h3><a name="client_tls_reuse">Client-side TLS connection reuse</a> </h3>
+
+<p> Historically, the Postfix SMTP client has supported multiple
+deliveries per plaintext connection. Postfix 3.4 introduces support
+for multiple deliveries per TLS-encrypted connection. Multiple
+deliveries per connection improve mail delivery performance,
+especially for destinations that throttle clients that don't combine
+deliveries. </p>
+
+<p> To enable multiple deliveries per TLS connection, specify:</p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_connection_reuse = yes
+</pre>
+</blockquote>
+
+<p> Alternatively, specify the attribute "connection_reuse=yes" in
+an smtp_tls_policy_maps entry. </p>
+
+<p> The implementation of TLS connection reuse relies on the same
+scache(8) service as used for delivering plaintext SMTP mail, the
+same tlsproxy(8) daemon as used by the postscreen(8) service, and
+relies on the same hints from the qmgr(8) daemon.
+
+See "<a href="CONNECTION_CACHE_README.html">Postfix Connection
+Cache</a>" for a description of the underlying connection reuse
+infrastructure. </p>
+
+<p> Initial SMTP handshake:</p>
+<pre> smtp(8) -&gt; remote SMTP server</pre>
+
+<p> Reused SMTP/TLS connection, or new SMTP/TLS connection: </p>
+<pre> smtp(8) -&gt; tlsproxy(8) -&gt; remote SMTP server </pre>
+
+<p> Cached SMTP/TLS connection:</p>
+<pre> scache(8) -&gt; tlsproxy(8) -&gt; remote SMTP server</pre>
+
+<p> As of Postfix 3.4, TLS connection reuse is disabled by default.
+This may change once the impact on over-all performance is understood.
+</p>
+
+<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>
+
+<p> The remote SMTP server and the Postfix SMTP client negotiate a
+session, which takes some computer time and network bandwidth. By
+default, this session information is cached only in the smtp(8)
+process actually using this session and is lost when the process
+terminates. To share the session information between multiple
+smtp(8) processes, a persistent session cache can be used. You
+can specify any database type that can store objects of several
+kbytes and that supports the sequence operator. DBM databases are
+not suitable because they can only store small objects. The cache
+is maintained by the tlsmgr(8) process, so there is no problem with
+concurrent access. Session caching is highly recommended, because
+the cost of repeatedly negotiating TLS session keys is high. Future
+Postfix SMTP servers may limit the number of sessions that a client
+is allowed to negotiate per unit time.</p>
+
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache
+</pre>
+</blockquote>
+
+<p> Note: as of version 2.5, Postfix no longer uses root privileges
+when opening this file. The file should now be stored under the
+Postfix-owned data_directory. As a migration aid, an attempt to
+open the file under a non-Postfix directory is redirected to the
+Postfix-owned data_directory, and a warning is logged. </p>
+
+<p> Cached Postfix SMTP client session information expires after
+a certain amount of time. Postfix/TLS does not use the OpenSSL
+default of 300s, but a longer time of 3600s (=1 hour). RFC 2246
+recommends a maximum of 24 hours. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_session_cache_timeout = 3600s
+</pre>
+</blockquote>
+
+<p> As of Postfix 2.11 this setting cannot exceed 100 days. If set
+&le; 0, session caching is disabled. If set to a positive value
+less than 2 minutes, the minimum value of 2 minutes is used instead. </p>
+
+<h3><a name="client_tls_limits"> Client TLS limitations </a>
+</h3>
+
+<p> The security properties of TLS communication channels are
+application specific. While the TLS protocol can provide a confidential,
+tamper-resistant, mutually authenticated channel between client
+and server, not all of these security features are applicable to every
+communication. </p>
+
+<p> For example, while mutual TLS authentication between browsers and web
+servers is possible, it is not practical, or even useful, for web-servers
+that serve the public to verify the identity of every potential user. In
+practice, most HTTPS transactions are asymmetric: the browser verifies
+the HTTPS server's identity, but the user remains anonymous. Much of
+the security policy is up to the client. If the client chooses to not
+verify the server's name, the server is not aware of this. There are many
+interesting browser security topics, but we shall not dwell
+on them here. Rather, our goal is to understand the security features
+of TLS in conjunction with SMTP. </p>
+
+<p> An important SMTP-specific observation is that a public MX host is
+even more at the mercy of the SMTP client than is an HTTPS server. Not only
+can it not enforce due care in the client's use of TLS, but it cannot even
+enforce the use of TLS, because TLS support in SMTP clients is still the
+exception rather than the rule. One cannot, in practice, limit access to
+one's MX hosts to just TLS-enabled clients. Such a policy would result
+in a vast reduction in one's ability to communicate by email with the
+world at large. </p>
+
+<p> One may be tempted to try enforcing TLS for mail from specific
+sending organizations, but this, too, runs into obstacles. One such
+obstacle is that we don't know who is (allegedly) sending mail until
+we see the "MAIL FROM:" SMTP command, and at that point, if TLS
+is not already in use, a potentially sensitive sender address (and
+with SMTP PIPELINING one or more of the recipients) has (have) already been
+leaked in the clear. Another obstacle is that mail from the sender to
+the recipient may be forwarded, and the forwarding organization may not
+have any security arrangements with the final destination. Bounces also
+need to be protected. These can only be identified by the IP address and
+HELO name of the connecting client, and it is difficult to keep track
+of all the potential IP addresses or HELO names of the outbound email
+servers of the sending organization. </p>
+
+<p> Consequently, TLS security for mail delivery to public MX hosts is
+almost entirely the client's responsibility. The server is largely a
+passive enabler of TLS security, the rest is up to the client. While the
+server has a greater opportunity to mandate client security policy when
+it is a dedicated MSA that only handles outbound mail from trusted clients,
+below we focus on the client security policy. </p>
+
+<p> On the SMTP client, there are further complications. When
+delivering mail to a given domain, in contrast to HTTPS, one rarely
+uses the domain name directly as the target host of the SMTP session.
+More typically, one uses MX lookups &mdash; these are usually
+unauthenticated &mdash; to obtain the domain's SMTP server hostname(s).
+When, as is current practice, the client verifies the insecurely
+obtained MX hostname, it is subject to a DNS man-in-the-middle
+attack. </p>
+
+<p> Adoption of DNSSEC and RFC6698 (DANE) may gradually (as domains
+implement DNSSEC and publish TLSA records for their MX hosts) address
+the DNS man-in-the-middle risk and provide scalable key management
+for SMTP with TLS. Postfix &ge; 2.11 supports the new <a
+href="#client_tls_dane">dane</a> and <a href="#client_tls_dane">dane-only</a>
+security levels that take advantage of these standards. </p>
+
+<p> If clients instead attempted to verify the recipient domain name,
+an SMTP server for multiple domains would need to
+list all its email domain names in its certificate, and generate a
+new certificate each time a new domain were added. At least some CAs set
+fairly low limits (20 for one prominent CA) on the number of names that
+server certificates can contain. This approach is not consistent with
+current practice and does not scale. </p>
+
+<p> It is regrettably the case that TLS <i>secure-channels</i>
+(fully authenticated and immune to man-in-the-middle attacks) impose
+constraints on the sending and receiving sites that preclude ubiquitous
+deployment. One needs to manually configure this type of security for
+each destination domain, and in many cases implement non-default TLS
+<a href="#client_tls_policy">policy table</a> entries for additional
+domains hosted at a common secured destination. For these reasons
+secure-channel configurations
+will never be the norm. For the generic domain with which you
+have made no specific security arrangements, this security level is not
+a good fit. </p>
+
+<p> Given that strong authentication is not generally possible, and that
+verifiable certificates cost time and money, many servers that implement
+TLS use self-signed certificates or private CAs. This further limits
+the applicability of verified TLS on the public Internet. </p>
+
+<p> Historical note: while the documentation of these issues and many of the
+related features were new with Postfix 2.3, the issue was well
+understood before Postfix 1.0, when Lutz J&auml;nicke was designing
+the first unofficial Postfix TLS patch. See his original post <a
+href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>
+and the first response <a
+href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.
+The problem is not even unique to SMTP or even TLS, similar issues exist
+for secure connections via aliases for HTTPS and Kerberos. SMTP merely
+uses indirect naming (via MX records) more frequently. </p>
+
+<h3> <a name="client_tls_policy"> TLS policy table </a>
+</h3>
+
+<p> A small fraction of servers offer STARTTLS but the negotiation
+consistently fails. As long as encryption is not mandatory, the
+Postfix SMTP client retries the delivery immediately with TLS
+disabled, without any need to explicitly disable TLS for the problem
+destinations. </p>
+
+<p> The policy table is specified via the smtp_tls_policy_maps
+parameter. This lists optional lookup tables with the Postfix SMTP client
+TLS security policy by next-hop destination. </p>
+
+<p> The TLS policy table is indexed by the full next-hop destination,
+which is either the recipient domain, or the verbatim next-hop
+specified in the transport table, $local_transport, $virtual_transport,
+$relay_transport or $default_transport. This includes any enclosing
+square brackets and any non-default destination server port suffix. The
+<a href="#client_lmtp_tls">LMTP</a> socket type prefix (inet: or unix:)
+is not included in the lookup key. </p>
+
+<p> Only the next-hop domain, or $myhostname with LMTP over UNIX-domain
+sockets, is used as the nexthop name for certificate verification. The
+port and any enclosing square brackets are used in the table lookup key,
+but are not used for server name verification. </p>
+
+<p> When the lookup key is a domain name without enclosing square brackets
+or any <i>:port</i> suffix (typically the recipient domain), and the full
+domain is not found in the table, just as with the transport(5) table,
+the parent domain starting with a leading "." is matched recursively. This
+allows one to specify a security policy for a recipient domain and all
+its sub-domains. </p>
+
+<p> The lookup result is a security level, followed by an optional
+list of whitespace and/or comma separated name=value attributes
+that override related main.cf settings. The TLS security <a
+href="#client_tls_levels">levels</a> are described above. Below, we
+describe the corresponding table syntax: </p>
+
+<dl>
+
+<dt><b>none</b></dt> <dd><a href="#client_tls_none">No TLS</a>. No
+additional attributes are supported at this level. </dd>
+
+<dt><b>may</b></dt> <dd><a href="#client_tls_may">Opportunistic TLS</a>.
+The optional "ciphers", "exclude" and "protocols" attributes
+(available for opportunistic TLS with Postfix &ge; 2.6) override the
+"smtp_tls_ciphers", "smtp_tls_exclude_ciphers" and "smtp_tls_protocols"
+configuration parameters. At this level and higher, the optional
+"servername" attribute (available with Postfix &ge; 3.4) overrides the
+global "smtp_tls_servername" parameter, enabling per-destination
+configuration of the SNI extension sent to the remote SMTP server. </dd>
+
+<dt><b>encrypt</b></dt> <dd><a href="#client_tls_encrypt"> Mandatory encryption</a>.
+Mail is delivered only if the remote SMTP server offers STARTTLS
+and the TLS handshake succeeds. At this level and higher, the optional
+"protocols" attribute overrides the main.cf smtp_tls_mandatory_protocols
+parameter, the optional "ciphers" attribute overrides the
+main.cf smtp_tls_mandatory_ciphers parameter, and the optional
+"exclude" attribute (Postfix &ge; 2.6) overrides the main.cf
+smtp_tls_mandatory_exclude_ciphers parameter. </dd>
+
+<dt><b>dane</b></dt> <dd><a href="#client_tls_dane">Opportunistic DANE TLS</a>.
+The TLS policy for the destination is obtained via TLSA records in
+DNSSEC. If no TLSA records are found, the effective security level
+used is <a href="#client_tls_may">may</a>. If TLSA records are
+found, but none are usable, the effective security level is <a
+href="#client_tls_encrypt">encrypt</a>. When usable TLSA records
+are obtained for the remote SMTP server, SSLv2+3 are automatically
+disabled (see smtp_tls_mandatory_protocols), and the server certificate
+must match the TLSA records. RFC 7672 (DANE) TLS authentication
+and DNSSEC support is available with Postfix 2.11 and later. </dd>
+
+<dt><b>dane-only</b></dt> <dd><a href="#client_tls_dane">Mandatory DANE TLS</a>.
+The TLS policy for the destination is obtained via TLSA records in
+DNSSEC. If no TLSA records are found, or none are usable, no
+connection is made to the server. When usable TLSA records are
+obtained for the remote SMTP server, SSLv2+3 are automatically disabled
+(see smtp_tls_mandatory_protocols), and the server certificate must
+match the TLSA records. RFC 7672 (DANE) TLS authentication and
+DNSSEC support is available with Postfix 2.11 and later. </dd>
+
+<dt><b>fingerprint</b></dt> <dd><a href="#client_tls_fprint">Certificate
+fingerprint verification.</a> Available with Postfix 2.5 and
+later. At this security level, there are no trusted Certification
+Authorities. The certificate trust chain, expiration date, ... are
+not checked. Instead, the optional <b>match</b> attribute, or else
+the main.cf <b>smtp_tls_fingerprint_cert_match</b> parameter, lists
+the server certificate fingerprints or public key fingerprints
+(Postfix 2.9 and later). The
+digest algorithm used to calculate fingerprints is selected by the
+<b>smtp_tls_fingerprint_digest</b> parameter. Multiple fingerprints can
+be combined with a "|" delimiter in a single match attribute, or multiple
+match attributes can be employed. The ":" character is not used as a
+delimiter as it occurs between each pair of fingerprint (hexadecimal)
+digits. </dd>
+
+<dt><b>verify</b></dt> <dd><a href="#client_tls_verify">Mandatory
+server certificate verification</a>. Mail is delivered only if the
+TLS handshake succeeds, if the remote SMTP server certificate can
+be validated (not expired or revoked, and signed by a trusted
+Certification Authority), and if the server certificate name matches
+the optional "match" attribute (or the main.cf smtp_tls_verify_cert_match
+parameter value when no optional "match" attribute is specified).
+With Postfix &ge; 2.11 the "tafile" attribute optionally modifies
+trust chain verification in the same manner as the
+"smtp_tls_trust_anchor_file" parameter. The "tafile" attribute
+may be specified multiple times to load multiple trust-anchor
+files. </dd>
+
+<dt><b>secure</b></dt> <dd><a href="#client_tls_secure">Secure certificate
+verification.</a> Mail is delivered only if the TLS handshake succeeds,
+if the remote SMTP server certificate can be validated (not expired
+or revoked, and signed by a trusted Certification Authority), and if the
+server certificate name matches the optional "match" attribute (or the
+main.cf smtp_tls_secure_cert_match parameter value when no optional
+"match" attribute is specified). With Postfix &ge; 2.11 the "tafile"
+attribute optionally modifies trust chain verification in the same manner
+as the "smtp_tls_trust_anchor_file" parameter. The "tafile" attribute
+may be specified multiple times to load multiple trust-anchor
+files. </dd>
+
+</dl>
+
+<p> Notes: </p>
+
+<ul>
+
+<li> <p> The "match" attribute is especially useful to verify TLS
+certificates for domains that are hosted on a shared server. In
+that case, specify "match" rules for the shared server's name.
+While secure verification can also be achieved with manual routing
+overrides in Postfix transport(5) tables, that approach can deliver
+mail to the wrong host when domains are assigned to new gateway
+hosts. The "match" attribute approach avoids the problems of manual
+routing overrides; mail is deferred if verification of a new MX
+host fails. </p>
+
+<li> <p> When a policy table entry specifies multiple match patterns,
+multiple match strategies, or multiple protocols, these must be
+separated by colons. </p>
+
+<li> <p> The "exclude" attribute (Postfix &ge; 2.6) is used to disable
+ciphers that cause handshake failures with a specific mandatory TLS
+destination, without disabling the ciphers for all mandatory destinations.
+Alternatively, you can exclude ciphers that cause issues with multiple
+remote servers in main.cf, and selectively enable them on a per-destination
+basis in the policy table by setting a shorter or empty exclusion list. The
+per-destination "exclude" list preempts both the opportunistic and
+mandatory security level exclusions, so that all excluded ciphers
+can be enabled for known-good destinations. For non-mandatory TLS
+destinations that exhibit cipher-specific problems, Postfix will fall
+back to plain-text delivery. If plain-text is not acceptable make TLS
+mandatory and exclude the problem ciphers. </p>
+
+</ul>
+
+<p>
+Example:
+</p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
+ # Postfix 2.5 and later
+ smtp_tls_fingerprint_digest = md5
+/etc/postfix/tls_policy:
+ example.edu none
+ example.mil may
+ example.gov encrypt ciphers=high
+ example.com verify match=hostname:dot-nexthop ciphers=high
+ example.net secure
+ .example.net secure match=.example.net:example.net
+ [mail.example.org]:587 secure match=nexthop
+ # Postfix 2.5 and later
+ [thumb.example.org] fingerprint
+ match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35
+ match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1
+ # Postfix 2.6 and later
+ example.info may protocols=!SSLv2 ciphers=medium exclude=3DES
+</pre>
+</blockquote>
+
+<p> <b>Note:</b> The "hostname" strategy if listed in a non-default setting
+of smtp_tls_secure_cert_match or in the "match" attribute in the policy
+table can render the "secure" level vulnerable to DNS forgery. Do not use
+the "hostname" strategy for <a href="#client_tls_secure">secure-channel</a>
+configurations in environments where DNS security is not assured. </p>
+
+<h3> <a name="client_tls_discover"> Discovering servers that support
+TLS </a> </h3>
+
+<p> As we decide on a "per site" basis whether or not to use TLS,
+it would be good to have a list of sites that offered "STARTTLS".
+We can collect it ourselves with this option. </p>
+
+<p> If the smtp_tls_note_starttls_offer feature is enabled and a
+server offers STARTTLS while TLS is not already enabled for that
+server, the Postfix SMTP client logs a line as follows: </p>
+
+<blockquote>
+<pre>
+postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com]
+</pre>
+</blockquote>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_note_starttls_offer = yes
+</pre>
+</blockquote>
+
+<h3><a name="client_vrfy_server">Server certificate verification depth</a> </h3>
+
+<p> The server certificate verification depth is specified with the
+main.cf smtp_tls_scert_verifydepth parameter. The default verification
+depth is 9 (the OpenSSL default), for compatibility with Postfix
+versions before 2.5 where smtp_tls_scert_verifydepth was ignored.
+When you configure trust
+in a root CA, it is not necessary to explicitly trust intermediary CAs
+signed by the root CA, unless $smtp_tls_scert_verifydepth is less than the
+number of CAs in the certificate chain for the servers of interest. With
+a verify depth of 1 you can only verify certificates directly signed
+by a trusted CA, and all trusted intermediary CAs need to be configured
+explicitly. With a verify depth of 2 you can verify servers signed by a
+root CA or a direct intermediary CA (so long as the server is correctly
+configured to supply its intermediate CA certificate). </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_scert_verifydepth = 2
+</pre>
+</blockquote>
+
+<h3> <a name="client_cipher">Client-side cipher controls </a> </h3>
+
+<p> The Postfix SMTP client supports 5 distinct cipher grades
+as specified by the smtp_tls_mandatory_ciphers configuration
+parameter. This setting controls the minimum acceptable SMTP client
+TLS cipher grade for use with mandatory TLS encryption. The default
+value "medium" is suitable for most destinations with which you may
+want to enforce TLS, and is beyond the reach of today's cryptanalytic
+methods. See smtp_tls_policy_maps for information on how to configure
+ciphers on a per-destination basis. </p>
+
+<p> By default anonymous ciphers are allowed, and automatically
+disabled when remote SMTP server certificates are verified. If you
+want to
+disable anonymous ciphers even at the "encrypt" security level, set
+"smtp_tls_mandatory_exclude_ciphers = aNULL"; and to
+disable anonymous ciphers even with opportunistic TLS, set
+"smtp_tls_exclude_ciphers = aNULL". There is generally
+no need to take these measures. Anonymous ciphers save bandwidth
+and TLS session cache space, if certificates are ignored, there is
+little point in requesting them. </p>
+
+<p> The "smtp_tls_ciphers" configuration parameter (Postfix &ge; 2.6)
+provides control over the minimum cipher grade for opportunistic TLS.
+The default minimum cipher grade for opportunistic TLS is "medium"
+for Postfix releases after the middle of 2015, and "export" for
+older releases. With Postfix &lt; 2.6, the minimum opportunistic
+TLS cipher grade is always "export". </p>
+
+<p> With mandatory and opportunistic TLS encryption, the Postfix
+SMTP client will by default disable SSLv2 and SSLv3. The mandatory
+TLS protocol list is specified via the
+smtp_tls_mandatory_protocols configuration parameter. The corresponding
+smtp_tls_protocols parameter (Postfix &ge; 2.6) controls
+the SSL/TLS protocols used with opportunistic TLS. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_mandatory_ciphers = medium
+ smtp_tls_mandatory_exclude_ciphers = RC4, MD5
+ smtp_tls_exclude_ciphers = aNULL
+ # Preferred form with Postfix &ge; 2.5:
+ smtp_tls_mandatory_protocols = !SSLv2
+ # Legacy form for Postfix &lt; 2.5:
+ smtp_tls_mandatory_protocols = SSLv3, TLSv1
+ # Also available with Postfix &ge; 2.6:
+ smtp_tls_ciphers = medium
+ smtp_tls_protocols = !SSLv2
+</pre>
+</blockquote>
+
+<h3> <a name="client_smtps">Client-side SMTPS support </a> </h3>
+
+<p> These sections show how to send mail to a server that does not
+support STARTTLS, but that provides the deprecated SMTPS service
+on TCP port 465. Depending on the Postfix version, some additional
+tooling may be required. </p>
+
+<h4> Postfix &ge; 3.0 </h4>
+
+<p> The Postfix SMTP client has SMTPS support built-in as of version
+3.0. Use one of the following examples, to send all remote mail,
+or to send only some remote mail, to an SMTPS server. </p>
+
+<h5> Postfix &ge; 3.0: Sending all remote mail to an SMTPS server </h5>
+
+<p> The first example will send all remote mail over SMTPS through
+a provider's server called "mail.example.com": </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ # Client-side SMTPS requires "encrypt" or stronger.
+ smtp_tls_security_level = encrypt
+ smtp_tls_wrappermode = yes
+ # The [] suppress MX lookups.
+ relayhost = [mail.example.com]:465
+</pre>
+</blockquote>
+
+<p> Use "postfix reload" to make the change effective. </p>
+
+<p> See SOHO_README for additional information about SASL authentication.
+</p>
+
+<h5> Postfix &ge; 3.0: Sending only mail for a specific destination
+via SMTPS </h5>
+
+<p> The second example will send only mail for "example.com" via
+SMTPS. This time, Postfix uses a transport map to deliver only
+mail for "example.com" via SMTPS: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ transport_maps = hash:/etc/postfix/transport
+
+/etc/postfix/transport:
+ example.com relay-smtps:example.com:465
+
+/etc/postfix/master.cf:
+ relay-smtps unix - - n - - smtp
+ # Client-side SMTPS requires "encrypt" or stronger.
+ -o smtp_tls_security_level=encrypt
+ -o smtp_tls_wrappermode=yes
+</pre>
+</blockquote>
+
+<p> Use "postmap hash:/etc/postfix/transport" and "postfix reload"
+to make the change effective. </p>
+
+<p> See SOHO_README for additional information about SASL
+authentication. </p>
+
+<h4> Postfix &lt; 3.0 </h4>
+
+<p> Although older Postfix SMTP client versions do not support TLS
+wrapper mode, it is relatively easy to forward a connection through
+the stunnel program if Postfix needs to deliver mail to some legacy
+system that doesn't support STARTTLS. </p>
+
+<h5> Postfix &lt; 3.0: Sending all remote mail to an SMTPS server </h5>
+
+<p> The first example uses SMTPS to send all remote mail to a
+provider's mail server called "mail.example.com". </p>
+
+<p> A minimal stunnel.conf file is sufficient to set up a tunnel
+from local port 11125 to the remote destination "mail.example.com"
+and port "smtps". Postfix will later use this tunnel to connect to
+the remote server. </p>
+
+<blockquote>
+<pre>
+/path/to/stunnel.conf:
+ [smtp-tls-wrapper]
+ accept = 11125
+ client = yes
+ connect = mail.example.com:smtps
+</pre>
+</blockquote>
+
+<p> To test this tunnel, use: </p>
+
+<blockquote>
+<pre>
+$ telnet localhost 11125
+</pre>
+</blockquote>
+
+<p> This should produce the greeting from the remote SMTP server
+at mail.example.com. </p>
+
+<p> On the Postfix side, the relayhost feature sends all remote
+mail through the local stunnel listener on port 11125: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ relayhost = [127.0.0.1]:11125
+</pre>
+</blockquote>
+
+<p> Use "postfix reload" to make the change effective. </p>
+
+<p> See SOHO_README for additional information about SASL
+authentication. </p>
+
+<h4> Postfix &lt; 3.0: Sending only mail for a specific destination via SMTPS </h4>
+
+<p> The second example will use SMTPS to send only mail for
+"example.com" via SMTPS. It uses the same stunnel configuration
+file as the first example, so it won't be repeated here. </p>
+
+<p> This time, the Postfix side uses a transport map to direct only
+mail for "example.com" through the tunnel: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ transport_maps = hash:/etc/postfix/transport
+
+/etc/postfix/transport:
+ example.com relay:[127.0.0.1]:11125
+</pre>
+</blockquote>
+
+<p> Use "postmap hash:/etc/postfix/transport" and "postfix reload"
+to make the change effective. </p>
+
+<p> See SOHO_README for additional information about SASL authentication.
+</p>
+
+<h3> <a name="client_misc"> Miscellaneous client controls </a> </h3>
+
+<p> The smtp_starttls_timeout parameter limits the time of Postfix
+SMTP client write and read operations during TLS startup and shutdown
+handshake procedures. In case of problems the Postfix SMTP client
+tries the next network address on the mail exchanger list, and
+defers delivery if no alternative server is available. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_starttls_timeout = 300s
+</pre>
+</blockquote>
+
+<p> With Postfix 2.8 and later, the tls_disable_workarounds parameter
+specifies a list or bit-mask of OpenSSL bug work-arounds to disable. This
+may be necessary if one of the work-arounds enabled by default in
+OpenSSL proves to pose a security risk, or introduces an unexpected
+interoperability issue. Some bug work-arounds known to be problematic
+are disabled in the default value of the parameter when linked with
+an OpenSSL library that could be vulnerable. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_disable_workarounds = 0xFFFFFFFF
+ tls_disable_workarounds = CVE-2010-4180, LEGACY_SERVER_CONNECT
+</pre>
+</blockquote>
+
+<p> Note: Disabling LEGACY_SERVER_CONNECT is not wise at this
+time, lots of servers are still unpatched and Postfix is <a
+href="http://www.postfix.org/wip.html#tls-renegotiation">not
+significantly vulnerable</a> to the renegotiation issue in the TLS
+protocol. </p>
+
+<p> With Postfix &ge; 2.11, the tls_ssl_options parameter specifies
+a list or bit-mask of OpenSSL options to enable. Specify one or
+more of the named options below, or a hexadecimal bitmask of options
+found in the ssl.h file corresponding to the run-time OpenSSL
+library. While it may be reasonable to turn off all bug workarounds
+(see above), it is not a good idea to attempt to turn on all features.
+</p>
+
+<p> A future version of OpenSSL may by default no longer allow
+connections to servers that don't support secure renegotiation.
+Since the exposure for SMTP is minimal, and some SMTP servers may
+remain unpatched, you can add LEGACY_SERVER_CONNECT to the
+options to restore the more permissive default of current OpenSSL
+releases. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_ssl_options = NO_TICKET, NO_COMPRESSION, LEGACY_SERVER_CONNECT
+</pre>
+</blockquote>
+
+<p> You should only enable features via the hexadecimal mask when
+the need to control the feature is critical (to deal with a new
+vulnerability or a serious interoperability problem). Postfix DOES
+NOT promise backwards compatible behavior with respect to the mask
+bits. A feature enabled via the mask in one release may be enabled
+by other means in a later release, and the mask bit will then be
+ignored. Therefore, use of the hexadecimal mask is only a temporary
+measure until a new Postfix or OpenSSL release provides a better
+solution. </p>
+
+<h2><a name="tlsmgr_controls"> TLS manager specific settings </a> </h2>
+
+<p> The security of cryptographic software such as TLS depends
+critically on the ability to generate unpredictable numbers for
+keys and other information. To this end, the tlsmgr(8) process
+maintains a Pseudo Random Number Generator (PRNG) pool. This is
+queried by the smtp(8) and smtpd(8) processes when they initialize.
+By default, these daemons request 32 bytes, the equivalent to 256
+bits. This is more than sufficient to generate a 128bit (or 168bit)
+session key. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_daemon_random_bytes = 32
+</pre>
+</blockquote>
+
+<p> In order to feed its in-memory PRNG pool, the tlsmgr(8) reads
+entropy from an external source, both at startup and during run-time.
+Specify a good entropy source, like EGD or /dev/urandom; be sure
+to only use non-blocking sources (on OpenBSD, use /dev/arandom
+when tlsmgr(8) complains about /dev/urandom timeout errors).
+If the entropy source is not a
+regular file, you must prepend the source type to the source name:
+"dev:" for a device special file, or "egd:" for a source with EGD
+compatible socket interface. </p>
+
+<p> Examples (specify only one in main.cf): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_random_source = dev:/dev/urandom
+ tls_random_source = egd:/var/run/egd-pool
+</pre>
+</blockquote>
+
+<p> By default, tlsmgr(8) reads 32 bytes from the external entropy
+source at each seeding event. This amount (256bits) is more than
+sufficient for generating a 128bit symmetric key. With EGD and
+device entropy sources, the tlsmgr(8) limits the amount of data
+read at each step to 255 bytes. If you specify a regular file as
+entropy source, a larger amount of data can be read. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_random_bytes = 32
+</pre>
+</blockquote>
+
+<p> In order to update its in-memory PRNG pool, the tlsmgr(8)
+queries the external entropy source again after a pseudo-random
+amount of time. The time is calculated using the PRNG, and is
+between 0 and the maximal time specified with tls_random_reseed_period.
+The default maximal time interval is 1 hour. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_random_reseed_period = 3600s
+</pre>
+</blockquote>
+
+<p> The tlsmgr(8) process saves the PRNG state to a persistent
+exchange file at regular times and when the process terminates, so
+that it can recover the PRNG state the next time it starts up.
+This file is created when it does not exist. </p>
+
+<p> Examples: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ tls_random_exchange_name = /var/lib/postfix/prng_exch
+ tls_random_prng_update_period = 3600s
+</pre>
+</blockquote>
+
+<p> As of version 2.5, Postfix no longer uses root privileges when
+opening this file. The file should now be stored under the Postfix-owned
+data_directory. As a migration aid, an attempt to open the file
+under a non-Postfix directory is redirected to the Postfix-owned
+data_directory, and a warning is logged. If you wish to continue
+using a pre-existing PRNG state file, move it to the data_directory
+and change the ownership to the account specified with the mail_owner
+parameter. </p>
+
+<p> With earlier Postfix versions the default file location
+is under the Postfix configuration directory, which is not the
+proper place for information that is modified by Postfix. </p>
+
+<h2><a name="quick-start">Getting started, quick and dirty</a></h2>
+
+<p> The following steps will get you started quickly. Because you
+sign your own Postfix public key certificate, you get TLS encryption
+but no TLS authentication. This is sufficient for testing, and
+for exchanging email with sites that you have no trust relationship
+with. For real authentication you need also enable DNSSEC record
+signing for your domain and publish TLSA records and/or your Postfix
+public key certificate needs to be signed by a recognized Certification
+Authority. To authenticate the certificates of remote host you
+need a DNSSEC-validating local resolver and to enable <a
+href="#client_tls_dane">DANE</a> authentication and/or configure
+the Postfix SMTP client with a list of public key certificates of
+Certification Authorities, but make sure to read about the <a
+href="#client_tls_limits">limitations</a> of the latter approach.
+</p>
+
+<p> In the examples below, user input is shown in <b><tt>bold</tt></b>
+font, and a "<tt>#</tt>" prompt indicates a super-user shell. </p>
+
+<ul>
+
+<li> <p> <a href="#built-in">Quick-start TLS with Postfix &ge; 3.1</a>.</p>
+
+<li> <p> <a href="#self-signed">Self-signed server certificate</a>.</p>
+
+<li> <p> <a href="#private-ca">Private Certification Authority</a>. </p>
+
+</ul>
+
+<h3><a name="built-in">Quick-start TLS with Postfix &ge; 3.1</a></h3>
+
+<p> Postfix 3.1 provides built-in support for enabling TLS in the
+SMTP client and server and for ongoing certificate and DANE TLSA
+record management.
+
+<ul>
+<li> <p> <a href="#quick-client">Quick-start TLS in the Postfix &ge; 3.1 SMTP client</a>. </p>
+<li> <p> <a href="#quick-server">Quick-start TLS in the Postfix &ge; 3.1 SMTP server</a>. </p>
+</ul>
+
+<h4> <a name="quick-client">Quick-start TLS in the Postfix &ge; 3.1 SMTP client</a>. </h4>
+
+<p> If you are using Postfix 3.1 or later, and your SMTP client TLS
+settings are in their default state, you can enable <a
+href="#client_tls_may">opportunistic</a> TLS in the SMTP client as
+follows: </p>
+
+<blockquote>
+<pre>
+# postfix tls enable-client
+# postfix reload
+</pre>
+</blockquote>
+
+<p> If some of the Postfix SMTP client TLS settings are not in their
+default state, this will not make any changes, but will instead
+suggest the minimal required settings for SMTP client TLS. The
+"postfix reload" command is optional, it is only needed if you want
+the settings to take effect right away. Note, this does not enable
+trust in any public certification authorities, and does not configure
+client TLS certificates as these are largely pointless with <a
+href="#client_tls_may">opportunistic</a> TLS. </p>
+
+<p> There is not yet a turn-key command for enabling <a
+href="#client_tls_dane">DANE</a> authentication. This is because
+DANE requires changes to your <b>resolv.conf</b> file and a
+corresponding DNSSEC-validating resolver local to the Postfix host,
+these changes are difficult to automate in a portable way. </p>
+
+<p> If you're willing to revert your settings to the defaults and
+switch to a "stock" opportunistic TLS configuration, then you can:
+erase all the SMTP client TLS settings and then enable client TLS: </p>
+
+<blockquote>
+<pre>
+# postconf -X `postconf -nH | egrep '^smtp(_|_enforce_|_use_)tls'`
+# postfix tls enable-client
+# postfix reload
+</pre>
+</blockquote>
+
+<h4><a name="quick-server">Quick-start TLS in the Postfix &ge; 3.1 SMTP server</a>.</h4>
+
+<p> If you are using Postfix 3.1 or later, and your SMTP server TLS
+settings are in their default state, you can enable
+opportunistic TLS in the SMTP server as follows: </p>
+
+<blockquote>
+<pre>
+# postfix tls enable-server
+# postfix reload
+</pre>
+</blockquote>
+
+<p> If some of the Postfix SMTP client TLS settings are not in their
+default state, this will not make any changes, but will instead
+suggest the minimal required settings for SMTP client TLS. The
+"postfix reload" command is optional, it is only needed if you want
+the settings to take effect right away. This will generate a
+self-signed private key and certificate and enable TLS in the Postfix
+SMTP server. </p>
+
+<p> If you're willing to revert your settings to the defaults and
+switch to a "stock" server TLS configuration, then you can: erase
+all the SMTP server TLS settings and then enable server TLS: </p>
+
+<blockquote>
+<pre>
+# postconf -X `postconf -nH | egrep '^smtpd(_|_enforce_|_use_)tls'`
+# postfix tls enable-server
+# postfix reload
+</pre>
+</blockquote>
+
+<p> Postfix &ge; 3.1 provides additional built-in support for ongoing
+management of TLS in the SMTP server, via additional "postfix tls"
+sub-commands. These make it easy to generate certificate signing
+requests, create and deploy new keys and certificates, and generate
+DANE TLSA records. See the postfix-tls(1) documentation for details.
+</p>
+
+<h3><a name="self-signed">Self-signed server certificate</a></h3>
+
+<p> The following commands (credits: Viktor Dukhovni) generate and
+install a 2048-bit RSA private key and 10-year self-signed certificate
+for the local Postfix system. This requires super-user privileges.
+(By using date-specific filenames for the certificate and key files,
+and updating main.cf with new filenames, a potential race condition
+in which the key and certificate might not match is avoided).
+</p>
+
+<blockquote>
+<pre>
+# dir="$(postconf -h config_directory)"
+# fqdn=$(postconf -h myhostname)
+# case $fqdn in /*) fqdn=$(cat "$fqdn");; esac
+# ymd=$(date +%Y-%m-%d)
+# key="${dir}/key-${ymd}.pem"; rm -f "${key}"
+# cert="${dir}/cert-${ymd}.pem"; rm -f "${cert}"
+# (umask 077; openssl genrsa -out "${key}" 2048) &&
+ openssl req -new -key "${key}" \
+ -x509 -subj "/CN=${fqdn}" -days 3650 -out "${cert}" &&
+ postconf -e \
+ "smtpd_tls_cert_file = ${cert}" \
+ "smtpd_tls_key_file = ${key}" \
+ 'smtpd_tls_security_level = may' \
+ 'smtpd_tls_received_header = yes' \
+ 'smtpd_tls_loglevel = 1' \
+ 'smtp_tls_security_level = may' \
+ 'smtp_tls_loglevel = 1' \
+ 'smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache' \
+ 'tls_random_source = dev:/dev/urandom'
+</pre>
+</blockquote>
+
+<p> Note: the last command requires both single (') and double (")
+quotes. </p>
+
+<p> The postconf(1) command above enables opportunistic TLS for
+receiving and sending mail. It also enables logging of TLS connections
+and recording of TLS use in the "Received" header. TLS session
+caching is also enabled in the Postfix SMTP client. With Postfix
+&ge; 2.10, the SMTP server does not need an explicit session cache
+since session reuse is better handled via RFC 5077 TLS session
+tickets. </p>
+
+<h3><a name="private-ca">Private Certification Authority</a></h3>
+
+<ul>
+
+<li> <p> Become your own Certification Authority, so that you can
+sign your own certificates, and so that your own systems can
+authenticate certificates from your own CA. This example uses the
+CA.pl script that ships with OpenSSL. On some systems, OpenSSL
+installs this as <tt>/usr/local/openssl/misc/CA.pl</tt>. Some systems
+install this as
+part of a package named <tt>openssl-perl</tt> or something similar.
+The script creates a private key in <tt>./demoCA/private/cakey.pem</tt>
+and a public key in <tt>./demoCA/cacert.pem</tt>.</p>
+
+<blockquote>
+<pre>
+% <b>/usr/local/ssl/misc/CA.pl -newca</b>
+CA certificate filename (or enter to create)
+
+Making CA certificate ...
+Using configuration from /etc/ssl/openssl.cnf
+Generating a 1024 bit RSA private key
+....................++++++
+.....++++++
+writing new private key to './demoCA/private/cakey.pem'
+Enter PEM pass phrase:<b>whatever</b>
+</pre>
+</blockquote>
+
+<li> <p> Create an unpassworded private key for host foo.porcupine.org and create
+an unsigned public key certificate. </p>
+
+<blockquote>
+<pre>
+% <b>(umask 077; openssl req -new -newkey rsa:2048 -nodes -keyout foo-key.pem -out foo-req.pem)</b>
+Using configuration from /etc/ssl/openssl.cnf
+Generating a 2048 bit RSA private key
+........................................++++++
+....++++++
+writing new private key to 'foo-key.pem'
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:<b>US</b>
+State or Province Name (full name) [Some-State]:<b>New York</b>
+Locality Name (eg, city) []:<b>Westchester</b>
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:<b>Porcupine</b>
+Organizational Unit Name (eg, section) []:
+Common Name (eg, YOUR name) []:<b>foo.porcupine.org</b>
+Email Address []:<b>wietse@porcupine.org</b>
+
+Please enter the following 'extra' attributes
+to be sent with your certificate request
+A challenge password []:<b>whatever</b>
+An optional company name []:
+</pre>
+</blockquote>
+
+<li> <p> Sign the public key certificate for host foo.porcupine.org with the
+Certification Authority private key that we created a few
+steps ago. </p>
+
+<blockquote>
+<pre>
+% <b>openssl ca -out foo-cert.pem -days 365 -infiles foo-req.pem</b>
+Using configuration from /etc/ssl/openssl.cnf
+Enter PEM pass phrase:<b>whatever</b>
+Check that the request matches the signature
+Signature ok
+The Subjects Distinguished Name is as follows
+countryName :PRINTABLE:'US'
+stateOrProvinceName :PRINTABLE:'New York'
+localityName :PRINTABLE:'Westchester'
+organizationName :PRINTABLE:'Porcupine'
+commonName :PRINTABLE:'foo.porcupine.org'
+emailAddress :IA5STRING:'wietse@porcupine.org'
+Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days)
+Sign the certificate? [y/n]:<b>y</b>
+
+
+1 out of 1 certificate requests certified, commit? [y/n]<b>y</b>
+Write out database with 1 new entries
+Data Base Updated
+</pre>
+</blockquote>
+
+<li> <p> Install the host private key, the host public key certificate,
+and the Certification Authority certificate files. This requires
+super-user privileges. </p>
+
+<p> The following commands assume that the key and certificate will
+be installed for the local Postfix MTA. You will need to adjust the
+commands if the Postfix MTA is on a different host. </p>
+
+<blockquote>
+<pre>
+# <b>cp demoCA/cacert.pem foo-key.pem foo-cert.pem /etc/postfix</b>
+# <b>chmod 644 /etc/postfix/foo-cert.pem /etc/postfix/cacert.pem</b>
+# <b>chmod 400 /etc/postfix/foo-key.pem</b>
+</pre>
+</blockquote>
+
+<li> <p> Configure Postfix, by adding the following to
+<tt>/etc/postfix/main.cf </tt>. It is generally best to not configure
+client certificates, unless there are servers which authenticate your mail
+submission via client certificates. Often servers that perform TLS client
+authentication will issue the required certificates signed by their own
+CA. If you configure the client certificate and key incorrectly, you
+will be unable to send mail to sites that request client certificate,
+but don't require them from all clients. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_CAfile = /etc/postfix/cacert.pem
+ smtp_tls_session_cache_database =
+ btree:/var/lib/postfix/smtp_tls_session_cache
+ smtp_tls_security_level = may
+ smtp_tls_loglevel = 1
+ smtpd_tls_CAfile = /etc/postfix/cacert.pem
+ smtpd_tls_cert_file = /etc/postfix/foo-cert.pem
+ smtpd_tls_key_file = /etc/postfix/foo-key.pem
+ smtpd_tls_received_header = yes
+ smtpd_tls_session_cache_database =
+ btree:/var/lib/postfix/smtpd_tls_session_cache
+ tls_random_source = dev:/dev/urandom
+ smtpd_tls_security_level = may
+ smtpd_tls_loglevel = 1
+</pre>
+</blockquote>
+
+</ul>
+
+
+<h2><a name="build_tls">Building Postfix with TLS support</a></h2>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the INSTALL document. Some modification may
+be required if you build Postfix from a vendor-specific source
+package. </p>
+
+<p> To build Postfix with TLS support, first we need to generate
+the <tt>make(1)</tt> files with the necessary definitions. This is
+done by invoking the command "<tt>make makefiles</tt>" in the Postfix
+top-level directory and with arguments as shown next. </p>
+
+<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate
+a Postfix daemon process with exit status code 2, instead of allowing
+Postfix to 1) report the error to the maillog file, and to 2) provide
+plaintext service where this is appropriate. </b> </p>
+
+<ul>
+
+<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
+in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries
+(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in
+directory <tt>/usr/lib</tt>: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b>
+</pre>
+</blockquote>
+
+<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
+in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL
+libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)
+are in directory <tt>/usr/local/lib</tt>: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+ AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b>
+</pre>
+</blockquote>
+
+<p> On Solaris, specify the <tt>-R</tt> option as shown below:
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+ AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b>
+</pre>
+</blockquote>
+
+</ul>
+
+<p> If you need to apply other customizations (such as Berkeley DB
+databases, MySQL, PostgreSQL, LDAP or SASL), see the respective
+Postfix README documents, and combine their "<tt>make makefiles</tt>"
+instructions with the instructions above: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS \
+ <i>(other -D or -I options)</i>" \
+ AUXLIBS="-lssl -lcrypto \
+ <i>(other -l options for libraries in /usr/lib)</i> \
+ <i>(-L/path/name + -l options for other libraries)</i>"</b>
+</pre>
+</blockquote>
+
+<p> To complete the build process, see the Postfix INSTALL
+instructions. Postfix has TLS support turned off by default, so
+you can start using Postfix as soon as it is installed. </p>
+
+<h2> <a name="problems"> Reporting problems </a> </h2>
+
+<p> Problems are preferably reported via &lt;postfix-users@postfix.org&gt;.
+See http://www.postfix.org/lists.html for subscription information.
+When reporting a problem, please be thorough in the report. Patches,
+when possible, are greatly appreciated too. </p>
+
+<h2><a name="credits">Credits </a> </h2>
+
+<ul>
+
+<li> TLS support for Postfix was originally developed by Lutz
+J&auml;nicke at Cottbus Technical University.
+
+<li> Wietse Venema adopted the code, did some restructuring, and
+compiled this part of the documentation from Lutz's documents.
+
+<li> Victor Duchovni was instrumental with the re-implementation
+of the smtp_tls_per_site code in terms of enforcement levels, which
+simplified the implementation greatly.
+
+<li> Victor Duchovni implemented the fingerprint security level,
+added more sanity checks, and separated TLS connection management
+from security policy enforcement. The latter change simplified the
+code that verifies certificate signatures, certificate names, and
+certificate fingerprints.
+
+</ul>
+
+</body>
+
+</html>