Postfix REQUIRETLS HowtoPostfix REQUIRETLS Howto(The REQUIRETLS extension in ESMTP allows a sender to request that a message will be sent over connections that are protected with TLS. For background information, see below for a REQUIRETLS quick summary .)
This document covers the Postfix default settings for using the REQUIRETLS extension. The purpose of these defaults is to make REQUIRETLS support usable in an existing environment, with a path towards the future.
The main issues with deploying REQUIRETLS are a lack of support in existing infrastructure:
REQUIRETLS requires that server certificates are authenticated. When email is sent across the Internet, this involves a DANE or MTA-STS policy that is published by a mail receiving domain, using DNSSEC or HTTPS. At this time, many domains do not publish such a policy.
REQUIRETLS is not (yet) supported by existing local infrastructure such as internal message stores or Postfix content filters. REQUIRETLS is over-kill for connections that happen behind a perimeter MTA within a trusted internal network.
Postfix has one global parameter setting that controls REQUIRETLS support in all Postfix processes. The default setting is:
/etc/postfix/main.cf:
requiretls_enable = yes
With this, the Postfix SMTP server will announce REQUIRETLS support, and more importantly, will receive messages from senders that for some reason request REQUIRETLS support -- messages that you would otherwise not receive.
Read the next sections if you also want to send or forward messages with REQUIRETLS and want to use a content filter based on FILTER_README or SMTPD_PROXY_README.
If, on the other hand, all you want is receiving messages with REQUIRETLS, without ever sending or forwarding messages with REQUIRETLS, then you can stop reading this document after adding the additional settings below.
/etc/postfix/main.cf:
# Don't detect or add a "Require-TLS-ESMTP: yes" header.
requiretls_esmtp_header = no
# Don't enforce REQUIRETLS when delivering mail with SMTP or LMTP.
smtp_requiretls_policy = disable
lmtp_requiretls_policy = disable
The requiretls_esmtp_header feature enables support for a message header "Require-TLS-ESMTP: yes" that allows Postfix to propagate the sender's REQUIRETLS request through a content filter. This feature can safely be disabled if there is no need for content inspection based on SMTPD_PROXY_README or FILTER_README.
REQUIRETLS is historically not supported by message stores such as Dovecot, and by content filters based on FILTER_README or SMTPD_PROXY_README. The settings below allow for that reality, while also preparing for future REQUIRETLS support.
The Postfix SMTP (LMTP) client supports a permissive REQUIRETLS policy that is suitable for communication with internal message stores and content filters based on FILTER_README or SMTPD_PROXY_README.
opportunistic: STARTTLS and REQUIRETLS support are optional. When the sender requests REQUIRETLS, and an SMTP or LMTP server supports STARTTLS and REQUIRETLS, then send REQUIRETLS, otherwise simply deliver the message without REQUIRETLS.
For REQUIRETLS, the relevant Postfix 3.11 configuration default settings are:
/etc/postfix/main.cf:
smtp_tls_security_level = may
requiretls_esmtp_header = yes
lmtp_requiretls_policy = opportunistic
smtp_requiretls_policy =
inline:{
{$mydomain = opportunistic}
{.$mydomain = opportunistic}
{localhost = opportunistic}
{127.0.0.1 = opportunistic} }
...to be continued later...
The requiretls_esmtp_header setting enables support for a message header "Require-TLS-ESMTP: yes" that allows Postfix to propagate the sender's REQUIRETLS request through a content filter. This feature can safely be disabled if there is no need for content inspection based on SMTPD_PROXY_README or FILTER_README.
The Postfix FILTER_README describes content inspection based on a pipe-to-command approach. For REQUIRETLS, the relevant Postfix 3.11 default setting is:
/etc/postfix/main.cf:
requiretls_esmtp_header = yes
The requiretls_esmtp_header feature enables support for a message header "Require-TLS-ESMTP: yes" that allows Postfix to propagate the sender's REQUIRETLS request through a content filter. This feature can safely be disabled if there is no need for content inspection based on SMTPD_PROXY_README or FILTER_README.
For communication with external servers, the Postfix SMTP client supports multiple levels of enforcement:
enforce: When the sender requests REQUIRETLS, require secure lookup of MX hosts (for example, using DNSSEC or SMTPS), require a server certificate match (for example, based on a published DANE or STS policy), and require that the remote server supports REQUIRETLS. Otherwise return the message as undeliverable.
opportunistic+starttls: When the sender requests REQUIRETLS, require that the server supports STARTTLS. Send REQUIRETLS if the server supports REQUIRETLS, otherwise simply deliver the message without REQUIRETLS.
opportunistic: STARTTLS and REQUIRETLS support are optional. When the sender requests REQUIRETLS, and an SMTP or LMTP server supports STARTTLS and REQUIRETLS, then send REQUIRETLS, otherwise simply deliver the message without REQUIRETLS.
For sending mail with REQUIRETLS, the relevant Postfix 3.11 default settings are (with one suggested comment):
/etc/postfix/main.cf:
smtp_tls_security_level = may
# smtp_tls_policy_maps = dane/sts plugin
requiretls_esmtp_header = yes
smtp_requiretls_policy =
inline:{
{$mydomain = opportunistic}
{.$mydomain = opportunistic}
{localhost = opportunistic}
{127.0.0.1 = opportunistic} }
opportunistic+starttls
This default reflects the reality that many domains do not publish a DANE or STS policy, that many MTAs support STARTTLS but not REQUIRETLS, and that most email will travel over just one hop: from the sender's perimeter to the receiver's perimeter.
Question: does opportunistic+starttls hit a "sweet spot", or do we need a level like enforce-certmatch that enforces everything except the secure server lookup and certificate match requirement? It's a slippery target...
The 'opportunistic' enforcement level may be useful to discover REQUIRETLS support globally. The idea is to turn on REQUIRETLS for all outbound mail, and watch in Postfix TLS status logging how often delivery is logged as "requiretls" (all requirements satisfied), "requiretls:nocertmatch" (no DANE or STS policy, or certificate not trusted or not matched), "requiretls:none" (no REQUIRETLS support), or "requiretls:nostarttls". For more details on this logging format, see smtp_log_tls_feature_status.
There are two options:
Specify the Postfix-specific "sendmail -Orequiretls=yes" command-line option. This option is always available, but may not be convenient to use.
Add a Postfix-specific "Require-TLS-ESMTP: yes" message header. This is easier to use, but requires the setting "requiretls_esmtp_header = yes" which is not recommended for systems without content filters based on SMTPD_PROXY_README or FILTER_README.
Question: perhaps there needs to be a parameter setting to request REQUIRETLS for specific email sources or contexts?
By default, Postfix redacts an undeliverable REQUIRETLS message as described in RFC 8689, before returning it to the sender:
Return only the message header, as if the message was received with the RFC 3461 DSN option "RET=HDRS".
Remove the label "this message needs REQUIRETLS".
The relevant default setting is:
/etc/postfix/main.cf:
requiretls_redact_dsn = yes
When a message was received with a "TLS-Required: no" header, and REQUIRETLS was not requested, then the "TLS-Required: no" header is copied to the delivery status notification.
RFC 8689 defines two SMTP features:
A message header "TLS-Required: no" that disables TLS enforcement: do not require a server certificate match, and allow falling back to plaintext if TLS is unavailable. This may be useful to report a TLS problem, as described in TLSRPT_README. This feature has lower precedence than REQUIRETLS, and is not discussed further in this document.
An ESMTP protocol extension named "REQUIRETLS" that an SMTP server may list in its EHLO response, and that an SMTP client may request in a MAIL FROM command. This extension can be used only in an encrypted session, as illustrated with the fragment below:
. . . C: STARTTLS S: 220 Ready to start TLS C: EHLO client.example.org S: 250-mail.example.com . . . 250 REQUIRETLS C: MAIL FROM:<sender@example.org> REQUIRETLS S: 250 OK . . .
RFC 8689 applies equally to message relay [RFC 5321], submission [RFC 6409], and the LMTP Local Mail Transfer Protocol [RFC 2033].
REQUIRETLS is an end-to-end feature, unlike SMTP which is hop-by-hop. When a sender requests REQUIRETLS, each MTA in the forward path must support REQUIRETLS.
Each connection in the forward path must be made to an MX server that has been looked up securely (for example, with DNSSEC or HTTPS).
Each server certificate must be verified. To match a server certificate, the Postfix SMTP client needs to use an appropriate policy type:
A TLS policy type 'secure' or 'verify', with certificate name matching info. For example, a policy returned by an MTA-STS plugin that looks up certificate matching info using HTTPS;
A TLS policy type 'dane-only", which looks up certificate or public-key matching info using DNSSEC. For example, a policy that is returned by a DANE+STS plugin;
A TLS policy type 'fingerprint', with digital fingerprints. This is a non-scalable solution for special deployments, mentioned here only for completeness.
A message that requires REQUIRETLS must be returned to the sender if any of the above requirements is not satisfied (no STARTTLS support, no secure lookup of MX servers, no trusted or no matching server certificate, or no server that announces REQUIRETLS support).
Returning an undeliverable message that requires REQUIRETLS comes with its own challenges: the return path may differ from the forward path, and the return path may not support REQUIRETLS all the way back to the sender, even if the forward path supported REQUIRETLS.