From b540f1d62fb2ea4d1e754d9d4fb6a1061cf0706e Mon Sep 17 00:00:00 2001
From: rpaulo
Date: Sat, 25 Feb 2006 22:04:07 +0000
Subject: [PATCH] postfix 2.2.9
---
gnu/dist/postfix/HISTORY | 78 +++++
.../postfix/README_FILES/SCHEDULER_README | 2 +-
gnu/dist/postfix/README_FILES/TLS_README | 247 +++++++++-----
gnu/dist/postfix/html/SCHEDULER_README.html | 2 +-
gnu/dist/postfix/html/TLS_README.html | 314 +++++++++++++-----
gnu/dist/postfix/html/postconf.5.html | 102 ++++--
gnu/dist/postfix/html/smtp.8.html | 206 ++++++------
gnu/dist/postfix/man/man8/smtp.8 | 6 +-
gnu/dist/postfix/mantools/postlink | 1 +
gnu/dist/postfix/proto/SCHEDULER_README.html | 2 +-
gnu/dist/postfix/proto/TLS_README.html | 314 +++++++++++++-----
gnu/dist/postfix/proto/postconf.proto | 98 ++++--
gnu/dist/postfix/src/cleanup/cleanup_api.c | 10 +-
gnu/dist/postfix/src/dns/dns.h | 8 +-
gnu/dist/postfix/src/dns/dns_rr.c | 22 +-
gnu/dist/postfix/src/dns/dns_sa_to_rr.c | 6 +-
gnu/dist/postfix/src/dns/test_dns_lookup.c | 4 +-
gnu/dist/postfix/src/global/ehlo_mask.ref | 4 +-
gnu/dist/postfix/src/global/input_transp.c | 4 +-
gnu/dist/postfix/src/global/mail_addr_find.c | 7 +-
gnu/dist/postfix/src/global/mail_version.h | 6 +-
gnu/dist/postfix/src/lmtp/lmtp_addr.c | 4 +-
gnu/dist/postfix/src/lmtp/lmtp_connect.c | 6 +-
gnu/dist/postfix/src/local/local.c | 4 +-
gnu/dist/postfix/src/oqmgr/qmgr_message.c | 10 +-
gnu/dist/postfix/src/smtp/smtp.c | 8 +-
gnu/dist/postfix/src/smtp/smtp.h | 8 +-
gnu/dist/postfix/src/smtp/smtp_session.c | 187 +++++++----
gnu/dist/postfix/src/smtpd/smtpd_exp.ref | 4 +-
.../postfix/src/trivial-rewrite/rewrite.c | 6 +-
gnu/dist/postfix/src/util/inet_util.c | 2 +-
gnu/dist/postfix/src/util/inet_util.h | 2 +-
32 files changed, 1169 insertions(+), 515 deletions(-)
diff --git a/gnu/dist/postfix/HISTORY b/gnu/dist/postfix/HISTORY
index a6fac711b4ae..0fea8fb362b2 100644
--- a/gnu/dist/postfix/HISTORY
+++ b/gnu/dist/postfix/HISTORY
@@ -10794,3 +10794,81 @@ Apologies for any names omitted.
Portability: FreeBSD 6 is a supported platform. Files:
util/sys_defs.h, makedefs.
+
+20010604
+
+ Safety: new "smtp_cname_overrides_servername" parameter.
+ The default value ("yes") is backwards compatible.
+
+ With a value of "no", the Postfix SMTP client no longer
+ allows CNAME expansion to override the hostname that is
+ used for logging, SASL password lookup, TLS policy decisions,
+ or TLS certificate verification. Instead it uses the name
+ of the recipient domain, the host or domain name specified
+ in Postfix configuration files, or the hostnames obtained
+ with MX lookups. To prevent cheating with hostnames in MX
+ lookup results, you will have to suppress MX lookups with
+ explicit [hostname] entries in transport maps. Files:
+ dns/dns_lookup.c, dns/dns_rr.c, proto/postconf.proto.
+
+20060108
+
+ Bugfix: mailbox_command_maps was not subject to $name
+ expansion. File: local/local.c.
+
+20060115
+
+ Bugfix: don't ignore the per-site policy when SSL library
+ initialization fails. Introduced after adopting the TLS
+ patch. File: smtp/smtp_session.c.
+
+20060121
+
+ Bugfix: a TLS per-site MUST_NOPEERMATCH policy could not
+ override a stronger main.cf policy, while a per-site NONE
+ policy could. Fixed with a clean re-implementation from
+ Postfix 2.3. File: smtp/smtp_session.c.
+
+ Bugfix: a combined TLS per-site (host, recipient) policy
+ of (NONE, MAY) changed a global MUST policy into NONE, and
+ a global MUST_NOPEERMATCH into MAY. The result is now NONE.
+ Problem found by exhaustive simulation. Fixed with a clean
+ re-implementation from Postfix 2.3. File: smtp/smtp_session.c.
+
+20060130
+
+ Bugfix: an empty remote_header_rewrite_domain value caused
+ trivial-rewrite to dereference a null pointer, but only in
+ regression tests, not in production. Postfix rewrites
+ addresses in the remote rewriting context only when the
+ remote_header_rewrite_domain parameter value is non-empty.
+ File: trivial-rewrite/rewrite.c.
+
+20060202
+
+ Workaround: a malformed domain name lookup result (such as
+ null MX record) is now treated as a hard error, so that
+ Postfix will no longer repeatedly try to deliver mail until
+ the message expires in the queue. However, this will not
+ reject mail with reject_unknown_sender/recipient_domain.
+ That would require too much change for a stable release.
+ File: dns/dns_lookup.c.
+
+20060203
+
+ Bugfix: smtpd core dump when SASL is compiled in, turned
+ off (smtpd_sasl_auth_enable = no) and permit_sasl_authenticated
+ is specified in local_header_rewrite_clients. Victor Duchovni.
+ File: smtpd/smtpd_check.c.
+
+20060204
+
+ Bugfix: disable the content_filter feature for user-requested
+ "sendmail -bv" probes, just like it is disabled for probes
+ generated by Postfix itself. File: *qmgr/qmgr_message.c.
+
+20060212
+
+ Workaround: don't consume in_flow tokens when incoming mail
+ is placed on hold. Back-ported from Postfix 2.3. File:
+ cleanup/cleanup_api.c.
diff --git a/gnu/dist/postfix/README_FILES/SCHEDULER_README b/gnu/dist/postfix/README_FILES/SCHEDULER_README
index ec924e9064b4..f94581196b1e 100644
--- a/gnu/dist/postfix/README_FILES/SCHEDULER_README
+++ b/gnu/dist/postfix/README_FILES/SCHEDULER_README
@@ -43,7 +43,7 @@ how next message is chosen when delivery agent becomes available. You already
know that oqmgr(8) uses round-robin by destination while qmgr(8) uses simple
FIFO, except for some preemptive magic. The postconf(5) manual documents all
the knobs the user can use to control this preemptive magic - there is nothing
-else to the preemption than the quite simple conditions described below.
+else to the preemption than the quite simple conditions described in there.
As for programmer-level documentation, this will have to be extracted from all
those emails we have exchanged with Wietse [rats! I hoped that Patrik would do
diff --git a/gnu/dist/postfix/README_FILES/TLS_README b/gnu/dist/postfix/README_FILES/TLS_README
index 25d0aa43d312..ba9fb6d10a0d 100644
--- a/gnu/dist/postfix/README_FILES/TLS_README
+++ b/gnu/dist/postfix/README_FILES/TLS_README
@@ -68,6 +68,11 @@ To build Postfix with TLS support, first we need to generate the make(1) files
with the necessary definitions. This is done by invoking the command "make
makefiles" in the Postfix top-level directory and with arguments as shown next.
+NNOOTTEE:: DDoo nnoott uussee GGnnuu TTLLSS.. IItt wwiillll ssppoonnttaanneeoouussllyy tteerrmmiinnaattee aa PPoossttffiixx ddaaeemmoonn
+pprroocceessss wwiitthh eexxiitt ssttaattuuss ccooddee 22,, iinnsstteeaadd ooff aalllloowwiinngg PPoossttffiixx ttoo 11)) rreeppoorrtt tthhee
+eerrrroorr ttoo tthhee mmaaiilllloogg ffiillee,, aanndd ttoo 22)) pprroovviiddee ppllaaiinntteexxtt sseerrvviiccee wwhheerree tthhiiss iiss
+aapppprroopprriiaattee..
+
* If the OpenSSL include files (such as ssl.h) are in directory /usr/include/
openssl, and the OpenSSL libraries (such as libssl.so and libcrypto.so) are
in directory /usr/lib:
@@ -364,7 +369,9 @@ between multiple smtpd(8) processes, a persistent session cache can be used.
You can specify any database type that can store objects of several kbytes and
that supports the sequence operator. DBM databases are not suitable because
they can only store small objects. The cache is maintained by the tlsmgr(8)
-process, so there is no problem with concurrent access.
+process, so there is no problem with concurrent access. Session caching is
+highly recommended, because the cost of repeatedly negotiating TLS session keys
+is high.
Example:
@@ -420,7 +427,7 @@ Example:
...
The Postfix list manipulation routines give special treatment to whitespace and
-some other characters, making the use of certificate names unpractical. Instead
+some other characters, making the use of certificate names impractical. Instead
we use the certificate fingerprints as they are difficult to fake but easy to
use for lookup. Postfix lookup tables are in the form of (key, value) pairs.
Since we only need the key, the value can be chosen freely, e.g. the name of
@@ -485,7 +492,12 @@ Topics covered in this section:
* Client-side TLS activity logging
* Client-side TLS session cache
* Enabling TLS in the Postfix SMTP client
- * Server certificate verification
+ * Requiring TLS encryption
+ * Disabling server certificate verification
+ * Per-site TLS policies
+ * Closing a DNS loophole with per-site TLS policies
+ * Discovering servers that support TLS
+ * Server certificate verification depth
* Client-side cipher controls
* Miscellaneous client controls
@@ -530,12 +542,12 @@ If you want the Postfix SMTP client to accept remote SMTP server certificates
issued by these CAs, append the root certificate to $smtp_tls_CAfile or install
it in the $smtp_tls_CApath directory. When you configure trust in a root CA, it
is not necessary to explicitly trust intermediary CAs signed by the root CA,
-unless $smtp_tls_verify_depth is less than the number of CAs in the certificate
-chain for the servers of interest. With a verify depth of 1 you can only verify
-certificates directly signed by a trusted CA, and all trusted intermediary CAs
-need to be configured explicitly. With a verify depth of 2 you can verify
-servers signed by a root CA or a direct intermediary CA (so long as the server
-is correctly configured to supply its intermediate CA certificate).
+unless $smtp_tls_scert_verifydepth is less than the number of CAs in the
+certificate chain for the servers of interest. With a verify depth of 1 you can
+only verify certificates directly signed by a trusted CA, and all trusted
+intermediary CAs need to be configured explicitly. With a verify depth of 2 you
+can verify servers signed by a root CA or a direct intermediary CA (so long as
+the server is correctly configured to supply its intermediate CA certificate).
RSA key and certificate examples:
@@ -608,7 +620,10 @@ between multiple smtp(8) processes, a persistent session cache can be used. You
can specify any database type that can store objects of several kbytes and that
supports the sequence operator. DBM databases are not suitable because they can
only store small objects. The cache is maintained by the tlsmgr(8) process, so
-there is no problem with concurrent access.
+there is no problem with concurrent access. Session caching is highly
+recommended, because the cost of repeatedly negotiating TLS session keys is
+high. Future Postfix SMTP servers may limit the number of sessions that a
+client is allowed to negotiate per unit time.
Example:
@@ -630,20 +645,19 @@ By default, TLS is disabled in the Postfix SMTP client, so no difference to
plain Postfix is visible. If you enable TLS, the Postfix SMTP client will send
STARTTLS when TLS support is announced by the remote SMTP server.
-WARNING: MS Exchange servers will announce STARTTLS support even when the
-service is not configured, so that the TLS handshake will fail. It may be wise
-to not use this option on your central mail hub, as you don't know in advance
-whether you are going to connect to such a host. Instead, use the
-smtp_tls_per_site recipient/site specific options that are described below.
-
-When the TLS handshake fails and no other server is available, the Postfix SMTP
-client defers the delivery attempt, and the mail stays in the queue.
+When the server accepts the STARTTLS command, but the subsequent TLS handshake
+fails, and no other server is available, the Postfix SMTP client defers the
+delivery attempt, and the mail stays in the queue. After a handshake failure,
+the communications channel is in an indeterminate state and cannot be used for
+non-TLS deliveries.
Example:
/etc/postfix/main.cf:
smtp_use_tls = yes
+RReeqquuiirriinngg TTLLSS eennccrryyppttiioonn
+
You can ENFORCE the use of TLS, so that the Postfix SMTP client will not
deliver mail over unencrypted connections. In this mode, the remote SMTP server
hostname must match the information in the remote server certificate, and the
@@ -652,21 +666,22 @@ client. If the remote server certificate doesn't verify or the remote SMTP
server hostname doesn't match, and no other server is available, the delivery
attempt is deferred and the mail stays in the queue.
-The remote SMTP server hostname used in the check is beyond question, as it
-must be the principal hostname (no CNAME allowed here). Checks are performed
-against all names provided as dNSNames in the SubjectAlternativeName. If no
-dNSNames are specified, the CommonName is checked. The behavior may be changed
-with the smtp_tls_enforce_peername option which is discussed below.
+The remote SMTP server hostname is verified against all names provided as
+dNSNames in the SubjectAlternativeName. If no dNSNames are specified, the
+CommonName is checked. Verification may be turned off with the
+smtp_tls_enforce_peername option which is discussed below.
-This option is useful only if you know that you will only connect to servers
-that support RFC 2487 _and_ that present server certificates that meet the
-above requirements. An example would be a client only sends email to one
+Enforcing the use of TLS is useful if you know that you will only connect to
+servers that support RFC 2487 _and_ that present server certificates that meet
+the above requirements. An example would be a client only sends email to one
specific mailhub that offers the necessary STARTTLS support.
Example:
/etc/postfix/main.cf:
- smtp_enforce_tls = no
+ smtp_enforce_tls = yes
+
+DDiissaabblliinngg sseerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn
As of RFC 2487 the requirements for hostname checking for MTA clients are not
set. When TLS is required (smtp_enforce_tls = yes), the option
@@ -674,79 +689,140 @@ smtp_tls_enforce_peername can be set to "no" to disable strict remote SMTP
server hostname checking. In this case, the mail delivery will proceed
regardless of the CommonName etc. listed in the certificate.
-Note: the smtp_tls_enforce_peername setting has no effect on sessions that are
-controlled via the smtp_tls_per_site table.
-
-Disabling the remote SMTP server hostname verification can make sense in closed
-environment where special CAs are created. If not used carefully, this option
-opens the danger of a "man-in-the-middle" attack (the CommonName of this
-possible attacker is logged).
+Despite the potential for eliminating "man-in-the-middle" and other attacks,
+mandatory certificate/peername verification is not viable as a default Internet
+mail delivery policy at this time. A significant fraction of TLS enabled MTAs
+uses self-signed certificates, or certificates that are signed by a private
+certificate authority. On a machine that delivers mail to the Internet, if you
+set smtp_enforce_tls = yes, you should probably also set
+smtp_tls_enforce_peername = no. You can use the per-site TLS policies (see
+below) to enable full peer verification for specific destinations that are
+known to have verifiable TLS server certificates.
Example:
/etc/postfix/main.cf:
- smtp_tls_enforce_peername = yes
+ smtp_enforce_tls = yes
+ smtp_tls_enforce_peername = no
-Generally, trying TLS can be a bad idea, as some servers offer STARTTLS but the
-negotiation will fail leading to unexplainable failures. Instead, it may be a
-good idea to choose the TLS usage policy based on the recipient or the mailhub
-to which you are connecting.
+PPeerr--ssiittee TTLLSS ppoolliicciieess
-Deciding the TLS usage policy per recipient may be difficult, since a single
-email delivery attempt can involve several recipients. Instead, use of TLS is
-controlled by the Postfix next-hop destination domain name and by the remote
-SMTP server hostname. If either of these matches an entry in the
-smtp_tls_per_site table, appropriate action is taken.
+A small fraction of servers offer STARTTLS but the negotiation consistently
+fails, leading to mail aging out of the queue and bouncing back to the sender.
+In such cases, you can use the per-site policies to disable TLS for the problem
+sites. Alternatively, you can enable TLS for just a few specific sites and not
+enable it for all sites.
-The remote SMTP server hostname is simply the DNS name of the server that the
-Postfix SMTP client connects to. The next-hop destination is Postfix specific.
-By default, this is the domain name in the recipient address, but this
-information can be overruled by the transport(5) table or by the relayhost
-parameter setting. In these cases the relayhost etc. must be listed in the
-smtp_tls_per_site table, instead of the recipient domain name.
+The smtp_tls_per_site table is searched for a policy that matches the following
+information:
-Format of the table: domain or host names are specified on the left-hand side;
-no wildcards are allowed. On the right hand side specify one of the following
-keywords:
+ remote SMTP server hostname
+ This is simply the DNS name of the server that the Postfix SMTP client
+ connects to; this name may be obtained from other DNS lookups, such as
+ MX lookups or CNAME lookups.
+ next-hop destination
+ This is normally the domain portion of the recipient address, but it
+ may be overruled by information from the transport(5) table, from the
+ relayhost parameter setting, or from the relay_transport setting. When
+ it's not the recipient domain, the next-hop destination can have the
+ Postfix-specific form "[name]", [name]:port", "name" or "name:port".
+
+When both the hostname lookup and the next-hop lookup succeed, the host policy
+does not automatically override the next-hop policy. Instead, precedence is
+given to either the more specific or the more secure per-site policy as
+described below.
+
+The smtp_tls_per_site table uses a simple "name whitespace value" format.
+Specify host names or next-hop destinations on the left-hand side; no wildcards
+are allowed. On the right hand side specify one of the following keywords:
NONE
- Don't use TLS at all.
+ Don't use TLS at all. This overrides a less specific MMAAYY lookup result
+ from the alternate host or next-hop lookup key, and overrides the
+ global smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername
+ settings.
MAY
- Try to use STARTTLS if offered, otherwise use the unencrypted
- connection.
+ Try to use TLS if the server announces support, otherwise use the
+ unencrypted connection. This has less precedence than a more specific
+ result (including NNOONNEE) from the alternate host or next-hop lookup key,
+ and has less precedence than the more specific global "smtp_enforce_tls
+ = yes" or "smtp_tls_enforce_peername = yes".
+ MUST_NOPEERMATCH
+ Require TLS encryption, but do not require that the remote SMTP server
+ hostname matches the information in the remote SMTP server certificate,
+ or that the server certificate was issued by a trusted CA. This
+ overrides a less secure NNOONNEE or a less specific MMAAYY lookup result from
+ the alternate host or next-hop lookup key, and overrides the global
+ smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername settings.
MUST
- Require usage of STARTTLS, require that the remote SMTP server hostname
+ Require TLS encryption, require that the remote SMTP server hostname
matches the information in the remote SMTP server certificate, and
require that the remote SMTP server certificate was issued by a trusted
- CA.
- MUST_NOPEERMATCH
- Require usage of STARTTLS, but do not require that the remote SMTP
- server hostname matches the information in the remote SMTP server
- certificate, or that the server certificate was issued by a trusted CA.
+ CA. This overrides a less secure NNOONNEE and MMUUSSTT__NNOOPPEEEERRMMAATTCCHH or a less
+ specific MMAAYY lookup result from the alternate host or next-hop lookup
+ key, and overrides the global smtp_use_tls, smtp_enforce_tls and
+ smtp_tls_enforce_peername settings.
-The actual TLS usage policy depends not only on whether the next-hop
-destination or remote SMTP server hostname are found in the smtp_tls_per_site
-table, but also on the smtp_enforce_tls setting:
+The precedences between global (main.cf) and per-site TLS policies can be
+summarized as follows:
- * If no match was found, the policy is applied as specified with
- smtp_enforce_tls.
+ * When neither the remote SMTP server hostname nor the next-hop destination
+ are found in the smtp_tls_per_site table, the policy is based on
+ smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername. Note:
+ "smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes" imply
+ "smtp_use_tls = yes".
- * If a match was found, and the smtp_enforce_tls policy is "enforce", NONE
- explicitly switches it off; otherwise the "enforce" mode is used even for
- entries that specify MAY.
+ * When both hostname and next-hop destination lookups produce a result, the
+ more specific per-site policy (NONE, MUST, etc) overrides the less specific
+ one (MAY), and the more secure per-site policy (MUST, etc) overrides the
+ less secure one (NONE).
-Special hint for TLS enforcement mode: since no secure DNS lookup mechanism is
-available, mail can be delivered to the wrong remote SMTP server. This is not
-prevented by specifying MUST for the next-hop domain name. The recommended
-setup is: specify local transport(5) table entries for sensitive domains with
-explicit smtp:[mailhost] destinations (since you can assure security of this
-table unlike DNS), then specify MUST for these mail hosts in the
-smtp_tls_per_site table.
+ * After the per-site policy lookups are combined, the result generally
+ overrides the global policy. The exception is the less specific MMAAYY per-
+ site policy, which is overruled by the more specific global
+ "smtp_enforce_tls = yes" with server certificate verification as specified
+ with the smtp_tls_enforce_peername parameter.
+
+CClloossiinngg aa DDNNSS lloooopphhoollee wwiitthh ppeerr--ssiittee TTLLSS ppoolliicciieess
+
+As long as no secure DNS lookup mechanism is available, false hostnames in MX
+or CNAME responses can change the server hostname that Postfix uses for TLS
+policy lookup and server certificate verification. Even with a perfect match
+between the server hostname and the server certificate, there is no guarantee
+that Postfix is connected to the right server. To avoid this loophole take the
+following steps:
+
+ * Eliminate MX lookups. Specify local transport(5) table entries for
+ sensitive domains with explicit smtp:[mailhost] or smtp:[mailhost]:port
+ destinations (you can assure security of this table unlike DNS); in the
+ smtp_tls_per_site table specify the value MMUUSSTT for the key [mailhost] or
+ smtp:[mailhost]:port. This prevents false hostname information in DNS MX
+ records from changing the server hostname that Postfix uses for TLS policy
+ lookup and server certificate verification.
+
+ * Disallow CNAME hostname overrides. In main.cf specify
+ "smtp_cname_overrides_servername = no". This prevents false hostname
+ information in DNS CNAME records from changing the server hostname that
+ Postfix uses for TLS policy lookup and server certificate verification.
+ This feature requires Postfix 2.2.9 or later.
Example:
/etc/postfix/main.cf:
smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+ relayhost = [msa.example.net]:587
+
+ /etc/postfix/tls_per_site:
+ # relayhost exact nexthop match
+ [msa.example.net]:587 MUST
+
+ # TLS should not be used with the example.org MX hosts.
+ example.org NONE
+
+ # TLS should not be used with the host smtp.example.com.
+ smtp.example.com NONE
+
+DDiissccoovveerriinngg sseerrvveerrss tthhaatt ssuuppppoorrtt TTLLSS
As we decide on a "per site" basis whether or not to use TLS, it would be good
to have a list of sites that offered "STARTTLS". We can collect it ourselves
@@ -763,7 +839,7 @@ Example:
/etc/postfix/main.cf:
smtp_tls_note_starttls_offer = yes
-SSeerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn
+SSeerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn ddeepptthh
When verifying a remote SMTP server certificate, a verification depth of 1 is
sufficient if the certificate is directly issued by a CA specified with
@@ -1012,10 +1088,25 @@ J
and in order to access the TLS session cache databases. Such a protocol
cannot be run across fifos.
+ * smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy cannot override the
+ global "smtp_tls_enforce_peername = yes" setting.
+
+ * smtp_tls_per_site: a combined (NONE + MAY) lookup result for (hostname and
+ next-hop destination) produces counter-intuitive results for different
+ main.cf settings. TLS is enabled with "smtp_tls_enforce_peername = no", but
+ it is disabled when both "smtp_enforce_tls = yes" and
+ "smtp_tls_enforce_peername = yes".
+
+The smtp_tls_per_site limitations were removed by the end of the Postfix 2.2
+support cycle.
+
CCrreeddiittss
* TLS support for Postfix was originally developed by Lutz Jänicke at Cottbus
Technical University.
* Wietse Venema adopted the code, did some restructuring, and compiled this
part of the documentation from Lutz's documents.
+ * Victor Duchovni was instrumental with the re-implementation of the
+ smtp_tls_per_site code in terms of enforcement levels, which simplified the
+ implementation greatly.
diff --git a/gnu/dist/postfix/html/SCHEDULER_README.html b/gnu/dist/postfix/html/SCHEDULER_README.html
index d2a0973f05da..25f56a51aae9 100644
--- a/gnu/dist/postfix/html/SCHEDULER_README.html
+++ b/gnu/dist/postfix/html/SCHEDULER_README.html
@@ -68,7 +68,7 @@ available. You already know that oqmgr(8) uses round-
while qmgr(8) uses simple FIFO, except for some preemptive magic.
The postconf(5) manual documents all the knobs the user
can use to control this preemptive magic - there is nothing else
-to the preemption than the quite simple conditions described below.
+to the preemption than the quite simple conditions described in there.
As for programmer-level documentation, this will have to be
diff --git a/gnu/dist/postfix/html/TLS_README.html b/gnu/dist/postfix/html/TLS_README.html
index cf4b4c6e289d..f34021436243 100644
--- a/gnu/dist/postfix/html/TLS_README.html
+++ b/gnu/dist/postfix/html/TLS_README.html
@@ -129,6 +129,11 @@ the make(1) files with the necessary definitions. This is
done by invoking the command "make makefiles" in the Postfix
top-level directory and with arguments as shown next.
+ NOTE: Do not use Gnu TLS. It will spontaneously terminate
+a Postfix daemon process with exit status code 2, instead of allowing
+Postfix to 1) report the error to the maillog file, and to 2) provide
+plaintext service where this is appropriate.
+
-
If the OpenSSL include files (such as ssl.h) are
@@ -553,7 +558,8 @@ can specify any database type that can store objects of several
kbytes and that supports the sequence operator. DBM databases are
not suitable because they can only store small objects. The cache
is maintained by the tlsmgr(8) process, so there is no problem with
-concurrent access.
+concurrent access. Session caching is highly recommended, because
+the cost of repeatedly negotiating TLS session keys is high.
Example:
@@ -632,7 +638,7 @@ certificate must no longer be used (e.g. an employee leaving).
The Postfix list manipulation routines give special treatment
to whitespace and some other characters, making the use of certificate
-names unpractical. Instead we use the certificate fingerprints as
+names impractical. Instead we use the certificate fingerprints as
they are difficult to fake but easy to use for lookup. Postfix
lookup tables are in the form of (key, value) pairs. Since we only
need the key, the value can be chosen freely, e.g. the name of
@@ -725,9 +731,23 @@ key configuration
- Client-side TLS session cache
-
- Enabling TLS in the Postfix SMTP client
+
- Enabling TLS in the Postfix SMTP client
-
- Server certificate verification
+
- Requiring TLS encryption
+
+
- Disabling server certificate verification
+
+
- Per-site TLS policies
+
+
+
+
- Closing a DNS loophole with per-site TLS policies
+
+
- Discovering servers that support TLS
+
+
- Server certificate verification depth
- Client-side cipher controls
@@ -787,7 +807,7 @@ the overhead of the TLS exchange.
certificates issued by these CAs, append the root certificate to
$smtp_tls_CAfile or install it in the $smtp_tls_CApath directory. When
you configure trust in a root CA, it is not necessary to explicitly trust
-intermediary CAs signed by the root CA, unless $smtp_tls_verify_depth
+intermediary CAs signed by the root CA, unless $smtp_tls_scert_verifydepth
is less than the number of CAs in the certificate chain for the servers
of interest. With a verify depth of 1 you can only verify certificates
directly signed by a trusted CA, and all trusted intermediary CAs need to
@@ -904,7 +924,10 @@ can specify any database type that can store objects of several
kbytes and that supports the sequence operator. DBM databases are
not suitable because they can only store small objects. The cache
is maintained by the tlsmgr(8) process, so there is no problem with
-concurrent access.
+concurrent access. Session caching is highly recommended, because
+the cost of repeatedly negotiating TLS session keys is high. Future
+Postfix SMTP servers may limit the number of sessions that a client
+is allowed to negotiate per unit time.
Example:
@@ -930,24 +953,19 @@ recommends a maximum of 24 hours.
-
+
By default, TLS is disabled in the Postfix SMTP client, so no
difference to plain Postfix is visible. If you enable TLS, the
Postfix SMTP client will send STARTTLS when TLS support is announced
by the remote SMTP server.
- WARNING: MS Exchange servers will announce STARTTLS support
-even when the service is not configured, so that the TLS handshake
-will fail. It may be wise to not use this option on your central
-mail hub, as you don't know in advance whether you are going to
-connect to such a host. Instead, use the smtp_tls_per_site
-recipient/site specific options that are described below.
-
- When the TLS handshake fails and no other server is available,
-the Postfix SMTP client defers the delivery attempt, and the mail
-stays in the queue.
+ When the server accepts the STARTTLS command, but the subsequent
+TLS handshake fails, and no other server is available, the Postfix SMTP
+client defers the delivery attempt, and the mail stays in the queue. After
+a handshake failure, the communications channel is in an indeterminate
+state and cannot be used for non-TLS deliveries.
Example:
@@ -958,6 +976,9 @@ stays in the queue.
+
+
You can ENFORCE the use of TLS, so that the Postfix SMTP client
will not deliver mail over unencrypted connections. In this mode,
the remote SMTP server hostname must match the information in the
@@ -967,14 +988,14 @@ server certificate doesn't verify or the remote SMTP server hostname
doesn't match, and no other server is available, the delivery
attempt is deferred and the mail stays in the queue.
- The remote SMTP server hostname used in the check is beyond
-question, as it must be the principal hostname (no CNAME allowed
-here). Checks are performed against all names provided as dNSNames
+
The remote SMTP server hostname is verified against all names
+provided as dNSNames
in the SubjectAlternativeName. If no dNSNames are specified, the
-CommonName is checked. The behavior may be changed with the
+CommonName is checked. Verification may be turned off with the
smtp_tls_enforce_peername option which is discussed below.
- This option is useful only if you know that you will only
+
Enforcing the use of TLS is useful if you know that you will
+only
connect to servers that support RFC 2487 _and_ that present server
certificates that meet the above requirements. An example would
be a client only sends email to one specific mailhub that offers
@@ -985,10 +1006,13 @@ the necessary STARTTLS support.
/etc/postfix/main.cf:
- smtp_enforce_tls = no
+ smtp_enforce_tls = yes
+
+
As of RFC 2487 the requirements for hostname checking for MTA
clients are not set. When TLS is required (smtp_enforce_tls = yes),
the option smtp_tls_enforce_peername can be set to "no" to disable
@@ -996,106 +1020,200 @@ strict remote SMTP server hostname checking. In this case, the mail
delivery will proceed regardless of the CommonName etc. listed in
the certificate.
- Note: the smtp_tls_enforce_peername setting has no effect on
-sessions that are controlled via the smtp_tls_per_site table.
-
- Disabling the remote SMTP server hostname verification can
-make sense in closed environment where special CAs are created.
-If not used carefully, this option opens the danger of a
-"man-in-the-middle" attack (the CommonName of this possible attacker
-is logged).
+ Despite the potential for eliminating "man-in-the-middle" and
+other attacks, mandatory certificate/peername verification is not
+viable as a default Internet mail delivery policy at this time. A
+significant fraction of TLS enabled MTAs uses self-signed certificates,
+or certificates that are signed by a private certificate authority.
+On a machine that delivers mail to the Internet, if you set
+smtp_enforce_tls = yes, you should probably also set
+smtp_tls_enforce_peername = no. You can use the per-site TLS
+policies (see below) to enable full peer verification for specific
+destinations that are known to have verifiable TLS server certificates.
+
Example:
/etc/postfix/main.cf:
- smtp_tls_enforce_peername = yes
+ smtp_enforce_tls = yes
+ smtp_tls_enforce_peername = no
- Generally, trying TLS can be a bad idea, as some servers offer
-STARTTLS but the negotiation will fail leading to unexplainable
-failures. Instead, it may be a good idea to choose the TLS usage
-policy based on the recipient or the mailhub to which you are
-connecting.
+
- Deciding the TLS usage policy per recipient may be difficult,
-since a single email delivery attempt can involve several recipients.
-Instead, use of TLS is controlled by the Postfix next-hop destination
-domain name and by the remote SMTP server hostname. If either of these
-matches an entry in the smtp_tls_per_site table, appropriate action
-is taken.
+ A small fraction of servers offer STARTTLS but the negotiation
+consistently fails, leading to mail aging out of the queue and
+bouncing back to the sender. In such cases, you can use the per-site
+policies to disable TLS for the problem sites. Alternatively, you
+can enable TLS for just a few specific sites and not enable it for
+all sites.
- The remote SMTP server hostname is simply the DNS name of the
-server that the Postfix SMTP client connects to. The next-hop
-destination is Postfix specific. By default, this is the domain
-name in the recipient address, but this information can be overruled
-by the transport(5) table or by the relayhost parameter setting.
-In these cases the relayhost etc. must be listed in the smtp_tls_per_site
-table, instead of the recipient domain name.
+
+
+ The smtp_tls_per_site table is searched for a policy that matches
+the following information:
-- NONE
- Don't use TLS at all.
+- remote SMTP server hostname
- This is simply the DNS
+name of the server that the Postfix SMTP client connects to; this
+name may be obtained from other DNS lookups, such as MX lookups or
+CNAME lookups.
-- MAY
- Try to use STARTTLS if offered, otherwise use
-the unencrypted connection.
-
-- MUST
- Require usage of STARTTLS, require that the
-remote SMTP server hostname matches the information in the remote
-SMTP server certificate, and require that the remote SMTP server
-certificate was issued by a trusted CA.
-
-- MUST_NOPEERMATCH
- Require usage of STARTTLS, but do
-not require that the remote SMTP server hostname matches the
-information in the remote SMTP server certificate, or that the
-server certificate was issued by a trusted CA.
+- next-hop destination
- This is normally the domain
+portion of the recipient address, but it may be overruled by
+information from the transport(5) table, from the relayhost parameter
+setting, or from the relay_transport setting. When it's not the
+recipient domain, the next-hop destination can have the Postfix-specific
+form "[name]", [name]:port", "name" or
+"name:port".
- The actual TLS usage policy depends not only on whether the
-next-hop destination or remote SMTP server hostname are found in
-the smtp_tls_per_site table, but also on the smtp_enforce_tls
-setting:
+ When both the hostname lookup and the next-hop lookup succeed,
+the host policy does not automatically override the next-hop policy.
+Instead, precedence is given to either the more specific or the
+more secure per-site policy as described below.
+
+ The smtp_tls_per_site table uses a simple "name whitespace
+value" format. Specify host names or next-hop destinations on
+the left-hand side; no wildcards are allowed. On the right hand
+side specify one of the following keywords:
+
+
+
+
+
+- NONE
- Don't use TLS at all. This overrides a less
+specific MAY lookup result from the alternate host or next-hop
+lookup key, and overrides the global smtp_use_tls, smtp_enforce_tls,
+and smtp_tls_enforce_peername settings.
+
+- MAY
- Try to use TLS if the server announces support,
+otherwise use the unencrypted connection. This has less precedence
+than a more specific result (including NONE) from the alternate
+host or next-hop lookup key, and has less precedence than the more
+specific global "smtp_enforce_tls = yes" or "smtp_tls_enforce_peername
+= yes".
+
+- MUST_NOPEERMATCH
- Require TLS encryption, but do not
+require that the remote SMTP server hostname matches the information
+in the remote SMTP server certificate, or that the server certificate
+was issued by a trusted CA. This overrides a less secure NONE
+or a less specific MAY lookup result from the alternate host
+or next-hop lookup key, and overrides the global smtp_use_tls,
+smtp_enforce_tls and smtp_tls_enforce_peername settings.
+
+- MUST
- Require TLS encryption, require that the remote
+SMTP server hostname matches the information in the remote SMTP
+server certificate, and require that the remote SMTP server certificate
+was issued by a trusted CA. This overrides a less secure NONE
+and MUST_NOPEERMATCH or a less specific MAY lookup
+result from the alternate host or next-hop lookup key, and overrides
+the global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername
+settings.
+
+
+
+
+
+ The precedences between global (main.cf) and per-site TLS
+policies can be summarized as follows:
--
If no match was found, the policy is applied as specified
-with smtp_enforce_tls.
+ -
When neither the remote SMTP server hostname nor the
+next-hop destination are found in the smtp_tls_per_site table, the
+policy is based on smtp_use_tls, smtp_enforce_tls and
+smtp_tls_enforce_peername. Note: "smtp_enforce_tls = yes" and
+"smtp_tls_enforce_peername = yes" imply "smtp_use_tls = yes".
- -
If a match was found, and the smtp_enforce_tls policy is
-"enforce", NONE explicitly switches it off; otherwise the "enforce"
-mode is used even for entries that specify MAY.
+ -
When both hostname and next-hop destination lookups produce
+a result, the more specific per-site policy (NONE, MUST, etc)
+overrides the less specific one (MAY), and the more secure per-site
+policy (MUST, etc) overrides the less secure one (NONE).
+
+ -
After the per-site policy lookups are combined, the result
+generally overrides the global policy. The exception is the less
+specific MAY per-site policy, which is overruled by the more
+specific global "smtp_enforce_tls = yes" with server certificate
+verification as specified with the smtp_tls_enforce_peername
+parameter.
- Special hint for TLS enforcement mode: since no secure DNS
-lookup mechanism is available, mail can be delivered to the wrong
-remote SMTP server. This is not prevented by specifying MUST for
-the next-hop domain name. The recommended setup is: specify local
-transport(5) table entries for sensitive domains with explicit
-smtp:[mailhost] destinations (since you can assure security of this
-table unlike DNS), then specify MUST for these mail hosts in the
-smtp_tls_per_site table.
+
+
+ As long as no secure DNS lookup mechanism is available, false
+hostnames in MX or CNAME responses can change the server hostname
+that Postfix uses for TLS policy lookup and server certificate
+verification. Even with a perfect match between the server hostname
+and the server certificate, there is no guarantee that Postfix is
+connected to the right server. To avoid this loophole take the
+following steps:
+
+
+
+-
Eliminate MX lookups. Specify local transport(5) table
+entries for sensitive domains with explicit smtp:[mailhost]
+or smtp:[mailhost]:port destinations (you can assure
+security of this table unlike DNS); in the smtp_tls_per_site table
+specify the value MUST for the key [mailhost] or
+smtp:[mailhost]:port. This prevents false hostname
+information in DNS MX records from changing the server hostname
+that Postfix uses for TLS policy lookup and server certificate
+verification.
+
+ -
Disallow CNAME hostname overrides. In main.cf specify
+"smtp_cname_overrides_servername = no". This prevents false hostname
+information in DNS CNAME records from changing the server hostname
+that Postfix uses for TLS policy lookup and server certificate
+verification. This feature requires Postfix 2.2.9 or later.
+
+
Example:
-
-
-
+
+
/etc/postfix/main.cf:
smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+ relayhost = [msa.example.net]:587
+
+/etc/postfix/tls_per_site:
+ # relayhost exact nexthop match
+ [msa.example.net]:587 MUST
+
+ # TLS should not be used with the example.org MX hosts.
+ example.org NONE
+
+ # TLS should not be used with the host smtp.example.com.
+ smtp.example.com NONE
+
+
As we decide on a "per site" basis whether or not to use TLS,
it would be good to have a list of sites that offered "STARTTLS".
We can collect it ourselves with this option.
@@ -1119,7 +1237,7 @@ postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com]
-
+
When verifying a remote SMTP server certificate, a verification
depth of 1 is sufficient if the certificate is directly issued by
@@ -1376,7 +1494,7 @@ super-user privileges.
-
Configure Postfix, by adding the following to
-/etc/postfix/main.cf.
+/etc/postfix/main.cf .
@@ -1443,8 +1561,22 @@ protocol in order to access the tlsmgr(8) pseudo-ran
generation (PRNG) pool, and in order to access the TLS session
cache databases. Such a protocol cannot be run across fifos.
+
-
smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy
+cannot override the global "smtp_tls_enforce_peername = yes" setting.
+
+
+ -
smtp_tls_per_site: a combined (NONE + MAY) lookup result
+for (hostname and next-hop destination) produces counter-intuitive
+results for different main.cf settings. TLS is enabled with
+"smtp_tls_enforce_peername = no", but it is disabled when both
+"smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes".
+
+
+ The smtp_tls_per_site limitations were removed by the end of
+the Postfix 2.2 support cycle.
+
@@ -1455,6 +1587,10 @@ Jänicke at Cottbus Technical University.
- Wietse Venema adopted the code, did some restructuring, and
compiled this part of the documentation from Lutz's documents.
+
- Victor Duchovni was instrumental with the re-implementation
+of the smtp_tls_per_site code in terms of enforcement levels, which
+simplified the implementation greatly.
+