diff --git a/postfix/HISTORY b/postfix/HISTORY index 83f568404..0ecbb813a 100644 --- a/postfix/HISTORY +++ b/postfix/HISTORY @@ -28887,4 +28887,14 @@ Apologies for any names omitted. Cleanup: a few remaining pre-ANSI C function definitions in the lowest-level Postfix code. Files: util/binhash.c, - util/close_on_exec.c, util/non_blocking.c. + util/close_on_exec.c, util/non_blocking.c, util/ring.c. + +20250130 + + Updated the TLSRPT_README introduction, github info, and + build instructions. File: proto/TLSRPT_README.html. + +20250131 + + Debug: verbose logging for the tlsrpt_wrapper functions. + File: tls/tlsrpt_wrapper.c. diff --git a/postfix/README_FILES/TLSRPT_README b/postfix/README_FILES/TLSRPT_README index 2553348e4..8c8c24553 100644 --- a/postfix/README_FILES/TLSRPT_README +++ b/postfix/README_FILES/TLSRPT_README @@ -30,14 +30,12 @@ successful and failed SMTP over TLS connections to domain example.com, and to report those summaries via email to the specified address. Instead of mailto:, a policy may specify an https: destination. -The high-level diagram shows how Postfix reports summaries to domains that -publish a TLSRPT policy. +The high-level diagram below shows how TLS handshake success and failure events +from Postfix are collected and processed into daily summary reports. - Postfix SMTP and TLSRPT client TLSRPT summary Email or HTTP - TLS client --> library --> generator --> delivery - engines - -When Postfix TLSRPT support is enabled (with "smtp_tlsrpt_enable = yes"): + Postfix SMTP and TLSRPT client TLSRPT collector, Email or HTTP + TLS client engines -> library (linked -> fetcher, and -> delivery + into Postfix) summary generator * The Postfix SMTP and TLS client engines will generate a "success" or "failure" event for each TLS handshake, @@ -45,9 +43,13 @@ When Postfix TLSRPT support is enabled (with "smtp_tlsrpt_enable = yes"): * They will pass those events to an in-process TLSRPT client library that sends data over a local socket to - * A TLSRPT report generator that produces daily summary reports. + * A local TLSRPT collector that runs on each Postfix machine. A TLSRPT + fetcher gathers information from individual collectors, and a central + TLSRPT report generator produces daily summary reports. -The TLSRPT client library and report generator are maintained by sys4. +The TLSRPT client library, and the infrastructure to collect, fetch, and report +TLSRPT information are maintained by sys4 at https://github.com/sys4/libtlsrpt +and https://github.com/sys4/tlsrpt-reporter, respectively. The Postfix implementation supports both DANE (Postfix built-in) and MTA-STS (through an smtp_tls_policy_maps plug-in). @@ -64,33 +66,35 @@ These instructions assume that you build Postfix from source code as described in the INSTALL document. Some modification may be required if you build Postfix from a vendor-specific source package. -The Postfix TLSRPT client builds on a TLSRPT client library whose source code -can be obtained from: +The Postfix TLSRPT client builds on a TLSRPT library which may be available as +a built package (rpm, deb, etc.), or which you can build from source code from: - https://github.com/sys4/tlsrpt + https://github.com/sys4/libtlsrpt The library is typically installed as a header file in /usr/local/include/ tlsrpt.h and an object library in /usr/local/lib/libtlsrpt.a or /usr/local/lib/ libtlsrpt.so. The actual pathnames will depend on OS platform conventions. In order to build Postfix with TLSRPT support, you will need to add compiler -options -DUSE_TLSRPT (to build with TLSRPT support), and -I (with the directory +options -DUSE_TLSRPT (to build with TLSRPT support) and -I (with the directory containing the tlsrpt.h header file), and you will need to add linker options to link with the TLSRPT client library, for example: make -f Makefile.init makefiles \ "CCARGS=-DUSE_TLSRPT -I/usr/local/include" \ - "AUXLIBS=-L/usr/local/lib -ltlsrpt" + "AUXLIBS=-L/usr/local/lib -Wl,-rpath,/usr/local/lib -ltlsrpt" + +(On Solaris systems you may need to use "-Wl,-R" instead of "-Wl,-rpath".) Then, just run 'make'. Note: if your build command line already has CCARGS or AUXLIBS settings, then simply append the above settings to the existing CCARGS or AUXLIBS - values. + values: - make -f Makefile.init makefiles \ - "CCARGS=existing settings... -DUSE_TLSRPT -I/usr/local/include" \ - "AUXLIBS=existing settings... -L/usr/local/lib -ltlsrpt" + make -f Makefile.init makefiles \ + "CCARGS=... -DUSE_TLSRPT -I/usr/local/include" \ + "AUXLIBS=... -L/usr/local/lib -Wl,-rpath,/usr/local/lib -ltlsrpt" TTuurrnniinngg oonn TTLLSSRRPPTT @@ -98,20 +102,29 @@ After installing Postfix TLSRPT support, you can enable TLSRPT support in main.cf like this: smtp_tlsrpt_enable = yes - smtp_tlsrpt_socket_name = /path/to/socket + smtp_tlsrpt_socket_name = path/to/socket -The smtp_tlsrpt_socket_name parameter specifies an absolute pathname, or a -pathname that is relative to $queue_directory. +The smtp_tlsrpt_socket_name parameter specifies either an absolute pathname, or +a pathname that is relative to $queue_directory. - Note: the recommended socket location is still to be determined. A good - socket location would be under the Postfix queue directory, for example: +Notes: + + * The recommended socket location is still to be determined. A good socket + location would be under the Postfix queue directory, for example: "smtp_tlsrpt_socket_name = run/tlsrpt/tlsrpt.sock". The advantage of using a relative name is that it will work equally well whether or not Postfix chroot is turned on. -Do not specify a location under a directory such as private or public that is -already used by Postfix programs. Only Postfix programs should create sockets -there. + * Regardless of whether Postfix chroot is enabled, the TLSRPT receiver + (tlsrpt_collectd) will need to be configured with the socket's absolute + pathname. + + * Do not specify a TLSRPT socket location under a Postfix socket directory + such as private or public. Only Postfix programs should create sockets + there. + +For details on how to run the TLSRPT collection and reporting infrastructure, +see the documentation at https://github.com/sys4/tlsrpt-reporter. TTLLSSRRPPTT SSttaattuuss llooggggiinngg @@ -176,16 +189,17 @@ Notes: DDeelliivveerriinngg TTLLSSRRPPTT ssuummmmaarriieess vviiaa eemmaaiill RFC 8460 Section 3 specifies that an MTA must not enforce TLS security when -sending failure reports via email. However, Postfix currently has no way to -request that TLS enforcement will be disabled when submitting an email message. +sending failure reports via email. Options: - * Specify the "TTLLSS--RReeqquuiirreedd:: nnoo" message header, defined in RFC 8689, to - reduce the TLS security level to "mmaayy" (that is, do not verify remote SMTP - server certificates, and fall back to plaintext if TLS is unavailable). + * In an email report, specify the "TTLLSS--RReeqquuiirreedd:: nnoo" message header, defined + in RFC 8689, to reduce the Postfix SMTP client TLS security level to "mmaayy" + (that is, do not verify remote SMTP server certificates, and fall back to + plaintext if TLS is unavailable). - This feature is available in Postfix 3.10 and later. + This feature is available in Postfix 3.10 and later. If your outbound MTAs + run an older version, you can use one of the options described below. * Do nothing. When TLS security enforcement is required but fails, a TLSRPT summary message will be delayed until the problem is addressed, or until @@ -193,10 +207,11 @@ Options: real-time monitoring service; it takes on average 12 hours before a failure is reported through TLSRPT. - * Exclude the sender of TLSRPT summaries from TLS security enforcement. - Implement the configuration below on outbound MTA instances (replace - noreply-smtp-tls-reporting@example.com with your actual report generator's - sender address): + * On outbound MTAs that don't support the "TTLLSS--RReeqquuiirreedd:: nnoo" header feature + (such as Postfix 3.9 and earlier), disable TLS security enforcement for the + sender of TLSRPT summaries. Implement the configuration below on outbound + MTA instances (replace noreply-smtp-tls-reporting@example.com with your + actual report generator's sender address): /etc/postfix/main.cf: # Limitation: this setting is overruled with transport_maps. diff --git a/postfix/html/TLSRPT_README.html b/postfix/html/TLSRPT_README.html index af9933257..602857f0b 100644 --- a/postfix/html/TLSRPT_README.html +++ b/postfix/html/TLSRPT_README.html @@ -55,32 +55,33 @@ summaries of successful and failed SMTP over TLS connections to domain specified address. Instead of mailto:, a policy may specify an https: destination.

-

The high-level diagram shows how Postfix reports summaries to -domains that publish a TLSRPT policy. +

The high-level diagram below shows how TLS handshake success +and failure events from Postfix are collected and processed into +daily summary reports.

- + - + - + - + +
Postfix SMTP and
TLS -client engines 		-->
Postfix SMTP and TLS +client engines → TLSRPT client
library -		 --> TLSRPT client library +(linked into Postfix) → TLSRPT summary
generator -		 --> TLSRPT collector, +fetcher, and summary generator → + Email or HTTP
delivery -
Email or HTTP delivery
-

When Postfix TLSRPT support is enabled (with "smtp_tlsrpt_enable -= yes"):

- -

The TLSRPT client library and report generator are maintained -by sys4.

+

The TLSRPT client library, and the infrastructure to collect, +fetch, and report TLSRPT information are maintained by sys4 at +https://github.com/sys4/libtlsrpt and +https://github.com/sys4/tlsrpt-reporter, respectively.

The Postfix implementation supports both DANE (Postfix built-in) -and MTA-STS (through an smtp_tls_policy_maps plug-in). -

+and MTA-STS (through an smtp_tls_policy_maps plug-in).

The Postfix smtp(8) client process implements the SMTP client engine. With "smtp_tls_connection_reuse = no", the smtp(8) client @@ -116,11 +120,12 @@ code as described in the INSTALL document. Some modif be required if you build Postfix from a vendor-specific source package.

-

The Postfix TLSRPT client builds on a TLSRPT client library -whose source code can be obtained from:

+

The Postfix TLSRPT client builds on a TLSRPT library which may +be available as a built package (rpm, deb, etc.), or which you can +build from source code from:

-

https://github.com/sys4/tlsrpt

+

https://github.com/sys4/libtlsrpt

The library is typically installed as a header file in @@ -130,7 +135,7 @@ actual pathnames will depend on OS platform conventions.

In order to build Postfix with TLSRPT support, you will need to add compiler options -DUSE_TLSRPT (to build with TLSRPT -support), and -I (with the directory containing the tlsrpt.h +support) and -I (with the directory containing the tlsrpt.h header file), and you will need to add linker options to link with the TLSRPT client library, for example:

@@ -138,28 +143,28 @@ the TLSRPT client library, for example: 

 make -f Makefile.init makefiles \
   "CCARGS=-DUSE_TLSRPT -I/usr/local/include" \
-  "AUXLIBS=-L/usr/local/lib -ltlsrpt"
+  "AUXLIBS=-L/usr/local/lib -Wl,-rpath,/usr/local/lib -ltlsrpt"
+

(On Solaris systems you may need to use "-Wl,-R" instead +of "-Wl,-rpath".)

+

Then, just run 'make'.

Note: if your build command line already has CCARGS or AUXLIBS settings, then simply append the above settings to the existing CCARGS -or AUXLIBS values.

+or AUXLIBS values:

-
 make -f Makefile.init makefiles \
-  "CCARGS=existing settings... -DUSE_TLSRPT -I/usr/local/include" \
-  "AUXLIBS=existing settings... -L/usr/local/lib -ltlsrpt"
+  "CCARGS=... -DUSE_TLSRPT -I/usr/local/include" \
+  "AUXLIBS=... -L/usr/local/lib -Wl,-rpath,/usr/local/lib -ltlsrpt"
-
-

Turning on TLSRPT

After installing Postfix TLSRPT support, you can enable TLSRPT @@ -168,27 +173,38 @@ support in main.cf like this: 

 smtp_tlsrpt_enable = yes
-smtp_tlsrpt_socket_name = /path/to/socket
+smtp_tlsrpt_socket_name = path/to/socket
-

The smtp_tlsrpt_socket_name parameter specifies an absolute -pathname, or a pathname that is relative to $queue_directory.

+

The smtp_tlsrpt_socket_name parameter specifies either an +absolute pathname, or a pathname that is relative to $queue_directory. +

-
+

Notes:

-

Note: the recommended socket location is still to be determined. +

+

  • Regardless of whether Postfix chroot is enabled, the TLSRPT +receiver (tlsrpt_collectd) will need to be configured with +the socket's absolute pathname.

    -

    Do not specify a location under a directory such as private -or public that is already used by Postfix programs. Only Postfix +

  • Do not specify a TLSRPT socket location under a Postfix socket +directory such as private or public. Only Postfix programs should create sockets there.

    + + +

    For details on how to run the TLSRPT collection and reporting +infrastructure, see the documentation at +https://github.com/sys4/tlsrpt-reporter. +

    TLSRPT Status logging

    With TLSRPT support turned on, the Postfix TLSRPT client will @@ -268,19 +284,20 @@ have the details for why TLS authentication failed.

    RFC 8460 Section 3 specifies that an MTA must not enforce TLS -security when sending failure reports via email. However, Postfix -currently has no way to request that TLS enforcement will be disabled -when submitting an email message.

    +security when sending failure reports via email.

    Options:

    + +

    For details on how to run the TLSRPT collection and reporting +infrastructure, see the documentation at +https://github.com/sys4/tlsrpt-reporter. +

    TLSRPT Status logging

    With TLSRPT support turned on, the Postfix TLSRPT client will @@ -268,19 +284,20 @@ have the details for why TLS authentication failed.

    RFC 8460 Section 3 specifies that an MTA must not enforce TLS -security when sending failure reports via email. However, Postfix -currently has no way to request that TLS enforcement will be disabled -when submitting an email message.

    +security when sending failure reports via email.

    Options: