Topics covered in this section:
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 password. Both 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 applies to the key file only, and the certificate file may be
"world-readable".
Public Internet MX hosts without certificates signed by a "reputable"
CA must generate, and be prepared to present to most clients, a
self-signed or private-CA signed certificate. The client will not be
able to authenticate the server, but unless it is running Postfix 2.3 or
similar software, it will still insist on a server certificate.
For servers that are not public Internet MX hosts, Postfix
2.3 supports configurations with no certificates. This entails the
use of just the anonymous TLS ciphers, which are not supported by
typical SMTP clients. Since such clients will not, as a rule, fall
back to plain text after a TLS handshake failure, the server will
be unable to receive email from most TLS enabled clients. To avoid
accidental configurations with no certificates, Postfix 2.3 enables
certificate-less operation only when the administrator explicitly sets
"
smtpd_tls_cert_file = none". This ensures that new Postfix
configurations will not accidentally run with no certificates.
Both RSA and DSA certificates are supported. Typically you will
only have RSA certificates issued by a commercial CA. In addition,
the tools supplied with OpenSSL will by default issue RSA certificates.
You can have both at the same time, in which case the cipher used
determines which certificate is presented. For Netscape and OpenSSL
clients without special cipher choices, the RSA certificate is
preferred.
In order for remote SMTP clients to check the Postfix SMTP
server certificates, the CA certificate (in case of a certificate
chain, all CA certificates) must be available. You should add any
intermediate CA certificates to the server certificate: the server
certificate first, then the intermediate CA(s).
Example: the certificate for "server.dom.ain" was issued by
"intermediate CA" which itself has a certificate issued by "root
CA". Create the server.pem file with:
% cat server_cert.pem intermediate_CA.pem > server.pem
A Postfix SMTP server certificate supplied here must be usable
as SSL server certificate and hence pass the "openssl verify -purpose
sslserver ..." test.
A client 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 "server.pem" file reduces
the overhead of the TLS exchange.
If you want the Postfix SMTP server to accept remote SMTP client
certificates issued by these CAs, append the root certificate to
$
smtpd_tls_CAfile or install it in the $
smtpd_tls_CApath directory. When
you configure trust in a root CA, it is not necessary to explicitly trust
intermediary CAs signed by the root CA, unless $
smtpd_tls_ccert_verifydepth
is less than the number of CAs in the certificate chain for the clients
of interest. With a verify depth of 1 you can only verify certificates
directly signed by a trusted CA, and all trusted intermediary CAs need to
be configured explicitly. With a verify depth of 2 you can verify clients
signed by a root CA or a direct intermediary CA (so long as the client
is correctly configured to supply its intermediate CA certificate).
RSA key and certificate examples:
/etc/postfix/
main.cf:
smtpd_tls_cert_file = /etc/postfix/server.pem
smtpd_tls_key_file = $
smtpd_tls_cert_file
Their DSA counterparts:
/etc/postfix/
main.cf:
smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem
smtpd_tls_dkey_file = $
smtpd_tls_dcert_file
Postfix 2.3 and later, TLS without certificates for servers serving
exclusively anonymous-cipher capable clients:
/etc/postfix/
main.cf:
smtpd_tls_cert_file = none
To verify a remote SMTP client certificate, the Postfix SMTP
server needs to trust the certificates of the issuing certification
authorities. These certificates in "PEM" format can be stored in a
single $
smtpd_tls_CAfile or in multiple files, one CA per file in
the $
smtpd_tls_CApath directory. If you use a directory, don't forget
to create the necessary "hash" links with:
# $OPENSSL_HOME/bin/c_rehash /path/to/directory
The $
smtpd_tls_CAfile contains the CA certificates of one or
more trusted CAs. The file is opened (with root privileges) before
Postfix enters the optional chroot jail and so need not be accessible
from inside the chroot jail.
Additional trusted CAs can be specified via the $
smtpd_tls_CApath
directory, in which case the certificates are read (with $
mail_owner
privileges) from the files in the directory when the information
is needed. Thus, the $
smtpd_tls_CApath directory needs to be
accessible inside the optional chroot jail.
When you configure Postfix to request client certificates, any CA certificates
in $
smtpd_tls_CAfile are sent to the client, in order to allow it to
choose an identity signed by a CA you trust. If no $
smtpd_tls_CAfile
is specified, no preferred CA list is sent, and the client is free to
choose an identity signed by any CA. Many clients use a fixed identity
regardless of the preferred CA list and you may be able to reduce TLS
negotiation overhead by installing client CA certificates mostly or
only in $
smtpd_tls_CApath. In the latter case you need not specify a
$
smtpd_tls_CAfile.
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.
Example:
/etc/postfix/
main.cf:
smtpd_tls_CAfile = /etc/postfix/CAcert.pem
smtpd_tls_CApath = /etc/postfix/certs
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.
| 0 | Disable logging of TLS activity. |
| 1 | Log TLS handshake and certificate information.
|
| 2 | Log levels during TLS negotiation. |
| 3 | Log hexadecimal and ASCII dump of TLS
negotiation process |
| 4 | Log hexadecimal and ASCII dump of complete
transmission after STARTTLS |
Use log level 3 only in case of problems. Use of log level 4 is
strongly discouraged.
Example:
/etc/postfix/
main.cf:
smtpd_tls_loglevel = 0
To include information about the protocol and cipher used as
well as the client and issuer CommonName into the "Received:"
message header, set the
smtpd_tls_received_header variable to true.
The default is no, as the information is not necessarily authentic.
Only information recorded at the final destination is reliable,
since the headers may be changed by intermediate servers.
Example:
/etc/postfix/
main.cf:
smtpd_tls_received_header = yes
By default, TLS is disabled in the Postfix SMTP server, so no
difference to plain Postfix is visible. Explicitly switch it on
with "
smtpd_tls_security_level = may" (Postfix 2.3 and
later) or "
smtpd_use_tls = yes" (obsolete but still
supported).
Example:
/etc/postfix/
main.cf:
# Postfix 2.3 and later
smtpd_tls_security_level = may
# Obsolete, but still supported
smtpd_use_tls = yes
With this, Postfix SMTP server announces STARTTLS support to
SMTP clients, but does not require that clients use TLS encryption.
Note: when an unprivileged user invokes "sendmail -bs", STARTTLS
is never offered due to insufficient privileges to access the server
private key. This is intended behavior.
You can ENFORCE the use of TLS,
so that the Postfix SMTP server announces STARTTLS and accepts no
mail without TLS encryption, by setting
"
smtpd_tls_security_level = encrypt" (Postfix 2.3 and
later) or "
smtpd_enforce_tls = yes" (obsolete but still
supported). According to
RFC 2487 this MUST NOT be applied in case
of a publicly-referenced Postfix SMTP server. This option is off
by default and should only seldom be used.
Example:
/etc/postfix/
main.cf:
# Postfix 2.3 and later
smtpd_tls_security_level = encrypt
# Obsolete, but still supported
smtpd_enforce_tls = yes
TLS is sometimes used in the non-standard "wrapper" mode where
a server always uses TLS, instead of announcing STARTTLS support
and waiting for 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).
It is strictly discouraged to use this mode from
main.cf. If
you want to support this service, enable a special port in
master.cf
and specify "-o
smtpd_tls_wrappermode=yes" (note: no space around
the "=") as an
smtpd(8) command line option. Port 465 (smtps) was
once chosen for this feature.
Example:
/etc/postfix/
master.cf:
smtps inet n - n - - smtpd
-o
smtpd_tls_wrappermode=yes -o
smtpd_sasl_auth_enable=yes
To receive a remote SMTP client certificate, the Postfix SMTP
server must explicitly ask for one (any contents of $
smtpd_tls_CAfile
are also sent to the client as a hint for choosing a certificate from
a suitable CA). Unfortunately, Netscape clients will either complain
if no matching client certificate is available or will offer the user
client a list of certificates to choose from. Additionally some MTAs
(notably some versions of qmail) are unable to complete TLS negotiation
when client certificates are requested, and abort the SMTP session. So
this option is "off" by default. You will however need the certificate
if you want to use certificate based relaying with, for example, the
permit_tls_clientcerts feature. A server that wants client certificates
must first present its own certificate. While Postfix 2.3 by default
offers anonymous ciphers to clients, these are automatically suppressed
when the server is configured to ask for client certificates.
Example:
/etc/postfix/
main.cf:
smtpd_tls_ask_ccert = yes
# Postfix 2.3 and later
smtpd_tls_security_level = may
# Obsolete, but still supported
smtpd_use_tls = yes
When TLS is
enforced you may also decide
to REQUIRE a remote SMTP client certificate for all TLS connections,
by setting "
smtpd_tls_req_ccert = yes". This feature implies
"
smtpd_tls_ask_ccert = yes". When TLS is not enforced,
"
smtpd_tls_req_ccert = yes" is ignored and a warning is
logged.
Example:
/etc/postfix/
main.cf:
smtpd_tls_req_ccert = yes
# Postfix 2.3 and later
smtpd_tls_security_level = encrypt
# Obsolete, but still supported
smtpd_enforce_tls = yes
A client certificate verification depth of 1 is sufficient if
the certificate is directly issued by a CA listed in the CA file.
The default value (5) should also suffice for longer chains (root
CA issues special CA which then issues the actual certificate...)
Example:
/etc/postfix/
main.cf:
smtpd_tls_ccert_verifydepth = 5
Sending AUTH data over an unencrypted channel poses a security
risk. When TLS layer encryption is required
("
smtpd_tls_security_level = encrypt" or the obsolete
"
smtpd_enforce_tls = yes"), the Postfix SMTP server will
announce and accept AUTH only after the TLS layer has been activated
with STARTTLS. When TLS layer encryption is optional
("
smtpd_tls_security_level = may" or the obsolete
"
smtpd_enforce_tls = no"), it may however still be useful
to only offer AUTH when TLS is active. To maintain compatibility
with non-TLS clients, the default is to accept AUTH without encryption.
In order to change this behavior, set
"
smtpd_tls_auth_only = yes".
Example:
/etc/postfix/
main.cf:
smtpd_tls_auth_only = no
The Postfix SMTP server and the remote SMTP client negotiate
a session, which takes some computer time and network bandwidth.
By default, this session information is cached only in the
smtpd(8)
process actually using this session and is lost when the process
terminates. To share the session information between multiple
smtpd(8) processes, a persistent session cache can be used. You
can specify any database type that can store objects of several
kbytes and that supports the sequence operator. DBM databases are
not suitable because they can only store small objects. The cache
is maintained by the
tlsmgr(8) process, so there is no problem with
concurrent access. Session caching is highly recommended, because
the cost of repeatedly negotiating TLS session keys is high.
Example:
/etc/postfix/
main.cf:
smtpd_tls_session_cache_database = btree:/etc/postfix/smtpd_scache
Cached Postfix SMTP server session information expires after
a certain amount of time. Postfix/TLS does not use the OpenSSL
default of 300s, but a longer time of 3600sec (=1 hour).
RFC 2246
recommends a maximum of 24 hours.
Example:
/etc/postfix/
main.cf:
smtpd_tls_session_cache_timeout = 3600s
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 prevent such wastage, 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.
Example:
smtpd_tls_always_issue_session_ids = no
Postfix TLS support introduces three additional features for
Postfix SMTP server access control:
-
permit_tls_clientcerts
-
Allow the remote SMTP
client SMTP request if the client certificate passes verification,
and if its fingerprint is listed in the list of client certificates
(see
relay_clientcerts discussion below).
-
permit_tls_all_clientcerts
-
Allow the remote
client SMTP request if the client certificate passes verification.
-
check_ccert_access
type:table
-
If the client certificate passes verification, use its fingerprint
as a key for the specified
access(5) table.
The
permit_tls_all_clientcerts feature must be used with caution,
because it can result in too many access permissions. Use this
feature only if a special CA issues the client certificates, and
only if this CA is listed as trusted CA. If other CAs are trusted,
any owner of a valid client certificate would be authorized.
The
permit_tls_all_clientcerts feature can be practical for a
specially created email relay server.
It is however recommended to stay with the
permit_tls_clientcerts
feature and list all certificates via $
relay_clientcerts, as
permit_tls_all_clientcerts does not permit any control when a
certificate must no longer be used (e.g. an employee leaving).
Example:
/etc/postfix/
main.cf:
smtpd_recipient_restrictions =
...
permit_tls_clientcerts
reject_unauth_destination
...
The Postfix list manipulation routines give special treatment
to whitespace and some other characters, making the use of certificate
names impractical. Instead we use the certificate fingerprints as
they are difficult to fake but easy to use for lookup. 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.
Example:
/etc/postfix/
main.cf:
relay_clientcerts = hash:/etc/postfix/relay_clientcerts
/etc/postfix/relay_clientcerts:
D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home
The description below is for Postfix 2.3; for Postfix < 2.3 the
smtpd_tls_cipherlist parameter specifies the acceptable ciphers as an
explicit OpenSSL cipherlist. The obsolete setting applies even when TLS
encryption is not enforced. Use of this control on public MX hosts is
strongly discouraged.
With mandatory TLS encryption, the Postfix SMTP server will by
default only use SSLv3 or TLSv1. SSLv2 is only used when TLS encryption
is optional. This is controlled by the
smtpd_tls_mandatory_protocols
configuration parameter.
The Postfix SMTP server supports 5 distinct cipher security levels
as specified by the
smtpd_tls_mandatory_ciphers configuration parameter,
which determines the cipher grade with mandatory TLS encryption. The
default value is "medium" which is essentially 128-bit encryption or better.
With opportunistic TLS encryption, the minimum accepted cipher grade is
always "export".
By default anonymous ciphers are allowed, and automatically disabled
when client certificates are requested. If clients are expected to always
verify the server certificate you may want to exclude anonymous ciphers
by setting "
smtpd_tls_mandatory_exclude_ciphers = aNULL".
One can't force a client to check the server certificate, so excluding
anonymous ciphers is generally unnecessary.
For a server that is not a public Internet MX host, Postfix 2.3
supports configurations with no
server
certificates that use only the anonymous ciphers. This is
enabled by explicitly setting "
smtpd_tls_cert_file = none"
and not specifying an
smtpd_tls_dcert_file.
Example: (MSA that requires TLS with high grade ciphers)
/etc/postfix/
main.cf:
smtpd_tls_cert_file = /etc/postfix/cert.pem
smtpd_tls_key_file = /etc/postfix/key.pem
smtpd_tls_mandatory_ciphers = high
smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5
# Postfix 2.3 and later
smtpd_tls_security_level = encrypt
# Obsolete, but still supported
smtpd_enforce_tls = yes
If you want to take advantage of ciphers with EDH, DH parameters
are needed. Instead of using the built-in DH parameters for both
1024bit and 512bit, it is better to generate your own parameters,
since otherwise it would "pay" for a possible attacker to start a
brute force attack against parameters that are used by everybody.
For this reason, the default parameters chosen by OpenSSL are already
different from those distributed with other TLS packages.
To generate your own set of DH parameters, use:
% openssl gendh -out /etc/postfix/dh_1024.pem -2 -rand /var/run/egd-pool 1024
% openssl gendh -out /etc/postfix/dh_512.pem -2 -rand /var/run/egd-pool 512
Examples:
/etc/postfix/
main.cf:
smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem
smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem
The
smtpd_starttls_timeout parameter limits the time of Postfix
SMTP server write and read operations during TLS startup and shutdown
handshake procedures.
Example:
/etc/postfix/
main.cf:
smtpd_starttls_timeout = 300s
