auxiliary/fix-grep/fix-grep.sh can revert the syntax if you
want to build Postfix on an older platform. Files: too many
to mention here.
+
+20230101
+
+ Documentation: add text that cidr:, pcre: and regexp: tables
+ support inline specification only in Postfix 3.7 and later.
+ Files: proto/cidr_table, proto/pcre_table, proto/regexp_table.
+
+20230102
+
+ Cleanup: in internal documentation, text about DHE was under
+ the corresponding ECDHE function. Viktor Dukhovni. File:
+ tls/tls_dh.c.
+
+20230103
+
+ Bugfix (introduced: Postfix 2.7): the verify daemon logged
+ a garbled cache name when terminating a cache scan in
+ progress. Reported by Phil Biggs, fix by Viktor Dukhovni.
+ File: util/dict_cache.c.
+
+20220104
+
+ Feature: configuration parameter tls_ffdhe_auto_groups for
+ FFDHE support in TLS 1.3 with OpenSSL 3.0. Viktor Dukhovni.
+ Files: mantools/postlink, proto/FORWARD_SECRECY_README.html,
+ proto/postconf.proto, src/tlsproxy/tlsproxy.c, src/smtpd/smtpd.c,
+ src/tls/tls.h, src/tls/tls_proxy_client_misc.c, src/tls/tls_misc.c,
+ src/tls/tls_dh.c, src/tls/tls_proxy_client_scan.c,
+ src/tls/tls_server.c, src/tls/tls_client.c,
+ src/tls/tls_proxy_client_print.c, src/tls/tls_proxy.h,
+ src/global/mail_params.h, src/smtp/smtp.c.
+
+ Documentation: remove text for behavior that is no longer
+ implemented in Postfix or in other relevant systems. Viktor
+ Dukhovni. File: proto/FORWARD_SECRECY_README.html.
+
+ Bitrot: fixes for linker warnings from newer Darwin (MacOS)
+ versions. Viktor Dukhovni. File: makedefs.
+
+20220108
+
+ Minor wordsmithing. Files: text in proto/postconf.proto,
+ warning message tls.tls_dh.c.
encrypted with the server's RSA public key. The server decrypts this with its
private key, and uses it together with other data exchanged in the clear to
generate the session key. An attacker with access to the server's private key
-can perform the same computation at any later time. The TLS library in Windows
-XP and Windows Server 2003 only supported cipher suites of this type, and
-Exchange 2003 servers largely do not support forward secrecy.
+can perform the same computation at any later time.
Later revisions to the TLS protocol introduced forward-secrecy cipher suites in
which the client and server implement a key exchange protocol based on
element of that group called a "generator". Presently, there are two flavors of
"groups" that work with PFS:
- * P\bPr\bri\bim\bme\be-\b-f\bfi\bie\bel\bld\bd g\bgr\bro\bou\bup\bps\bs (\b(E\bED\bDH\bH)\b):\b: The server needs to be configured with a
- suitably-large prime and a corresponding "generator". The acronym for
- forward secrecy over prime fields is EDH for Ephemeral Diffie-Hellman (also
- abbreviated as DHE).
-
- * E\bEl\bll\bli\bip\bpt\bti\bic\bc-\b-c\bcu\bur\brv\bve\be g\bgr\bro\bou\bup\bps\bs (\b(E\bEE\bEC\bCD\bDH\bH)\b):\b: The server needs to be configured with a
- "named curve". These offer better security at lower computational cost than
- prime field groups, but are not as widely implemented. The acronym for the
- elliptic curve version is EECDH which is short for Ephemeral Elliptic Curve
- Diffie-Hellman (also abbreviated as ECDHE).
-
-It is not essential to know what these are, but one does need to know that
-OpenSSL supports EECDH with version 1.0.0 or later. Thus the configuration
-parameters related to Elliptic-Curve forward secrecy are available when Postfix
-is linked with OpenSSL >= 1.0.0 (provided EC support has not been disabled by
-the vendor, as in some versions of RedHat Linux).
-
-Elliptic curves used in cryptography are typically identified by a "name" that
-stands for a set of well-known parameter values, and it is these "names" (or
-associated ASN.1 object identifiers) that are used in the TLS protocol. On the
-other hand, with TLS there are no specially designated prime field groups, so
-each server is free to select its own suitably-strong prime and generator.
+ * F\bFF\bFD\bDH\bHE\bE:\b: Finite-field Diffie-Hellman ephemeral key exchange groups (also EDH
+ or DHE). The server needs to be configured with a suitably-large prime and
+ a corresponding "generator". Standard choices of the prime and generator
+ are specified in RFC7919, and can be used in the TLS 1.3 protocol with the
+ server and client negotiating a mutually supported choice. In earlier
+ versions of TLS (1.0 through 1.2), when FFDHE key exchange is performed,
+ the server chooses the prime and generator unilaterally.
+
+ * E\bEE\bEC\bCD\bDH\bH:\b: This is short for Ephemeral Elliptic Curve Diffie-Hellman (also
+ abbreviated as ECDHE). EECDH offers better security at lower computational
+ cost than FFDHE. Elliptic curves used in cryptography are typically
+ identified by a "name" that stands for a set of well-known parameter
+ values, and it is these "named curves" (or, in certificates, associated
+ ASN.1 object identifiers) that are used in the TLS protocol. When EECDH key
+ exchange is used, a mutually supported named curve is negotiated as part of
+ the TLS handshake.
F\bFo\bor\brw\bwa\bar\brd\bd S\bSe\bec\bcr\bre\bec\bcy\by i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP S\bSe\ber\brv\bve\ber\br
secrecy, then the traffic between the server and client will resist decryption
even if the server's long-term authentication keys are later compromised.
-Some remote SMTP clients may support forward secrecy, but prefer cipher suites
-without forward secrecy. In that case, Postfix >= 2.8 could be configured to
-ignore the client's preference with the main.cf setting "tls_preempt_cipherlist
-= yes". However, this will likely cause interoperability issues with older
-Exchange servers and is not recommended for now.
-
-E\bED\bDH\bH S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt
-
-Postfix >= 2.2 supports 1024-bit-prime EDH out of the box, with no additional
-configuration, but you may want to override the default prime to be 2048 bits
-long, and you may want to regenerate your primes periodically. See the quick-
-start section for details. With Postfix >= 3.1 the out of the box (compiled-in)
-EDH prime size is 2048 bits.
-
-With prime-field EDH, OpenSSL wants the server to provide two explicitly-
-selected (prime, generator) combinations. One for the now long-obsolete
-"export" cipher suites, and another for non-export cipher suites. Postfix has
-two such default combinations compiled in, but also supports explicitly-
-configured overrides.
-
- * The "export" EDH parameters are used only with the obsolete "export"
- ciphers. To use a non-default prime, generate a 512-bit DH parameter file
- and set smtpd_tls_dh512_param_file to the filename (see the quick-start
- section for details). With Postfix releases after the middle of 2015 the
- default opportunistic TLS cipher grade (smtpd_tls_ciphers) is "medium" or
- stronger, and export ciphers are no longer used.
-
- * The non-export EDH parameters are used for all other EDH cipher suites. To
- use a non-default prime, generate a 1024-bit or 2048-bit DH parameter file
- and set smtpd_tls_dh1024_param_file to the filename. Despite the name this
- is simply the non-export parameter file and the prime need not actually be
- 1024 bits long (see the quick-start section for details).
-
-As of mid-2015, SMTP clients are starting to reject TLS handshakes with primes
-smaller than 2048 bits. Each site needs to determine which prime size works
-best for the majority of its clients. See the quick-start section for the
-recommended configuration to work around this issue.
+Most remote SMTP clients now support forward secrecy (the only choice as of TLS
+1.3), but some may prefer cipher suites without forward secrecy. Postfix >= 2.8
+servers can be configured to override the client's preference by setting
+"tls_preempt_cipherlist = yes".
+
+F\bFF\bFD\bDH\bHE\bE S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt
+
+Postfix >= 3.1 supports 2048-bit-prime FFDHE out of the box, with no additional
+configuration. You can also generate your own FFDHE parameters, but this is not
+necessary and no longer recommended. See the quick-start section for details.
+
+Postfix >= 3.8 supports the finite-field Diffie-Hellman ephemeral (FFDHE) key
+exchange group negotiation API of OpenSSL >= 3.0. FFDHE groups are explicitly
+negotiated between client and server starting with TLS 1.3. In earlier TLS
+versions, the server chooses the group unilaterally. The list of candidate
+FFDHE groups can be configured via "tls_ffdhe_auto_groups", which can be used
+to select a prioritized list of supported groups (most preferred first) on both
+the server and client. The default list is suitable for most users. Either, but
+not both of "tls_eecdh_auto_curves" and "tls_ffdhe_auto_groups" may be set
+empty, disabling either EC or FFDHE key exchange in OpenSSL 3.0 with TLS 1.3.
+That said, interoperability will be poor if the EC curves are all disabled or
+don't include the most widely used curves.
E\bEE\bEC\bCD\bDH\bH S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt
-Postfix >= 2.6 supports NIST P-256 EECDH when built with OpenSSL >= 1.0.0. When
-the remote SMTP client also supports EECDH and implements the P-256 curve,
-forward secrecy just works.
-
- Note: With Postfix 2.6 and 2.7, enable EECDH by setting the main.cf
- parameter smtpd_tls_eecdh_grade to "strong".
-
-The elliptic curve standards are evolving, with new curves introduced in RFC
-8031 to augment or replace the NIST curves tarnished by the Snowden
-revelations. Fortunately, TLS clients advertise their list of supported curves
-to the server so that servers can choose newer stronger curves when mutually
-supported. OpenSSL 1.0.2 released in January 2015 was the first release to
-implement negotiation of supported curves in TLS servers. In older OpenSSL
-releases, the server is limited to selecting a single widely supported curve.
-
-With Postfix prior to 3.2 or OpenSSL prior to 1.0.2, only a single server-side
-curve can be configured, by specifying a suitable EECDH "grade":
-
- smtpd_tls_eecdh_grade = strong | ultra
- # Underlying curves, best not changed:
- # tls_eecdh_strong_curve = prime256v1
- # tls_eecdh_ultra_curve = secp384r1
-
-Postfix >= 3.2 supports the curve negotiation API of OpenSSL >= 1.0.2. When
-using this software combination, the default setting of "smtpd_tls_eecdh_grade"
-changes to "auto", which selects a curve that is supported by both the server
-and client. The list of candidate curves can be configured via
-"tls_eecdh_auto_curves", which can be used to configure a prioritized list of
-supported curves (most preferred first) on both the server and client. The
-default list is suitable for most users.
+As of Postfix 3.2 and OpenSSL 1.0.2, a range of supported EECDH curves is
+enabled in the server and client, and a suitable mutually supported curve is
+negotiated as part of the TLS handshake. The list of supported curves is
+configurable via the "tls_eecdh_auto_curves" parameter. With TLS 1.2 the server
+needs to leave its setting of "smtpd_tls_eecdh_grade" at the default value of
+"auto" (earlier choices of an explicit single curve grade are deprecated). With
+TLS 1.3, the "smtpd_tls_eecdh_grade" parameter is not used, and curve selection
+is unconditionally negotiated.
F\bFo\bor\brw\bwa\bar\brd\bd S\bSe\bec\bcr\bre\bec\bcy\by i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP C\bCl\bli\bie\ben\bnt\bt
The Postfix >= 2.2 SMTP client supports forward secrecy in its default
-configuration. All supported OpenSSL releases support EDH key exchange. OpenSSL
-releases >= 1.0.0 also support EECDH key exchange (provided elliptic-curve
-support has not been disabled by the vendor as in some versions of RedHat
-Linux). If the remote SMTP server supports cipher suites with forward secrecy
+configuration. All supported OpenSSL releases support both FFDHE and EECDH key
+exchange. If the remote SMTP server supports cipher suites with forward secrecy
(and does not override the SMTP client's cipher preference), then the traffic
between the server and client will resist decryption even if the server's long-
-term authentication keys are later compromised.
+term authentication keys are later compromised. Forward secrecy is always on in
+TLS 1.3.
Postfix >= 3.2 supports the curve negotiation API of OpenSSL >= 1.0.2. The list
of candidate curves can be changed via the "tls_eecdh_auto_curves"
supported curves (most preferred first) on both the Postfix SMTP server and
SMTP client. The default list is suitable for most users.
-The default Postfix SMTP client cipher lists are correctly ordered to prefer
-EECDH and EDH cipher suites ahead of similar cipher suites that don't implement
-forward secrecy. Administrators are strongly discouraged from changing the
-cipher list definitions.
+Postfix >= 3.8 supports the finite-field Diffie-Hellman ephemeral (FFDHE) key
+exchange group negotiation API of OpenSSL >= 3.0. The list of candidate FFDHE
+groups can be configured via "tls_ffdhe_auto_groups", which can be used to
+select a prioritized list of supported groups (most preferred first) on both
+the server and client. The default list is suitable for most users.
-The default minimum cipher grade for opportunistic TLS is "medium" for Postfix
-releases after the middle of 2015, "export" for older releases. Changing the
-minimum cipher grade does not change the cipher preference order. Note that
-cipher grades higher than "medium" exclude Exchange 2003 and likely other MTAs,
-thus a "high" cipher grade should be chosen only on a case-by-case basis via
-the TLS policy table.
+The default Postfix SMTP client cipher lists are correctly ordered to prefer
+EECDH and FFDHE cipher suites ahead of similar cipher suites that don't
+implement forward secrecy. Administrators are strongly discouraged from
+changing the cipher list definitions.
G\bGe\bet\btt\bti\bin\bng\bg s\bst\bta\bar\brt\bte\bed\bd,\b, q\bqu\bui\bic\bck\bk a\ban\bnd\bd d\bdi\bir\brt\bty\by
-E\bEE\bEC\bCD\bDH\bH C\bCl\bli\bie\ben\bnt\bt s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 2\b2.\b.2\b2 w\bwi\bit\bth\bh O\bOp\bpe\ben\bnS\bSS\bSL\bL >\b>=\b= 1\b1.\b.0\b0.\b.0\b0)\b)
+E\bEE\bEC\bCD\bDH\bH C\bCl\bli\bie\ben\bnt\bt s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 3\b3.\b.2\b2 w\bwi\bit\bth\bh O\bOp\bpe\ben\bnS\bSS\bSL\bL >\b>=\b= 1\b1.\b.1\b1.\b.1\b1)\b)
+
+This works "out of the box" with no need for additional configuration.
+
+Postfix >= 3.2 supports the curve negotiation API of OpenSSL >= 1.0.2. The list
+of candidate curves can be changed via the "tls_eecdh_auto_curves"
+configuration parameter, which can be used to select a prioritized list of
+supported curves (most preferred first) on both the Postfix SMTP server and
+SMTP client. The default list is suitable for most users.
+
+E\bEE\bEC\bCD\bDH\bH S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 3\b3.\b.2\b2 w\bwi\bit\bth\bh O\bOp\bpe\ben\bnS\bSS\bSL\bL >\b>=\b= 1\b1.\b.1\b1.\b.1\b1)\b)
This works "out of the box" with no need for additional configuration.
supported curves (most preferred first) on both the Postfix SMTP server and
SMTP client. The default list is suitable for most users.
-E\bEE\bEC\bCD\bDH\bH S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 2\b2.\b.6\b6 w\bwi\bit\bth\bh O\bOp\bpe\ben\bnS\bSS\bSL\bL >\b>=\b= 1\b1.\b.0\b0.\b.0\b0)\b)
-
-With Postfix 2.6 and 2.7, enable elliptic-curve support in the Postfix SMTP
-server. This is the default with Postfix >= 2.8. Note, however, that elliptic-
-curve support may be disabled by the vendor, as in some versions of RedHat
-Linux.
-
- /etc/postfix/main.cf:
- # Postfix 2.6 & 2.7 only. EECDH is on by default with Postfix >= 2.8.
- # The default grade is "auto" with Postfix >= 3.2.
- smtpd_tls_eecdh_grade = strong
-
-E\bED\bDH\bH C\bCl\bli\bie\ben\bnt\bt s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 2\b2.\b.2\b2,\b, a\bal\bll\bl s\bsu\bup\bpp\bpo\bor\brt\bte\bed\bd O\bOp\bpe\ben\bnS\bSS\bSL\bL v\bve\ber\brs\bsi\bio\bon\bns\bs)\b)
-
-This works "out of the box" without additional configuration.
-
-E\bED\bDH\bH S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 2\b2.\b.2\b2,\b, a\bal\bll\bl s\bsu\bup\bpp\bpo\bor\brt\bte\bed\bd O\bOp\bpe\ben\bnS\bSS\bSL\bL v\bve\ber\brs\bsi\bio\bon\bns\bs)\b)
-
-Optionally generate non-default Postfix SMTP server EDH parameters for improved
-security against pre-computation attacks and for compatibility with Debian-
-patched Exim SMTP clients that require a >= 2048-bit length for the non-export
-prime.
-
-With Postfix >= 3.7 built against OpenSSL version is 3.0.0 or later, when the
-value of smtpd_tls_dh1024_param_file is either empty or "a\bau\but\bto\bo", the EDH
-parameter selection is delegated to the OpenSSL library, which selects
-appropriate parameters based on the TLS handshake. This choice is likely to be
-the most interoperable with SMTP clients using various TLS libraries, and
-custom local parameters are no longer recommended when using Postfix >= 3.7
-built against OpenSSL 3.0.0. Just leave smtpd_tls_dh1024_param_file at its
-default value (both in main.cf(5) and any master.cf(5) overrides, and let
-OpenSSL do the work.
-
-Otherwise, execute as root (prime group generation can take a few seconds to a
-few minutes):
-
- # cd /etc/postfix
- # umask 022
- # openssl dhparam -out dh512.tmp 512 && mv dh512.tmp dh512.pem
- # openssl dhparam -out dh1024.tmp 1024 && mv dh1024.tmp dh1024.pem
- # openssl dhparam -out dh2048.tmp 2048 && mv dh2048.tmp dh2048.pem
- # chmod 644 dh512.pem dh1024.pem dh2048.pem
-
-The Postfix SMTP server EDH parameter files are not secret, after all these
-parameters are sent to all remote SMTP clients in the clear. Mode 0644 is
-appropriate.
-
-You can improve security against pre-computation attacks further by
-regenerating the Postfix SMTP server EDH parameters periodically (an hourly or
-daily cron job running the above commands as root can automate this task).
-
-Once the parameters are in place, update main.cf as follows:
-
- /etc/postfix/main.cf:
- smtpd_tls_dh1024_param_file = ${config_directory}/dh2048.pem
- smtpd_tls_dh512_param_file = ${config_directory}/dh512.pem
-
-If some of your MSA clients don't support 2048-bit EDH, you may need to adjust
-the submission entry in master.cf accordingly:
-
- /etc/postfix/master.cf:
- submission inet n - n - - smtpd
- # Some submission clients may not yet do 2048-bit EDH, if such
- # clients use your MSA, configure 1024-bit EDH instead. However,
- # as of mid-2015, many submission clients no longer accept primes
- # with less than 2048-bits. Each site needs to determine which
- # type of client is more important to support.
- -o smtpd_tls_dh1024_param_file=${config_directory}/dh1024.pem
- -o smtpd_tls_security_level=encrypt
- -o smtpd_sasl_auth_enable=yes
- ...
+F\bFF\bFD\bDH\bHE\bE C\bCl\bli\bie\ben\bnt\bt s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 3\b3.\b.2\b2,\b, O\bOp\bpe\ben\bnS\bSS\bSL\bL >\b>=\b= 1\b1.\b.1\b1.\b.1\b1)\b)
+
+In Postfix < 3.8, or OpenSSL prior to 3.0, FFDHE for TLS 1.2 or below works
+"out of the box", no additional configuration is necessary. The most one can do
+is (not advisable) disable all "kDHE" ciphers, which would then disable FFDHE
+key exchange in TLS 1.2 and below.
+
+With OpenSSL 1.1.1, FFDHE is not supported for TLS 1.3, which uses only EECDH
+key exchange. Support for FFDHE with TLS 1.3 was added in OpenSSL 3.0. With
+OpenSSL 3.0 and Postfix 3.8 the list of supported TLS 1.3 FFDHE groups becomes
+configurable via the "tls_ffdhe_auto_groups" parameter, which can be set empty
+to disable FFDHE in TLS 1.3, or conversely expanded to support more groups. The
+default should work well for most users.
+
+F\bFF\bFD\bDH\bHE\bE S\bSe\ber\brv\bve\ber\br s\bsu\bup\bpp\bpo\bor\brt\bt (\b(P\bPo\bos\bst\btf\bfi\bix\bx >\b>=\b= 2\b2.\b.2\b2,\b, a\bal\bll\bl s\bsu\bup\bpp\bpo\bor\brt\bte\bed\bd O\bOp\bpe\ben\bnS\bSS\bSL\bL v\bve\ber\brs\bsi\bio\bon\bns\bs)\b)
+
+In Postfix < 3.8, or OpenSSL prior to 3.0, FFDHE for TLS 1.2 or below works
+"out of the box", no additional configuration is necessary. One can of course
+(not advisable) disable all "kDHE" ciphers, which would then disable FFDHE key
+exchange in TLS 1.2 and below.
+
+The built-in default Postfix FFDHE group is a 2048-bit group as of Postfix 3.1.
+You can optionally generate non-default Postfix SMTP server FFDHE parameters
+for possibly improved security against pre-computation attacks, but this is not
+necessary or recommended. Just leave "smtpd_tls_dh1024_param_file" at its
+default empty value.
+
+The set of FFDHE groups enabled for use with TLS 1.3 becomes configurable with
+Postfix >= 3.8 and OpenSSL >= 3.0. The default setting of
+"tls_ffdhe_auto_groups" enables the RFC7919 2048 and 3072-bit groups. If you
+need more security, you should probably be using EECDH.
H\bHo\bow\bw c\bca\ban\bn I\bI s\bse\bee\be t\bth\bha\bat\bt a\ba c\bco\bon\bnn\bne\bec\bct\bti\bio\bon\bn h\bha\bas\bs f\bfo\bor\brw\bwa\bar\brd\bd s\bse\bec\bcr\bre\bec\bcy\by?\b?
Scan Postfix code with github.com/googleprojectzero/weggli
(depends on "rust").
+ In smtpd.c, move the comment block with info_log_address_format.
+
+ Is there any code that calls attr_scan*() and that works
+ when the number of attributes received < the expected number?
+ If there is no such code, then we can simplify a few things.
+
In tls_fprint.c() rename unsafe macros to upper-case names.
For example, checkok() has a function-like name, but it
evaluates arguments conditionally. Rename all macros that
server's RSA public key. The server decrypts this with its private
key, and uses it together with other data exchanged in the clear
to generate the session key. An attacker with access to the server's
-private key can perform the same computation at any later time.
-The TLS library in Windows XP and Windows Server 2003 only supported
-cipher suites of this type, and Exchange 2003 servers largely do
-not support forward secrecy. </p>
+private key can perform the same computation at any later time. </p>
<p> Later revisions to the TLS protocol introduced forward-secrecy
cipher suites in which the client and server implement a key exchange
<ul>
-<li> <p> <b> Prime-field groups (EDH):</b> The server needs to be
-configured with a suitably-large prime and a corresponding "generator".
-The acronym for forward secrecy over prime fields is EDH for Ephemeral
-Diffie-Hellman (also abbreviated as DHE).
-</p>
-
-<li> <p> <b> Elliptic-curve groups (EECDH): </b> The server needs
-to be configured with a "named curve". These offer better security
-at lower computational cost than prime field groups, but are not
-as widely implemented. The acronym for the elliptic curve version
-is EECDH which is short for Ephemeral Elliptic Curve Diffie-Hellman
-(also abbreviated as ECDHE). </p>
+<li> <p> <b>FFDHE:</b> Finite-field Diffie-Hellman ephemeral key
+exchange groups (also EDH or DHE). The server needs to be configured
+with a suitably-large prime and a corresponding "generator". Standard
+choices of the prime and generator are specified in <a href="https://tools.ietf.org/html/rfc7919">RFC7919</a>, and can be
+used in the TLS 1.3 protocol with the server and client negotiating a
+mutually supported choice. In earlier versions of TLS (1.0 through
+1.2), when FFDHE key exchange is performed, the server chooses the prime
+and generator unilaterally. </p>
+
+<li> <p> <b>EECDH:</b> This is short for Ephemeral Elliptic Curve
+Diffie-Hellman (also abbreviated as ECDHE). EECDH offers better
+security at lower computational cost than FFDHE. Elliptic curves used
+in cryptography are typically identified by a "name" that stands for a
+set of well-known parameter values, and it is these "named curves" (or,
+in certificates, associated ASN.1 object identifiers) that are used in
+the TLS protocol. When EECDH key exchange is used, a mutually supported
+named curve is negotiated as part of the TLS handshake. </p>
</ul>
-<p> It is not essential to know what these are, but one does need
-to know that OpenSSL supports EECDH with version 1.0.0 or later.
-Thus the configuration parameters related to Elliptic-Curve forward
-secrecy are available when Postfix is linked with OpenSSL ≥ 1.0.0
-(provided EC support has not been disabled by the vendor, as in
-some versions of RedHat Linux). </p>
-
-<p> Elliptic curves used in cryptography are typically identified
-by a "name" that stands for a set of well-known parameter values,
-and it is these "names" (or associated ASN.1 object identifiers)
-that are used in the TLS protocol. On the other hand, with TLS there
-are no specially designated prime field groups, so each server is
-free to select its own suitably-strong prime and generator. </p>
-
<h2><a name="server_fs">Forward Secrecy in the Postfix SMTP Server</a></h2>
<p> The Postfix ≥ 2.2 SMTP server supports forward secrecy in
and client will resist decryption even if the server's long-term
authentication keys are <i>later</i> compromised. </p>
-<p> Some remote SMTP clients may support forward secrecy, but prefer
-cipher suites <i>without</i> forward secrecy. In that case, Postfix
-≥ 2.8 could be configured to ignore the client's preference with
-the <a href="postconf.5.html">main.cf</a> setting "<a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> = yes". However, this
-will likely cause interoperability issues with older Exchange servers
-and is not recommended for now. </p>
-
-<h3> EDH Server support </h3>
-
-<p> Postfix ≥ 2.2 supports 1024-bit-prime EDH out of the box,
-with no additional configuration, but you may want to override the
-default prime to be 2048 bits long, and you may want to regenerate
-your primes periodically. See the <a href="#quick-start">quick-start</a>
-section for details. With Postfix ≥ 3.1 the out of the box
-(compiled-in) EDH prime size is 2048 bits. </p>
-
-<p> With prime-field EDH, OpenSSL wants the server to provide
-two explicitly-selected (prime, generator) combinations. One for
-the now long-obsolete "export" cipher suites, and another for
-non-export cipher suites. Postfix has two such default combinations
-compiled in, but also supports explicitly-configured overrides.
-</p>
-
-<ul>
-
-<li> <p> The "export" EDH parameters are used only with the obsolete
-"export" ciphers. To use a non-default prime, generate a 512-bit
-DH parameter file and set <a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a> to the filename
-(see the <a href="#quick-start">quick-start</a> section for details).
-With Postfix releases after the middle of 2015 the default opportunistic
-TLS cipher grade (<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a>) is "medium" or stronger, and
-export ciphers are no longer used. </p>
-
-<li> <p> The non-export EDH parameters are used for all other EDH
-cipher suites. To use a non-default prime, generate a 1024-bit or
-2048-bit DH parameter file and set <a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a> to
-the filename. Despite the name this is simply the non-export
-parameter file and the prime need not actually be 1024 bits long
-(see the <a href="#quick-start">quick-start</a> section for details).
-</p>
-
-</ul>
-
-<p> As of mid-2015, SMTP clients are starting to reject TLS
-handshakes with primes smaller than 2048 bits. Each site needs to
-determine which prime size works best for the majority of its
-clients. See the <a href="#quick-start">quick-start</a> section
-for the recommended configuration to work around this issue. </p>
+<p> Most remote SMTP clients now support forward secrecy (the only
+choice as of TLS 1.3), but some may prefer cipher suites <i>without</i>
+forward secrecy. Postfix ≥ 2.8 servers can be configured to override
+the client's preference by setting "<a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> = yes". </p>
+
+<h3> FFDHE Server support </h3>
+
+<p> Postfix ≥ 3.1 supports 2048-bit-prime FFDHE out of the box, with
+no additional configuration. You can also generate your own FFDHE
+parameters, but this is not necessary and no longer recommended. See
+the <a href="#quick-start">quick-start</a> section for details. </p>
+
+<p> Postfix ≥ 3.8 supports the finite-field Diffie-Hellman ephemeral
+(FFDHE) key exchange group negotiation API of OpenSSL ≥ 3.0. FFDHE
+groups are explicitly negotiated between client and server starting with
+TLS 1.3. In earlier TLS versions, the server chooses the group
+unilaterally. The list of candidate FFDHE groups can be configured via
+"<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>", which can be used to select a prioritized list
+of supported groups (most preferred first) on both the server and
+client. The default list is suitable for most users. Either, but not
+both of "<a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a>" and "<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>" may be set
+empty, disabling either EC or FFDHE key exchange in OpenSSL 3.0 with TLS
+1.3. That said, interoperability will be poor if the EC curves are
+all disabled or don't include the most widely used curves. </p>
<h3> EECDH Server support </h3>
-<p> Postfix ≥ 2.6 supports NIST P-256 EECDH when built with OpenSSL
-≥ 1.0.0. When the remote SMTP client also supports EECDH and
-implements the P-256 curve, forward secrecy just works. </p>
-
-<blockquote> <p> Note: With Postfix 2.6 and 2.7, enable EECDH by
-setting the <a href="postconf.5.html">main.cf</a> parameter <a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> to "strong".
-</p> </blockquote>
-
-<p> The elliptic curve standards are evolving, with new curves
-introduced in <a href="https://tools.ietf.org/html/rfc8031">RFC 8031</a> to augment or replace the NIST curves tarnished
-by the Snowden revelations. Fortunately, TLS clients advertise
-their list of supported curves to the server so that servers can
-choose newer stronger curves when mutually supported. OpenSSL 1.0.2
-released in January 2015 was the first release to implement negotiation
-of supported curves in TLS servers. In older OpenSSL releases, the
-server is limited to selecting a single widely supported curve. </p>
-
-<p> With Postfix prior to 3.2 or OpenSSL prior to 1.0.2, only a
-single server-side curve can be configured, by specifying a suitable
-EECDH "grade": </p>
-
-<blockquote>
-<pre>
- <a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> = strong | ultra
- # Underlying curves, best not changed:
- # <a href="postconf.5.html#tls_eecdh_strong_curve">tls_eecdh_strong_curve</a> = prime256v1
- # <a href="postconf.5.html#tls_eecdh_ultra_curve">tls_eecdh_ultra_curve</a> = secp384r1
-</pre>
-</blockquote>
-
-<p> Postfix ≥ 3.2 supports the curve negotiation API of OpenSSL
-≥ 1.0.2. When using this software combination, the default setting
-of "<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a>" changes to "auto", which selects a curve
-that is supported by both the server and client. The list of
-candidate curves can be configured via "<a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a>",
-which can be used to configure a prioritized list of supported
-curves (most preferred first) on both the server and client.
-The default list is suitable for most users. </p>
+<p> As of Postfix 3.2 and OpenSSL 1.0.2, a range of supported EECDH
+curves is enabled in the server and client, and a suitable mutually
+supported curve is negotiated as part of the TLS handshake. The list of
+supported curves is configurable via the "<a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a>"
+parameter. With TLS 1.2 the server needs to leave its setting of
+"<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a>" at the default value of "auto" (earlier choices
+of an explicit single curve grade are deprecated). With TLS 1.3, the
+"<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a>" parameter is not used, and curve selection is
+unconditionally negotiated. </p>
<h2> <a name="client_fs">Forward Secrecy in the Postfix SMTP Client</a> </h2>
-<p> The Postfix ≥ 2.2 SMTP client supports forward secrecy in
-its default configuration. All supported OpenSSL releases support
-EDH key exchange. OpenSSL releases ≥ 1.0.0 also support EECDH
-key exchange (provided elliptic-curve support has not been disabled
-by the vendor as in some versions of RedHat Linux). If the
-remote SMTP server supports cipher suites with forward secrecy (and
-does not override the SMTP client's cipher preference), then the
-traffic between the server and client will resist decryption even
-if the server's long-term authentication keys are <i>later</i>
-compromised. </p>
+<p> The Postfix ≥ 2.2 SMTP client supports forward secrecy in its
+default configuration. All supported OpenSSL releases support both
+FFDHE and EECDH key exchange. If the remote SMTP server supports cipher
+suites with forward secrecy (and does not override the SMTP client's
+cipher preference), then the traffic between the server and client will
+resist decryption even if the server's long-term authentication keys are
+<i>later</i> compromised. Forward secrecy is always on in TLS 1.3. </p>
<p> Postfix ≥ 3.2 supports the curve negotiation API of OpenSSL
≥ 1.0.2. The list of candidate curves can be changed via the
first) on both the Postfix SMTP server and SMTP client. The default
list is suitable for most users. </p>
-<p> The default Postfix SMTP client cipher lists are correctly
-ordered to prefer EECDH and EDH cipher suites ahead of similar
-cipher suites that don't implement forward secrecy. Administrators
-are strongly discouraged from changing the cipher list definitions. </p>
+<p> Postfix ≥ 3.8 supports the finite-field Diffie-Hellman ephemeral
+(FFDHE) key exchange group negotiation API of OpenSSL ≥ 3.0.
+The list of candidate FFDHE groups can be configured via
+"<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>", which can be used to select a prioritized list
+of supported groups (most preferred first) on both the server and
+client. The default list is suitable for most users. </p>
-<p> The default minimum cipher grade for opportunistic TLS is
-"medium" for Postfix releases after the middle of 2015, "export"
-for older releases. Changing the minimum cipher grade does not
-change the cipher preference order. Note that cipher grades higher
-than "medium" exclude Exchange 2003 and likely other MTAs, thus a
-"high" cipher grade should be chosen only on a case-by-case basis
-via the <a href="TLS_README.html#client_tls_policy">TLS policy</a>
-table. </p>
+<p> The default Postfix SMTP client cipher lists are correctly ordered
+to prefer EECDH and FFDHE cipher suites ahead of similar cipher suites
+that don't implement forward secrecy. Administrators are strongly
+discouraged from changing the cipher list definitions. </p>
<h2><a name="quick-start">Getting started, quick and dirty</a></h2>
-<h3> EECDH Client support (Postfix ≥ 2.2 with OpenSSL ≥ 1.0.0) </h3>
+<h3> EECDH Client support (Postfix ≥ 3.2 with OpenSSL ≥ 1.1.1) </h3>
<p> This works "out of the box" with no need for additional
configuration. </p>
first) on both the Postfix SMTP server and SMTP client. The default
list is suitable for most users. </p>
-<h3> EECDH Server support (Postfix ≥ 2.6 with OpenSSL ≥ 1.0.0) </h3>
-
-<p> With Postfix 2.6 and 2.7, enable elliptic-curve support in the
-Postfix SMTP server. This is the default with Postfix
-≥ 2.8. Note, however, that elliptic-curve support may be disabled
-by the vendor, as in some versions of RedHat Linux. </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- # Postfix 2.6 & 2.7 only. EECDH is on by default with Postfix ≥ 2.8.
- # The default grade is "auto" with Postfix ≥ 3.2.
- <a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> = strong
-</pre>
-</blockquote>
-
-<h3> EDH Client support (Postfix ≥ 2.2, all supported OpenSSL
-versions) </h3>
-
-<p> This works "out of the box" without additional configuration. </p>
-
-<h3> EDH Server support (Postfix ≥ 2.2, all supported OpenSSL
-versions) </h3>
+<h3> EECDH Server support (Postfix ≥ 3.2 with OpenSSL ≥ 1.1.1) </h3>
-<p> Optionally generate non-default Postfix SMTP server EDH parameters
-for improved security against pre-computation attacks and for
-compatibility with Debian-patched Exim SMTP clients that require a
-≥ 2048-bit length for the non-export prime. </p>
-
-<p> With Postfix ≥ 3.7 built against OpenSSL version is 3.0.0 or later, when
-the value of <a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a> is either empty or "<b>auto</b>", the
-EDH parameter selection is delegated to the OpenSSL library, which selects
-appropriate parameters based on the TLS handshake. This choice is likely to be
-the most interoperable with SMTP clients using various TLS libraries, and
-custom local parameters are no longer recommended when using Postfix ≥ 3.7
-built against OpenSSL 3.0.0. Just leave <a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a> at its
-default value (both in <a href="postconf.5.html">main.cf</a>(5) and any <a href="master.5.html">master.cf</a>(5) overrides, and let
-OpenSSL do the work. </p>
-
-<p> Otherwise, execute as root (prime group generation can take a
-few seconds to a few minutes): </p>
-
-<blockquote>
-<pre>
-# cd /etc/postfix
-# umask 022
-# openssl dhparam -out dh512.tmp 512 && mv dh512.tmp dh512.pem
-# openssl dhparam -out dh1024.tmp 1024 && mv dh1024.tmp dh1024.pem
-# openssl dhparam -out dh2048.tmp 2048 && mv dh2048.tmp dh2048.pem
-# chmod 644 dh512.pem dh1024.pem dh2048.pem
-</pre>
-</blockquote>
+<p> This works "out of the box" with no need for additional
+configuration. </p>
-<p> The Postfix SMTP server EDH parameter files are not secret,
-after all these parameters are sent to all remote SMTP clients in
-the clear. Mode 0644 is appropriate. </p>
+<p> Postfix ≥ 3.2 supports the curve negotiation API of OpenSSL
+≥ 1.0.2. The list of candidate curves can be changed via the
+"<a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a>" configuration parameter, which can be used
+to select a prioritized list of supported curves (most preferred
+first) on both the Postfix SMTP server and SMTP client. The default
+list is suitable for most users. </p>
-<p> You can improve security against pre-computation attacks further
-by regenerating the Postfix SMTP server EDH parameters periodically
-(an hourly or daily cron job running the above commands as root can
-automate this task). </p>
+<h3> FFDHE Client support (Postfix ≥ 3.2, OpenSSL ≥ 1.1.1) </h3>
-<p> Once the parameters are in place, update <a href="postconf.5.html">main.cf</a> as follows: </p>
+<p> In Postfix < 3.8, or OpenSSL prior to 3.0, FFDHE for TLS 1.2 or
+below works "out of the box", no additional configuration is necessary.
+The most one can do is (not advisable) disable all "kDHE" ciphers, which
+would then disable FFDHE key exchange in TLS 1.2 and below. </p>
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a> = ${<a href="postconf.5.html#config_directory">config_directory</a>}/dh2048.pem
- <a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a> = ${<a href="postconf.5.html#config_directory">config_directory</a>}/dh512.pem
-</pre>
-</blockquote>
+<p> With OpenSSL 1.1.1, FFDHE is not supported for TLS 1.3, which uses
+only EECDH key exchange. Support for FFDHE with TLS 1.3 was added in
+OpenSSL 3.0. With OpenSSL 3.0 and Postfix 3.8 the list of supported TLS
+1.3 FFDHE groups becomes configurable via the "<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>"
+parameter, which can be set empty to disable FFDHE in TLS 1.3, or
+conversely expanded to support more groups. The default should work
+well for most users. </p>
-<p> If some of your MSA clients don't support 2048-bit EDH, you may
-need to adjust the submission entry in <a href="master.5.html">master.cf</a> accordingly: </p>
+<h3> FFDHE Server support (Postfix ≥ 2.2, all supported OpenSSL
+versions) </h3>
-<blockquote>
-<pre>
-/etc/postfix/<a href="master.5.html">master.cf</a>:
- submission inet n - n - - smtpd
- # Some submission clients may not yet do 2048-bit EDH, if such
- # clients use your MSA, configure 1024-bit EDH instead. However,
- # as of mid-2015, many submission clients no longer accept primes
- # with less than 2048-bits. Each site needs to determine which
- # type of client is more important to support.
- -o <a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a>=${<a href="postconf.5.html#config_directory">config_directory</a>}/dh1024.pem
- -o <a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a>=encrypt
- -o <a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a>=yes
- ...
-</pre>
-</blockquote>
+<p> In Postfix < 3.8, or OpenSSL prior to 3.0, FFDHE for TLS 1.2 or
+below works "out of the box", no additional configuration is necessary.
+One can of course (not advisable) disable all "kDHE" ciphers, which
+would then disable FFDHE key exchange in TLS 1.2 and below. </p>
+
+<p> The built-in default Postfix FFDHE group is a 2048-bit group as of
+Postfix 3.1. You can optionally generate non-default Postfix SMTP
+server FFDHE parameters for possibly improved security against
+pre-computation attacks, but this is not necessary or recommended. Just
+leave "<a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a>" at its default empty value. </p>
+
+<p> The set of FFDHE groups enabled for use with TLS 1.3 becomes
+configurable with Postfix ≥ 3.8 and OpenSSL ≥ 3.0. The default
+setting of "<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>" enables the <a href="https://tools.ietf.org/html/rfc7919">RFC7919</a> 2048 and 3072-bit
+groups. If you need more security, you should probably be using EECDH.
+</p>
<h2><a name="test">How can I see that a connection has forward
secrecy? </a> </h2>
not required.
<b>INLINE SPECIFICATION</b>
- The contents of a table may be specified in the table name. The basic
- syntax is:
+ The contents of a table may be specified in the table name (Postfix 3.7
+ and later). The basic syntax is:
<a href="postconf.5.html">main.cf</a>:
<i>parameter</i> <b>= .. <a href="cidr_table.5.html">cidr</a>:{ {</b> <i>rule-1</i> <b>}, {</b> <i>rule-2</i> <b>} .. } ..</b>
nexthop destination security level is <b>dane</b>, but the MX record
was found via an "insecure" MX lookup.
+ Available in Postfix version 3.2 and later:
+
+ <b><a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a> (see 'postconf -d' output)</b>
+ The prioritized list of elliptic curves supported by the Postfix
+ SMTP client and server.
+
Available in Postfix version 3.4 and later:
<b><a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> (no)</b>
Try to make multiple deliveries per TLS-encrypted connection.
<b><a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a> (empty)</b>
- List of one or more PEM files, each holding one or more private
+ List of one or more PEM files, each holding one or more private
keys directly followed by a corresponding certificate chain.
<b><a href="postconf.5.html#smtp_tls_servername">smtp_tls_servername</a> (empty)</b>
- Optional name to send to the remote SMTP server in the TLS
+ Optional name to send to the remote SMTP server in the TLS
Server Name Indication (SNI) extension.
Available in Postfix 3.5, 3.4.6, 3.3.5, 3.2.10, 3.1.13 and later:
<b><a href="postconf.5.html#tls_fast_shutdown_enable">tls_fast_shutdown_enable</a> (yes)</b>
- A workaround for implementations that hang Postfix while shut-
+ A workaround for implementations that hang Postfix while shut-
ting down a TLS session, until Postfix times out.
+ Available in Postfix version 3.8 and later:
+
+ <b><a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a> (see 'postconf -d' output)</b>
+ The prioritized list of finite-field Diffie-Hellman ephemeral
+ (FFDHE) key exchange groups supported by the Postfix SMTP client
+ and server.
+
<b>OBSOLETE STARTTLS CONTROLS</b>
- The following configuration parameters exist for compatibility with
- Postfix versions before 2.3. Support for these will be removed in a
+ The following configuration parameters exist for compatibility with
+ Postfix versions before 2.3. Support for these will be removed in a
future release.
<b><a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> (no)</b>
- Opportunistic mode: use TLS when a remote SMTP server announces
+ Opportunistic mode: use TLS when a remote SMTP server announces
STARTTLS support, otherwise send the mail in the clear.
<b><a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> (no)</b>
- Enforcement mode: require that remote SMTP servers use TLS
+ Enforcement mode: require that remote SMTP servers use TLS
encryption, and never send mail in the clear.
<b><a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> (yes)</b>
- With mandatory TLS encryption, require that the remote SMTP
- server hostname matches the information in the remote SMTP
+ With mandatory TLS encryption, require that the remote SMTP
+ server hostname matches the information in the remote SMTP
server certificate.
<b><a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> (empty)</b>
- Optional lookup tables with the Postfix SMTP client TLS usage
- policy by next-hop destination and by remote SMTP server host-
+ Optional lookup tables with the Postfix SMTP client TLS usage
+ policy by next-hop destination and by remote SMTP server host-
name.
<b><a href="postconf.5.html#smtp_tls_cipherlist">smtp_tls_cipherlist</a> (empty)</b>
- Obsolete Postfix < 2.3 control for the Postfix SMTP client TLS
+ Obsolete Postfix < 2.3 control for the Postfix SMTP client TLS
cipher list.
<b>RESOURCE AND RATE CONTROLS</b>
<b><a href="postconf.5.html#smtp_connect_timeout">smtp_connect_timeout</a> (30s)</b>
- The Postfix SMTP client time limit for completing a TCP connec-
+ The Postfix SMTP client time limit for completing a TCP connec-
tion, or zero (use the operating system built-in time limit).
<b><a href="postconf.5.html#smtp_helo_timeout">smtp_helo_timeout</a> (300s)</b>
- The Postfix SMTP client time limit for sending the HELO or EHLO
- command, and for receiving the initial remote SMTP server
+ The Postfix SMTP client time limit for sending the HELO or EHLO
+ command, and for receiving the initial remote SMTP server
response.
<b><a href="postconf.5.html#lmtp_lhlo_timeout">lmtp_lhlo_timeout</a> (300s)</b>
mand, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_mail_timeout">smtp_mail_timeout</a> (300s)</b>
- The Postfix SMTP client time limit for sending the MAIL FROM
+ The Postfix SMTP client time limit for sending the MAIL FROM
command, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_rcpt_timeout">smtp_rcpt_timeout</a> (300s)</b>
- The Postfix SMTP client time limit for sending the SMTP RCPT TO
+ The Postfix SMTP client time limit for sending the SMTP RCPT TO
command, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_data_init_timeout">smtp_data_init_timeout</a> (120s)</b>
- The Postfix SMTP client time limit for sending the SMTP DATA
+ The Postfix SMTP client time limit for sending the SMTP DATA
command, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_data_xfer_timeout">smtp_data_xfer_timeout</a> (180s)</b>
- The Postfix SMTP client time limit for sending the SMTP message
+ The Postfix SMTP client time limit for sending the SMTP message
content.
<b><a href="postconf.5.html#smtp_data_done_timeout">smtp_data_done_timeout</a> (600s)</b>
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtp_mx_address_limit">smtp_mx_address_limit</a> (5)</b>
- The maximal number of MX (mail exchanger) IP addresses that can
- result from Postfix SMTP client mail exchanger lookups, or zero
+ The maximal number of MX (mail exchanger) IP addresses that can
+ result from Postfix SMTP client mail exchanger lookups, or zero
(no limit).
<b><a href="postconf.5.html#smtp_mx_session_limit">smtp_mx_session_limit</a> (2)</b>
- The maximal number of SMTP sessions per delivery request before
- the Postfix SMTP client gives up or delivers to a fall-back
+ The maximal number of SMTP sessions per delivery request before
+ the Postfix SMTP client gives up or delivers to a fall-back
<a href="postconf.5.html#relayhost">relay host</a>, or zero (no limit).
<b><a href="postconf.5.html#smtp_rset_timeout">smtp_rset_timeout</a> (20s)</b>
Available in Postfix version 2.2 and earlier:
<b><a href="postconf.5.html#lmtp_cache_connection">lmtp_cache_connection</a> (yes)</b>
- Keep
Postfix LMTP client connections open for up to $<a href="postconf.5.html#max_idle">max_idle</a>
+ Keep
Postfix LMTP client connections open for up to $<a href="postconf.5.html#max_idle">max_idle</a>
seconds.
Available in Postfix version 2.2 and later:
<b><a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> (empty)</b>
- Permanently enable SMTP connection caching for the specified
+ Permanently enable SMTP connection caching for the specified
destinations.
<b><a href="postconf.5.html#smtp_connection_cache_on_demand">smtp_connection_cache_on_demand</a> (yes)</b>
- Temporarily enable SMTP connection caching while a destination
+ Temporarily enable SMTP connection caching while a destination
has a high volume of mail in the <a href="QSHAPE_README.html#active_queue">active queue</a>.
<b><a href="postconf.5.html#smtp_connection_reuse_time_limit">smtp_connection_reuse_time_limit</a> (300s)</b>
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#connection_cache_protocol_timeout">connection_cache_protocol_timeout</a> (5s)</b>
- Time limit for connection cache connect, send or receive opera-
+ Time limit for connection cache connect, send or receive opera-
tions.
Available in Postfix version 2.9 - 3.6:
<b><a href="postconf.5.html#smtp_per_record_deadline">smtp_per_record_deadline</a> (no)</b>
- Change the behavior of the smtp_*_timeout time limits, from a
- time limit per read or write system call, to a time limit to
- send or receive a complete record (an SMTP command line, SMTP
- response line, SMTP message content line, or TLS protocol mes-
+ Change the behavior of the smtp_*_timeout time limits, from a
+ time limit per read or write system call, to a time limit to
+ send or receive a complete record (an SMTP command line, SMTP
+ response line, SMTP message content line, or TLS protocol mes-
sage).
Available in Postfix version 2.11 and later:
<b><a href="postconf.5.html#smtp_connection_reuse_count_limit">smtp_connection_reuse_count_limit</a> (0)</b>
- When SMTP connection caching is enabled, the number of times
- that an SMTP session may be reused before it is closed, or zero
+ When SMTP connection caching is enabled, the number of times
+ that an SMTP session may be reused before it is closed, or zero
(no limit).
Available in Postfix version 3.4 and later:
Available in Postfix version 3.7 and later:
<b><a href="postconf.5.html#smtp_per_request_deadline">smtp_per_request_deadline</a> (no)</b>
- Change the behavior of the smtp_*_timeout time limits, from a
- time limit per plaintext or TLS read or write call, to a com-
- bined time limit for sending a complete SMTP request and for
+ Change the behavior of the smtp_*_timeout time limits, from a
+ time limit per plaintext or TLS read or write call, to a com-
+ bined time limit for sending a complete SMTP request and for
receiving a complete SMTP response.
<b><a href="postconf.5.html#smtp_min_data_rate">smtp_min_data_rate</a> (500)</b>
- The minimum plaintext data transfer rate in bytes/second for
+ The minimum plaintext data transfer rate in bytes/second for
DATA requests, when deadlines are enabled with
<a href="postconf.5.html#smtp_per_request_deadline">smtp_per_request_deadline</a>.
<b><a href="postconf.5.html#transport_destination_concurrency_limit">transport_destination_concurrency_limit</a> ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concur</a>-</b>
<b><a href="postconf.5.html#default_destination_concurrency_limit">rency_limit</a>)</b>
- A
transport-specific override for the <a href="postconf.5.html#default_destination_concurrency_limit">default_destination_con</a>-
+ A
transport-specific override for the <a href="postconf.5.html#default_destination_concurrency_limit">default_destination_con</a>-
<a href="postconf.5.html#default_destination_concurrency_limit">currency_limit</a> parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a>
name of the message delivery transport.
<b><a href="postconf.5.html#transport_destination_recipient_limit">transport_destination_recipient_limit</a> ($<a href="postconf.5.html#default_destination_recipient_limit">default_destination_recipi</a>-</b>
<b><a href="postconf.5.html#default_destination_recipient_limit">ent_limit</a>)</b>
A transport-specific override for the <a href="postconf.5.html#default_destination_recipient_limit">default_destination_recip</a>-
- <a href="postconf.5.html#default_destination_recipient_limit">ient_limit</a>
parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a>
+ <a href="postconf.5.html#default_destination_recipient_limit">ient_limit</a>
parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a>
name of the message delivery transport.
<b>SMTPUTF8 CONTROLS</b>
Preliminary SMTPUTF8 support is introduced with Postfix 3.0.
<b><a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> (yes)</b>
- Enable preliminary SMTPUTF8 support for the protocols described
+ Enable preliminary SMTPUTF8 support for the protocols described
in <a href="https://tools.ietf.org/html/rfc6531">RFC 6531</a>, <a href="https://tools.ietf.org/html/rfc6532">RFC 6532</a>, and <a href="https://tools.ietf.org/html/rfc6533">RFC 6533</a>.
<b><a href="postconf.5.html#smtputf8_autodetect_classes">smtputf8_autodetect_classes</a> (sendmail, verify)</b>
- Detect that a message requires SMTPUTF8 support for the speci-
+ Detect that a message requires SMTPUTF8 support for the speci-
fied mail origin classes.
Available in Postfix version 3.2 and later:
<b><a href="postconf.5.html#enable_idna2003_compatibility">enable_idna2003_compatibility</a> (no)</b>
- Enable 'transitional' compatibility between IDNA2003 and
- IDNA2008, when converting UTF-8 domain names to/from the ASCII
+ Enable 'transitional' compatibility between IDNA2003 and
+ IDNA2008, when converting UTF-8 domain names to/from the ASCII
form that is used for DNS lookups.
<b>TROUBLE SHOOTING CONTROLS</b>
<b><a href="postconf.5.html#debug_peer_level">debug_peer_level</a> (2)</b>
- The increment in verbose logging level when a nexthop destina-
- tion, remote client or server name or network address matches a
+ The increment in verbose logging level when a nexthop destina-
+ tion, remote client or server name or network address matches a
pattern given with the <a href="postconf.5.html#debug_peer_list">debug_peer_list</a> parameter.
<b><a href="postconf.5.html#debug_peer_list">debug_peer_list</a> (empty)</b>
- Optional list of nexthop destination, remote client or server
- name or network address patterns that, if matched, cause the
- verbose logging level to increase by the amount specified in
+ Optional list of nexthop destination, remote client or server
+ name or network address patterns that, if matched, cause the
+ verbose logging level to increase by the amount specified in
$<a href="postconf.5.html#debug_peer_level">debug_peer_level</a>.
<b><a href="postconf.5.html#error_notice_recipient">error_notice_recipient</a> (postmaster)</b>
- The recipient of postmaster notifications about mail delivery
+ The recipient of postmaster notifications about mail delivery
problems that are caused by policy, resource, software or proto-
col errors.
<b><a href="postconf.5.html#internal_mail_filter_classes">internal_mail_filter_classes</a> (empty)</b>
- What categories of Postfix-generated mail are subject to
- before-queue
content inspection by <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>,
+ What categories of Postfix-generated mail are subject to
+ before-queue
content inspection by <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>,
<a href="postconf.5.html#header_checks">header_checks</a> and <a href="postconf.5.html#body_checks">body_checks</a>.
<b><a href="postconf.5.html#notify_classes">notify_classes</a> (resource, software)</b>
<b>MISCELLANEOUS CONTROLS</b>
<b><a href="postconf.5.html#best_mx_transport">best_mx_transport</a> (empty)</b>
- Where the Postfix SMTP client should deliver mail when it
+ Where the Postfix SMTP client should deliver mail when it
detects a "mail loops back to myself" error condition.
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
+ The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
figuration files.
<b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
- How much time a Postfix daemon process may take to handle a
+ How much time a Postfix daemon process may take to handle a
request before it is terminated by a built-in watchdog timer.
<b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
- The maximal number of digits after the decimal point when log-
+ The maximal number of digits after the decimal point when log-
ging sub-second delay values.
<b><a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> (no)</b>
Disable DNS lookups in the Postfix SMTP and LMTP clients.
<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b>
- The network interface addresses that this mail system receives
- mail on.
+ The local network interface addresses that this mail system
+ receives mail on.
<b><a href="postconf.5.html#inet_protocols">inet_protocols</a> (see 'postconf -d output')</b>
- The Internet protocols Postfix will attempt to use when making
+ The Internet protocols Postfix will attempt to use when making
or accepting connections.
<b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
- The time limit for sending or receiving information over an
+ The time limit for sending or receiving information over an
internal communication channel.
<b><a href="postconf.5.html#lmtp_assume_final">lmtp_assume_final</a> (no)</b>
- When a remote LMTP server announces no DSN support, assume that
- the server performs final delivery, and send "delivered" deliv-
+ When a remote LMTP server announces no DSN support, assume that
+ the server performs final delivery, and send "delivered" deliv-
ery status notifications instead of "relayed".
<b><a href="postconf.5.html#lmtp_tcp_port">lmtp_tcp_port</a> (24)</b>
The default TCP port that the Postfix LMTP client connects to.
<b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
- The maximum amount of time that an idle Postfix daemon process
+ The maximum amount of time that an idle Postfix daemon process
waits for an incoming connection before terminating voluntarily.
<b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
The process name of a Postfix command or daemon process.
<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b>
- The network interface addresses that this mail system receives
- mail on by way of a proxy or network address translation unit.
+ The remote network interface addresses that this mail system
+ receives mail on by way of a proxy or network address transla-
+ tion unit.
<b><a href="postconf.5.html#smtp_address_preference">smtp_address_preference</a> (any)</b>
The address type ("ipv6", "ipv4" or "any") that the Postfix SMTP
Available with Postfix 2.3 and later:
<b><a href="postconf.5.html#smtp_fallback_relay">smtp_fallback_relay</a> ($<a href="postconf.5.html#fallback_relay">fallback_relay</a>)</b>
- Optional list of relay hosts for SMTP destinations that can't be
- found or that are unreachable.
+ Optional list of relay destinations that will be used when an
+ SMTP destination is not found, or when delivery fails due to a
+ non-permanent error.
Available with Postfix 3.0 and later:
<b><a href="postconf.5.html#smtp_address_verify_target">smtp_address_verify_target</a> (rcpt)</b>
- In the context of email address verification, the SMTP protocol
+ In the context of email address verification, the SMTP protocol
stage that determines whether an email address is deliverable.
Available with Postfix 3.1 and later:
Available in Postfix 3.7 and later:
<b><a href="postconf.5.html#smtp_bind_address_enforce">smtp_bind_address_enforce</a> (no)</b>
- Defer delivery when the Postfix SMTP client cannot apply the
+ Defer delivery when the Postfix SMTP client cannot apply the
<a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> or <a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a> setting.
<b>SEE ALSO</b>
negated patterns.
<b>INLINE SPECIFICATION</b>
- The contents of a table may be specified in the table name. The basic
- syntax is:
+ The contents of a table may be specified in the table name (Postfix 3.7
+ and later). The basic syntax is:
<a href="postconf.5.html">main.cf</a>:
<i>parameter</i> <b>= .. <a href="pcre_table.5.html">pcre</a>:{ {</b> <i>rule-1</i> <b>}, {</b> <i>rule-2</i> <b>} .. } ..</b>
<p> The prioritized list of elliptic curves supported by the Postfix
SMTP client and server. These curves are used by the Postfix SMTP
-server when "<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> = auto". The selected curves
-must be implemented by OpenSSL and be standardized for use in TLS
-(<a href="https://tools.ietf.org/html/rfc8422">RFC 8422</a>). It is unwise to list only
-"bleeding-edge" curves supported by a small subset of clients. The
-default list is suitable for most users. </p>
+server when "<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> = auto". The selected curves must be
+implemented by OpenSSL and be standardized for use in TLS (<a href="https://tools.ietf.org/html/rfc8422">RFC 8422</a>).
+It is unwise to list only "bleeding-edge" curves supported by a small
+subset of clients. The default list is suitable for most users. </p>
<p> Postfix skips curve names that are unknown to OpenSSL, or that
are known but not yet implemented. This makes it possible to
in the default value of this parameter, even though they'll only
be usable with later versions of OpenSSL. </p>
+<p> See also the "<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>" parameter, which supports
+customizing the list of FFDHE groups enabled with TLS 1.3. That setting
+is introduced with Postfix 3.8, when built against OpenSSL 3.0 or later.
+</p>
+
<p> This feature is available in Postfix 3.2 and later, when it is
compiled and linked with OpenSSL 1.0.2 or later on platforms where
EC algorithms have not been disabled by the vendor. </p>
later. </p>
+</DD>
+
+<DT><b><a name="tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>
+(default: see "postconf -d" output)</b></DT><DD>
+
+<p> The prioritized list of finite-field Diffie-Hellman ephemeral
+(FFDHE) key exchange groups supported by the Postfix SMTP client and
+server. OpenSSL 3.0 adds support for FFDHE key agreement in TLS 1.3.
+In OpenSSL 1.1.1, TLS 1.3 was only supported with elliptic-curve based
+key agreement. The "<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>" parameter makes it possible
+to configure the list of FFDHE groups that the Postfix client or server
+will enable in OpenSSL 3.0 and up. This parameter has no effect when
+Postfix is built against earlier OpenSSL versions. </p>
+
+<p> The default list of FFDHE groups that Postfix enables in OpenSSL 3.0
+and up includes just the 2048 and 3072-bit groups. Stronger FFDHE
+groups perform poorly and EC groups are a much better choice for the
+same security level. Postfix ignores group names that are unknown to
+OpenSSL, or that are known but not yet implemented. The FFDHE groups
+are largely a backup, in case some peer does not support EC key
+exchange, or EC key exchange needs to be disabled for some pressing
+reason. </p>
+
+<p> Setting this parameter empty disables FFDHE support in TLS 1.3.
+Whether FFDHE key agreement is enabled in TLS 1.2 and earlier depends
+on whether any of the "kDHE" ciphers are included in the cipherlist.
+</p>
+
+<p> Conversely, setting "<a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a>" empty disables TLS 1.3
+EC key agreement in OpenSSL 3.0 and later. Note that at least one of
+"<a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a>" and "<a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a>" must be non-empty,
+this is required by OpenSSL 3.0. If both are inadvertently set empty,
+Postfix will fall back to the compiled-in defaults. </p>
+
+<p> All the default groups and EC curves should sufficiently strong
+to make "pruning" the defaults unwise. At a minimum, "X25519" and
+"P-256" (a.k.a. "prime256v1") should be among the enabled EC curves,
+while "dhe2048" and "dhe3072" should be among the FFDHE groups. </p>
+
+<p> This feature is available in Postfix 3.8 and later, when it is
+compiled and linked with OpenSSL 3.0 or later. </p>
+
+
</DD>
<DT><b><a name="tls_high_cipherlist">tls_high_cipherlist</a>
negated patterns.
<b>INLINE SPECIFICATION</b>
- The contents of a table may be specified in the table name. The basic
- syntax is:
+ The contents of a table may be specified in the table name (Postfix 3.7
+ and later). The basic syntax is:
<a href="postconf.5.html">main.cf</a>:
<i>parameter</i> <b>= .. <a href="regexp_table.5.html">regexp</a>:{ {</b> <i>rule-1</i> <b>}, {</b> <i>rule-2</i> <b>} .. } ..</b>
nexthop destination security level is <b>dane</b>, but the MX record
was found via an "insecure" MX lookup.
+ Available in Postfix version 3.2 and later:
+
+ <b><a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a> (see 'postconf -d' output)</b>
+ The prioritized list of elliptic curves supported by the Postfix
+ SMTP client and server.
+
Available in Postfix version 3.4 and later:
<b><a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> (no)</b>
Try to make multiple deliveries per TLS-encrypted connection.
<b><a href="postconf.5.html#smtp_tls_chain_files">smtp_tls_chain_files</a> (empty)</b>
- List of one or more PEM files, each holding one or more private
+ List of one or more PEM files, each holding one or more private
keys directly followed by a corresponding certificate chain.
<b><a href="postconf.5.html#smtp_tls_servername">smtp_tls_servername</a> (empty)</b>
- Optional name to send to the remote SMTP server in the TLS
+ Optional name to send to the remote SMTP server in the TLS
Server Name Indication (SNI) extension.
Available in Postfix 3.5, 3.4.6, 3.3.5, 3.2.10, 3.1.13 and later:
<b><a href="postconf.5.html#tls_fast_shutdown_enable">tls_fast_shutdown_enable</a> (yes)</b>
- A workaround for implementations that hang Postfix while shut-
+ A workaround for implementations that hang Postfix while shut-
ting down a TLS session, until Postfix times out.
+ Available in Postfix version 3.8 and later:
+
+ <b><a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a> (see 'postconf -d' output)</b>
+ The prioritized list of finite-field Diffie-Hellman ephemeral
+ (FFDHE) key exchange groups supported by the Postfix SMTP client
+ and server.
+
<b>OBSOLETE STARTTLS CONTROLS</b>
- The following configuration parameters exist for compatibility with
- Postfix versions before 2.3. Support for these will be removed in a
+ The following configuration parameters exist for compatibility with
+ Postfix versions before 2.3. Support for these will be removed in a
future release.
<b><a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> (no)</b>
- Opportunistic mode: use TLS when a remote SMTP server announces
+ Opportunistic mode: use TLS when a remote SMTP server announces
STARTTLS support, otherwise send the mail in the clear.
<b><a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> (no)</b>
- Enforcement mode: require that remote SMTP servers use TLS
+ Enforcement mode: require that remote SMTP servers use TLS
encryption, and never send mail in the clear.
<b><a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> (yes)</b>
- With mandatory TLS encryption, require that the remote SMTP
- server hostname matches the information in the remote SMTP
+ With mandatory TLS encryption, require that the remote SMTP
+ server hostname matches the information in the remote SMTP
server certificate.
<b><a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> (empty)</b>
- Optional lookup tables with the Postfix SMTP client TLS usage
- policy by next-hop destination and by remote SMTP server host-
+ Optional lookup tables with the Postfix SMTP client TLS usage
+ policy by next-hop destination and by remote SMTP server host-
name.
<b><a href="postconf.5.html#smtp_tls_cipherlist">smtp_tls_cipherlist</a> (empty)</b>
- Obsolete Postfix < 2.3 control for the Postfix SMTP client TLS
+ Obsolete Postfix < 2.3 control for the Postfix SMTP client TLS
cipher list.
<b>RESOURCE AND RATE CONTROLS</b>
<b><a href="postconf.5.html#smtp_connect_timeout">smtp_connect_timeout</a> (30s)</b>
- The Postfix SMTP client time limit for completing a TCP connec-
+ The Postfix SMTP client time limit for completing a TCP connec-
tion, or zero (use the operating system built-in time limit).
<b><a href="postconf.5.html#smtp_helo_timeout">smtp_helo_timeout</a> (300s)</b>
- The Postfix SMTP client time limit for sending the HELO or EHLO
- command, and for receiving the initial remote SMTP server
+ The Postfix SMTP client time limit for sending the HELO or EHLO
+ command, and for receiving the initial remote SMTP server
response.
<b><a href="postconf.5.html#lmtp_lhlo_timeout">lmtp_lhlo_timeout</a> (300s)</b>
mand, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_mail_timeout">smtp_mail_timeout</a> (300s)</b>
- The Postfix SMTP client time limit for sending the MAIL FROM
+ The Postfix SMTP client time limit for sending the MAIL FROM
command, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_rcpt_timeout">smtp_rcpt_timeout</a> (300s)</b>
- The Postfix SMTP client time limit for sending the SMTP RCPT TO
+ The Postfix SMTP client time limit for sending the SMTP RCPT TO
command, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_data_init_timeout">smtp_data_init_timeout</a> (120s)</b>
- The Postfix SMTP client time limit for sending the SMTP DATA
+ The Postfix SMTP client time limit for sending the SMTP DATA
command, and for receiving the remote SMTP server response.
<b><a href="postconf.5.html#smtp_data_xfer_timeout">smtp_data_xfer_timeout</a> (180s)</b>
- The Postfix SMTP client time limit for sending the SMTP message
+ The Postfix SMTP client time limit for sending the SMTP message
content.
<b><a href="postconf.5.html#smtp_data_done_timeout">smtp_data_done_timeout</a> (600s)</b>
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtp_mx_address_limit">smtp_mx_address_limit</a> (5)</b>
- The maximal number of MX (mail exchanger) IP addresses that can
- result from Postfix SMTP client mail exchanger lookups, or zero
+ The maximal number of MX (mail exchanger) IP addresses that can
+ result from Postfix SMTP client mail exchanger lookups, or zero
(no limit).
<b><a href="postconf.5.html#smtp_mx_session_limit">smtp_mx_session_limit</a> (2)</b>
- The maximal number of SMTP sessions per delivery request before
- the Postfix SMTP client gives up or delivers to a fall-back
+ The maximal number of SMTP sessions per delivery request before
+ the Postfix SMTP client gives up or delivers to a fall-back
<a href="postconf.5.html#relayhost">relay host</a>, or zero (no limit).
<b><a href="postconf.5.html#smtp_rset_timeout">smtp_rset_timeout</a> (20s)</b>
Available in Postfix version 2.2 and earlier:
<b><a href="postconf.5.html#lmtp_cache_connection">lmtp_cache_connection</a> (yes)</b>
- Keep
Postfix LMTP client connections open for up to $<a href="postconf.5.html#max_idle">max_idle</a>
+ Keep
Postfix LMTP client connections open for up to $<a href="postconf.5.html#max_idle">max_idle</a>
seconds.
Available in Postfix version 2.2 and later:
<b><a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> (empty)</b>
- Permanently enable SMTP connection caching for the specified
+ Permanently enable SMTP connection caching for the specified
destinations.
<b><a href="postconf.5.html#smtp_connection_cache_on_demand">smtp_connection_cache_on_demand</a> (yes)</b>
- Temporarily enable SMTP connection caching while a destination
+ Temporarily enable SMTP connection caching while a destination
has a high volume of mail in the <a href="QSHAPE_README.html#active_queue">active queue</a>.
<b><a href="postconf.5.html#smtp_connection_reuse_time_limit">smtp_connection_reuse_time_limit</a> (300s)</b>
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#connection_cache_protocol_timeout">connection_cache_protocol_timeout</a> (5s)</b>
- Time limit for connection cache connect, send or receive opera-
+ Time limit for connection cache connect, send or receive opera-
tions.
Available in Postfix version 2.9 - 3.6:
<b><a href="postconf.5.html#smtp_per_record_deadline">smtp_per_record_deadline</a> (no)</b>
- Change the behavior of the smtp_*_timeout time limits, from a
- time limit per read or write system call, to a time limit to
- send or receive a complete record (an SMTP command line, SMTP
- response line, SMTP message content line, or TLS protocol mes-
+ Change the behavior of the smtp_*_timeout time limits, from a
+ time limit per read or write system call, to a time limit to
+ send or receive a complete record (an SMTP command line, SMTP
+ response line, SMTP message content line, or TLS protocol mes-
sage).
Available in Postfix version 2.11 and later:
<b><a href="postconf.5.html#smtp_connection_reuse_count_limit">smtp_connection_reuse_count_limit</a> (0)</b>
- When SMTP connection caching is enabled, the number of times
- that an SMTP session may be reused before it is closed, or zero
+ When SMTP connection caching is enabled, the number of times
+ that an SMTP session may be reused before it is closed, or zero
(no limit).
Available in Postfix version 3.4 and later:
Available in Postfix version 3.7 and later:
<b><a href="postconf.5.html#smtp_per_request_deadline">smtp_per_request_deadline</a> (no)</b>
- Change the behavior of the smtp_*_timeout time limits, from a
- time limit per plaintext or TLS read or write call, to a com-
- bined time limit for sending a complete SMTP request and for
+ Change the behavior of the smtp_*_timeout time limits, from a
+ time limit per plaintext or TLS read or write call, to a com-
+ bined time limit for sending a complete SMTP request and for
receiving a complete SMTP response.
<b><a href="postconf.5.html#smtp_min_data_rate">smtp_min_data_rate</a> (500)</b>
- The minimum plaintext data transfer rate in bytes/second for
+ The minimum plaintext data transfer rate in bytes/second for
DATA requests, when deadlines are enabled with
<a href="postconf.5.html#smtp_per_request_deadline">smtp_per_request_deadline</a>.
<b><a href="postconf.5.html#transport_destination_concurrency_limit">transport_destination_concurrency_limit</a> ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concur</a>-</b>
<b><a href="postconf.5.html#default_destination_concurrency_limit">rency_limit</a>)</b>
- A
transport-specific override for the <a href="postconf.5.html#default_destination_concurrency_limit">default_destination_con</a>-
+ A
transport-specific override for the <a href="postconf.5.html#default_destination_concurrency_limit">default_destination_con</a>-
<a href="postconf.5.html#default_destination_concurrency_limit">currency_limit</a> parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a>
name of the message delivery transport.
<b><a href="postconf.5.html#transport_destination_recipient_limit">transport_destination_recipient_limit</a> ($<a href="postconf.5.html#default_destination_recipient_limit">default_destination_recipi</a>-</b>
<b><a href="postconf.5.html#default_destination_recipient_limit">ent_limit</a>)</b>
A transport-specific override for the <a href="postconf.5.html#default_destination_recipient_limit">default_destination_recip</a>-
- <a href="postconf.5.html#default_destination_recipient_limit">ient_limit</a>
parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a>
+ <a href="postconf.5.html#default_destination_recipient_limit">ient_limit</a>
parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a>
name of the message delivery transport.
<b>SMTPUTF8 CONTROLS</b>
Preliminary SMTPUTF8 support is introduced with Postfix 3.0.
<b><a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> (yes)</b>
- Enable preliminary SMTPUTF8 support for the protocols described
+ Enable preliminary SMTPUTF8 support for the protocols described
in <a href="https://tools.ietf.org/html/rfc6531">RFC 6531</a>, <a href="https://tools.ietf.org/html/rfc6532">RFC 6532</a>, and <a href="https://tools.ietf.org/html/rfc6533">RFC 6533</a>.
<b><a href="postconf.5.html#smtputf8_autodetect_classes">smtputf8_autodetect_classes</a> (sendmail, verify)</b>
- Detect that a message requires SMTPUTF8 support for the speci-
+ Detect that a message requires SMTPUTF8 support for the speci-
fied mail origin classes.
Available in Postfix version 3.2 and later:
<b><a href="postconf.5.html#enable_idna2003_compatibility">enable_idna2003_compatibility</a> (no)</b>
- Enable 'transitional' compatibility between IDNA2003 and
- IDNA2008, when converting UTF-8 domain names to/from the ASCII
+ Enable 'transitional' compatibility between IDNA2003 and
+ IDNA2008, when converting UTF-8 domain names to/from the ASCII
form that is used for DNS lookups.
<b>TROUBLE SHOOTING CONTROLS</b>
<b><a href="postconf.5.html#debug_peer_level">debug_peer_level</a> (2)</b>
- The increment in verbose logging level when a nexthop destina-
- tion, remote client or server name or network address matches a
+ The increment in verbose logging level when a nexthop destina-
+ tion, remote client or server name or network address matches a
pattern given with the <a href="postconf.5.html#debug_peer_list">debug_peer_list</a> parameter.
<b><a href="postconf.5.html#debug_peer_list">debug_peer_list</a> (empty)</b>
- Optional list of nexthop destination, remote client or server
- name or network address patterns that, if matched, cause the
- verbose logging level to increase by the amount specified in
+ Optional list of nexthop destination, remote client or server
+ name or network address patterns that, if matched, cause the
+ verbose logging level to increase by the amount specified in
$<a href="postconf.5.html#debug_peer_level">debug_peer_level</a>.
<b><a href="postconf.5.html#error_notice_recipient">error_notice_recipient</a> (postmaster)</b>
- The recipient of postmaster notifications about mail delivery
+ The recipient of postmaster notifications about mail delivery
problems that are caused by policy, resource, software or proto-
col errors.
<b><a href="postconf.5.html#internal_mail_filter_classes">internal_mail_filter_classes</a> (empty)</b>
- What categories of Postfix-generated mail are subject to
- before-queue
content inspection by <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>,
+ What categories of Postfix-generated mail are subject to
+ before-queue
content inspection by <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>,
<a href="postconf.5.html#header_checks">header_checks</a> and <a href="postconf.5.html#body_checks">body_checks</a>.
<b><a href="postconf.5.html#notify_classes">notify_classes</a> (resource, software)</b>
<b>MISCELLANEOUS CONTROLS</b>
<b><a href="postconf.5.html#best_mx_transport">best_mx_transport</a> (empty)</b>
- Where the Postfix SMTP client should deliver mail when it
+ Where the Postfix SMTP client should deliver mail when it
detects a "mail loops back to myself" error condition.
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
+ The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
figuration files.
<b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
- How much time a Postfix daemon process may take to handle a
+ How much time a Postfix daemon process may take to handle a
request before it is terminated by a built-in watchdog timer.
<b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
- The maximal number of digits after the decimal point when log-
+ The maximal number of digits after the decimal point when log-
ging sub-second delay values.
<b><a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> (no)</b>
Disable DNS lookups in the Postfix SMTP and LMTP clients.
<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b>
- The network interface addresses that this mail system receives
- mail on.
+ The local network interface addresses that this mail system
+ receives mail on.
<b><a href="postconf.5.html#inet_protocols">inet_protocols</a> (see 'postconf -d output')</b>
- The Internet protocols Postfix will attempt to use when making
+ The Internet protocols Postfix will attempt to use when making
or accepting connections.
<b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
- The time limit for sending or receiving information over an
+ The time limit for sending or receiving information over an
internal communication channel.
<b><a href="postconf.5.html#lmtp_assume_final">lmtp_assume_final</a> (no)</b>
- When a remote LMTP server announces no DSN support, assume that
- the server performs final delivery, and send "delivered" deliv-
+ When a remote LMTP server announces no DSN support, assume that
+ the server performs final delivery, and send "delivered" deliv-
ery status notifications instead of "relayed".
<b><a href="postconf.5.html#lmtp_tcp_port">lmtp_tcp_port</a> (24)</b>
The default TCP port that the Postfix LMTP client connects to.
<b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
- The maximum amount of time that an idle Postfix daemon process
+ The maximum amount of time that an idle Postfix daemon process
waits for an incoming connection before terminating voluntarily.
<b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
The process name of a Postfix command or daemon process.
<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b>
- The network interface addresses that this mail system receives
- mail on by way of a proxy or network address translation unit.
+ The remote network interface addresses that this mail system
+ receives mail on by way of a proxy or network address transla-
+ tion unit.
<b><a href="postconf.5.html#smtp_address_preference">smtp_address_preference</a> (any)</b>
The address type ("ipv6", "ipv4" or "any") that the Postfix SMTP
Available with Postfix 2.3 and later:
<b><a href="postconf.5.html#smtp_fallback_relay">smtp_fallback_relay</a> ($<a href="postconf.5.html#fallback_relay">fallback_relay</a>)</b>
- Optional list of relay hosts for SMTP destinations that can't be
- found or that are unreachable.
+ Optional list of relay destinations that will be used when an
+ SMTP destination is not found, or when delivery fails due to a
+ non-permanent error.
Available with Postfix 3.0 and later:
<b><a href="postconf.5.html#smtp_address_verify_target">smtp_address_verify_target</a> (rcpt)</b>
- In the context of email address verification, the SMTP protocol
+ In the context of email address verification, the SMTP protocol
stage that determines whether an email address is deliverable.
Available with Postfix 3.1 and later:
Available in Postfix 3.7 and later:
<b><a href="postconf.5.html#smtp_bind_address_enforce">smtp_bind_address_enforce</a> (no)</b>
- Defer delivery when the Postfix SMTP client cannot apply the
+ Defer delivery when the Postfix SMTP client cannot apply the
<a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> or <a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a> setting.
<b>SEE ALSO</b>
The email address form that will be used in non-debug logging
(info, warning, etc.).
+ Available in Postfix version 3.8 and later:
+
+ <b><a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a> (see 'postconf -d' output)</b>
+ The prioritized list of finite-field Diffie-Hellman ephemeral
+ (FFDHE) key exchange groups supported by the Postfix SMTP client
+ and server.
+
<b>OBSOLETE STARTTLS CONTROLS</b>
The following configuration parameters exist for compatibility with
Postfix versions before 2.3. Support for these will be removed in a
A workaround for implementations that hang Postfix while shut-
ting down a TLS session, until Postfix times out.
+ Available in Postfix version 3.8 and later:
+
+ <b><a href="postconf.5.html#tls_ffdhe_auto_groups">tls_ffdhe_auto_groups</a> (see 'postconf -d' output)</b>
+ The prioritized list of finite-field Diffie-Hellman ephemeral
+ (FFDHE) key exchange groups supported by the Postfix SMTP client
+ and server.
+
<b>STARTTLS SERVER CONTROLS</b>
These settings are clones of Postfix SMTP server settings. They allow
<a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> to load the same certificate and private key information as
?.*|10.*) ;;
*) SYSLIBS="$SYSLIBS -lresolv";;
esac
+ # Darwin 21 linker without additional coaxing complains about
+ # -Wl,-undefined,dynamic_lookup
+ case $RELEASE in
+ 2[1-9].*|[3-9]?.*) NOFIXUP="-Wl,-no_fixup_chains ";;
+ *) NOFIXUP="";;
+ esac
# kqueue and/or poll are broken in MacOS X 10.5 (Darwin 9).
# kqueue works in Mac OS X 10.8 (Darwin 12).
case $RELEASE in
esac
: ${SHLIB_CFLAGS=-fPIC}
: ${SHLIB_SUFFIX=.dylib}
- : ${SHLIB_LD='cc -shared -Wl,-flat_namespace -Wl,-undefined,dynamic_lookup -Wl,-install_name,@rpath/${LIB}'}
+ : ${SHLIB_LD="cc -shared -Wl,-flat_namespace ${NOFIXUP}-Wl,-undefined,dynamic_lookup "'-Wl,-install_name,@rpath/${LIB}'}
: ${SHLIB_RPATH='-Wl,-rpath,${SHLIB_DIR}'}
# In MacOS/X 10.11.x /bin/sh unsets DYLD_LIBRARY_PATH, so we
# have export it into postfix-install indirectly!
: ${SHLIB_ENV="DYLD_LIBRARY_PATH=`pwd`/lib SHLIB_ENV_VAR=DYLD_LIBRARY_PATH SHLIB_ENV_VAL=`pwd`/lib"}
- : ${PLUGIN_LD='cc -shared -Wl,-flat_namespace -Wl,-undefined,dynamic_lookup'}
+ : ${PLUGIN_LD="cc -shared -Wl,-flat_namespace ${NOFIXUP}-Wl,-undefined,dynamic_lookup"}
;;
dcosx.1*) SYSTYPE=DCOSX1
RANLIB=echo
.nf
.ad
.fi
-The contents of a table may be specified in the table name.
+The contents of a table may be specified in the table name
+(Postfix 3.7 and later).
The basic syntax is:
.nf
.nf
.ad
.fi
-The contents of a table may be specified in the table name.
+The contents of a table may be specified in the table name
+(Postfix 3.7 and later).
The basic syntax is:
.nf
.SH tls_eecdh_auto_curves (default: see "postconf \-d" output)
The prioritized list of elliptic curves supported by the Postfix
SMTP client and server. These curves are used by the Postfix SMTP
-server when "smtpd_tls_eecdh_grade = auto". The selected curves
-must be implemented by OpenSSL and be standardized for use in TLS
-(RFC 8422). It is unwise to list only
-"bleeding\-edge" curves supported by a small subset of clients. The
-default list is suitable for most users.
+server when "smtpd_tls_eecdh_grade = auto". The selected curves must be
+implemented by OpenSSL and be standardized for use in TLS (RFC 8422).
+It is unwise to list only "bleeding\-edge" curves supported by a small
+subset of clients. The default list is suitable for most users.
.PP
Postfix skips curve names that are unknown to OpenSSL, or that
are known but not yet implemented. This makes it possible to
in the default value of this parameter, even though they'll only
be usable with later versions of OpenSSL.
.PP
+See also the "tls_ffdhe_auto_groups" parameter, which supports
+customizing the list of FFDHE groups enabled with TLS 1.3. That setting
+is introduced with Postfix 3.8, when built against OpenSSL 3.0 or later.
+.PP
This feature is available in Postfix 3.2 and later, when it is
compiled and linked with OpenSSL 1.0.2 or later on platforms where
EC algorithms have not been disabled by the vendor.
Postfix will not wait for the remote TLS peer to respond to a TLS
\&'close' notification. This behavior is recommended for TLSv1.0 and
later.
+.SH tls_ffdhe_auto_groups (default: see "postconf \-d" output)
+The prioritized list of finite\-field Diffie\-Hellman ephemeral
+(FFDHE) key exchange groups supported by the Postfix SMTP client and
+server. OpenSSL 3.0 adds support for FFDHE key agreement in TLS 1.3.
+In OpenSSL 1.1.1, TLS 1.3 was only supported with elliptic\-curve based
+key agreement. The "tls_ffdhe_auto_groups" parameter makes it possible
+to configure the list of FFDHE groups that the Postfix client or server
+will enable in OpenSSL 3.0 and up. This parameter has no effect when
+Postfix is built against earlier OpenSSL versions.
+.PP
+The default list of FFDHE groups that Postfix enables in OpenSSL 3.0
+and up includes just the 2048 and 3072\-bit groups. Stronger FFDHE
+groups perform poorly and EC groups are a much better choice for the
+same security level. Postfix ignores group names that are unknown to
+OpenSSL, or that are known but not yet implemented. The FFDHE groups
+are largely a backup, in case some peer does not support EC key
+exchange, or EC key exchange needs to be disabled for some pressing
+reason.
+.PP
+Setting this parameter empty disables FFDHE support in TLS 1.3.
+Whether FFDHE key agreement is enabled in TLS 1.2 and earlier depends
+on whether any of the "kDHE" ciphers are included in the cipherlist.
+.PP
+Conversely, setting "tls_eecdh_auto_curves" empty disables TLS 1.3
+EC key agreement in OpenSSL 3.0 and later. Note that at least one of
+"tls_eecdh_auto_curves" and "tls_ffdhe_auto_groups" must be non\-empty,
+this is required by OpenSSL 3.0. If both are inadvertently set empty,
+Postfix will fall back to the compiled\-in defaults.
+.PP
+All the default groups and EC curves should sufficiently strong
+to make "pruning" the defaults unwise. At a minimum, "X25519" and
+"P\-256" (a.k.a. "prime256v1") should be among the enabled EC curves,
+while "dhe2048" and "dhe3072" should be among the FFDHE groups.
+.PP
+This feature is available in Postfix 3.8 and later, when it is
+compiled and linked with OpenSSL 3.0 or later.
.SH tls_high_cipherlist (default: see "postconf \-d" output)
The OpenSSL cipherlist for "high" grade ciphers. This defines
the meaning of the "high" setting in smtpd_tls_ciphers,
.nf
.ad
.fi
-The contents of a table may be specified in the table name.
+The contents of a table may be specified in the table name
+(Postfix 3.7 and later).
The basic syntax is:
.nf
nexthop destination security level is \fBdane\fR, but the MX
record was found via an "insecure" MX lookup.
.PP
+Available in Postfix version 3.2 and later:
+.IP "\fBtls_eecdh_auto_curves (see 'postconf -d' output)\fR"
+The prioritized list of elliptic curves supported by the Postfix
+SMTP client and server.
+.PP
Available in Postfix version 3.4 and later:
.IP "\fBsmtp_tls_connection_reuse (no)\fR"
Try to make multiple deliveries per TLS\-encrypted connection.
.IP "\fBtls_fast_shutdown_enable (yes)\fR"
A workaround for implementations that hang Postfix while shutting
down a TLS session, until Postfix times out.
+.PP
+Available in Postfix version 3.8 and later:
+.IP "\fBtls_ffdhe_auto_groups (see 'postconf -d' output)\fR"
+The prioritized list of finite\-field Diffie\-Hellman ephemeral
+(FFDHE) key exchange groups supported by the Postfix SMTP client and
+server.
.SH "OBSOLETE STARTTLS CONTROLS"
.na
.nf
.IP "\fBdisable_dns_lookups (no)\fR"
Disable DNS lookups in the Postfix SMTP and LMTP clients.
.IP "\fBinet_interfaces (all)\fR"
-The network interface addresses that this mail system receives
+The local network interface addresses that this mail system receives
mail on.
.IP "\fBinet_protocols (see 'postconf -d output')\fR"
The Internet protocols Postfix will attempt to use when making
.IP "\fBprocess_name (read\-only)\fR"
The process name of a Postfix command or daemon process.
.IP "\fBproxy_interfaces (empty)\fR"
-The network interface addresses that this mail system receives mail
+The remote network interface addresses that this mail system receives mail
on by way of a proxy or network address translation unit.
.IP "\fBsmtp_address_preference (any)\fR"
The address type ("ipv6", "ipv4" or "any") that the Postfix
.PP
Available with Postfix 2.3 and later:
.IP "\fBsmtp_fallback_relay ($fallback_relay)\fR"
-Optional list of relay hosts for SMTP destinations that can't be
-found or that are unreachable.
+Optional list of relay destinations that will be used when an
+SMTP destination is not found, or when delivery fails due to a
+non\-permanent error.
.PP
Available with Postfix 3.0 and later:
.IP "\fBsmtp_address_verify_target (rcpt)\fR"
.IP "\fBinfo_log_address_format (external)\fR"
The email address form that will be used in non\-debug logging
(info, warning, etc.).
+.PP
+Available in Postfix version 3.8 and later:
+.IP "\fBtls_ffdhe_auto_groups (see 'postconf -d' output)\fR"
+The prioritized list of finite\-field Diffie\-Hellman ephemeral
+(FFDHE) key exchange groups supported by the Postfix SMTP client and
+server.
.SH "OBSOLETE STARTTLS CONTROLS"
.na
.nf
.IP "\fBtls_fast_shutdown_enable (yes)\fR"
A workaround for implementations that hang Postfix while shutting
down a TLS session, until Postfix times out.
+.PP
+Available in Postfix version 3.8 and later:
+.IP "\fBtls_ffdhe_auto_groups (see 'postconf -d' output)\fR"
+The prioritized list of finite\-field Diffie\-Hellman ephemeral
+(FFDHE) key exchange groups supported by the Postfix SMTP client and
+server.
.SH "STARTTLS SERVER CONTROLS"
.na
.nf
s;\btls_eecdh_auto_curves\b;<a href="postconf.5.html#tls_eecdh_auto_curves">$&</a>;g;
s;\btls_eecdh_strong_curve\b;<a href="postconf.5.html#tls_eecdh_strong_curve">$&</a>;g;
s;\btls_eecdh_ultra_curve\b;<a href="postconf.5.html#tls_eecdh_ultra_curve">$&</a>;g;
+ s;\btls_ffdhe_auto_groups\b;<a href="postconf.5.html#tls_ffdhe_auto_groups">$&</a>;g;
s;\btls_preempt_cipherlist\b;<a href="postconf.5.html#tls_preempt_cipherlist">$&</a>;g;
s;\btls_disable_workarounds\b;<a href="postconf.5.html#tls_disable_workarounds">$&</a>;g;
s;\btls_append_default_CA\b;<a href="postconf.5.html#tls_append_default_CA">$&</a>;g;
server's RSA public key. The server decrypts this with its private
key, and uses it together with other data exchanged in the clear
to generate the session key. An attacker with access to the server's
-private key can perform the same computation at any later time.
-The TLS library in Windows XP and Windows Server 2003 only supported
-cipher suites of this type, and Exchange 2003 servers largely do
-not support forward secrecy. </p>
+private key can perform the same computation at any later time. </p>
<p> Later revisions to the TLS protocol introduced forward-secrecy
cipher suites in which the client and server implement a key exchange
<ul>
-<li> <p> <b> Prime-field groups (EDH):</b> The server needs to be
-configured with a suitably-large prime and a corresponding "generator".
-The acronym for forward secrecy over prime fields is EDH for Ephemeral
-Diffie-Hellman (also abbreviated as DHE).
-</p>
-
-<li> <p> <b> Elliptic-curve groups (EECDH): </b> The server needs
-to be configured with a "named curve". These offer better security
-at lower computational cost than prime field groups, but are not
-as widely implemented. The acronym for the elliptic curve version
-is EECDH which is short for Ephemeral Elliptic Curve Diffie-Hellman
-(also abbreviated as ECDHE). </p>
+<li> <p> <b>FFDHE:</b> Finite-field Diffie-Hellman ephemeral key
+exchange groups (also EDH or DHE). The server needs to be configured
+with a suitably-large prime and a corresponding "generator". Standard
+choices of the prime and generator are specified in RFC7919, and can be
+used in the TLS 1.3 protocol with the server and client negotiating a
+mutually supported choice. In earlier versions of TLS (1.0 through
+1.2), when FFDHE key exchange is performed, the server chooses the prime
+and generator unilaterally. </p>
+
+<li> <p> <b>EECDH:</b> This is short for Ephemeral Elliptic Curve
+Diffie-Hellman (also abbreviated as ECDHE). EECDH offers better
+security at lower computational cost than FFDHE. Elliptic curves used
+in cryptography are typically identified by a "name" that stands for a
+set of well-known parameter values, and it is these "named curves" (or,
+in certificates, associated ASN.1 object identifiers) that are used in
+the TLS protocol. When EECDH key exchange is used, a mutually supported
+named curve is negotiated as part of the TLS handshake. </p>
</ul>
-<p> It is not essential to know what these are, but one does need
-to know that OpenSSL supports EECDH with version 1.0.0 or later.
-Thus the configuration parameters related to Elliptic-Curve forward
-secrecy are available when Postfix is linked with OpenSSL ≥ 1.0.0
-(provided EC support has not been disabled by the vendor, as in
-some versions of RedHat Linux). </p>
-
-<p> Elliptic curves used in cryptography are typically identified
-by a "name" that stands for a set of well-known parameter values,
-and it is these "names" (or associated ASN.1 object identifiers)
-that are used in the TLS protocol. On the other hand, with TLS there
-are no specially designated prime field groups, so each server is
-free to select its own suitably-strong prime and generator. </p>
-
<h2><a name="server_fs">Forward Secrecy in the Postfix SMTP Server</a></h2>
<p> The Postfix ≥ 2.2 SMTP server supports forward secrecy in
and client will resist decryption even if the server's long-term
authentication keys are <i>later</i> compromised. </p>
-<p> Some remote SMTP clients may support forward secrecy, but prefer
-cipher suites <i>without</i> forward secrecy. In that case, Postfix
-≥ 2.8 could be configured to ignore the client's preference with
-the main.cf setting "tls_preempt_cipherlist = yes". However, this
-will likely cause interoperability issues with older Exchange servers
-and is not recommended for now. </p>
-
-<h3> EDH Server support </h3>
-
-<p> Postfix ≥ 2.2 supports 1024-bit-prime EDH out of the box,
-with no additional configuration, but you may want to override the
-default prime to be 2048 bits long, and you may want to regenerate
-your primes periodically. See the <a href="#quick-start">quick-start</a>
-section for details. With Postfix ≥ 3.1 the out of the box
-(compiled-in) EDH prime size is 2048 bits. </p>
-
-<p> With prime-field EDH, OpenSSL wants the server to provide
-two explicitly-selected (prime, generator) combinations. One for
-the now long-obsolete "export" cipher suites, and another for
-non-export cipher suites. Postfix has two such default combinations
-compiled in, but also supports explicitly-configured overrides.
-</p>
-
-<ul>
-
-<li> <p> The "export" EDH parameters are used only with the obsolete
-"export" ciphers. To use a non-default prime, generate a 512-bit
-DH parameter file and set smtpd_tls_dh512_param_file to the filename
-(see the <a href="#quick-start">quick-start</a> section for details).
-With Postfix releases after the middle of 2015 the default opportunistic
-TLS cipher grade (smtpd_tls_ciphers) is "medium" or stronger, and
-export ciphers are no longer used. </p>
-
-<li> <p> The non-export EDH parameters are used for all other EDH
-cipher suites. To use a non-default prime, generate a 1024-bit or
-2048-bit DH parameter file and set smtpd_tls_dh1024_param_file to
-the filename. Despite the name this is simply the non-export
-parameter file and the prime need not actually be 1024 bits long
-(see the <a href="#quick-start">quick-start</a> section for details).
-</p>
-
-</ul>
-
-<p> As of mid-2015, SMTP clients are starting to reject TLS
-handshakes with primes smaller than 2048 bits. Each site needs to
-determine which prime size works best for the majority of its
-clients. See the <a href="#quick-start">quick-start</a> section
-for the recommended configuration to work around this issue. </p>
+<p> Most remote SMTP clients now support forward secrecy (the only
+choice as of TLS 1.3), but some may prefer cipher suites <i>without</i>
+forward secrecy. Postfix ≥ 2.8 servers can be configured to override
+the client's preference by setting "tls_preempt_cipherlist = yes". </p>
+
+<h3> FFDHE Server support </h3>
+
+<p> Postfix ≥ 3.1 supports 2048-bit-prime FFDHE out of the box, with
+no additional configuration. You can also generate your own FFDHE
+parameters, but this is not necessary and no longer recommended. See
+the <a href="#quick-start">quick-start</a> section for details. </p>
+
+<p> Postfix ≥ 3.8 supports the finite-field Diffie-Hellman ephemeral
+(FFDHE) key exchange group negotiation API of OpenSSL ≥ 3.0. FFDHE
+groups are explicitly negotiated between client and server starting with
+TLS 1.3. In earlier TLS versions, the server chooses the group
+unilaterally. The list of candidate FFDHE groups can be configured via
+"tls_ffdhe_auto_groups", which can be used to select a prioritized list
+of supported groups (most preferred first) on both the server and
+client. The default list is suitable for most users. Either, but not
+both of "tls_eecdh_auto_curves" and "tls_ffdhe_auto_groups" may be set
+empty, disabling either EC or FFDHE key exchange in OpenSSL 3.0 with TLS
+1.3. That said, interoperability will be poor if the EC curves are
+all disabled or don't include the most widely used curves. </p>
<h3> EECDH Server support </h3>
-<p> Postfix ≥ 2.6 supports NIST P-256 EECDH when built with OpenSSL
-≥ 1.0.0. When the remote SMTP client also supports EECDH and
-implements the P-256 curve, forward secrecy just works. </p>
-
-<blockquote> <p> Note: With Postfix 2.6 and 2.7, enable EECDH by
-setting the main.cf parameter smtpd_tls_eecdh_grade to "strong".
-</p> </blockquote>
-
-<p> The elliptic curve standards are evolving, with new curves
-introduced in RFC 8031 to augment or replace the NIST curves tarnished
-by the Snowden revelations. Fortunately, TLS clients advertise
-their list of supported curves to the server so that servers can
-choose newer stronger curves when mutually supported. OpenSSL 1.0.2
-released in January 2015 was the first release to implement negotiation
-of supported curves in TLS servers. In older OpenSSL releases, the
-server is limited to selecting a single widely supported curve. </p>
-
-<p> With Postfix prior to 3.2 or OpenSSL prior to 1.0.2, only a
-single server-side curve can be configured, by specifying a suitable
-EECDH "grade": </p>
-
-<blockquote>
-<pre>
- smtpd_tls_eecdh_grade = strong | ultra
- # Underlying curves, best not changed:
- # tls_eecdh_strong_curve = prime256v1
- # tls_eecdh_ultra_curve = secp384r1
-</pre>
-</blockquote>
-
-<p> Postfix ≥ 3.2 supports the curve negotiation API of OpenSSL
-≥ 1.0.2. When using this software combination, the default setting
-of "smtpd_tls_eecdh_grade" changes to "auto", which selects a curve
-that is supported by both the server and client. The list of
-candidate curves can be configured via "tls_eecdh_auto_curves",
-which can be used to configure a prioritized list of supported
-curves (most preferred first) on both the server and client.
-The default list is suitable for most users. </p>
+<p> As of Postfix 3.2 and OpenSSL 1.0.2, a range of supported EECDH
+curves is enabled in the server and client, and a suitable mutually
+supported curve is negotiated as part of the TLS handshake. The list of
+supported curves is configurable via the "tls_eecdh_auto_curves"
+parameter. With TLS 1.2 the server needs to leave its setting of
+"smtpd_tls_eecdh_grade" at the default value of "auto" (earlier choices
+of an explicit single curve grade are deprecated). With TLS 1.3, the
+"smtpd_tls_eecdh_grade" parameter is not used, and curve selection is
+unconditionally negotiated. </p>
<h2> <a name="client_fs">Forward Secrecy in the Postfix SMTP Client</a> </h2>
-<p> The Postfix ≥ 2.2 SMTP client supports forward secrecy in
-its default configuration. All supported OpenSSL releases support
-EDH key exchange. OpenSSL releases ≥ 1.0.0 also support EECDH
-key exchange (provided elliptic-curve support has not been disabled
-by the vendor as in some versions of RedHat Linux). If the
-remote SMTP server supports cipher suites with forward secrecy (and
-does not override the SMTP client's cipher preference), then the
-traffic between the server and client will resist decryption even
-if the server's long-term authentication keys are <i>later</i>
-compromised. </p>
+<p> The Postfix ≥ 2.2 SMTP client supports forward secrecy in its
+default configuration. All supported OpenSSL releases support both
+FFDHE and EECDH key exchange. If the remote SMTP server supports cipher
+suites with forward secrecy (and does not override the SMTP client's
+cipher preference), then the traffic between the server and client will
+resist decryption even if the server's long-term authentication keys are
+<i>later</i> compromised. Forward secrecy is always on in TLS 1.3. </p>
<p> Postfix ≥ 3.2 supports the curve negotiation API of OpenSSL
≥ 1.0.2. The list of candidate curves can be changed via the
first) on both the Postfix SMTP server and SMTP client. The default
list is suitable for most users. </p>
-<p> The default Postfix SMTP client cipher lists are correctly
-ordered to prefer EECDH and EDH cipher suites ahead of similar
-cipher suites that don't implement forward secrecy. Administrators
-are strongly discouraged from changing the cipher list definitions. </p>
+<p> Postfix ≥ 3.8 supports the finite-field Diffie-Hellman ephemeral
+(FFDHE) key exchange group negotiation API of OpenSSL ≥ 3.0.
+The list of candidate FFDHE groups can be configured via
+"tls_ffdhe_auto_groups", which can be used to select a prioritized list
+of supported groups (most preferred first) on both the server and
+client. The default list is suitable for most users. </p>
-<p> The default minimum cipher grade for opportunistic TLS is
-"medium" for Postfix releases after the middle of 2015, "export"
-for older releases. Changing the minimum cipher grade does not
-change the cipher preference order. Note that cipher grades higher
-than "medium" exclude Exchange 2003 and likely other MTAs, thus a
-"high" cipher grade should be chosen only on a case-by-case basis
-via the <a href="TLS_README.html#client_tls_policy">TLS policy</a>
-table. </p>
+<p> The default Postfix SMTP client cipher lists are correctly ordered
+to prefer EECDH and FFDHE cipher suites ahead of similar cipher suites
+that don't implement forward secrecy. Administrators are strongly
+discouraged from changing the cipher list definitions. </p>
<h2><a name="quick-start">Getting started, quick and dirty</a></h2>
-<h3> EECDH Client support (Postfix ≥ 2.2 with OpenSSL ≥ 1.0.0) </h3>
+<h3> EECDH Client support (Postfix ≥ 3.2 with OpenSSL ≥ 1.1.1) </h3>
<p> This works "out of the box" with no need for additional
configuration. </p>
first) on both the Postfix SMTP server and SMTP client. The default
list is suitable for most users. </p>
-<h3> EECDH Server support (Postfix ≥ 2.6 with OpenSSL ≥ 1.0.0) </h3>
-
-<p> With Postfix 2.6 and 2.7, enable elliptic-curve support in the
-Postfix SMTP server. This is the default with Postfix
-≥ 2.8. Note, however, that elliptic-curve support may be disabled
-by the vendor, as in some versions of RedHat Linux. </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- # Postfix 2.6 & 2.7 only. EECDH is on by default with Postfix ≥ 2.8.
- # The default grade is "auto" with Postfix ≥ 3.2.
- smtpd_tls_eecdh_grade = strong
-</pre>
-</blockquote>
-
-<h3> EDH Client support (Postfix ≥ 2.2, all supported OpenSSL
-versions) </h3>
-
-<p> This works "out of the box" without additional configuration. </p>
-
-<h3> EDH Server support (Postfix ≥ 2.2, all supported OpenSSL
-versions) </h3>
+<h3> EECDH Server support (Postfix ≥ 3.2 with OpenSSL ≥ 1.1.1) </h3>
-<p> Optionally generate non-default Postfix SMTP server EDH parameters
-for improved security against pre-computation attacks and for
-compatibility with Debian-patched Exim SMTP clients that require a
-≥ 2048-bit length for the non-export prime. </p>
-
-<p> With Postfix ≥ 3.7 built against OpenSSL version is 3.0.0 or later, when
-the value of smtpd_tls_dh1024_param_file is either empty or "<b>auto</b>", the
-EDH parameter selection is delegated to the OpenSSL library, which selects
-appropriate parameters based on the TLS handshake. This choice is likely to be
-the most interoperable with SMTP clients using various TLS libraries, and
-custom local parameters are no longer recommended when using Postfix ≥ 3.7
-built against OpenSSL 3.0.0. Just leave smtpd_tls_dh1024_param_file at its
-default value (both in main.cf(5) and any master.cf(5) overrides, and let
-OpenSSL do the work. </p>
-
-<p> Otherwise, execute as root (prime group generation can take a
-few seconds to a few minutes): </p>
-
-<blockquote>
-<pre>
-# cd /etc/postfix
-# umask 022
-# openssl dhparam -out dh512.tmp 512 && mv dh512.tmp dh512.pem
-# openssl dhparam -out dh1024.tmp 1024 && mv dh1024.tmp dh1024.pem
-# openssl dhparam -out dh2048.tmp 2048 && mv dh2048.tmp dh2048.pem
-# chmod 644 dh512.pem dh1024.pem dh2048.pem
-</pre>
-</blockquote>
+<p> This works "out of the box" with no need for additional
+configuration. </p>
-<p> The Postfix SMTP server EDH parameter files are not secret,
-after all these parameters are sent to all remote SMTP clients in
-the clear. Mode 0644 is appropriate. </p>
+<p> Postfix ≥ 3.2 supports the curve negotiation API of OpenSSL
+≥ 1.0.2. The list of candidate curves can be changed via the
+"tls_eecdh_auto_curves" configuration parameter, which can be used
+to select a prioritized list of supported curves (most preferred
+first) on both the Postfix SMTP server and SMTP client. The default
+list is suitable for most users. </p>
-<p> You can improve security against pre-computation attacks further
-by regenerating the Postfix SMTP server EDH parameters periodically
-(an hourly or daily cron job running the above commands as root can
-automate this task). </p>
+<h3> FFDHE Client support (Postfix ≥ 3.2, OpenSSL ≥ 1.1.1) </h3>
-<p> Once the parameters are in place, update main.cf as follows: </p>
+<p> In Postfix < 3.8, or OpenSSL prior to 3.0, FFDHE for TLS 1.2 or
+below works "out of the box", no additional configuration is necessary.
+The most one can do is (not advisable) disable all "kDHE" ciphers, which
+would then disable FFDHE key exchange in TLS 1.2 and below. </p>
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtpd_tls_dh1024_param_file = ${config_directory}/dh2048.pem
- smtpd_tls_dh512_param_file = ${config_directory}/dh512.pem
-</pre>
-</blockquote>
+<p> With OpenSSL 1.1.1, FFDHE is not supported for TLS 1.3, which uses
+only EECDH key exchange. Support for FFDHE with TLS 1.3 was added in
+OpenSSL 3.0. With OpenSSL 3.0 and Postfix 3.8 the list of supported TLS
+1.3 FFDHE groups becomes configurable via the "tls_ffdhe_auto_groups"
+parameter, which can be set empty to disable FFDHE in TLS 1.3, or
+conversely expanded to support more groups. The default should work
+well for most users. </p>
-<p> If some of your MSA clients don't support 2048-bit EDH, you may
-need to adjust the submission entry in master.cf accordingly: </p>
+<h3> FFDHE Server support (Postfix ≥ 2.2, all supported OpenSSL
+versions) </h3>
-<blockquote>
-<pre>
-/etc/postfix/master.cf:
- submission inet n - n - - smtpd
- # Some submission clients may not yet do 2048-bit EDH, if such
- # clients use your MSA, configure 1024-bit EDH instead. However,
- # as of mid-2015, many submission clients no longer accept primes
- # with less than 2048-bits. Each site needs to determine which
- # type of client is more important to support.
- -o smtpd_tls_dh1024_param_file=${config_directory}/dh1024.pem
- -o smtpd_tls_security_level=encrypt
- -o smtpd_sasl_auth_enable=yes
- ...
-</pre>
-</blockquote>
+<p> In Postfix < 3.8, or OpenSSL prior to 3.0, FFDHE for TLS 1.2 or
+below works "out of the box", no additional configuration is necessary.
+One can of course (not advisable) disable all "kDHE" ciphers, which
+would then disable FFDHE key exchange in TLS 1.2 and below. </p>
+
+<p> The built-in default Postfix FFDHE group is a 2048-bit group as of
+Postfix 3.1. You can optionally generate non-default Postfix SMTP
+server FFDHE parameters for possibly improved security against
+pre-computation attacks, but this is not necessary or recommended. Just
+leave "smtpd_tls_dh1024_param_file" at its default empty value. </p>
+
+<p> The set of FFDHE groups enabled for use with TLS 1.3 becomes
+configurable with Postfix ≥ 3.8 and OpenSSL ≥ 3.0. The default
+setting of "tls_ffdhe_auto_groups" enables the RFC7919 2048 and 3072-bit
+groups. If you need more security, you should probably be using EECDH.
+</p>
<h2><a name="test">How can I see that a connection has forward
secrecy? </a> </h2>
# INLINE SPECIFICATION
# .ad
# .fi
-# The contents of a table may be specified in the table name.
+# The contents of a table may be specified in the table name
+# (Postfix 3.7 and later).
# The basic syntax is:
#
# .nf
# INLINE SPECIFICATION
# .ad
# .fi
-# The contents of a table may be specified in the table name.
+# The contents of a table may be specified in the table name
+# (Postfix 3.7 and later).
# The basic syntax is:
#
# .nf
<p> The prioritized list of elliptic curves supported by the Postfix
SMTP client and server. These curves are used by the Postfix SMTP
-server when "smtpd_tls_eecdh_grade = auto". The selected curves
-must be implemented by OpenSSL and be standardized for use in TLS
-(RFC 8422). It is unwise to list only
-"bleeding-edge" curves supported by a small subset of clients. The
-default list is suitable for most users. </p>
+server when "smtpd_tls_eecdh_grade = auto". The selected curves must be
+implemented by OpenSSL and be standardized for use in TLS (RFC 8422).
+It is unwise to list only "bleeding-edge" curves supported by a small
+subset of clients. The default list is suitable for most users. </p>
<p> Postfix skips curve names that are unknown to OpenSSL, or that
are known but not yet implemented. This makes it possible to
in the default value of this parameter, even though they'll only
be usable with later versions of OpenSSL. </p>
+<p> See also the "tls_ffdhe_auto_groups" parameter, which supports
+customizing the list of FFDHE groups enabled with TLS 1.3. That setting
+is introduced with Postfix 3.8, when built against OpenSSL 3.0 or later.
+</p>
+
<p> This feature is available in Postfix 3.2 and later, when it is
compiled and linked with OpenSSL 1.0.2 or later on platforms where
EC algorithms have not been disabled by the vendor. </p>
+%PARAM tls_ffdhe_auto_groups see "postconf -d" output
+
+<p> The prioritized list of finite-field Diffie-Hellman ephemeral
+(FFDHE) key exchange groups supported by the Postfix SMTP client and
+server. OpenSSL 3.0 adds support for FFDHE key agreement in TLS 1.3.
+In OpenSSL 1.1.1, TLS 1.3 was only supported with elliptic-curve based
+key agreement. The "tls_ffdhe_auto_groups" parameter makes it possible
+to configure the list of FFDHE groups that the Postfix client or server
+will enable in OpenSSL 3.0 and up. This parameter has no effect when
+Postfix is built against earlier OpenSSL versions. </p>
+
+<p> The default list of FFDHE groups that Postfix enables in OpenSSL 3.0
+and up includes just the 2048 and 3072-bit groups. Stronger FFDHE
+groups perform poorly and EC groups are a much better choice for the
+same security level. Postfix ignores group names that are unknown to
+OpenSSL, or that are known but not yet implemented. The FFDHE groups
+are largely a backup, in case some peer does not support EC key
+exchange, or EC key exchange needs to be disabled for some pressing
+reason. </p>
+
+<p> Setting this parameter empty disables FFDHE support in TLS 1.3.
+Whether FFDHE key agreement is enabled in TLS 1.2 and earlier depends
+on whether any of the "kDHE" ciphers are included in the cipherlist.
+</p>
+
+<p> Conversely, setting "tls_eecdh_auto_curves" empty disables TLS 1.3
+EC key agreement in OpenSSL 3.0 and later. Note that at least one of
+"tls_eecdh_auto_curves" and "tls_ffdhe_auto_groups" must be non-empty,
+this is required by OpenSSL 3.0. If both are inadvertently set empty,
+Postfix will fall back to the compiled-in defaults. </p>
+
+<p> All the default groups and EC curves should sufficiently strong
+to make "pruning" the defaults unwise. At a minimum, "X25519" and
+"P-256" (a.k.a. "prime256v1") should be among the enabled EC curves,
+while "dhe2048" and "dhe3072" should be among the FFDHE groups. </p>
+
+<p> This feature is available in Postfix 3.8 and later, when it is
+compiled and linked with OpenSSL 3.0 or later. </p>
+
%PARAM tls_eecdh_strong_curve prime256v1
<p> The elliptic curve used by the Postfix SMTP server for sensibly
# INLINE SPECIFICATION
# .ad
# .fi
-# The contents of a table may be specified in the table name.
+# The contents of a table may be specified in the table name
+# (Postfix 3.7 and later).
# The basic syntax is:
#
# .nf
manpage File postqueue postqueue c
Fix by Viktor Dukhovni Files tls tls h tls tls_dane c
Discovered by Benny Pedersen File postscreen postscreen c
+ proto postconf proto src tlsproxy tlsproxy c src smtpd smtpd c
+ proto postconf proto src tlsproxy tlsproxy c src smtpd smtpd c
+ src tls tls h src tls tls_proxy_client_misc c src tls tls_misc c
+ src global mail_params h src smtp smtp c
deduplicate
digestbyname
mdctxPtr
+ffdhe
Pedersen
Typofixes
segfault
+Biggs
+wordsmithing
rsyslogd
hardcode
pattern's
+FFDHE
+dhe
+ffdhe
+kDHE
#define DEF_TLS_EECDH_ULTRA "secp384r1"
extern char *var_tls_eecdh_ultra;
+#if defined(SN_ffdhe2048) && defined(NID_ffdhe2048)
+#define DEF_TLS_FFDHE_AUTO_1 SN_ffdhe2048 " "
+#else
+#define DEF_TLS_FFDHE_AUTO_1 ""
+#endif
+#if defined(SN_ffdhe3072) && defined(NID_ffdhe3072)
+#define DEF_TLS_FFDHE_AUTO_2 SN_ffdhe3072 " "
+#else
+#define DEF_TLS_FFDHE_AUTO_2 ""
+#endif
+
+#define VAR_TLS_FFDHE_AUTO "tls_ffdhe_auto_groups"
+#define DEF_TLS_FFDHE_AUTO DEF_TLS_FFDHE_AUTO_1 \
+ DEF_TLS_FFDHE_AUTO_2
+extern char *var_tls_ffdhe_auto;
+
#define VAR_TLS_PREEMPT_CLIST "tls_preempt_cipherlist"
#define DEF_TLS_PREEMPT_CLIST 0
extern bool var_tls_preempt_clist;
* Patches change both the patchlevel and the release date. Snapshots have no
* patchlevel; they change the release date only.
*/
-#define MAIL_RELEASE_DATE "20221228"
+#define MAIL_RELEASE_DATE "20230108"
#define MAIL_VERSION_NUMBER "3.8"
#ifdef SNAPSHOT
/* nexthop destination security level is \fBdane\fR, but the MX
/* record was found via an "insecure" MX lookup.
/* .PP
+/* Available in Postfix version 3.2 and later:
+/* .IP "\fBtls_eecdh_auto_curves (see 'postconf -d' output)\fR"
+/* The prioritized list of elliptic curves supported by the Postfix
+/* SMTP client and server.
+/* .PP
/* Available in Postfix version 3.4 and later:
/* .IP "\fBsmtp_tls_connection_reuse (no)\fR"
/* Try to make multiple deliveries per TLS-encrypted connection.
/* .IP "\fBtls_fast_shutdown_enable (yes)\fR"
/* A workaround for implementations that hang Postfix while shutting
/* down a TLS session, until Postfix times out.
+/* .PP
+/* Available in Postfix version 3.8 and later:
+/* .IP "\fBtls_ffdhe_auto_groups (see 'postconf -d' output)\fR"
+/* The prioritized list of finite-field Diffie-Hellman ephemeral
+/* (FFDHE) key exchange groups supported by the Postfix SMTP client and
+/* server.
/* OBSOLETE STARTTLS CONTROLS
/* .ad
/* .fi
/* .IP "\fBdisable_dns_lookups (no)\fR"
/* Disable DNS lookups in the Postfix SMTP and LMTP clients.
/* .IP "\fBinet_interfaces (all)\fR"
-/* The network interface addresses that this mail system receives
+/* The local network interface addresses that this mail system receives
/* mail on.
/* .IP "\fBinet_protocols (see 'postconf -d output')\fR"
/* The Internet protocols Postfix will attempt to use when making
/* .IP "\fBprocess_name (read-only)\fR"
/* The process name of a Postfix command or daemon process.
/* .IP "\fBproxy_interfaces (empty)\fR"
-/* The network interface addresses that this mail system receives mail
+/* The remote network interface addresses that this mail system receives mail
/* on by way of a proxy or network address translation unit.
/* .IP "\fBsmtp_address_preference (any)\fR"
/* The address type ("ipv6", "ipv4" or "any") that the Postfix
/* .PP
/* Available with Postfix 2.3 and later:
/* .IP "\fBsmtp_fallback_relay ($fallback_relay)\fR"
-/* Optional list of relay hosts for SMTP destinations that can't be
-/* found or that are unreachable.
+/* Optional list of relay destinations that will be used when an
+/* SMTP destination is not found, or when delivery fails due to a
+/* non-permanent error.
/* .PP
/* Available with Postfix 3.0 and later:
/* .IP "\fBsmtp_address_verify_target (rcpt)\fR"
/* .IP "\fBinfo_log_address_format (external)\fR"
/* The email address form that will be used in non-debug logging
/* (info, warning, etc.).
+/* .PP
+/* Available in Postfix version 3.8 and later:
+/* .IP "\fBtls_ffdhe_auto_groups (see 'postconf -d' output)\fR"
+/* The prioritized list of finite-field Diffie-Hellman ephemeral
+/* (FFDHE) key exchange groups supported by the Postfix SMTP client and
+/* server.
/* OBSOLETE STARTTLS CONTROLS
/* .ad
/* .fi
*/
extern void tls_set_dh_from_file(const char *);
extern void tls_tmp_dh(SSL_CTX *, int);
-extern void tls_auto_eecdh_curves(SSL_CTX *, const char *);
+extern void tls_auto_groups(SSL_CTX *, const char *, const char *);
/*
* tls_verify.c
/*
* With OpenSSL 1.0.2 and later the client EECDH curve list becomes
* configurable with the preferred curve negotiated via the supported
- * curves extension.
+ * curves extension. With OpenSSL 3.0 and TLS 1.3, the same applies
+ * to the FFDHE groups which become part of a unified "groups" list.
*/
- tls_auto_eecdh_curves(client_ctx, var_tls_eecdh_auto);
+ tls_auto_groups(client_ctx, var_tls_eecdh_auto, var_tls_ffdhe_auto);
/*
* Finally, the setup for the server certificate checking, done "by the
/* void tls_set_dh_from_file(path)
/* const char *path;
/*
-/* void tls_auto_eecdh_curves(ctx, configured)
+/* void tls_auto_groups(ctx, eecdh, ffdhe)
/* SSL_CTX *ctx;
-/* char *configured;
+/* char *eecdh;
+/* char *ffdhe;
/*
/* void tls_tmp_dh(ctx, useauto)
/* SSL_CTX *ctx;
/* This module maintains parameters for Diffie-Hellman key generation.
/*
/* tls_tmp_dh() returns the configured or compiled-in FFDHE
-/* group parameters.
+/* group parameters. The useauto argument enables OpenSSL-builtin group
+/* selection in preference to our own compiled-in group. This may
+/* interoperate better with overly strict peers that accept only
+/* "standard" groups.
/*
/* tls_set_dh_from_file() overrides compiled-in DH parameters
/* with those specified in the named files. The file format
/* is as expected by the PEM_read_DHparams() routine.
/*
-/* tls_auto_eecdh_curves() enables negotiation of the most preferred curve
-/* among the curves specified by the "configured" argument. The useauto
-/* argument enables OpenSSL-builtin group selection in preference to our
-/* own compiled-in group. This may interoperate better with overly strict
-/* peers that accept only "standard" groups (bogus threat model).
+/* tls_auto_groups() enables negotiation of the most preferred key
+/* exchange group among those specified by the "eecdh" and "ffdhe"
+/* arguments. The "ffdhe" argument is only used with OpenSSL 3.0
+/* and later, and applies to TLS 1.3 and up.
/* DIAGNOSTICS
/* In case of error, tls_set_dh_from_file() logs a warning and
/* ignores the request.
/* ------------------------------------- Common API */
-void tls_auto_eecdh_curves(SSL_CTX *ctx, const char *configured)
+#define AG_STAT_OK (0)
+#define AG_STAT_NO_GROUP (-1) /* no usable group, may retry */
+#define AG_STAT_NO_RETRY (-2) /* other error, don't retry */
+
+static int setup_auto_groups(SSL_CTX *ctx, const char *origin,
+ const char *eecdh,
+ const char *ffdhe)
{
#ifndef OPENSSL_NO_ECDH
SSL_CTX *tmpctx;
int *nids;
- int space = 5;
+ int space = 10;
int n = 0;
- int unknown = 0;
char *save;
- char *curves;
- char *curve;
+ char *groups;
+ char *group;
if ((tmpctx = SSL_CTX_new(TLS_method())) == 0) {
- msg_warn("cannot allocate temp SSL_CTX, using default ECDHE curves");
+ msg_warn("cannot allocate temp SSL_CTX");
tls_print_errors();
- return;
+ return (AG_STAT_NO_RETRY);
}
nids = mymalloc(space * sizeof(int));
- curves = save = mystrdup(configured);
-#define RETURN do { \
+
+#define SETUP_AG_RETURN(val) do { \
myfree(save); \
myfree(nids); \
SSL_CTX_free(tmpctx); \
- return; \
+ return (val); \
} while (0)
- while ((curve = mystrtok(&curves, CHARS_COMMA_SP)) != 0) {
- int nid = EC_curve_nist2nid(curve);
+ groups = save = concatenate(eecdh, " ", ffdhe, NULL);
+ if ((group = mystrtok(&groups, CHARS_COMMA_SP)) == 0) {
+ msg_warn("no %s key exchange group - OpenSSL requires at least one",
+ origin);
+ SETUP_AG_RETURN(AG_STAT_NO_GROUP);
+ }
+ for (; group != 0; group = mystrtok(&groups, CHARS_COMMA_SP)) {
+ int nid = EC_curve_nist2nid(group);
if (nid == NID_undef)
- nid = OBJ_sn2nid(curve);
+ nid = OBJ_sn2nid(group);
if (nid == NID_undef)
- nid = OBJ_ln2nid(curve);
+ nid = OBJ_ln2nid(group);
if (nid == NID_undef) {
- msg_warn("ignoring unknown ECDHE curve \"%s\"",
- curve);
+ msg_warn("ignoring unknown key exchange group \"%s\"", group);
continue;
}
/*
- * Validate the NID by trying it as the sole EC curve for a
- * throw-away SSL context. Silently skip unsupported code points.
- * This way, we can list X25519 and X448 as soon as the nids are
- * assigned, and before the supporting code is implemented. They'll
- * be silently skipped when not yet supported.
+ * Validate the NID by trying it as the group for a throw-away SSL
+ * context. Silently skip unsupported code points. This way, we can
+ * list X25519 and X448 as soon as the nids are assigned, and before
+ * the supporting code is implemented. They'll be silently skipped
+ * when not yet supported.
*/
if (SSL_CTX_set1_curves(tmpctx, &nid, 1) <= 0) {
- ++unknown;
continue;
}
if (++n > space) {
}
if (n == 0) {
- if (unknown > 0)
- msg_warn("none of the configured ECDHE curves are supported");
- RETURN;
+ /* The names may be case-sensitive */
+ msg_warn("none of the %s key exchange groups are supported", origin);
+ SETUP_AG_RETURN(AG_STAT_NO_GROUP);
}
if (SSL_CTX_set1_curves(ctx, nids, n) <= 0) {
- msg_warn("failed to configure ECDHE curves");
+ msg_warn("failed to set up the %s key exchange groups", origin);
tls_print_errors();
- RETURN;
+ SETUP_AG_RETURN(AG_STAT_NO_RETRY);
+ }
+ SETUP_AG_RETURN(AG_STAT_OK);
+#endif
+}
+
+void tls_auto_groups(SSL_CTX *ctx, const char *eecdh, const char *ffdhe)
+{
+#ifndef OPENSSL_NO_ECDH
+ char *def_eecdh = DEF_TLS_EECDH_AUTO;
+
+#if OPENSSL_VERSION_PREREQ(3, 0)
+ char *def_ffdhe = DEF_TLS_FFDHE_AUTO;
+
+#else
+ char *def_ffdhe = "";
+
+ /* Has no effect prior to OpenSSL 3.0 */
+ ffdhe = def_ffdhe;
+#endif
+ const char *origin;
+
+ /*
+ * Try the user-specified list first. If that fails (empty list or no
+ * known group name), try again with the Postfix defaults. We assume that
+ * group selection is mere performance tuning and not security critical.
+ * All the groups supported for negotiation should be strong enough.
+ */
+ for (origin = "configured"; /* void */ ; /* void */) {
+ switch (setup_auto_groups(ctx, origin, eecdh, ffdhe)) {
+ case AG_STAT_OK:
+ return;
+ case AG_STAT_NO_GROUP:
+ if (strcmp(eecdh, def_eecdh) != 0
+ || strcmp(ffdhe, def_ffdhe) != 0) {
+ msg_warn("using Postfix default key exchange groups instead");
+ origin = "Postfix default";
+ eecdh = def_eecdh;
+ ffdhe = def_ffdhe;
+ break;
+ }
+ /* FALLTHROUGH */
+ default:
+ msg_warn("using OpenSSL default key exchange groups instead");
+ return;
+ }
}
- RETURN;
#endif
}
/* char *var_tls_eecdh_auto;
/* char *var_tls_eecdh_strong;
/* char *var_tls_eecdh_ultra;
+/* char *var_tls_ffdhe_auto;
/* char *var_tls_dane_digests;
/* int var_tls_daemon_rand_bytes;
/* bool var_tls_append_def_CA;
char *var_tls_eecdh_auto;
char *var_tls_eecdh_strong;
char *var_tls_eecdh_ultra;
+char *var_tls_ffdhe_auto;
char *var_tls_dane_digests;
bool var_tls_append_def_CA;
char *var_tls_bug_tweaks;
VAR_TLS_LOW_CLIST, DEF_TLS_LOW_CLIST, &var_tls_low_clist, 1, 0,
VAR_TLS_EXPORT_CLIST, DEF_TLS_EXPORT_CLIST, &var_tls_export_clist, 1, 0,
VAR_TLS_NULL_CLIST, DEF_TLS_NULL_CLIST, &var_tls_null_clist, 1, 0,
- VAR_TLS_EECDH_AUTO, DEF_TLS_EECDH_AUTO, &var_tls_eecdh_auto, 1, 0,
+ VAR_TLS_EECDH_AUTO, DEF_TLS_EECDH_AUTO, &var_tls_eecdh_auto, 0, 0,
VAR_TLS_EECDH_STRONG, DEF_TLS_EECDH_STRONG, &var_tls_eecdh_strong, 1, 0,
VAR_TLS_EECDH_ULTRA, DEF_TLS_EECDH_ULTRA, &var_tls_eecdh_ultra, 1, 0,
+ VAR_TLS_FFDHE_AUTO, DEF_TLS_FFDHE_AUTO, &var_tls_ffdhe_auto, 0, 0,
VAR_TLS_BUG_TWEAKS, DEF_TLS_BUG_TWEAKS, &var_tls_bug_tweaks, 0, 0,
VAR_TLS_SSL_OPTIONS, DEF_TLS_SSL_OPTIONS, &var_tls_ssl_options, 0, 0,
VAR_TLS_DANE_DIGESTS, DEF_TLS_DANE_DIGESTS, &var_tls_dane_digests, 1, 0,
char *tls_eecdh_auto;
char *tls_eecdh_strong;
char *tls_eecdh_ultra;
+ char *tls_ffdhe_auto;
char *tls_bug_tweaks;
char *tls_ssl_options;
char *tls_dane_digests;
} TLS_CLIENT_PARAMS;
#define TLS_PROXY_PARAMS(params, a1, a2, a3, a4, a5, a6, a7, a8, \
- a9, a10, a11, a12, a13, a14, a15, a16, a17, a18) \
+ a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19) \
(((params)->a1), ((params)->a2), ((params)->a3), \
((params)->a4), ((params)->a5), ((params)->a6), ((params)->a7), \
((params)->a8), ((params)->a9), ((params)->a10), ((params)->a11), \
((params)->a12), ((params)->a13), ((params)->a14), ((params)->a15), \
- ((params)->a16), ((params)->a17), ((params)->a18))
+ ((params)->a16), ((params)->a17), ((params)->a18), ((params)->a19))
/*
* tls_proxy_client_param_misc.c, tls_proxy_client_param_print.c, and
tls_eecdh_auto = var_tls_eecdh_auto,
tls_eecdh_strong = var_tls_eecdh_strong,
tls_eecdh_ultra = var_tls_eecdh_ultra,
+ tls_ffdhe_auto = var_tls_ffdhe_auto,
tls_bug_tweaks = var_tls_bug_tweaks,
tls_ssl_options = var_tls_ssl_options,
tls_dane_digests = var_tls_dane_digests,
params->tls_eecdh_strong),
SEND_ATTR_STR(VAR_TLS_EECDH_ULTRA,
params->tls_eecdh_ultra),
+ SEND_ATTR_STR(VAR_TLS_FFDHE_AUTO, params->tls_ffdhe_auto),
SEND_ATTR_STR(VAR_TLS_BUG_TWEAKS, params->tls_bug_tweaks),
SEND_ATTR_STR(VAR_TLS_SSL_OPTIONS,
params->tls_ssl_options),
myfree(params->tls_eecdh_auto);
myfree(params->tls_eecdh_strong);
myfree(params->tls_eecdh_ultra);
+ myfree(params->tls_ffdhe_auto);
myfree(params->tls_bug_tweaks);
myfree(params->tls_ssl_options);
myfree(params->tls_dane_digests);
VSTRING *tls_eecdh_auto = vstring_alloc(25);
VSTRING *tls_eecdh_strong = vstring_alloc(25);
VSTRING *tls_eecdh_ultra = vstring_alloc(25);
+ VSTRING *tls_ffdhe_auto = vstring_alloc(25);
VSTRING *tls_bug_tweaks = vstring_alloc(25);
VSTRING *tls_ssl_options = vstring_alloc(25);
VSTRING *tls_dane_digests = vstring_alloc(25);
RECV_ATTR_STR(VAR_TLS_EECDH_AUTO, tls_eecdh_auto),
RECV_ATTR_STR(VAR_TLS_EECDH_STRONG, tls_eecdh_strong),
RECV_ATTR_STR(VAR_TLS_EECDH_ULTRA, tls_eecdh_ultra),
+ RECV_ATTR_STR(VAR_TLS_FFDHE_AUTO, tls_ffdhe_auto),
RECV_ATTR_STR(VAR_TLS_BUG_TWEAKS, tls_bug_tweaks),
RECV_ATTR_STR(VAR_TLS_SSL_OPTIONS, tls_ssl_options),
RECV_ATTR_STR(VAR_TLS_DANE_DIGESTS, tls_dane_digests),
params->tls_eecdh_auto = vstring_export(tls_eecdh_auto);
params->tls_eecdh_strong = vstring_export(tls_eecdh_strong);
params->tls_eecdh_ultra = vstring_export(tls_eecdh_ultra);
+ params->tls_ffdhe_auto = vstring_export(tls_ffdhe_auto);
params->tls_bug_tweaks = vstring_export(tls_bug_tweaks);
params->tls_ssl_options = vstring_export(tls_ssl_options);
params->tls_dane_digests = vstring_export(tls_dane_digests);
params->tls_mgr_service = vstring_export(tls_mgr_service);
params->tls_tkt_cipher = vstring_export(tls_tkt_cipher);
- ret = (ret == 18 ? 1 : -1);
+ ret = (ret == 19 ? 1 : -1);
if (ret != 1) {
tls_proxy_client_param_free(params);
params = 0;
tls_tmp_dh(sni_ctx, 1);
/*
- * Enable EECDH if available, errors are not fatal, we just keep going
- * with any remaining key-exchange algorithms.
+ * Enable EECDH if available, errors are not fatal, we just keep going with
+ * any remaining key-exchange algorithms. With OpenSSL 3.0 and TLS 1.3,
+ * the same applies to the FFDHE groups which become part of a unified
+ * "groups" list.
*/
- tls_auto_eecdh_curves(server_ctx, var_tls_eecdh_auto);
- tls_auto_eecdh_curves(sni_ctx, var_tls_eecdh_auto);
+ tls_auto_groups(server_ctx, var_tls_eecdh_auto, var_tls_ffdhe_auto);
+ tls_auto_groups(sni_ctx, var_tls_eecdh_auto, var_tls_ffdhe_auto);
/*
* If we want to check client certificates, we have to indicate it in
/* .IP "\fBtls_fast_shutdown_enable (yes)\fR"
/* A workaround for implementations that hang Postfix while shutting
/* down a TLS session, until Postfix times out.
+/* .PP
+/* Available in Postfix version 3.8 and later:
+/* .IP "\fBtls_ffdhe_auto_groups (see 'postconf -d' output)\fR"
+/* The prioritized list of finite-field Diffie-Hellman ephemeral
+/* (FFDHE) key exchange groups supported by the Postfix SMTP client and
+/* server.
/* STARTTLS SERVER CONTROLS
/* .ad
/* .fi
/* Log cache statistics after each cache cleanup run.
/* .RE
/* .IP "CA_DICT_CACHE_CTL_INTERVAL(int interval)"
-/* The interval between cache cleanup runs. Specify a null
-/* validator or interval to stop cache cleanup.
+/* The interval between cache cleanup runs. Specify a null
+/* validator or interval to stop cache cleanup and log cache
+/* statistics if a cleanup run was in progress.
/* .IP "CA_DICT_CACHE_CTL_VALIDATOR(DICT_CACHE_VALIDATOR_FN validator)"
/* An application call-back routine that returns non-zero when
/* a cache entry should be kept. The call-back function should
void dict_cache_close(DICT_CACHE *cp)
{
+ /*
+ * Cancel the cache cleanup thread. This also logs (and resets)
+ * statistics for a scan that is in progress.
+ */
+ dict_cache_control(cp, DICT_CACHE_CTL_INTERVAL, 0, DICT_CACHE_CTL_END);
+
/*
* Destroy the DICT_CACHE object.
*/
myfree(cp->name);
- dict_cache_control(cp, DICT_CACHE_CTL_INTERVAL, 0, DICT_CACHE_CTL_END);
dict_close(cp->db);
if (cp->saved_curr_key)
myfree(cp->saved_curr_key);
projects / thirdparty / postfix.git / commitdiff
