106
107
new Postfix SMTP server configurations will not accidentally run with no
109
RSA, DSA and ECDSA (Postfix >= 2.6) certificates are supported. Typically you
110
will only have RSA certificates issued by a commercial CA. In addition, the
111
tools supplied with OpenSSL will by default issue RSA certificates. You can
112
configure all three at the same time, in which case the cipher used determines
113
which certificate is presented. For Netscape and OpenSSL clients without
114
special cipher choices, the RSA certificate is preferred.
116
To enable a remote SMTP client to verify the Postfix SMTP server certificate,
117
the issuing CA certificates must be made available to the client. You should
118
include the required certificates in the server certificate file, the server
119
certificate first, then the issuing CA(s) (bottom-up order).
121
Example: the certificate for "server.example.com" was issued by "intermediate
122
CA" which itself has a certificate issued by "root CA". Create the server.pem
125
% ccaatt sseerrvveerr__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm >> sseerrvveerr..ppeemm
127
A Postfix SMTP server certificate supplied here must be usable as SSL server
110
RSA, DSA and ECDSA (Postfix >= 2.6) certificates are supported. Most sites only
111
have RSA certificates. You can configure all three at the same time, in which
112
case the ciphersuite negotiated with the remote SMTP client determines which
113
certificate is used. If your DNS zone is signed, and you want to publish RFC
114
6698 TLSA records, these must match any of the configured certificates. Since
115
the best practice is to publish "3 1 1" certificate associations, create a
116
separate TLSA record for each public-key certificate digest.
118
CCrreeaattiinngg tthhee sseerrvveerr cceerrttiiffiiccaattee ffiillee
120
To verify the Postfix SMTP server certificate, the remote SMTP client must
121
receive the issuing CA certificates via the TLS handshake or via public-key
122
infrastructure. This means that the Postfix server public-key certificate file
123
must include the server certificate first, then the issuing CA(s) (bottom-up
124
order). The Postfix SMTP server certificate must be usable as SSL server
128
125
certificate and hence pass the "openssl verify -purpose sslserver ..." test.
130
A client that trusts the root CA has a local copy of the root CA certificate,
131
so it is not necessary to include the root CA certificate here. Leaving it out
132
of the "server.pem" file reduces the overhead of the TLS exchange.
127
The examples that follow show how to create a server certificate file. We
128
assume that the certificate for "server.example.com" was issued by
129
"intermediate CA" which itself has a certificate issued by "root CA".
131
* With legacy public CA trust verification, you can omit the root certificate
132
from the "server.pem" certificate file. If the client trusts the root CA,
133
it will already have a local copy of the root CA certificate. Omitting the
134
root CA certificate reduces the size of the server TLS handshake.
136
% ccaatt sseerrvveerr__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm >> sseerrvveerr..ppeemm
138
* If you publish RFC 6698 TLSA "2 0 1" or "2 1 1" records to specify root CA
139
certificate digests, you must include the corresponding root CA
140
certificates in the "server.pem" certificate file. See the documentation of
141
the tls_dane_trust_anchor_digest_enable main.cf parameter.
143
% ccaatt sseerrvveerr__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm rroooott..ppeemm >> sseerrvveerr..ppeemm
145
Remote SMTP clients will be able to use the TLSA record you publish (which
146
only contains the certificate digest) only if they have access to the
147
corresponding certificate. Failure to verify certificates per the server's
148
published TLSA records will typically cause the SMTP client to defer mail
149
delivery. The foregoing also applies to "2 0 2" and "2 1 2" TLSA records or
150
any other digest of a CA certificate, but it is expected that SHA256 will
151
be by far the most common digest for TLSA.
153
As a best practice, publish either "3 0 1" or "3 1 1" TLSA associations
154
that specify the SHA256 digest of the server certificate public key with
155
the alias-expanded hostname of each STARTTLS capable SMTP server. These
156
continue to work when a certificate is renewed with the same public/private
159
For instructions on how to compute the digest of a certificate or its public
160
key for use in TLSA records, see the documentation of the
161
smtpd_tls_fingerprint_digest main.cf parameter.
163
When a new key or certificate is generated, an additional TLSA record with the
164
new digest must be published in advance of the actual deployment of the new key
165
or certificate on the server. You must allow sufficient time for any TLSA
166
RRsets with only the old digest to expire from DNS caches. The safest practice
167
is to wait until the DNSSEC signature on the previous TLSA RRset expires, and
168
only then switch the server to use new keys published in the updated TLSA
169
RRset. Once the new certificate trust chain and private key are in effect, the
170
DNS should be updated once again to remove the old digest from the TLSA RRset.
134
172
If you want the Postfix SMTP server to accept remote SMTP client certificates
135
issued by these CAs, append the root certificate to $smtpd_tls_CAfile or
136
install it in the $smtpd_tls_CApath directory.
173
issued by one or more root CAs, append the root certificate to
174
$smtpd_tls_CAfile or install it in the $smtpd_tls_CApath directory.
176
CCoonnffiigguurriinngg tthhee sseerrvveerr cceerrttiiffiiccaattee aanndd kkeeyy ffiilleess
138
178
RSA key and certificate examples:
364
404
SSeerrvveerr--ssiiddee TTLLSS sseessssiioonn ccaacchhee
366
406
The Postfix SMTP server and the remote SMTP client negotiate a session, which
367
takes some computer time and network bandwidth. By default, this session
368
information is cached only in the smtpd(8) process actually using this session
369
and is lost when the process terminates. To share the session information
370
between multiple smtpd(8) processes, a persistent session cache can be used.
371
You can specify any database type that can store objects of several kbytes and
372
that supports the sequence operator. DBM databases are not suitable because
373
they can only store small objects. The cache is maintained by the tlsmgr(8)
374
process, so there is no problem with concurrent access. Session caching is
375
highly recommended, because the cost of repeatedly negotiating TLS session keys
407
takes some computer time and network bandwidth. SSL protocol versions other
408
than SSLv2 support resumption of cached sessions. Not only is this more CPU and
409
bandwidth efficient, it also reduces latency as only one network round-trip is
410
used to resume a session while it takes two round-trips to create a session
413
Since Postfix uses multiple smtpd(8) service processes, an in-memory cache is
414
not sufficient for session re-use. Clients store at most one cached session per
415
server and are very unlikely to repeatedly connect to the same server process.
416
Thus session caching in the Postfix SMTP server generally requires a shared
417
cache (an alternative available with Postfix >= 2.11 is described below).
419
To share the session information between multiple smtpd(8) processes, a session
420
cache database is used. You can specify any database type that can store
421
objects of several kbytes and that supports the sequence operator. DBM
422
databases are not suitable because they can only store small objects. The cache
423
is maintained by the tlsmgr(8) process, so there is no problem with concurrent
424
access. Session caching is highly recommended, because the cost of repeatedly
425
negotiating TLS session keys is high.
427
Starting with Postfix 2.11, linked with a compatible OpenSSL library (at least
428
0.9.8h, preferably 1.0.0 or later) the Postfix SMTP server supports RFC 5077
429
TLS session resumption without server-side state when the remote SMTP client
430
also supports RFC 5077. The session is encrypted by the server in a session
431
ticket returned to client for storage. When a client sends a valid session
432
ticket, the server decrypts it and resumes the session, provided neither the
433
ticket nor the session have expired. This makes it possible to resume cached
434
sessions without allocating space for a shared database on the server. This
435
feature can be disabled by setting the session cache timeout to zero, otherwise
436
the timeout must be at least 2 minutes and at most 100 days.
438
Note, session tickets can only be negotiated if the client disables SSLv2 and
439
does not use the legacy SSLv2 compatible HELLO message. This is true by default
440
with the Postfix >= 2.6 SMTP client.
548
617
smtpd_tls_mandatory_ciphers = high
549
618
smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5
550
619
smtpd_tls_security_level = encrypt
551
# Preferred form with Postfix >= 2.5:
620
# Preferred syntax with Postfix >= 2.5:
552
621
smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3
554
623
smtpd_tls_mandatory_protocols = TLSv1
556
If you want to take advantage of ciphers with ephemeral Diffie-Hellman (EDH)
557
key exchange (this offers "forward-secrecy"), DH parameters are needed. Instead
558
of using the built-in DH parameters for both 1024-bit (non-export ciphers) and
559
512-bit (export ciphers), it is better to generate your own parameters, since
560
otherwise it would "pay" for a possible attacker to start a brute force attack
561
against parameters that are used by everybody. Postfix defaults to compiled-in
562
parameters that are shared by all Postfix users who don't generate their own
565
To generate your own set of DH parameters, use:
567
% ooppeennssssll ggeennddhh --oouutt //eettcc//ppoossttffiixx//ddhh__551122..ppeemm --22 551122
568
% ooppeennssssll ggeennddhh --oouutt //eettcc//ppoossttffiixx//ddhh__11002244..ppeemm --22 11002244
570
Support for elliptic curve cryptography is available with Postfix 2.6 and
571
OpenSSL 1.0.0 or later. To enable ephemeral elliptic curve Diffie-Hellman
572
(EECDH) key-exchange, set "smtpd_tls_eecdh_grade = strong" or
573
"smtpd_tls_eecdh_grade = ultra". The "ultra" setting is substantially more CPU
574
intensive, and "strong" is sufficiently secure for most situations.
578
/etc/postfix/main.cf:
579
smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem
580
smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem
582
smtpd_tls_eecdh_grade = strong
625
If you want to take maximal advantage of ciphers that offer forward secrecy see
626
the Getting started section of FORWARD_SECRECY_README. The full document
627
conveniently presents all information about Postfix "perfect" forward secrecy
628
support in one place: what forward secrecy is, how to tweak settings, and what
629
you can expect to see when Postfix uses ciphers with forward secrecy.
584
631
Postfix 2.8 and later, in combination with OpenSSL 0.9.7 and later allows TLS
585
servers to preempt the TLS client's cipher preference list. This is possible
586
only with SSLv3 and later, as in SSLv2 the client chooses the cipher from a
587
list supplied by the server.
589
By default, the OpenSSL server selects the client's most preferred cipher that
590
the server supports. With SSLv3 and later, the server may choose its own most
591
preferred cipher that is supported (offered) by the client. Setting
592
"tls_preempt_cipherlist = yes" enables server cipher preferences. The default
593
OpenSSL behavior applies with "tls_preempt_cipherlist = no".
595
While server cipher selection may in some cases lead to a more secure or
596
performant cipher choice, there is some risk of interoperability issues. In the
597
past, some SSL clients have listed lower priority ciphers that they did not
598
implement correctly. If the server chooses a cipher that the client prefers
599
less, it may select a cipher whose client implementation is flawed.
632
servers to preempt the TLS client's cipher-suite preference list. This is
633
possible only with SSLv3 and later, as in SSLv2 the client chooses the cipher-
634
suite from a list supplied by the server.
636
By default, the OpenSSL server selects the client's most preferred cipher-suite
637
that the server supports. With SSLv3 and later, the server may choose its own
638
most preferred cipher-suite that is supported (offered) by the client. Setting
639
"tls_preempt_cipherlist = yes" enables server cipher-suite preferences. The
640
default OpenSSL behavior applies with "tls_preempt_cipherlist = no".
642
While server cipher-suite selection may in some cases lead to a more secure or
643
performant cipher-suite choice, there is some risk of interoperability issues.
644
In the past, some SSL clients have listed lower priority ciphers that they did
645
not implement correctly. If the server chooses a cipher that the client prefers
646
less, it may select a cipher whose client implementation is flawed. Most
647
notably Windows 2003 Microsoft Exchange servers have flawed implementations of
648
DES-CBC3-SHA, which OpenSSL considers stronger than RC4-SHA. Enabling server
649
cipher-suite selection may create interoperability issues with Windows 2003
650
Microsoft Exchange clients.
601
652
MMiisscceellllaanneeoouuss sseerrvveerr ccoonnttrroollss
805
884
[example.net]:msa encrypt protocols=TLSv1 ciphers=high
806
885
[example.net]:submission encrypt protocols=TLSv1 ciphers=high
887
DDAANNEE TTLLSS aauutthheennttiiccaattiioonn..
889
The Postfix SMTP client supports two TLS security levels based on RFC6698 DANE
890
TLSA records. The opportunistic "dane" level and the mandatory "dane-only"
893
The "dane" level is a stronger form of opportunistic TLS that is resistant to
894
man in the middle and downgrade attacks when the destination domain uses DNSSEC
895
to publish DANE TLSA records for its MX hosts. If a remote SMTP server has
896
"usable" (see RFC 6698) DANE TLSA records, the server connection will be
897
authenticated. When DANE authentication fails, there is no fallback to
898
unauthenticated or plaintext delivery.
900
If TLSA records are published for a given remote SMTP server (implying TLS
901
support), but are all "unusable" due to unsupported parameters or malformed
902
data, the Postfix SMTP client will use mandatory unauthenticated TLS.
903
Otherwise, when no TLSA records are published, the Postfix SMTP client behavior
904
is the same as with may.
906
TLSA records must be published in DNSSEC validated DNS zones. Any TLSA records
907
in DNS zones not protected via DNSSEC are ignored. The Postfix SMTP client will
908
not look for TLSA records associated with MX hosts whose "A" or "AAAA" records
909
lie in an "insecure" DNS zone. Such lookups have been observed to cause
910
interoperability issues with poorly implemented DNS servers, and are in any
911
case not expected to ever yield "secure" results, since that would require a
912
very unlikely DLV DNS trust anchor configured between the host record and the
913
associated "_25._tcp" child TLSA record.
915
The "dane-only" level is a form of secure-channel TLS based on the DANE PKI. If
916
"usable" TLSA records are present these are used to authenticate the remote
917
SMTP server. Otherwise, or when server certificate verification fails, delivery
918
via the server in question tempfails.
920
At both security levels, the TLS policy for the destination is obtained via
921
TLSA records validated with DNSSEC. For TLSA policy to be in effect, the
922
destination domain's containing DNS zone must be signed and the Postfix SMTP
923
client's operating system must be configured to send its DNS queries to a
924
recursive DNS nameserver that is able to validate the signed records. Each MX
925
host's DNS zone needs to also be signed, and needs to publish DANE TLSA (RFC
926
6698) records that specify how that MX host's TLS certificate is to be
929
TLSA records do not preempt the normal SMTP MX host selection algorithm, if
930
some MX hosts support TLSA and others do not, TLS security will vary from
931
delivery to delivery. It is up to the domain owner to configure their MX hosts
932
and their DNS sensibly. To configure the Postfix SMTP client for DNSSEC lookups
933
see the documentation for the smtp_dns_support_level main.cf parameter. The
934
tls_dane_trust_anchor_digest_enable main.cf parameter controls support for
935
trust-anchor digest TLSA records. The tls_dane_digests and
936
tls_dane_digest_agility parameters control the list of supported digests and
937
digest downgrade attack resistance.
939
DANE for SMTP MTAs deviates in some details from the baseline DANE protocol in
940
RFC 6698. Most notably, it is not expected that SMTP MTAs can reasonably
941
include every public CA that a remote SMTP server's administrator may believe
942
to be well-known. Nor is there an interactive user to "click OK" when
943
authentication fails.
945
Therefore, certificate usages "0" and "1" from RFC 6698 which are intended to
946
"constrain" existing PKI trust, are not supported. TLSA records with usage "0"
947
are treated as "unusable". TLSA records with usage "1" are instead treated as
948
"trust assertions" and mapped to usage "3". Specifically, with certificate
949
usage "1", Postfix will not require the remote SMTP server's certificate to be
950
trusted with respect to any locally defined public CAs, it is the domain
951
owner's responsibility to ensure that the certificate associations in their
952
TLSA records are appropriate to authenticate their SMTP servers.
954
The Postfix SMTP client supports only certificate usages "2" and "3" (with "1"
955
treated as though it were "3"). See tls_dane_trust_anchor_digest_enable for
956
usage "2" usability considerations. Support for certificate usage "1" is an
957
experiment, it may be withdrawn in the future. Server operators SHOULD NOT
958
publish TLSA records with usage "1".
960
When usable TLSA records are obtained for the remote SMTP server the Postfix
961
SMTP client sends the SNI TLS extension in its SSL client hello message. This
962
may help the remote SMTP server live up to its promise to provide a certificate
963
that matches its TLSA records.
965
For purposes of protocol and cipher selection, the "dane" security level is
966
treated like a "mandatory" TLS security level, and weak ciphers and protocols
967
are disabled. Since DANE authenticates server certificates the "aNULL" cipher-
968
suites are transparently excluded at this level, no need to configure this
969
manually. RFC 6698 (DANE) TLS authentication is available with Postfix 2.11 and
972
When a DANE TLSA record specifies a trust-anchor (TA) certificate (that is an
973
issuing CA), the strategy used to verify the peername of the server certificate
974
is unconditionally "nexthop, hostname". Both the nexthop domain and the
975
hostname obtained from the DNSSEC-validated MX lookup are safe from forgery and
976
the server certificate must contain at least one of these names.
978
When a DANE TLSA record specifies an end-entity (EE) certificate, (that is the
979
actual server certificate), as with the fingerprint security level below, no
980
name checks or certificate expiration checks are applied. The server
981
certificate (or its public key) either matches the DANE record or not. Server
982
administrators should publish such EE records in preference to all other types.
984
The pre-requisites for DANE support in the Postfix SMTP client are:
986
* A compile-time OpenSSL library that supports the TLS SNI extension and
987
"SHA-2" message digests.
988
* A compile-time DNS resolver library that supports DNSSEC. Postfix binaries
989
built on an older system will not support DNSSEC even if deployed on a
990
system with an updated resolver library.
991
* The "smtp_dns_support_level" must be set to "dnssec".
992
* The "smtp_host_lookup" parameter must include "dns".
993
* A DNSSEC-validating recursive resolver (see note below).
995
The above client pre-requisites do not apply to the Postfix SMTP server. It
996
will support DANE provided it supports TLSv1 and its TLSA records are published
997
in a DNSSEC signed zone. To receive DANE secured mail for multiple domains, use
998
the same hostname to add the server to each domain's MX records. There are no
999
plans to implement SNI in the Postfix SMTP server.
1001
Note: The Postfix SMTP client's internal stub DNS resolver is DNSSEC-aware, but
1002
it does not itself validate DNSSEC records, rather it delegates DNSSEC
1003
validation to the operating system's configured recursive DNS nameserver. The
1004
Postfix DNS client relies on a secure channel to the resolver's cache for
1005
DNSSEC integrity, but does not support TSIG to protect the transmission channel
1006
between itself and the nameserver. Therefore, it is strongly recommended (DANE
1007
security guarantee void otherwise) that each MTA run a local DNSSEC-validating
1008
recursive resolver ("unbound" from nlnetlabs.nl is a reasonable choice)
1009
listening on the loopback interface, and that the system be configured to use
1010
only this local nameserver. The local nameserver may forward queries to an
1011
upstream recursive resolver on another host if desired.
1013
Note: When the operating system's recursive nameserver is not local, enabling
1014
EDNS0 expanded DNS packet sizes and turning on the DNSSEC "DO" bit in the DNS
1015
request and/or the new DNSSEC-specific records returned in the nameserver's
1016
replies may cause problems with older or buggy firewall and DNS server
1017
implementations. Therefore, Postfix does not enable DNSSEC by default. Since MX
1018
lookups happen before the security level is determined, DANE support is
1019
disabled for all destinations unless you set "smtp_dns_support_level = dnssec".
1020
To enable DNSSEC lookups selectively, define a new dedicated transport with a
1021
"-o smtp_dns_support_level=dnssec" override in master.cf and route selected
1022
domains to that transport. If DNSSEC proves to be sufficiently reliable for
1023
these domains, you can enable it for all destinations by changing the global
1024
smtp_dns_support_level in main.cf.
1026
EExxaammppllee: "dane" security for selected destinations, with opportunistic TLS by
1027
default. This is the recommended configuration for early adopters.
1029
* The "example.com" destination uses DANE, but if TLSA records are not
1030
present or are unusable, mail is deferred.
1032
* The "example.org" destination uses DANE if possible, but if no TLSA records
1033
are found opportunistic TLS is used.
1036
indexed = ${default_database_type}:${config_directory}/
1038
# default: Opportunistic TLS with no DNSSEC lookups.
1040
smtp_tls_security_level = may
1041
smtp_dns_support_level = enabled
1043
# Per-destination TLS policy
1045
smtp_tls_policy_maps = ${indexed}tls_policy
1047
# default_transport = smtp, but some destinations are special:
1049
transport_maps = ${indexed}transport
1056
example.com dane-only
1059
dane unix - - n - - smtp
1060
-o smtp_dns_support_level=dnssec
1061
-o smtp_tls_security_level=dane
808
1063
CCeerrttiiffiiccaattee ffiinnggeerrpprriinntt vveerriiffiiccaattiioonn
810
Certificate fingerprint verification is available with Postfix 2.5 and later.
811
At this security level ("smtp_tls_security_level = fingerprint"), no trusted
812
certificate authorities are used or required. The certificate trust chain,
813
expiration date, ... are not checked. Instead, the
814
smtp_tls_fingerprint_cert_match parameter or the "match" attribute in the
815
policy table lists the remote SMTP server certificate fingerprint or public key
816
fingerprint (Postfix 2.9 and later).
1065
At the fingerprint security level, no trusted certificate authorities are used
1066
or required. The certificate trust chain, expiration date, etc., are not
1067
checked. Instead, the smtp_tls_fingerprint_cert_match parameter or the "match"
1068
attribute in the policy table lists the remote SMTP server certificate
1069
fingerprint or public key fingerprint. Certificate fingerprint verification is
1070
available with Postfix 2.5 and later, public-key fingerprint support is
1071
available with Postfix 2.9 and later.
818
1073
If certificate fingerprints are exchanged securely, this is the strongest, and
819
1074
least scalable security level. The administrator needs to securely collect the
1572
1882
/etc/postfix/main.cf:
1573
1883
smtp_starttls_timeout = 300s
1885
With Postfix 2.8 and later, the tls_disable_workarounds parameter specifies a
1886
list or bit-mask of OpenSSL bug work-arounds to disable. This may be necessary
1887
if one of the work-arounds enabled by default in OpenSSL proves to pose a
1888
security risk, or introduces an unexpected interoperability issue. Some bug
1889
work-arounds known to be problematic are disabled in the default value of the
1890
parameter when linked with an OpenSSL library that could be vulnerable.
1894
/etc/postfix/main.cf:
1895
tls_disable_workarounds = 0xFFFFFFFF
1896
tls_disable_workarounds = CVE-2010-4180, LEGACY_SERVER_CONNECT
1898
Note: Disabling LEGACY_SERVER_CONNECT is not wise at this time, lots of servers
1899
are still unpatched and Postfix is not significantly vulnerable to the
1900
renegotiation issue in the TLS protocol.
1902
With Postfix >= 2.11, the tls_ssl_options parameter specifies a list or bit-
1903
mask of OpenSSL options to enable. Specify one or more of the named options
1904
below, or a hexadecimal bitmask of options found in the ssl.h file
1905
corresponding to the run-time OpenSSL library. While it may be reasonable to
1906
turn off all bug workarounds (see above), it is not a good idea to attempt to
1907
turn on all features.
1909
A future version of OpenSSL may by default no longer allow connections to
1910
servers that don't support secure renegotiation. Since the exposure for SMTP is
1911
minimal, and some SMTP servers may remain unpatched, you can add
1912
LEGACY_SERVER_CONNECT to the options to restore the more permissive default of
1913
current OpenSSL releases.
1917
/etc/postfix/main.cf:
1918
tls_ssl_options = NO_TICKET, NO_COMPRESSION, LEGACY_SERVER_CONNECT
1920
You should only enable features via the hexadecimal mask when the need to
1921
control the feature is critical (to deal with a new vulnerability or a serious
1922
interoperability problem). Postfix DOES NOT promise backwards compatible
1923
behavior with respect to the mask bits. A feature enabled via the mask in one
1924
release may be enabled by other means in a later release, and the mask bit will
1925
then be ignored. Therefore, use of the hexadecimal mask is only a temporary
1926
measure until a new Postfix or OpenSSL release provides a better solution.
1575
1928
TTLLSS mmaannaaggeerr ssppeecciiffiicc sseettttiinnggss
1577
1930
The security of cryptographic software such as TLS depends critically on the
added
removed
README_FILES/TLS_README
