3223 lines
152 KiB
HTML
3223 lines
152 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
|
|
<html>
|
|
|
|
<head>
|
|
|
|
<title>Postfix TLS Support </title>
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
|
|
</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 introduces 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 <a href="smtpd.8.html">smtpd(8)</a> server implements the SMTP over TLS server
|
|
side. </p>
|
|
|
|
<li> <p> The <a href="smtp.8.html">smtp(8)</a> client implements the SMTP (and LMTP) over TLS
|
|
client side. </p>
|
|
|
|
<li> <p> The <a href="tlsmgr.8.html">tlsmgr(8)</a> server maintains the pseudo-random number
|
|
generator (PRNG) that seeds the TLS engines in the <a href="smtpd.8.html">smtpd(8)</a> server
|
|
and <a href="smtp.8.html">smtp(8)</a> client processes, and maintains the TLS session key
|
|
cache files. </p>
|
|
|
|
</ul>
|
|
|
|
<p> Not shown in the figure are the <a href="tlsproxy.8.html">tlsproxy(8)</a> server and the
|
|
<a href="postscreen.8.html">postscreen(8)</a> server. These use TLS in the same manner as <a href="smtpd.8.html">smtpd(8)</a>.
|
|
</p>
|
|
|
|
<table>
|
|
|
|
<tr> <td>Network<tt>-> </tt> </td> <td align="center"
|
|
bgcolor="#f0f0ff"> <br> <a href="smtpd.8.html">smtpd(8)</a> <br> </td> <td colspan="2">
|
|
|
|
<tt> <---seed----<br><br><-key/cert-> </tt> </td> <td
|
|
align="center" bgcolor="#f0f0ff"> <br> <a href="tlsmgr.8.html">tlsmgr(8)</a> <br> </td>
|
|
<td colspan="3"> <tt> ----seed---><br> <br><-key/cert->
|
|
|
|
</tt> </td> <td align="center" bgcolor="#f0f0ff"> <br> <a href="smtp.8.html">smtp(8)</a> <br>
|
|
</td> <td> <tt> -></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
|
|
"<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = 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.2" (or, for Postfix < 3.6, "!TLSv1.3") in
|
|
"<a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a>" and perhaps also "<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a>".
|
|
It is simpler instead to just configure a certificate chain.
|
|
Certificate-less operation is not recommended. <p>
|
|
|
|
<p> RSA, DSA and ECDSA (Postfix ≥ 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 (<a href="https://tools.ietf.org/html/rfc6698">RFC 6698</a>,
|
|
<a href="https://tools.ietf.org/html/rfc7671">RFC 7671</a>, <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a>) 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 an 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 > server.pem</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<li> <p> If you publish DANE TLSA (<a href="https://tools.ietf.org/html/rfc6698">RFC 6698</a>, <a href="https://tools.ietf.org/html/rfc7671">RFC 7671</a>, <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a>)
|
|
"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 > 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 <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> <a href="postconf.5.html">main.cf</a> 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 $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>
|
|
directory. </p>
|
|
|
|
<h4> Configuring the server certificate and key files </h4>
|
|
|
|
<p> Example: Postfix ≥ 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 ≥ 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.
|
|
#
|
|
<a href="postconf.5.html#smtpd_tls_chain_files">smtpd_tls_chain_files</a> =
|
|
/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 ≥ 3.4.
|
|
# Storing keys separately from the associated certificates is not
|
|
# recommended.
|
|
<a href="postconf.5.html#smtpd_tls_chain_files">smtpd_tls_chain_files</a> =
|
|
/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 ≤ 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
|
|
≥ 3.4 avoids the race when the key and certificate are in the same
|
|
file, you should use the new "<a href="postconf.5.html#smtpd_tls_chain_files">smtpd_tls_chain_files</a>" interface shown
|
|
above. <p>
|
|
|
|
<p> RSA key and certificate examples: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/server.pem
|
|
<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = $<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Their DSA counterparts: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a> = /etc/postfix/server-dsa.pem
|
|
<a href="postconf.5.html#smtpd_tls_dkey_file">smtpd_tls_dkey_file</a> = $<a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 1.0.0): </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
# Some clients will not be ECDSA capable, so you will likely still need
|
|
# an RSA certificate and private key.
|
|
#
|
|
<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> = /etc/postfix/server-ecdsa.pem
|
|
<a href="postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file</a> = $<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> TLS without certificates for servers serving exclusively
|
|
anonymous-cipher capable clients: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
# Not recommended: breaks TLS 1.3 and clients that don't support
|
|
# anonymous cipher suites.
|
|
<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = 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 $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> or in multiple files, one CA per file in
|
|
the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> 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 $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> 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 $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>
|
|
directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>
|
|
privileges) from the files in the directory when the information
|
|
is needed. Thus, the $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> 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 $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> are sent to the client, in order to allow
|
|
it to choose an identity signed by a CA you trust. If no $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>
|
|
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 $<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>. In the latter case you need not specify a
|
|
$<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>. </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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> = /etc/postfix/CAcert.pem
|
|
<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a> = /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 — 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 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 <a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = 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 "<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may". </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = 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
|
|
"<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt". According to <a href="https://tools.ietf.org/html/rfc2487">RFC 2487</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> TLS is also used in the "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 < 5.0 and Win32 >=5.0 when run on a port<>25
|
|
and OE (5.01 Mac on all ports). </p>
|
|
|
|
<p> It is strictly discouraged to use this mode from <a href="postconf.5.html">main.cf</a>. If
|
|
you want to support this service, enable a special port in <a href="master.5.html">master.cf</a>
|
|
and specify "-o <a href="postconf.5.html#smtpd_tls_wrappermode">smtpd_tls_wrappermode</a>=yes" (note: no space around
|
|
the "=") as an <a href="smtpd.8.html">smtpd(8)</a> command line option. Port 465 (submissions,
|
|
formerly called smtps) is the most common example.
|
|
</p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="master.5.html">master.cf</a>:
|
|
submissions inet n - n - - smtpd
|
|
-o <a href="postconf.5.html#smtpd_tls_wrappermode">smtpd_tls_wrappermode</a>=yes -o <a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a>=yes
|
|
</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 $<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>
|
|
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
|
|
<a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes
|
|
<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = 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 "<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes". This feature implies
|
|
"<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes". When TLS is not enforced,
|
|
"<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes" is ignored and a warning is
|
|
logged. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes
|
|
<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> The client certificate verification depth is specified with the
|
|
<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> parameter. The default verification
|
|
depth is 9 (the OpenSSL default), for compatibility with Postfix
|
|
versions before 2.5 where <a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> 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 $<a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verifydepth</a> = 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
|
|
("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = 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
|
|
("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = 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
|
|
"<a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = yes". </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = 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 <a href="smtpd.8.html">smtpd(8)</a> 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 ≥ 2.11 is described below).
|
|
</p>
|
|
|
|
<p> To share the session information between multiple
|
|
<a href="smtpd.8.html">smtpd(8)</a> 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> 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 <a href="https://tools.ietf.org/html/rfc5077">RFC 5077</a> TLS session resumption without
|
|
server-side state when the remote SMTP client also supports <a href="https://tools.ietf.org/html/rfc5077">RFC</a>
|
|
<a href="https://tools.ietf.org/html/rfc5077">5077</a>. 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
|
|
≥ 2.11 the <a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> 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 ≥ 2.6 SMTP
|
|
client. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> = <a href="DATABASE_README.html#types">btree</a>:/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 <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to
|
|
open the file under a non-Postfix directory is redirected to the
|
|
Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, 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). <a href="https://tools.ietf.org/html/rfc2246">RFC 2246</a>
|
|
recommends a maximum of 24 hours. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_session_cache_timeout">smtpd_tls_session_cache_timeout</a> = 3600s
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> As of Postfix 2.11 this setting cannot exceed 100 days. If set
|
|
≤ 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>
|
|
<a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_session_ids</a> = 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> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </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 <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below).
|
|
</p> </dd>
|
|
|
|
<dt> <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> </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> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd> <p> Use the remote
|
|
SMTP client certificate fingerprint or public key fingerprint
|
|
(Postfix 2.9 and later) as the lookup key for the specified <a href="access.5.html">access(5)</a>
|
|
table. </p> </dd>
|
|
|
|
</dl>
|
|
|
|
</blockquote>
|
|
|
|
<p> The digest algorithm used to compute the client certificate
|
|
fingerprints is specified with the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a>
|
|
parameter. The default algorithm is <b>sha256</b> with Postfix ≥
|
|
3.6 and the <b><a href="postconf.5.html#compatibility_level">compatibility_level</a></b> set to 3.6 or higher. With
|
|
Postfix ≤ 3.5, the default algorithm is <b>md5</b>. The
|
|
best-practice algorithm is now <b>sha256</b>. Recent advances in hash
|
|
function cryptanalysis have led to md5 and sha1 being deprecated in
|
|
favor of sha256. However, as long as there are no known "second
|
|
pre-image" attacks against the older algorithms, their use in this
|
|
context, though not recommended, is still likely safe. </p>
|
|
|
|
<p> The <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> 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 a trusted CA. If other CAs are trusted,
|
|
any owner of a valid client certificate would be authorized.
|
|
The <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> feature can be practical for a
|
|
specially created email relay server. </p>
|
|
|
|
<p> It is however recommended to stay with the <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
|
|
feature and list all certificates via $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>, as
|
|
<a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> 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 <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>.
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> =
|
|
<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
|
|
<a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
|
|
<a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
|
|
</pre>
|
|
|
|
<pre>
|
|
# Older configurations combine relay control and spam control under
|
|
# <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a>. To use this example with Postfix ≥
|
|
# 2.10 specify "<a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=".
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
|
|
<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
|
|
<a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
|
|
<a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
|
|
...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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> = <a href="DATABASE_README.html#types">hash</a>:/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> Example: </p>
|
|
<blockquote>
|
|
<pre>
|
|
$ openssl x509 -in cert.pem -noout -pubkey |
|
|
openssl pkey -pubin -outform DER |
|
|
openssl dgst -sha256 -c
|
|
(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:...:8b:fc:09:1a:61:98:b5:bc:7c:60:58
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<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 <a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a> 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
|
|
<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a> parameter (Postfix ≥ 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 < 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 "<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL" or
|
|
"<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> = 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
|
|
<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> configuration parameter. The
|
|
<a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a> parameter (Postfix ≥ 2.6)
|
|
controls the 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 "<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = none"
|
|
and not specifying an <a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a> or <a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>.
|
|
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.2 or higher, with high grade
|
|
ciphers: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/cert.pem
|
|
<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = /etc/postfix/key.pem
|
|
<a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a> = high
|
|
<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL, MD5
|
|
<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt
|
|
# Preferred syntax with Postfix ≥ 3.6:
|
|
<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> = >=TLSv1.2
|
|
# Legacy syntax:
|
|
<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> With Postfix ≥ 3.4, specify instead a single file that holds the
|
|
key followed by the corresponding certificate and any associated issuing
|
|
certificates, leaving the "<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a>" and "<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a>"
|
|
and related DSA and ECDSA parameters empty. </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_tls_chain_files">smtpd_tls_chain_files</a> = /etc/postfix/rsachain.pem
|
|
<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> =
|
|
<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> =
|
|
...
|
|
</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 "<a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> = yes" enables server
|
|
cipher-suite preferences. The default OpenSSL behavior applies with
|
|
"<a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> = 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 <a href="postconf.5.html#smtpd_starttls_timeout">smtpd_starttls_timeout</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtpd_starttls_timeout">smtpd_starttls_timeout</a> = 300s
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> With Postfix 2.8 and later, the <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> 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
|
|
<a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> parameter documentation for the list of
|
|
supported values.</p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = 0xFFFFFFFF
|
|
<a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = CVE-2010-4180
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> With Postfix ≥ 2.11, the <a href="postconf.5.html#tls_ssl_options">tls_ssl_options</a> 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 <a href="postconf.5.html#tls_ssl_options">tls_ssl_options</a> parameter documentation for the list of
|
|
supported values. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_ssl_options">tls_ssl_options</a> = 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 submissions (formerly called 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 <a href="smtp.8.html">smtp(8)</a> and <a href="lmtp.8.html">lmtp(8)</a> 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 $<a href="postconf.5.html#myhostname">myhostname</a>
|
|
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 "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = 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 "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may".
|
|
For LMTP, use the corresponding "lmtp_" parameter. </p>
|
|
|
|
<p> The "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>" and "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>" configuration
|
|
parameters (Postfix ≥ 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = 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
|
|
"<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = 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 <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>
|
|
and <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> 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 <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>
|
|
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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/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, <a href="transport.5.html">transport(5)</a> table or <a href="postconf.5.html#relayhost">relayhost</a>
|
|
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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy
|
|
|
|
/etc/services:
|
|
submission 587/tcp msa # mail message submission
|
|
|
|
/etc/postfix/tls_policy:
|
|
# Postfix ≥ 3.6 "protocols" syntax
|
|
[example.net]:587 encrypt protocols=>=TLSv1.2 ciphers=high
|
|
# Legacy "protocols" syntax
|
|
[example.net]:msa encrypt protocols=!SSLv2:!SSLv3 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 (<a href="https://tools.ietf.org/html/rfc6698">RFC 6698</a>, <a href="https://tools.ietf.org/html/rfc7671">RFC 7671</a>, <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a>) 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 <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a>) 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 <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a>) 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 <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> <a href="postconf.5.html">main.cf</a>
|
|
parameter. The <a href="postconf.5.html#tls_dane_digests">tls_dane_digests</a> parameter controls the list of
|
|
supported digests. </p>
|
|
|
|
<p> As explained in section 3 of <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a>, 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. <a href="https://tools.ietf.org/html/rfc7672">RFC</a>
|
|
<a href="https://tools.ietf.org/html/rfc7672">7672</a> (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 "<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>" must be set to "dnssec".
|
|
<li> The "<a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a>" 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. The Postfix SMTP server supports SNI (Postfix 3.4 and later),
|
|
configured with <a href="postconf.5.html#tls_server_sni_maps">tls_server_sni_maps</a>. </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 "<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>
|
|
= dnssec". To enable DNSSEC lookups selectively, define a new
|
|
dedicated transport with a "-o <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>=dnssec"
|
|
override in <a href="master.5.html">master.cf</a> 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
|
|
<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> in <a href="postconf.5.html">main.cf</a>. </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>
|
|
<a href="postconf.5.html">main.cf</a>:
|
|
indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/
|
|
#
|
|
# default: Opportunistic TLS with no DNSSEC lookups.
|
|
#
|
|
<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may
|
|
<a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a> = enabled
|
|
#
|
|
# Per-destination TLS policy
|
|
#
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = ${indexed}tls_policy
|
|
#
|
|
# <a href="postconf.5.html#default_transport">default_transport</a> = smtp, but some destinations are special:
|
|
#
|
|
<a href="postconf.5.html#transport_maps">transport_maps</a> = ${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>
|
|
<a href="master.5.html">master.cf</a>:
|
|
dane unix - - n - - smtp
|
|
-o <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>=dnssec
|
|
-o <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>=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
|
|
<a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> 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><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></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> The default algorithm is <b>sha256</b> with Postfix ≥ 3.6
|
|
and the <b><a href="postconf.5.html#compatibility_level">compatibility_level</a></b> set to 3.6 or higher; with Postfix
|
|
≤ 3.5, the default algorithm is <b>md5</b>. The
|
|
best-practice algorithm is now <b>sha256</b>. Recent advances in hash
|
|
function cryptanalysis have led to md5 and sha1 being deprecated in
|
|
favor of sha256. However, as long as there are no known "second
|
|
pre-image" attacks against the older algorithms, their use in this
|
|
context, though not recommended, is still likely safe. </p>
|
|
|
|
<p> Example: fingerprint TLS security with an internal mailhub.
|
|
Two matching fingerprints are listed. The <a href="postconf.5.html#relayhost">relayhost</a> may be multiple
|
|
physical hosts behind a load-balancer, each with its own private/public
|
|
key and self-signed certificate. Alternatively, a single <a href="postconf.5.html#relayhost">relayhost</a> 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>
|
|
<a href="postconf.5.html#relayhost">relayhost</a> = [mailhub.example.com]
|
|
<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = fingerprint
|
|
<a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = sha256
|
|
<a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> =
|
|
51:e9:af:2e:1e:40:1f:de:64:...:30:35:2d:09:16:31:5a:eb:82:76
|
|
b6:b4:72:34:e2:59:cd:fb:c2:...:63:0d:4d:cc:2c:7d:84:de:e6:2f
|
|
</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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy
|
|
<a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = sha256
|
|
</pre>
|
|
</blockquote>
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/tls_policy:
|
|
example.com fingerprint
|
|
match=51:e9:af:2e:1e:40:1f:de:...:35:2d:09:16:31:5a:eb:82:76
|
|
match=b6:b4:72:34:e2:59:cd:fb:...:0d:4d:cc:2c:7d:84:de:e6:2f
|
|
</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> Example: </p>
|
|
<blockquote>
|
|
<pre>
|
|
$ openssl x509 -in cert.pem -noout -pubkey |
|
|
openssl pkey -pubin -outform DER |
|
|
openssl dgst -sha256 -c
|
|
(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:...:09:1a:61:98:b5:bc:7c:60:58
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<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
|
|
"<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = verify". The
|
|
<a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> 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 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a>
|
|
and <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>), 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 ≥ 2.11 the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" 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 <a href="https://tools.ietf.org/html/rfc2487">RFC 2487</a> <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/<a href="postconf.5.html">main.cf</a>:
|
|
indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/
|
|
<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = ${<a href="postconf.5.html#config_directory">config_directory</a>}/CAfile.pem
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = ${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 "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = secure".
|
|
The <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> 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 <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and
|
|
<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>), 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 ≥ 2.11 the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" 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 <a href="https://tools.ietf.org/html/rfc2487">RFC 2487</a> <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 <a href="transport.5.html">transport(5)</a> 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 <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/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 <a href="transport.5.html">transport(5)</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
|
|
<a href="postconf.5.html#transport_maps">transport_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy
|
|
|
|
/etc/postfix/transport:
|
|
example.com <a href="smtp.8.html">smtp</a>:[tls.example.com]
|
|
example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com]
|
|
example.co.jp <a href="smtp.8.html">smtp</a>:[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 — 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 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>
|
|
<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> =
|
|
<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> =
|
|
<a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> =
|
|
<a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> =
|
|
# Postfix ≥ 2.6
|
|
<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> =
|
|
<a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> =
|
|
# Postfix ≥ 3.4
|
|
<a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a> =
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> The best way to use the default settings is to comment out the above
|
|
parameters in <a href="postconf.5.html">main.cf</a> 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 ≥ 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
|
|
a password. Both parts (certificate and private key) may be in the
|
|
same file. </p>
|
|
|
|
<p> With OpenSSL 1.1.1 and Postfix ≥ 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
|
|
"<a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a>" 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 > chain.pem </b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> A Postfix SMTP client certificate supplied here must be usable
|
|
as an 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
|
|
$<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. </p>
|
|
|
|
<p> Example: Postfix ≥ 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 ≥ 3.4. Preferred configuration interface. Each file
|
|
# starts with the private key, followed by the corresponding
|
|
# certificate, and any intermediate issuer certificates.
|
|
#
|
|
<a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a> =
|
|
/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 ≥ 3.4.
|
|
# Storing keys separately from the associated certificates is not
|
|
# recommended.
|
|
<a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a> =
|
|
/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 ≤ 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
|
|
≥ 3.4 avoids the race when the key and certificate are in the same
|
|
file, you should use the new "<a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a>" interface shown
|
|
above. <p>
|
|
|
|
<p> RSA key and certificate examples: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem
|
|
<a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> = $<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Their DSA counterparts: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem
|
|
<a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = $<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 1.0.0): </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = /etc/postfix/client-ecdsa.pem
|
|
<a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = $<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a>
|
|
</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 $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in
|
|
the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> 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 $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> 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 $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>
|
|
directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>
|
|
privileges) from the files in the directory when the information
|
|
is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible
|
|
inside the optional chroot jail. </p>
|
|
|
|
<p> The choice between $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> is
|
|
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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem
|
|
<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> = yes
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Alternatively, specify the attribute "connection_reuse=yes" in
|
|
an <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> entry. </p>
|
|
|
|
<p> The implementation of TLS connection reuse relies on the same
|
|
<a href="scache.8.html">scache(8)</a> service as used for delivering plaintext SMTP mail, the
|
|
same <a href="tlsproxy.8.html">tlsproxy(8)</a> daemon as used by the <a href="postscreen.8.html">postscreen(8)</a> service, and
|
|
relies on the same hints from the <a href="qmgr.8.html">qmgr(8)</a> 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> <a href="smtp.8.html">smtp(8)</a> -> remote SMTP server</pre>
|
|
|
|
<p> Reused SMTP/TLS connection, or new SMTP/TLS connection: </p>
|
|
<pre> <a href="smtp.8.html">smtp(8)</a> -> <a href="tlsproxy.8.html">tlsproxy(8)</a> -> remote SMTP server </pre>
|
|
|
|
<p> Cached SMTP/TLS connection:</p>
|
|
<pre> <a href="scache.8.html">scache(8)</a> -> <a href="tlsproxy.8.html">tlsproxy(8)</a> -> 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 <a href="smtp.8.html">smtp(8)</a>
|
|
process actually using this session and is lost when the process
|
|
terminates. To share the session information between multiple
|
|
<a href="smtp.8.html">smtp(8)</a> 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = <a href="DATABASE_README.html#types">btree</a>:/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 <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to
|
|
open the file under a non-Postfix directory is redirected to the
|
|
Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, 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). <a href="https://tools.ietf.org/html/rfc2246">RFC 2246</a>
|
|
recommends a maximum of 24 hours. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> As of Postfix 2.11 this setting cannot exceed 100 days. If set
|
|
≤ 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 — these are usually
|
|
unauthenticated — 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 <a href="https://tools.ietf.org/html/rfc6698">RFC6698</a> (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 ≥ 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änicke was designing
|
|
the first unofficial Postfix TLS patch. See his original post <a
|
|
href="https://web.archive.org/web/20070816181658/http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">https://web.archive.org/web/20070816181658/http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>
|
|
and the first response <a
|
|
href="https://web.archive.org/web/20070807073846/http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">https://web.archive.org/web/20070807073846/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 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>
|
|
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, $<a href="postconf.5.html#local_transport">local_transport</a>, $<a href="postconf.5.html#virtual_transport">virtual_transport</a>,
|
|
$<a href="postconf.5.html#relay_transport">relay_transport</a> or $<a href="postconf.5.html#default_transport">default_transport</a>. This includes any enclosing
|
|
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 $<a href="postconf.5.html#myhostname">myhostname</a> 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 <a href="transport.5.html">transport(5)</a> 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 <a href="postconf.5.html">main.cf</a> 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 ≥ 2.6) and "connection_reuse"
|
|
attribute (Postfix ≥ 3.4) override the "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>",
|
|
"<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a>", "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>", and
|
|
"<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a>" configuration parameters. At this level and
|
|
higher, the optional "servername" attribute (available with Postfix ≥
|
|
3.4) overrides the global "<a href="postconf.5.html#smtp_tls_servername">smtp_tls_servername</a>" parameter, enabling
|
|
per-destination configuration of the SNI extension sent to the remote
|
|
SMTP server. The optional "enable_rpk" attribute (Postfix ≥ 3.9)
|
|
overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_enable_rpk">smtp_tls_enable_rpk</a> parameter. When opportunistic
|
|
TLS handshakes fail, Postfix retries the connection with TLS disabled.
|
|
This allows mail delivery to sites with non-interoperable TLS
|
|
implementations.</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 <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>
|
|
parameter, the optional "ciphers" attribute overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> parameter, the optional "exclude" attribute
|
|
(Postfix ≥ 2.6) overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> parameter, and the optional
|
|
"connection_reuse" attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. The optional "enable_rpk" attribute
|
|
(Postfix ≥ 3.9) overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_enable_rpk">smtp_tls_enable_rpk</a> 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, the server certificate must match
|
|
the TLSA records (and the SNI name is unconditionally set to the TLSA
|
|
<i>base domain</i>). <a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a> (DANE) TLS authentication and DNSSEC
|
|
support is available with Postfix 2.11 and later. The optional
|
|
"connection_reuse" attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. When the effective security level
|
|
used is <a href="#client_tls_may">may</a>, the optional "ciphers",
|
|
"exclude", and "protocols" attributes (Postfix ≥ 2.6) override the
|
|
"<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>", "<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a>", and "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>"
|
|
configuration parameters. When the effective security level used is <a
|
|
href="#client_tls_encrypt">encrypt</a>, the optional "ciphers",
|
|
"exclude", and "protocols" attributes (Postfix ≥ 2.6) override the
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a>", "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a>", and
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>" configuration parameters. </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, the server certificate must match the TLSA records.
|
|
<a href="https://tools.ietf.org/html/rfc7672">RFC 7672</a> (DANE) TLS authentication and DNSSEC support is available with
|
|
Postfix 2.11 and later. The optional "ciphers", "exclude", and
|
|
"protocols" attributes (Postfix ≥ 2.6) override the
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a>", "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a>", and
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>" configuration parameters. The optional
|
|
"connection_reuse" attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. </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 "match" attribute, or else the <a href="postconf.5.html">main.cf</a>
|
|
<b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter, lists the certificate
|
|
fingerprints or the public key fingerprints (Postfix 2.9 and later) of
|
|
acceptable server certificates. The digest algorithm used to calculate
|
|
the fingerprint is selected by the <b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></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. The optional "ciphers",
|
|
"exclude", and "protocols" attributes (Postfix ≥ 2.6) override the
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a>", "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a>", and
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>" configuration parameters. The optional
|
|
"connection_reuse" attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. The optional "enable_rpk"
|
|
attribute (Postfix ≥ 3.9) overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_enable_rpk">smtp_tls_enable_rpk</a>
|
|
parameter. </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, the remote SMTP server certificate chain can be
|
|
validated, and a DNS name in the certificate matches the specified match
|
|
criteria. At this security level, DNS MX lookups are presumed to be
|
|
secure enough, and the name verified in the server certificate is
|
|
potentially obtained via unauthenticated DNS MX lookups. The server
|
|
certificate name must match either the optional "match" attribute, or
|
|
else the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> parameter value. With
|
|
Postfix ≥ 2.11 the "tafile" attribute optionally modifies trust chain
|
|
verification in the same manner as the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>"
|
|
parameter. The "tafile" attribute may be specified multiple times to
|
|
load multiple trust-anchor files. The optional "connection_reuse"
|
|
attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
|
|
<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. </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, the remote SMTP
|
|
server certificate chain can be validated, and a DNS name in the
|
|
certificate matches the specified match criteria. At this security
|
|
level, DNS MX lookups, though potentially used to determine the
|
|
candidate next-hop gateway IP addresses, are <b>not</b> presumed to be
|
|
secure enough for TLS peername verification. Instead, the default name
|
|
verified in the server certificate is obtained directly from the
|
|
next-hop, or is explicitly specified via the optional "match" attribute
|
|
which overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> parameter. The
|
|
optional "ciphers", "exclude", and "protocols" attributes (Postfix ≥
|
|
2.6) override the "<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a>",
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a>", and "<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>"
|
|
configuration parameters. With Postfix ≥ 2.11 the "tafile" attribute
|
|
optionally modifies trust chain verification in the same manner as the
|
|
"<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter. The "tafile" attribute may be
|
|
specified multiple times to load multiple trust-anchor files. The
|
|
optional "connection_reuse" attribute (Postfix ≥ 3.4) overrides the
|
|
<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. </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 <a href="transport.5.html">transport(5)</a> 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 ≥ 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 <a href="postconf.5.html">main.cf</a>, 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy
|
|
# Postfix 2.5 and later
|
|
<a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = sha256
|
|
/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=b6:b4:72:34:e2:59:cd:fb:...:0d:4d:cc:2c:7d:84:de:e6:2f
|
|
match=51:e9:af:2e:1e:40:1f:de:...:35:2d:09:16:31:5a:eb:82:76
|
|
# Postfix ≥ 3.6 "protocols" syntax
|
|
example.info may protocols=>=TLSv1 ciphers=medium exclude=3DES
|
|
# Legacy protocols syntax
|
|
example.info may protocols=!SSLv2:!SSLv3 ciphers=medium exclude=3DES
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> <b>Note:</b> The "hostname" strategy if listed in a non-default setting
|
|
of <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> or in the "match" attribute in the policy
|
|
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 <a href="postconf.5.html#smtp_tls_note_starttls_offer">smtp_tls_note_starttls_offer</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_note_starttls_offer">smtp_tls_note_starttls_offer</a> = 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
|
|
<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> parameter. The default verification
|
|
depth is 9 (the OpenSSL default), for compatibility with Postfix
|
|
versions before 2.5 where <a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> 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 $<a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_scert_verifydepth">smtp_tls_scert_verifydepth</a> = 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 <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> 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 <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> 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
|
|
"<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = aNULL"; and to
|
|
disable anonymous ciphers even with opportunistic TLS, set
|
|
"<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a> = 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 "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>" configuration parameter (Postfix ≥ 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 < 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
|
|
<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> configuration parameter. The corresponding
|
|
<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a> parameter (Postfix ≥ 2.6) controls
|
|
the TLS protocols used with opportunistic TLS. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> = medium
|
|
<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = RC4, MD5
|
|
<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a> = aNULL
|
|
<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a> = medium
|
|
# Preferred form with Postfix ≥ 3.6:
|
|
<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> = >=TLSv1.2
|
|
<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a> = >=TLSv1
|
|
# Legacy form for Postfix < 3.6:
|
|
<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
|
|
<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a> = !SSLv2,!SSLv3
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h3> <a name="client_smtps">Client-side submissions (formerly called smtps) support </a> </h3>
|
|
|
|
<p> These sections show how to send mail to a server that does not
|
|
support STARTTLS, but that provides the submissions (smtps) service
|
|
on TCP port 465. Depending on the Postfix version, some additional
|
|
tooling may be required. </p>
|
|
|
|
<h4> Postfix ≥ 3.0 </h4>
|
|
|
|
<p> The Postfix SMTP client has submissions service 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 a submissions (smtps) server. </p>
|
|
|
|
<h5> Postfix ≥ 3.0: Sending all remote mail to a submissions (formerly called smtps) server </h5>
|
|
|
|
<p> The first example will send all remote mail to through a
|
|
provider's submissions server called "mail.example.com": </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
# Client-side submissions requires "encrypt" or stronger.
|
|
<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = encrypt
|
|
<a href="postconf.5.html#smtp_tls_wrappermode">smtp_tls_wrappermode</a> = yes
|
|
# The [] suppress MX lookups.
|
|
<a href="postconf.5.html#relayhost">relayhost</a> = [mail.example.com]:submissions
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Use "postfix reload" to make the change effective. </p>
|
|
|
|
<p> See <a href="SOHO_README.html">SOHO_README</a> for additional information about SASL authentication.
|
|
</p>
|
|
|
|
<h5> Postfix ≥ 3.0: Sending only mail for a specific destination
|
|
to a submissions (formerly called smtps) service </h5>
|
|
|
|
<p> The second example will send only mail for "example.com" using
|
|
the submissions (smtps) service.
|
|
This time, Postfix uses a transport map to deliver only
|
|
mail for "example.com" using the submissions (smtps) service: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#transport_maps">transport_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport
|
|
|
|
/etc/postfix/transport:
|
|
example.com relay-submissions:example.com:submissions
|
|
|
|
/etc/postfix/<a href="master.5.html">master.cf</a>:
|
|
relay-submissions unix - - n - - smtp
|
|
# Client-side submissions service requires "encrypt" or stronger.
|
|
-o <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>=encrypt
|
|
-o <a href="postconf.5.html#smtp_tls_wrappermode">smtp_tls_wrappermode</a>=yes
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Use "postmap <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/transport" and "postfix reload"
|
|
to make the change effective. </p>
|
|
|
|
<p> See <a href="SOHO_README.html">SOHO_README</a> for additional information about SASL
|
|
authentication. </p>
|
|
|
|
<h4> Postfix < 3.0 </h4>
|
|
|
|
<p> Please see <a href="TLS_LEGACY_README.html">TLS_LEGACY_README</a>. </p>
|
|
|
|
<h3> <a name="client_misc"> Miscellaneous client controls </a> </h3>
|
|
|
|
<p> The <a href="postconf.5.html#smtp_starttls_timeout">smtp_starttls_timeout</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_starttls_timeout">smtp_starttls_timeout</a> = 300s
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> With Postfix 2.8 and later, the <a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = 0xFFFFFFFF
|
|
<a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> = 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="https://www.postfix.org/wip.html#tls-renegotiation">not
|
|
significantly vulnerable</a> to the renegotiation issue in the TLS
|
|
protocol. </p>
|
|
|
|
<p> With Postfix ≥ 2.11, the <a href="postconf.5.html#tls_ssl_options">tls_ssl_options</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_ssl_options">tls_ssl_options</a> = 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> process
|
|
maintains a Pseudo Random Number Generator (PRNG) pool. This is
|
|
queried by the <a href="smtp.8.html">smtp(8)</a> and <a href="smtpd.8.html">smtpd(8)</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_daemon_random_bytes">tls_daemon_random_bytes</a> = 32
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> In order to feed its in-memory PRNG pool, the <a href="tlsmgr.8.html">tlsmgr(8)</a> 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> 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 <a href="postconf.5.html">main.cf</a>): </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom
|
|
<a href="postconf.5.html#tls_random_source">tls_random_source</a> = egd:/var/run/egd-pool
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> By default, <a href="tlsmgr.8.html">tlsmgr(8)</a> 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_random_bytes">tls_random_bytes</a> = 32
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> In order to update its in-memory PRNG pool, the <a href="tlsmgr.8.html">tlsmgr(8)</a>
|
|
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 <a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a>.
|
|
The default maximal time interval is 1 hour. </p>
|
|
|
|
<p> Example: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a> = 3600s
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> The <a href="tlsmgr.8.html">tlsmgr(8)</a> 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/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#tls_random_exchange_name">tls_random_exchange_name</a> = /var/lib/postfix/prng_exch
|
|
<a href="postconf.5.html#tls_random_prng_update_period">tls_random_prng_update_period</a> = 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
|
|
<a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to open the file
|
|
under a non-Postfix directory is redirected to the Postfix-owned
|
|
<a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. If you wish to continue
|
|
using a pre-existing PRNG state file, move it to the <a href="postconf.5.html#data_directory">data_directory</a>
|
|
and change the ownership to the account specified with the <a href="postconf.5.html#mail_owner">mail_owner</a>
|
|
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 a 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 ≥ 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 ≥ 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 ≥ 3.1 SMTP client</a>. </p>
|
|
<li> <p> <a href="#quick-server">Quick-start TLS in the Postfix ≥ 3.1 SMTP server</a>. </p>
|
|
</ul>
|
|
|
|
<h4> <a name="quick-client">Quick-start TLS in the Postfix ≥ 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>
|
|
# <a href="postfix-tls.1.html">postfix tls</a> 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 | grep -E '^smtp(_|_enforce_|_use_)tls'`
|
|
# <a href="postfix-tls.1.html">postfix tls</a> enable-client
|
|
# postfix reload
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="quick-server">Quick-start TLS in the Postfix ≥ 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>
|
|
# <a href="postfix-tls.1.html">postfix tls</a> 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 | grep -E '^smtpd(_|_enforce_|_use_)tls'`
|
|
# <a href="postfix-tls.1.html">postfix tls</a> enable-server
|
|
# postfix reload
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Postfix ≥ 3.1 provides additional built-in support for ongoing
|
|
management of TLS in the SMTP server, via additional "<a href="postfix-tls.1.html">postfix tls</a>"
|
|
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 <a href="postfix-tls.1.html">postfix-tls(1)</a> 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 <a href="postconf.5.html">main.cf</a> with new filenames, a potential race condition
|
|
in which the key and certificate might not match is avoided).
|
|
</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
# dir="$(postconf -h <a href="postconf.5.html#config_directory">config_directory</a>)"
|
|
# fqdn=$(postconf -h <a href="postconf.5.html#myhostname">myhostname</a>)
|
|
# 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 \
|
|
"<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = ${cert}" \
|
|
"<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = ${key}" \
|
|
'<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may' \
|
|
'<a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = yes' \
|
|
'<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 1' \
|
|
'<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may' \
|
|
'<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 1' \
|
|
'<a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = <a href="DATABASE_README.html#types">btree</a>:${<a href="postconf.5.html#data_directory">data_directory</a>}/smtp_scache' \
|
|
'<a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom'
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> Note: the last command requires both single (') and double (")
|
|
quotes. </p>
|
|
|
|
<p> The <a href="postconf.1.html">postconf(1)</a> 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
|
|
≥ 2.10, the SMTP server does not need an explicit session cache
|
|
since session reuse is better handled via <a href="https://tools.ietf.org/html/rfc5077">RFC 5077</a> 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/<a href="postconf.5.html">main.cf</a> </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 a client certificate,
|
|
but don't require them from all clients. </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/cacert.pem
|
|
<a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> =
|
|
<a href="DATABASE_README.html#types">btree</a>:/var/lib/postfix/smtp_tls_session_cache
|
|
<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may
|
|
<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 1
|
|
<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a> = /etc/postfix/cacert.pem
|
|
<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = /etc/postfix/foo-cert.pem
|
|
<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> = /etc/postfix/foo-key.pem
|
|
<a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> = yes
|
|
<a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> =
|
|
<a href="DATABASE_README.html#types">btree</a>:/var/lib/postfix/smtpd_tls_session_cache
|
|
<a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom
|
|
<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may
|
|
<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 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 <a href="INSTALL.html">INSTALL</a> 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> If your OpenSSL shared library is in a directory that the RUN-TIME
|
|
linker does not know about, add a "-Wl,-R,/path/to/directory" option after
|
|
"-lcrypto". </p>
|
|
|
|
<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 <a href="INSTALL.html">INSTALL</a>
|
|
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 <postfix-users@postfix.org>.
|
|
See <a href="https://www.postfix.org/lists.html">https://www.postfix.org/lists.html</a> 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ä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 <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> 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>
|