path: root/README_FILES/FORWARD_SECRECY_README

 TTLLSS FFoorrwwaarrdd SSeeccrreeccyy iinn PPoossttffiixx

-------------------------------------------------------------------------------

WWaarrnniinngg

Forward secrecy does not protect against active attacks such as forged DNS
replies or forged TLS server certificates. If such attacks are a concern, then
the SMTP client will need to authenticate the remote SMTP server in a
sufficiently-secure manner. For example, by the fingerprint of a (CA or leaf)
public key or certificate. Conventional PKI relies on many trusted parties and
is easily subverted by a state-funded adversary.

OOvveerrvviieeww

Postfix supports forward secrecy of TLS network communication since version
2.2. This support was adopted from Lutz Ja"nicke's "Postfix TLS patch" for
earlier Postfix versions. This document will focus on TLS Forward Secrecy in
the Postfix SMTP client and server. See TLS_README for a general description of
Postfix TLS support.

Topics covered in this document:

  * Give me some background on forward secrecy in Postfix

      o What is Forward Secrecy
      o Forward Secrecy in TLS
      o Forward Secrecy in the Postfix SMTP Server
      o Forward Secrecy in the Postfix SMTP Client

  * Never mind, just show me what it takes to get forward secrecy

      o Getting started, quick and dirty
      o How can I see that a connection has forward secrecy?
      o What ciphers provide forward secrecy?
      o What do "Anonymous", "Untrusted", etc. in Postfix logging mean?

  * Credits

WWhhaatt iiss FFoorrwwaarrdd SSeeccrreeccyy

The term "Forward Secrecy" (or sometimes "Perfect Forward Secrecy") is used to
describe security protocols in which the confidentiality of past traffic is not
compromised when long-term keys used by either or both sides are later
disclosed.

Forward secrecy is accomplished by negotiating session keys using per-session
cryptographically-strong random numbers that are not saved, and signing the
exchange with long-term authentication keys. Later disclosure of the long-term
keys allows impersonation of the key holder from that point on, but not
recovery of prior traffic, since with forward secrecy, the discarded random key
agreement inputs are not available to the attacker.

Forward secrecy is only "perfect" when brute-force attacks on the key agreement
algorithm are impractical even for the best-funded adversary and the random-
number generators used by both parties are sufficiently strong. Otherwise,
forward secrecy leaves the attacker with the challenge of cracking the key-
agreement protocol, which is likely quite computationally intensive, but may be
feasible for sessions of sufficiently high value. Thus forward secrecy places
cost constraints on the efficacy of bulk surveillance, recovering all past
traffic is generally infeasible, and even recovery of individual sessions may
be infeasible given a sufficiently-strong key agreement method.

FFoorrwwaarrdd SSeeccrreeccyy iinn TTLLSS

Early implementations of the SSL protocol do not provide forward secrecy (some
provide it only with artificially-weakened "export" cipher suites, but we will
ignore those here). The client sends a random "pre-master secret" to the server
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.

Later revisions to the TLS protocol introduced forward-secrecy cipher suites in
which the client and server implement a key exchange protocol based on
ephemeral secrets. Sessions encrypted with one of these newer cipher suites are
not compromised by future disclosure of long-term authentication keys.

The key-exchange algorithms used for forward secrecy require the TLS server to
designate appropriate "parameters" consisting of a mathematical "group" and an
element of that group called a "generator". Presently, there are two flavors of
"groups" that work with PFS:

  * FFFFDDHHEE:: 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.

  * EEEECCDDHH:: 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.

FFoorrwwaarrdd SSeeccrreeccyy iinn tthhee PPoossttffiixx SSMMTTPP SSeerrvveerr

The Postfix >= 2.2 SMTP server supports forward secrecy in its default
configuration. If the remote SMTP client prefers cipher suites with forward
secrecy, then the traffic between the server and client will resist decryption
even if the server's long-term authentication keys are later compromised.

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".

FFFFDDHHEE SSeerrvveerr ssuuppppoorrtt

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.

EEEECCDDHH SSeerrvveerr ssuuppppoorrtt

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.

FFoorrwwaarrdd SSeeccrreeccyy iinn tthhee PPoossttffiixx SSMMTTPP CClliieenntt

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 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"
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.

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 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.

GGeettttiinngg ssttaarrtteedd,, qquuiicckk aanndd ddiirrttyy

EEEECCDDHH CClliieenntt ssuuppppoorrtt ((PPoossttffiixx >>== 33..22 wwiitthh OOppeennSSSSLL >>== 11..11..11))

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.

EEEECCDDHH SSeerrvveerr ssuuppppoorrtt ((PPoossttffiixx >>== 33..22 wwiitthh OOppeennSSSSLL >>== 11..11..11))

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.

FFFFDDHHEE CClliieenntt ssuuppppoorrtt ((PPoossttffiixx >>== 33..22,, OOppeennSSSSLL >>== 11..11..11))

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.

FFFFDDHHEE SSeerrvveerr ssuuppppoorrtt ((PPoossttffiixx >>== 22..22,, aallll ssuuppppoorrtteedd OOppeennSSSSLL vveerrssiioonnss))

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.

HHooww ccaann II sseeee tthhaatt aa ccoonnnneeccttiioonn hhaass ffoorrwwaarrdd sseeccrreeccyy??

Postfix can be configured to report information about the negotiated cipher,
the corresponding key lengths, and the remote peer certificate or public-key
verification status.

  * With "smtp_tls_loglevel = 1" and "smtpd_tls_loglevel = 1", the Postfix SMTP
    client and server will log TLS connection information to the maillog file.
    The general logfile format is shown below. With TLS 1.3 there may be
    additional properties logged after the cipher name and bits.

        postfix/smtp[process-id]: Untrusted TLS connection established
        to host.example.com[192.168.0.2]:25: TLSv1 with cipher cipher-name
        (actual-key-size/raw-key-size bits)

        postfix/smtpd[process-id]: Anonymous TLS connection established
        from host.example.com[192.168.0.2]: TLSv1 with cipher cipher-name
        (actual-key-size/raw-key-size bits)

  * With "smtpd_tls_received_header = yes", the Postfix SMTP server will record
    TLS connection information in the Received: header in the form of comments
    (text inside parentheses). The general format depends on the
    smtpd_tls_ask_ccert setting. With TLS 1.3 there may be additional
    properties logged after the cipher name and bits.

        Received: from host.example.com (host.example.com [192.168.0.2])
                (using TLSv1 with cipher cipher-name
                (actual-key-size/raw-key-size bits))
                (Client CN "host.example.com", Issuer "John Doe" (not
        verified))

        Received: from host.example.com (host.example.com [192.168.0.2])
                (using TLSv1 with cipher cipher-name
                (actual-key-size/raw-key-size bits))
                (No client certificate requested)

    TLS 1.3 examples. Some of the new attributes may not appear when not
    applicable or not available in older versions of the OpenSSL library.

        Received: from localhost (localhost [127.0.0.1])
                (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256
        bits)
                 key-exchange X25519 server-signature RSA-PSS (2048 bits)
        server-digest SHA256)
                (No client certificate requested)

        Received: from localhost (localhost [127.0.0.1])
                (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256
        bits)
                 key-exchange X25519 server-signature RSA-PSS (2048 bits)
        server-digest SHA256
                 client-signature ECDSA (P-256) client-digest SHA256)
                (Client CN "example.org", Issuer "example.org" (not verified))

      o The "key-exchange" attribute records the type of "Diffie-Hellman" group
        used for key agreement. Possible values include "DHE", "ECDHE",
        "X25519" and "X448". With "DHE", the bit size of the prime will be
        reported in parentheses after the algorithm name, with "ECDHE", the
        curve name.

      o The "server-signature" attribute shows the public key signature
        algorithm used by the server. With "RSA-PSS", the bit size of the
        modulus will be reported in parentheses. With "ECDSA", the curve name.
        If, for example, the server has both an RSA and an ECDSA private key
        and certificate, it will be possible to track which one was used for a
        given connection.

      o The new "server-digest" attribute records the digest algorithm used by
        the server to prepare handshake messages for signing. The Ed25519 and
        Ed448 signature algorithms do not make use of such a digest, so no
        "server-digest" will be shown for these signature algorithms.

      o When a client certificate is requested with "smtpd_tls_ask_ccert" and
        the client uses a TLS client-certificate, the "client-signature" and
        "client-digest" attributes will record the corresponding properties of
        the client's TLS handshake signature.

The next sections will explain what cipher-name, key-size, and peer
verification status information to expect.

WWhhaatt cciipphheerrss pprroovviiddee ffoorrwwaarrdd sseeccrreeccyy??

There are dozens of ciphers that support forward secrecy. What follows is the
beginning of a list of 51 ciphers available with OpenSSL 1.0.1e. The list is
sorted in the default Postfix preference order. It excludes null ciphers that
only authenticate and don't encrypt, together with export and low-grade ciphers
whose encryption is too weak to offer meaningful secrecy. The first column
shows the cipher name, and the second shows the key exchange method.

    $ openssl ciphers -v \
            'aNULL:-aNULL:kEECDH:kEDH:+RC4:!eNULL:!EXPORT:!LOW:@STRENGTH' |
        awk '{printf "%-32s %s\n", $1, $3}'
    AECDH-AES256-SHA                 Kx=ECDH
    ECDHE-RSA-AES256-GCM-SHA384      Kx=ECDH
    ECDHE-ECDSA-AES256-GCM-SHA384    Kx=ECDH
    ECDHE-RSA-AES256-SHA384          Kx=ECDH
    ECDHE-ECDSA-AES256-SHA384        Kx=ECDH
    ECDHE-RSA-AES256-SHA             Kx=ECDH
    ECDHE-ECDSA-AES256-SHA           Kx=ECDH
    ADH-AES256-GCM-SHA384            Kx=DH
    ADH-AES256-SHA256                Kx=DH
    ADH-AES256-SHA                   Kx=DH
    ADH-CAMELLIA256-SHA              Kx=DH
    DHE-DSS-AES256-GCM-SHA384        Kx=DH
    DHE-RSA-AES256-GCM-SHA384        Kx=DH
    DHE-RSA-AES256-SHA256            Kx=DH
    ...

To date, all ciphers that support forward secrecy have one of five values for
the first component of their OpenSSL name: "AECDH", "ECDHE", "ADH", "EDH" or
"DHE". Ciphers that don't implement forward secrecy have names that don't start
with one of these prefixes. This pattern is likely to persist until some new
key-exchange mechanism is invented that also supports forward secrecy.

The actual key length and raw algorithm key length are generally the same with
non-export ciphers, but they may differ for the legacy export ciphers where the
actual key is artificially shortened.

Starting with TLS 1.3 the cipher name no longer contains enough information to
determine which forward-secrecy scheme was employed, but TLS 1.3 aallwwaayyss uses
forward-secrecy. On the client side, up-to-date Postfix releases log additional
information for TLS 1.3 connections, reporting the signature and key exchange
algorithms. Two examples below (the long single line messages are folded across
multiple lines for readability):

    postfix/smtp[process-id]:
      Untrusted TLS connection established to 127.0.0.1[127.0.0.1]:25:
      TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
      key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest
    SHA256
      client-signature ECDSA (P-256) client-digest SHA256

    postfix/smtp[process-id]:
      Untrusted TLS connection established to 127.0.0.1[127.0.0.1]:25:
      TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
      key-exchange ECDHE (P-256) server-signature ECDSA (P-256) server-digest
    SHA256

In the above connections, the "key-exchange" value records the "Diffie-Hellman"
algorithm used for key agreement. The "server-signature" value records the
public key algorithm used by the server to sign the key exchange. The "server-
digest" value records any hash algorithm used to prepare the data for signing.
With "ED25519" and "ED448", no separate hash algorithm is used.

Examples of Postfix SMTP server logging:

    postfix/smtpd[process-id]:
      Untrusted TLS connection established from localhost[127.0.0.1]:25:
      TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
      key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest
    SHA256
      client-signature ECDSA (P-256) client-digest SHA256

    postfix/smtpd[process-id]:
      Anonymous TLS connection established from localhost[127.0.0.1]:
      TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
      server-signature RSA-PSS (2048 bits) server-digest SHA256

    postfix/smtpd[process-id]:
      Anonymous TLS connection established from localhost[127.0.0.1]:
      TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
      server-signature ED25519

Note that Postfix >= 3.4 server logging may also include a "to sni-name"
element to record the use of an alternate server certificate chain for the
connection in question. This happens when the client uses the TLS SNI
extension, and the server selects a non-default certificate chain based on the
client's SNI value:

    postfix/smtpd[process-id]:
      Untrusted TLS connection established from client.example[192.0.2.1]
      to server.example: TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256
    bits)
      key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest
    SHA256
      client-signature ECDSA (P-256) client-digest SHA256

WWhhaatt ddoo ""AAnnoonnyymmoouuss"",, ""UUnnttrruusstteedd"",, eettcc.. iinn PPoossttffiixx llooggggiinngg mmeeaann??

The verification levels below are subject to man-in-the-middle attacks to
different degrees. If such attacks are a concern, then the SMTP client will
need to authenticate the remote SMTP server in a sufficiently-secure manner.
For example, by the fingerprint of a (CA or leaf) public key or certificate.
Remember that conventional PKI relies on many trusted parties and is easily
subverted by a state-funded adversary.

AAnnoonnyymmoouuss (no peer certificate)
    PPoossttffiixx SSMMTTPP cclliieenntt:: With opportunistic TLS (the "may" security level) the
    Postfix SMTP client does not verify any information in the peer
    certificate. In this case it enables and prefers anonymous cipher suites in
    which the remote SMTP server does not present a certificate (these ciphers
    offer forward secrecy of necessity). When the remote SMTP server also
    supports anonymous TLS, and agrees to such a cipher suite, the verification
    status will be logged as "Anonymous".

    PPoossttffiixx SSMMTTPP sseerrvveerr:: This is by far most common, as client certificates are
    optional, and the Postfix SMTP server does not request client certificates
    by default (see smtpd_tls_ask_ccert). Even when client certificates are
    requested, the remote SMTP client might not send a certificate. Unlike the
    Postfix SMTP client, the Postfix SMTP server "anonymous" verification
    status does not imply that the cipher suite is anonymous, which corresponds
    to the server not sending a certificate.

UUnnttrruusstteedd (peer certificate not signed by trusted CA)
    PPoossttffiixx SSMMTTPP cclliieenntt:: The remote SMTP server presented a certificate, but
    the Postfix SMTP client was unable to check the issuing CA signature. With
    opportunistic TLS this is common with remote SMTP servers that don't
    support anonymous cipher suites.

    PPoossttffiixx SSMMTTPP sseerrvveerr:: The remote SMTP client presented a certificate, but
    the Postfix SMTP server was unable to check the issuing CA signature. This
    can happen when the server is configured to request client certificates
    (see smtpd_tls_ask_ccert).

TTrruusstteedd (peer certificate signed by trusted CA, unverified peer name)
    PPoossttffiixx SSMMTTPP cclliieenntt:: The remote SMTP server's certificate was signed by a
    CA that the Postfix SMTP client trusts, but either the client was not
    configured to verify the destination server name against the certificate,
    or the server certificate did not contain any matching names. This is
    common with opportunistic TLS (smtp_tls_security_level is "may" or else
    "dane" with no usable TLSA DNS records) when the Postfix SMTP client's
    trusted CAs can verify the authenticity of the remote SMTP server's
    certificate, but the client is not configured or unable to verify the
    server name.

    PPoossttffiixx SSMMTTPP sseerrvveerr:: The remote SMTP client certificate was signed by a CA
    that the Postfix SMTP server trusts. The Postfix SMTP server never verifies
    the remote SMTP client name against the names in the client certificate.
    Since the client chooses to connect to the server, the Postfix SMTP server
    has no expectation of a particular client hostname.

VVeerriiffiieedd (peer certificate signed by trusted CA and verified peer name; or:
peer certificate with expected public-key or certificate fingerprint)
    PPoossttffiixx SSMMTTPP cclliieenntt:: The remote SMTP server's certificate was signed by a
    CA that the Postfix SMTP client trusts, and the certificate name matches
    the destination or server name(s). The Postfix SMTP client was configured
    to require a verified name, otherwise the verification status would have
    been just "Trusted".

    PPoossttffiixx SSMMTTPP cclliieenntt:: The "Verified" status may also mean that the Postfix
    SMTP client successfully matched the expected fingerprint against the
    remote SMTP server public key or certificate. The expected fingerprint may
    come from smtp_tls_policy_maps or from TLSA (secure) DNS records. The
    Postfix SMTP client ignores the CA signature.

    PPoossttffiixx SSMMTTPP sseerrvveerr:: The status is never "Verified", because the Postfix
    SMTP server never verifies the remote SMTP client name against the names in
    the client certificate, and because the Postfix SMTP server does not expect
    a specific fingerprint in the client public key or certificate.

CCrreeddiittss

  * TLS support for Postfix was originally developed by Lutz Ja"nicke at
    Cottbus Technical University.
  * Wietse Venema adopted and restructured the code and documentation.
  * Viktor Dukhovni implemented support for many subsequent TLS features,
    including EECDH, and authored the initial version of this document.