postfix-3.10-20240927

vdukhovni · Sep 28, 2024 · 7ad397c · 7ad397c
1 parent c42df83
commit 7ad397c
Show file tree

Hide file tree

Showing 25 changed files with 239 additions and 97 deletions.
diff --git a/postfix/HISTORY b/postfix/HISTORY
@@ -28301,3 +28301,15 @@ Apologies for any names omitted.
 	File: mantools/check-snapshot-nonprod.
 
 	First general Postfix release with TLSRPT support.
+
+20240927
+
+	Feature: new parameter smtp_tlsrpt_skip_reused_handshakes
+	(default: yes) to suppress TLSRPT status reports for TLS
+	handshakes that reuse a previously-negotiated TLS session
+	(there would be no new information to report). Specify "no"
+	for TLSRPT troubleshooting. Files: mantools/postlink,
+	proto/TLSRPT_README.html, proto/postconf.proto, smtp/smtp.c,
+	smtp/smtp_params.c, smtp/smtp_tlsrpt.c, tls/tls_client.c,
+	tls/tls_proxy_client_print.c, tls/tls_proxy_client_scan.c,
+	tls/tlsrpt_wrapper.c, tls/tlsrpt_wrapper.h.
diff --git a/postfix/README_FILES/TLSRPT_README b/postfix/README_FILES/TLSRPT_README
@@ -133,35 +133,45 @@ daemon:
     [ipaddr],
         failure_type=validation_failure, failure_reason=self-signed_certificate
 
-Note: Postfix logs and reports TLSRPT status only for TLS handshakes on a new
-SMTP connection. There is no TLSRPT status logging for a reused SMTP
-connection. Such connections have Postfix SMTP client logging like this:
+Notes:
+
+  * Postfix logs and reports the TLSRPT status only for TLS handshakes on a new
+    SMTP connection. There is no TLS handshake, and thus no TLSRPT status
+    logging, when an SMTP connection is reused. Such connections have Postfix
+    SMTP client logging like this:
 
     Verified TTLLSS ccoonnnneeccttiioonn rreeuusseedd to mail.example.com[ipaddr]:25:
         TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)
 
     Untrusted TTLLSS ccoonnnneeccttiioonn rreeuusseedd to mail.example.com[ipaddr]:25:
         TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)
 
-Postfix logs certificate verification failures with a level of detail that is
-different for a new or reused TLS session.
+  * By default, Postfix does not report the TLSRPT status for a TLS handshake
+    that reuses a previously-negotiated TLS session (there would be no new
+    information to report). Specify "smtp_tlsrpt_skip_reused_handshakes = no"
+    to report the TLSRPT status for all TLS handshakes. This may be useful for
+    troubleshooting.
 
-  * A new TLS session is logged with certificate verification failure details:
+  * Postfix logging for certificate verification failures may differ between
+    new or reused TLS sessions.
 
-    TLSRPT: status=failure, domain=example.org, receiving_mx=mail.example.org
-    [ipaddr],
-        ffaaiilluurree__ttyyppee==vvaalliiddaattiioonn__ffaaiilluurree, ffaaiilluurree__rreeaassoonn==sseellff--ssiiggnneedd__cceerrttiiffiiccaattee
+      o New TLS session:
 
-  * A reused TLS session is indicated as shown below, and has no certificate
-    verification details:
+        TLSRPT: status=failure, domain=example.org,
+        receiving_mx=mail.example.org[ipaddr],
+            ffaaiilluurree__ttyyppee==vvaalliiddaattiioonn__ffaaiilluurree, ffaaiilluurree__rreeaassoonn==sseellff--
+        ssiiggnneedd__cceerrttiiffiiccaattee
 
-    mail.example.org[ipaddr]:25: rree--uussiinngg sseessssiioonn with untrusted peer
-        credential, look for details earlier in the log
-    TLSRPT: status=failure, domain=example.org, receiving_mx=mail.example.org
-    [ipaddr],
-        ffaaiilluurree__ttyyppee==cceerrttiiffiiccaattee__nnoott__ttrruusstteedd
+      o Reused TLS session:
 
-Some Postfix users may wonder where the difference comes from. So this is why.
+        mail.example.org[ipaddr]:25: rree--uussiinngg sseessssiioonn with untrusted peer
+            credential, look for details earlier in the log
+        TLSRPT: status=failure, domain=example.org,
+        receiving_mx=mail.example.org[ipaddr],
+            ffaaiilluurree__ttyyppee==cceerrttiiffiiccaattee__nnoott__ttrruusstteedd
+
+    The logging may differ because a reused TLS session does not have the
+    details for why TLS authentication failed.
 
 DDeelliivveerriinngg TTLLSSRRPPTT ssuummmmaarriieess vviiaa eemmaaiill
 
@@ -258,16 +268,16 @@ datatracker.ietf.org/doc/html/rfc8460#section-4.5.
 
 LLiimmiittaattiioonnss
 
-The Postfix TLSRPT implementation reports at most one final TLS handshake
-status (either 'success' or 'failure') per connection. Postfix TLSRPT cannot
-report a failure and then later report a final status of 'success' for that
-same connection. The reason is that it's too complicated to filter TLS errors
-and to report error details from the TLS engine back to the SMTP protocol
-engine. It just is not how Postfix works internally.
-
 The Postfix TLSRPT implementation reports only TLS handshake success or
-failure. It does not report failure to connect, or connections that break after
-a successful TLS handshake.
+failure. It does not report failure to connect, or connections that break
+before or after a TLS handshake.
+
+The Postfix TLSRPT implementation reports at most one final TLS handshake
+status (either 'success' or 'failure') per SMTP connection. Postfix TLSRPT will
+not report a recoverable failure and then later report a final status of
+'success' for that same connection. The reason is that it's too complicated to
+filter TLS errors and to report error details from the TLS engine back to the
+SMTP protocol engine. It just is not how Postfix works internally.
 
 CCrreeddiittss
 

diff --git a/postfix/WISHLIST b/postfix/WISHLIST
@@ -7,7 +7,9 @@ Wish list:
 	Disable -DSNAPSHOT and -DNONPROD in makedefs.
 
 	Add smtp_tlsrpt_allow_list feature (default: static:all) to limit
-	the domains for which Postfix generates TLSRPT daily sumamries.
+	the domains for which Postfix generates TLSRPT daily summaries.
+
+	Rename TLS_SESS_STATE.rpt_reported to skip_tlsrpt_report.
 
 	Add unit tests for smtp_tlsrpt.c, tlstrpd_wrapper.c, ...
 

diff --git a/postfix/html/TLSRPT_README.html b/postfix/html/TLSRPT_README.html
@@ -105,8 +105,8 @@ <h2> <a name="intro"> Introduction </a> </h2>
 engine. With "<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> = no", the <a href="smtp.8.html">smtp(8)</a> client
 process also implements the TLS client engine. With
 "<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> = yes", the <a href="smtp.8.html">smtp(8)</a> client process
-delegates TLS processing to a Postfix <a href="tlsproxy.8.html">tlsproxy(8)</a> process.  Either
-way, Postfix will generate the exact same TLSRPT events.  </p>
+delegates TLS processing to a Postfix <a href="tlsproxy.8.html">tlsproxy(8)</a> process. Either
+way, Postfix will generate the exact same TLSRPT events. </p>
 
 <h2> <a name="building"> Building Postfix with TLSRPT support </a>
 </h2>
@@ -211,36 +211,44 @@ <h2> <a name="logging"> TLSRPT Status logging </a> </h2>
 </pre>
 </blockquote>
 
-<p> Note: Postfix logs and reports TLSRPT status only for TLS
-handshakes on a new SMTP connection. There is no TLSRPT status
-logging for a reused SMTP connection. Such connections have 
-Postfix SMTP client logging like this: </p>
+<p> Notes: </p>
+
+<ul> 
+
+<li> <p> Postfix logs and reports the TLSRPT status only for TLS
+handshakes on a new SMTP connection. There is no TLS handshake, and
+thus no TLSRPT status logging, when an SMTP connection is reused.
+Such connections have Postfix SMTP client logging like this: </p>
 
-<blockquote> 
 <pre>
 Verified <b>TLS connection reused</b> to mail.example.com[ipaddr]:25:
     TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)
 &nbsp;
 Untrusted <b>TLS connection reused</b> to mail.example.com[ipaddr]:25:
     TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)
 </pre>
-</blockquote>
 
-<p> Postfix logs certificate verification failures with a level of
-detail that is different for a new or reused TLS session. </p>
+<li> <p> By default, Postfix does not report the TLSRPT status for
+a TLS handshake that reuses a previously-negotiated TLS session
+(there would be no new information to report). Specify
+"<a href="postconf.5.html#smtp_tlsrpt_skip_reused_handshakes">smtp_tlsrpt_skip_reused_handshakes</a> = no" to report the TLSRPT
+status for all TLS handshakes. This may be useful for troubleshooting.
+</p>
+
+<li> <p> Postfix logging for certificate verification failures may
+differ between new or reused TLS sessions. </p>
 
 <ul>
 
-<li> <p> A new TLS session is logged with certificate verification
-failure details: </p>
+<li> <p> New TLS session:
+</p>
 
 <pre>
 TLSRPT: status=failure, domain=example.org, receiving_mx=mail.example.org[ipaddr],
     <b>failure_type=validation_failure</b>, <b>failure_reason=self-signed_certificate</b>
 </pre>
 
-<li> <p> A reused TLS session is indicated as shown below, and has
-no certificate verification details: </p>
+<li> <p> Reused TLS session: </p>
 
 <pre>
 mail.example.org[ipaddr]:25: <b>re-using session</b> with untrusted peer
@@ -251,8 +259,10 @@ <h2> <a name="logging"> TLSRPT Status logging </a> </h2>
 
 </ul>
 
-<p> Some Postfix users may wonder where the difference comes from.
-So this is why. </p>
+<p> The logging may differ because a reused TLS session does not
+have the details for why TLS authentication failed. </p>
+
+</ul>
 
 <h2> <a name="delivering"> Delivering TLSRPT summaries via email</a> </h2>
 
@@ -381,17 +391,17 @@ <h2> <a name="mta-sts"> MTA-STS Support via smtp_tls_policy_maps
 
 <h2> <a name="limitations"> Limitations </a></h2>
 
-<p> The Postfix TLSRPT implementation reports at most one final TLS
-handshake status (either 'success' or 'failure') per connection.
-Postfix TLSRPT cannot report a failure and then later report a final
-status of 'success' for that same connection. The reason is that
-it's too complicated to filter TLS errors and to report error details
-from the TLS engine back to the SMTP protocol engine. It just is
-not how Postfix works internally. </p>
-
 <p> The Postfix TLSRPT implementation reports only TLS handshake
 success or failure. It does not report failure to connect, or
-connections that break after a successful TLS handshake. </p>
+connections that break before or after a TLS handshake. </p>
+
+<p> The Postfix TLSRPT implementation reports at most one final TLS
+handshake status (either 'success' or 'failure') per SMTP connection.
+Postfix TLSRPT will not report a recoverable failure and then later
+report a final status of 'success' for that same connection. The
+reason is that it's too complicated to filter TLS errors and to
+report error details from the TLS engine back to the SMTP protocol
+engine. It just is not how Postfix works internally. </p>
 
 <h2> <a name="credits"> Credits </a> </h2>
 

diff --git a/postfix/html/lmtp.8.html b/postfix/html/lmtp.8.html
@@ -702,8 +702,8 @@
        Available in Postfix version 3.2 and later:
 
        <b><a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a> (see 'postconf -d' output)</b>
-              The prioritized list of elliptic curves supported by the Postfix
-              SMTP client and server.
+              The prioritized list of elliptic curves, that should be  enabled
+              in the Postfix SMTP client and server.
 
        Available in Postfix version 3.4 and later:
 
@@ -753,6 +753,11 @@
               The pathname of a UNIX-domain datagram socket that is managed by
               a local TLSRPT reporting service.
 
+       <b><a href="postconf.5.html#smtp_tlsrpt_skip_reused_handshakes">smtp_tlsrpt_skip_reused_handshakes</a> (yes)</b>
+              Do not report the TLSRPT status for TLS protocol handshakes that
+              reuse a previously-negotiated  TLS  session  (there  is  no  new
+              information to report).
+
 <b>OBSOLETE STARTTLS CONTROLS</b>
        The  following  configuration  parameters  exist for compatibility with
        Postfix versions before 2.3. Support for these will  be  removed  in  a

diff --git a/postfix/html/postconf.5.html b/postfix/html/postconf.5.html
@@ -14808,12 +14808,27 @@ <h2> Postfix main.cf file format </h2>
 <p> Enable support for <a href="https://tools.ietf.org/html/rfc8460">RFC 8460</a> TLSRPT notifications. A mail receiving
 domain can publish a TLSRPT policy in DNS, to request periodic
 summaries of successful and failed SMTP over TLS connections to
-their mail servers. This feature requires that Postfix is built
+their MX servers. This feature requires that Postfix is built
 with a TLSRPT supporting library. </p>
 
 <p> This feature is available in Postfix &ge; 3.10. </p>
 
 
+</DD>
+
+<DT><b><a name="smtp_tlsrpt_skip_reused_handshakes">smtp_tlsrpt_skip_reused_handshakes</a>
+(default: yes)</b></DT><DD>
+
+<p> Do not report the TLSRPT status for TLS protocol handshakes
+that reuse a previously-negotiated TLS session (there is no new
+information to report). Report the TLSRPT status only for "new" TLS
+sessions. Set this to "no" to log the TLSRPT status of all TLS
+handshakes, for example to troubleshoot Postfix TLSRPT support.
+</p>
+
+<p> This feature is available in Postfix &ge; 3.10. </p>
+
+
 </DD>
 
 <DT><b><a name="smtp_tlsrpt_socket_name">smtp_tlsrpt_socket_name</a>

diff --git a/postfix/html/smtp.8.html b/postfix/html/smtp.8.html
@@ -702,8 +702,8 @@
        Available in Postfix version 3.2 and later:
 
        <b><a href="postconf.5.html#tls_eecdh_auto_curves">tls_eecdh_auto_curves</a> (see 'postconf -d' output)</b>
-              The prioritized list of elliptic curves supported by the Postfix
-              SMTP client and server.
+              The prioritized list of elliptic curves, that should be  enabled
+              in the Postfix SMTP client and server.
 
        Available in Postfix version 3.4 and later:
 
@@ -753,6 +753,11 @@
               The pathname of a UNIX-domain datagram socket that is managed by
               a local TLSRPT reporting service.
 
+       <b><a href="postconf.5.html#smtp_tlsrpt_skip_reused_handshakes">smtp_tlsrpt_skip_reused_handshakes</a> (yes)</b>
+              Do not report the TLSRPT status for TLS protocol handshakes that
+              reuse a previously-negotiated  TLS  session  (there  is  no  new
+              information to report).
+
 <b>OBSOLETE STARTTLS CONTROLS</b>
        The  following  configuration  parameters  exist for compatibility with
        Postfix versions before 2.3. Support for these will  be  removed  in  a

diff --git a/postfix/man/man5/postconf.5 b/postfix/man/man5/postconf.5
@@ -9864,10 +9864,18 @@ This feature is available in Postfix 3.0 and later.
 Enable support for RFC 8460 TLSRPT notifications. A mail receiving
 domain can publish a TLSRPT policy in DNS, to request periodic
 summaries of successful and failed SMTP over TLS connections to
-their mail servers. This feature requires that Postfix is built
+their MX servers. This feature requires that Postfix is built
 with a TLSRPT supporting library.
 .PP
 This feature is available in Postfix >= 3.10.
+.SH smtp_tlsrpt_skip_reused_handshakes (default: yes)
+Do not report the TLSRPT status for TLS protocol handshakes
+that reuse a previously\-negotiated TLS session (there is no new
+information to report). Report the TLSRPT status only for "new" TLS
+sessions. Set this to "no" to log the TLSRPT status of all TLS
+handshakes, for example to troubleshoot Postfix TLSRPT support.
+.PP
+This feature is available in Postfix >= 3.10.
 .SH smtp_tlsrpt_socket_name (default: empty)
 The pathname of a UNIX\-domain datagram socket that is managed
 by a local TLSRPT reporting service. This parameter must specify a

diff --git a/postfix/man/man8/smtp.8 b/postfix/man/man8/smtp.8
@@ -637,8 +637,8 @@ record was found via an "insecure" MX lookup.
 .PP
 Available in Postfix version 3.2 and later:
 .IP "\fBtls_eecdh_auto_curves (see 'postconf -d' output)\fR"
-The prioritized list of elliptic curves supported by the Postfix
-SMTP client and server.
+The prioritized list of elliptic curves, that should be enabled in the
+Postfix SMTP client and server.
 .PP
 Available in Postfix version 3.4 and later:
 .IP "\fBsmtp_tls_connection_reuse (no)\fR"
@@ -678,6 +678,10 @@ Enable support for RFC 8460 TLSRPT notifications.
 .IP "\fBsmtp_tlsrpt_socket_name (empty)\fR"
 The pathname of a UNIX\-domain datagram socket that is managed
 by a local TLSRPT reporting service.
+.IP "\fBsmtp_tlsrpt_skip_reused_handshakes (yes)\fR"
+Do not report the TLSRPT status for TLS protocol handshakes
+that reuse a previously\-negotiated TLS session (there is no new
+information to report).
 .SH "OBSOLETE STARTTLS CONTROLS"
 .na
 .nf

diff --git a/postfix/mantools/postlink b/postfix/mantools/postlink
@@ -723,8 +723,10 @@ while (<>) {
     s;\blmtp_tls_connection_reuse\b;<a href="postconf.5.html#lmtp_tls_connection_reuse">$&</a>;g;
     s;\bsmtp_tlsrpt_enable\b;<a href="postconf.5.html#smtp_tlsrpt_enable">$&</a>;g;
     s;\bsmtp_tlsrpt_socket_name\b;<a href="postconf.5.html#smtp_tlsrpt_socket_name">$&</a>;g;
+    s;\bsmtp_tlsrpt_skip_reused_handshakes\b;<a href="postconf.5.html#smtp_tlsrpt_skip_reused_handshakes">$&</a>;g;
     s;\blmtp_tlsrpt_enable\b;<a href="postconf.5.html#lmtp_tlsrpt_enable">$&</a>;g;
     s;\blmtp_tlsrpt_socket_name\b;<a href="postconf.5.html#lmtp_tlsrpt_socket_name">$&</a>;g;
+    s;\blmtp_tlsrpt_skip_reused_handshakes\b;<a href="postconf.5.html#lmtp_tlsrpt_skip_reused_handshakes">$&</a>;g;
     s;\bsmtpd_enforce_tls\b;<a href="postconf.5.html#smtpd_enforce_tls">$&</a>;g;
     s;\bsmtpd_sasl_tls_security_options\b;<a href="postconf.5.html#smtpd_sasl_tls_security_options">$&</a>;g;
     s;\bsmtpd_sasl_type\b;<a href="postconf.5.html#smtpd_sasl_type">$&</a>;g;