path: root/RELEASE_NOTES

This is the Postfix 3.7 (stable) release.

The stable Postfix release is called postfix-3.7.x where 3=major
release number, 7=minor release number, x=patchlevel.  The stable
release never changes except for patches that address bugs or
emergencies. Patches change the patchlevel and the release date.

New features are developed in snapshot releases. These are called
postfix-3.8-yyyymmdd where yyyymmdd is the release date (yyyy=year,
mm=month, dd=day).  Patches are never issued for snapshot releases;
instead, a new snapshot is released.

The mail_release_date configuration parameter (format: yyyymmdd)
specifies the release date of a stable release or snapshot release.

If you upgrade from Postfix 3.5 or earlier, read RELEASE_NOTES-3.6
before proceeding.

License change
---------------

This software is distributed with a dual license: in addition to the
historical IBM Public License 1.0, it is now also distributed with the
more recent Eclipse Public License 2.0. Recipients can choose to take
the software under the license of their choice. Those who are more
comfortable with the IPL can continue with that license.

Incompatibility with Postfix 3.8.5, 3.7.10, 3.6.14, and 3.5.24
==============================================================

Improvements for outbound SMTP smuggling defense:

- With "cleanup_replace_stray_cr_lf = yes" (the default), the cleanup
  daemon replaces each stray <CR> or <LF> character in message
  content with a space character. The replacement happens before
  any other content management (header/body_checks, Milters, etc).

  This prevents outbound SMTP smuggling, where an attacker uses
  Postfix to send email containing a non-standard End-of-DATA
  sequence, to exploit inbound SMTP smuggling at a vulnerable remote
  SMTP server.

  This also improves the remote evaluation of Postfix-added DKIM
  and other signatures, as the evaluation result will not depend
  on how a remote email server handles stray <CR> or <LF> characters.

This feature applies to all email that Postfix locally or remotely
sends out. It is not allowlisted based on client identity.

Major changes with Postfix 3.8.5, 3.7.10, 3.6.14, and 3.5.24
============================================================

Improvements for inbound SMTP smuggling defense:

- Better compatibility: the recommended setting "smtpd_forbid_bare_newline
  = normalize" requires the standard End-of-DATA sequence
  <CR><LF>.<CR><LF>, but allows bare newlines from SMTP clients,
  maintaining more compatibility with existing infrastructure.

- Improved logging for rejected input (it now includes queue ID,
  helo, mail, and rcpt, if available).

- The setting "smtpd_forbid_bare_newline = reject" requires
  that input lines end in <CR><LF>, requires the standard End-of-DATA
  sequence <CR><LF>.<CR><LF>, and rejects a command or message that
  contains a bare newline. To disconnect the client, specify
  "smtpd_forbid_bare_newline_reject_code = 521".

- The Postfix SMTP server no longer strips extra <CR> as in
  <CR><LF>.<CR><CR><LF>, to silence false alarms from test tools
  that send attack sequences that real mail servers cannot send.
  Details at https://www.postfix.org/false-smuggling-claims.html

- The old setting "yes" has become an alias for "normalize".

- The old setting "no" has not changed, and allows SMTP smuggling.

The recommended settings are now:

    # Require the standard End-of-DATA sequence <CR><LF>.<CR><LF>.
    # Otherwise, allow bare <LF> and process it as if the client sent
    # <CR><LF>.
    #
    # This maintains compatibility with many legitimate SMTP client
    # applications that send a mix of standard and non-standard line
    # endings, but will fail to receive email from client implementations
    # that do not terminate DATA content with the standard End-of-DATA
    # sequence <CR><LF>.<CR><LF>.
    #
    # Such clients can be allowlisted with smtpd_forbid_bare_newline_exclusions.
    # The example below allowlists SMTP clients in trusted networks.
    #
    smtpd_forbid_bare_newline = normalize
    smtpd_forbid_bare_newline_exclusions = $mynetworks

Alternative settings:

    # Reject input lines that contain <LF> and log a "bare <LF> received"
    # error. Require that input lines end in <CR><LF>, and require the
    # standard End-of-DATA sequence <CR><LF>.<CR><LF>.
    #
    # This will reject email from SMTP clients that send any non-standard
    # line endings such as web applications, netcat, or load balancer
    # health checks.
    #
    # This will also reject email from services that use BDAT to send
    # MIME text containing a bare newline (RFC 3030 Section 3 requires
    # canonical MIME format for text message types, defined in RFC 2045
    # Sections 2.7 and 2.8).
    #
    # Such clients can be allowlisted with smtpd_forbid_bare_newline_exclusions.
    # The example below allowlists SMTP clients in trusted networks.
    #
    smtpd_forbid_bare_newline = reject
    smtpd_forbid_bare_newline_exclusions = $mynetworks
    #
    # Alternatively, in the case of BDAT violations, BDAT can be selectively
    # disabled with smtpd_discard_ehlo_keyword_address_maps, or globally
    # disabled with smtpd_discard_ehlo_keywords.
    #
    # smtpd_discard_ehlo_keyword_address_maps = cidr:/path/to/file
    # /path/to/file:
    #     10.0.0.0/24 chunking, silent-discard
    # smtpd_discard_ehlo_keywords = chunking, silent-discard

Major changes with Postfix 3.7.6
================================

Security: the Postfix SMTP server optionally disconnects remote
SMTP clients that violate RFC 2920 (or 5321) command pipelining
constraints. The server replies with "554 5.5.0 Error: SMTP protocol
synchronization" and logs the unexpected remote SMTP client input.
Specify "smtpd_forbid_unauth_pipelining = yes" to enable. This
feature is enabled by default in Postfix 3.9 and later.

Workaround to limit collateral damage from OS distributions that
crank up security to 11, increasing the number of plaintext email
deliveries. This introduces basic OpenSSL configuration file support,
with two new parameters "tls_config_file" and "tls_config_name".
Details are in the postconf(5) manpage under "tls_config_file" and
"tls_config_name".

Bugfix for messages not delivered after "warning: Unexpected record type 'X'
============================================================================

Due to a bug introduced in Postfix 3.7.0, a message could falsely
be flagged as corrupt with "warning: Unexpected record type 'X'".

Such messages were moved to the "corrupt" queue directory, where
they may still be found. See below for instructions to deal with
these falsely flagged messages.

This could happen for messages with 5000 or more recipients, or
with fewer recipients on a busy mail server. The problem was first
reported by Frank Brendel, reproduced by John Alex.

A file in the "corrupt" queue directory may be inspected with the
command "postcat /var/spool/postfix/corrupt/<filename>. If delivery
of the file is still desired, the file can be moved back to
/var/spool/postfix/incoming after updating Postfix and executing
"postfix reload".

Major changes - configuration
-----------------------------

[Feature 20210605] Support to inline the content of small cidr:,
pcre:, and regexp: tables in Postfix parameter values.

Example:

    smtpd_forbidden_commands =
	CONNECT GET POST regexp:{{/^[^A-Z]/ Thrash}}

This is the new smtpd_forbidden_commands default value. It will
immediately disconnect a remote SMTP client when a command does not
start with a letter (a-z or A-Z).

The basic syntax is:

/etc/postfix/main.cf:
    parameter = .. map-type:{ { rule-1 }, { rule-2 } .. } ..

/etc/postfix/master.cf:
    .. -o { parameter = .. map-type:{ { rule-1 }, { rule-2 } .. } .. } ..

where map-type is one of cidr, pcre, or regexp.

Postfix ignores whitespace after '{' and before '}', and writes each
rule as one text line to a nameless in-memory file: 

in-memory file:
    rule-1
    rule-2
    ..

Postfix parses the result as if it is a file in /etc/postfix.

Note: if a rule contains $, specify $$ to keep Postfix from trying
to do $name expansion as it evaluates the parameter value.

Major changes - lmdb support
----------------------------

[Feature 20210605] Overhauled the LMDB client's error handling, and
added integration tests for future-proofing. There are no visible
changes in documented behavior.

Major changes - logging
-----------------------

[Feature 20210815] To make the maillog_file feature more useful,
the postlog(1) command is now set-gid postdrop, so that unprivileged
programs can use it to write logging through the postlogd(8) daemon.
This required hardening the postlog(1) command against privilege
escalation attacks. DO NOT turn on the set-gid bit with older
postlog(1) implementations.

Major changes - pcre2 support
-----------------------------

[Feature 20211127] Support for the pcre2 library (the legacy pcre
library is no longer maintained). The Postfix build procedure
automatically detects if the pcre2 library is installed, and if it
is unavailable, the Postfix build procedure will detect if the
legacy pcre library is installed. See PCRE_README if you need to
build Postfix with a specific library.

Visible differences: some error messages may have a different text,
and the 'X' pattern flag is no longer supported with pcre2.

Major changes - security
------------------------

[Feature 20220102] Postfix programs now randomize the initial state
of in-memory hash tables, to defend against hash collision attacks
involving a large number of attacker-chosen lookup keys. Presently,
the only known opportunity for such attacks involves remote SMTP
client IPv6 addresses in the anvil(8) service. The attack would
require making hundreds of short-lived connections per second from
thousands of different IP addresses, because the anvil(8) service
drops inactive counters after 100s. Other in-memory hash tables
with attacker-chosen lookup keys are by design limited in size. The
fix is cheap, and therefore implemented for all Postfix in-memory
hash tables. Problem reported by Pascal Junod.

[Feature 20211030] The postqueue command now sanitizes non-printable
characters (such as newlines) in strings before they are formatted
as json or as legacy output. These outputs are piped into other
programs that are run by administrative users. This closes a
hypothetical opportunity for privilege escalation.

[Feature 20210815] Updated defense against remote clients or servers
that 'trickle' SMTP or LMTP traffic, based on per-request deadlines
and minimum data rates.

Per-request deadlines:

The new {smtpd,smtp,lmtp}_per_request_deadline parameters replace
{smtpd,smtp,lmtp}_per_record_deadline, with backwards compatible
default settings. This defense is enabled by default in the Postfix
SMTP server in case of overload.

The new smtpd_per_record_deadline parameter limits the combined
time for the Postfix SMTP server to receive a request and to send
a response, while the new {smtp,lmtp}_per_record_deadline parameters
limit the combined time for the Postfix SMTP or LMTP client to send
a request and to receive a response.

Minimum data rates:

The new smtpd_min_data_rate parameter enforces a minimum plaintext
data transfer rate for DATA and BDAT requests, but only when
smtpd_per_record_deadline is enabled. After a read operation transfers
N plaintext bytes (possibly after TLS decryption), and after the
DATA or BDAT request deadline is decreased by the elapsed time of
that read operation, the DATA or BDAT request deadline is increased
by N/smtpd_min_data_rate seconds. However, the deadline is never
increased beyond the smtpd_timeout value. The default minimum data
rate is 500 (bytes/second) but is still subject to change.

The new {smtp,lmtp}_min_data_rate parameters enforce the corresponding
minimum DATA transfer rates for the Postfix SMTP and LMTP client.

Major changes - tls support
---------------------------

[Cleanup 20220121] The new tlsproxy_client_security_level parameter
replaces tlsproxy_client_level, and the new tlsproxy_client_policy_maps
parameter replaces tlsproxy_client_policy. This is for consistent
parameter naming (tlsproxy_client_xxx corresponds to smtp_tls_xxx).
This change was made with backwards-compatible default settings.

[Feature 20210926] Postfix was updated to support OpenSSL 3.0.0 API
features, and to work around OpenSSL 3.0.0 bit-rot (avoid using
deprecated API features).

Other code health
-----------------

[typos] Typo fixes by raf.

[pre-release checks] Added pre-release checks to detect a) new typos
in documentation and source-code comments, b) missing entries in
the postfix-files file (some documentation would not be installed),
c) missing rules in the postlink script (some text would not have
a hyperlink in documentation), and d) missing map-based $parameter
names in the proxy_read_maps default value (the proxymap daemon
would not automatically authorize some proxied maps).

[memory stream] Improved support for memory-based streams made it
possible to inline small cidr:, pcre:, and regexp: maps in Postfix
parameter values, and to eliminate some ad-hoc code that converted
tlsproxy(8) protocol data to or from serialized form.