1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
|
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"https://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Postfix TLSRPT notification Howto</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
</head>
<body>
<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix TLSRPT Howto</h1>
<hr>
<h2> Table of Contents </h2>
<ul>
<li> <a href="#intro"> Introduction </a> </li>
<li> <a href="#building"> Building Postfix with TLSRPT support </a>
<li> <a href="#using"> Turning on TLSRPT </a> </li>
<li> <a href="#logging"> TLSRPT Status logging </a> </li>
<li> <a href="#delivering"> Delivering TLSRPT summaries via email</a> </li>
<li> <a href="#mta-sts"> MTA-STS Support via smtp_tls_policy_maps </a> </li>
<li> <a href="#limitations"> Limitations </a></li>
<li> <a href="#credits"> Credits </a> </li>
</ul>
<h2> <a name="intro"> Introduction </a> </h2>
<p> The TLSRPT protocol is defined in <a href="https://tools.ietf.org/html/rfc8460">RFC 8460</a>. With this, an email
receiving domain can publish a policy in DNS, and request daily
summary reports for successful and failed SMTP over TLS connections
to that domain's MX hosts. Support for TLSRPT was added in Postfix
3.10. </p>
<p> A policy for domain <tt>example.com</tt> could look like this: </p>
<blockquote>
<pre>
_smtp._tls.example.com. IN TXT "v=TLSRPTv1; rua=mailto:smtp-tls-report@example.com"
</pre>
</blockquote>
<p> Instead of <tt>mailto:</tt>, a policy may specify an <tt>https:</tt>
destination. </p>
<p> The diagram below shows how Postfix TLS handshake success and
failure events are collected and processed into daily summary
reports. </p>
<blockquote>
<table>
<tr> <td align="center" bgcolor="#f0f0ff"> Postfix SMTP and TLS
client engines </td> <td> <tt> → </tt> </td>
<td align="center" bgcolor="#f0f0ff"> <a
href="https://github.com/sys4/libtlsrpt">TLSRPT client library </a>
(linked into Postfix) </td> <td> <tt> → </tt> </td>
<td align="center" bgcolor="#f0f0ff"> <a
href="https://github.com/sys4/tlsrpt-reporter">TLSRPT collector,
fetcher, and summary generator</a> </td> <td> <tt> → </tt>
</td>
<td align="center" bgcolor="#f0f0ff"> Email or HTTP delivery </td>
</tr>
</table>
</blockquote>
<ul>
<li> <p> The Postfix SMTP and TLS client engines will generate a
"success" or "failure" event for each TLS handshake, </p>
<li> <p> They will pass those events to an in-process TLSRPT client
library that sends data over a local socket to </p>
<li> <p> 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.
</p>
</ul>
<p> The TLSRPT client library, and the infrastructure to collect,
fetch, and report TLSRPT information, are implemented and maintained
by sys4 at <a href="https://github.com/sys4/libtlsrpt">https://github.com/sys4/libtlsrpt</a> and
<a href="https://github.com/sys4/tlsrpt-reporter">https://github.com/sys4/tlsrpt-reporter</a>, respectively. </p>
<p> The Postfix implementation supports TLSRPT or domains with DANE
(Postfix built-in) and MTA-STS (through an <a href="#mta-sts">
smtp_tls_policy_maps plug-in</a>). </p>
<p> The Postfix <a href="smtp.8.html">smtp(8)</a> client process implements the SMTP client
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>
<h2> <a name="building"> Building Postfix with TLSRPT support </a>
</h2>
<p> These instructions assume that you build Postfix from source
code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
be required if you build Postfix from a vendor-specific source
package. </p>
<p> 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: </p>
<blockquote>
<p> <a href="https://github.com/sys4/libtlsrpt">https://github.com/sys4/libtlsrpt</a> </p>
</blockquote>
<p> 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. </p>
<p> In order to build Postfix with TLSRPT support, you will need
to add compiler options <tt>-DUSE_TLSRPT</tt> (to build with TLSRPT
support) and <tt>-I</tt> (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: </p>
<blockquote>
<pre>
make -f Makefile.init makefiles \
"CCARGS=-DUSE_TLSRPT -I/usr/local/include" \
"AUXLIBS=-L/usr/local/lib -Wl,-rpath,/usr/local/lib -ltlsrpt"
</pre>
</blockquote>
<p> (On Solaris systems you may need to use "<tt>-Wl,-R</tt>" instead
of "<tt>-Wl,-rpath</tt>".) </p>
<p> Then, just run 'make'. </p>
<blockquote>
<p> 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: </p>
<pre>
make -f Makefile.init makefiles \
"CCARGS=... -DUSE_TLSRPT -I/usr/local/include" \
"AUXLIBS=... -L/usr/local/lib -Wl,-rpath,/usr/local/lib -ltlsrpt"
</pre>
</blockquote>
<h2> <a name="using"> Turning on TLSRPT </a> </h2>
<p> After installing Postfix TLSRPT support, you can enable TLSRPT
support in <a href="postconf.5.html">main.cf</a> like this: </p>
<blockquote>
<pre>
<a href="postconf.5.html#smtp_tlsrpt_enable">smtp_tlsrpt_enable</a> = yes
<a href="postconf.5.html#smtp_tlsrpt_socket_name">smtp_tlsrpt_socket_name</a> = path/to/socket
</pre>
</blockquote>
<p> The <a href="postconf.5.html#smtp_tlsrpt_socket_name">smtp_tlsrpt_socket_name</a> parameter specifies either an
absolute pathname, or a pathname that is relative to $<a href="postconf.5.html#queue_directory">queue_directory</a>.
</p>
<p> Notes: </p>
<ul>
<li> <p> The recommended socket location is still to be determined.
A good socket location would be under the Postfix queue directory,
for example: "<a href="postconf.5.html#smtp_tlsrpt_socket_name">smtp_tlsrpt_socket_name</a> = 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. </p>
<li> <p> Regardless of whether Postfix chroot is enabled, the TLSRPT
receiver (<tt>tlsrpt_collectd</tt>) will need to be configured with
the socket's absolute pathname. </p>
<li> <p> Do not specify a TLSRPT socket location under a Postfix socket
directory such as <tt>private</tt> or <tt>public</tt>. Only Postfix
programs should create sockets there. </p>
</ul>
<p> For details on how to run the TLSRPT collection and reporting
infrastructure, see the documentation at
<a href="https://github.com/sys4/tlsrpt-reporter">https://github.com/sys4/tlsrpt-reporter</a>.
<h2> <a name="logging"> TLSRPT Status logging </a> </h2>
<p> With TLSRPT support turned on, the Postfix TLSRPT client will
not only report an event to an invisible daily success/fail summary
queue, but it will also log a visible record to the mail logfile.
</p>
<p> Below are a few examples of logging from a Postfix SMTP client
or tlsproxy daemon: </p>
<blockquote>
<pre>
TLSRPT: status=success, domain=example.com, receiving_mx=mail.example.com[ipaddr]
TLSRPT: status=failure, domain=example.org, receiving_mx=mail.example.org[ipaddr],
failure_type=starttls_not_supported
TLSRPT: status=failure, domain=example.net, receiving_mx=mail.example.net[ipaddr],
failure_type=validation_failure, failure_reason=self-signed_certificate
</pre>
</blockquote>
<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>
<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)
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>
<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> 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> Reused TLS session: </p>
<pre>
mail.example.org[ipaddr]:25: <b>re-using session</b> with untrusted peer
credential, look for details earlier in the log
TLSRPT: status=failure, domain=example.org, receiving_mx=mail.example.org[ipaddr],
<b>failure_type=certificate_not_trusted</b>
</pre>
</ul>
<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>
<p> <a href="https://datatracker.ietf.org/doc/html/rfc8460#section-3">RFC
8460 Section 3</a> specifies that an MTA must not enforce TLS
security when sending failure reports via email. </p>
<p> Options:
<ul>
<li> <p> In an email report, specify the "<b>TLS-Required: no</b>"
message header,
defined in <a href="https://tools.ietf.org/html/rfc8689">RFC 8689</a>, to reduce the Postfix SMTP client TLS security
level to "<b>may</b>" (that is, do not verify remote SMTP server
certificates, and fall back to plaintext if TLS is unavailable).
<br> <br> 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. </p>
<li> <p> Do nothing. When TLS security enforcement is required but
fails, a TLSRPT summary message will be delayed
until the problem is addressed, or until the message expires
in the mail queue. Keep in mind that TLSRPT is not a real-time
monitoring service; it takes on average 12 hours before a failure
is reported through TLSRPT. </p>
<li> <p> On outbound MTAs that don't support the "<b>TLS-Required:
no</b>" 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): </p>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
# Limitation: this setting is overruled with <a href="postconf.5.html#transport_maps">transport_maps</a>.
<a href="postconf.5.html#sender_dependent_default_transport_maps">sender_dependent_default_transport_maps</a> = <a href="DATABASE_README.html#types">inline</a>:{
{ noreply-smtp-tls-reporting@example.com = allow-plaintext } }
 
/etc/postfix/<a href="master.5.html">master.cf</a>:
# service name type private unpriv chroot wakeup maxproc command
allow-plaintext unix - - - - - smtp
-o { <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may }
-o { <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">static</a>:may }
</pre>
</ul>
<h2> <a name="mta-sts"> MTA-STS Support via smtp_tls_policy_maps
</a></h2>
<p> Postfix supports MTA-STS though an <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> policy
plugin, which replies with a TLS security level and name=value
attributes with certificate matching requirements. Postfix 3.10 and
later extend the policy plugin response with additional name=value
attributes that are needed for TLSRPT. </p>
<p> Examples of <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> plugins with MTA-STS support
are: </p>
<ul>
<li> <p> <a href="https://github.com/Zuplu/postfix-tlspol">
postfix-tlspol</a>, supports domains with DANE (using Postfix
built-in DANE), and domains with MTA-STS. </p>
<li> <p> <a href="https://github.com/Snawoot/postfix-mta-sts-resolver">
postfix-mta-sts-resolver</a>, supports domains with MTA-STS as of
release 1.5.0 (February 2025). </p>
</ul>
<p> Both plugins can generate the additional name=value attributes
that Postfix needs for TLSRPT support (as of February 2025). This
is enabled by setting a <tt>tlsrpt</tt> boolean in a plugin
configuration file. This setting is safe with Postfix 3.10 and
later, even if Postfix TLSRPT support is disabled (at build time
or at run time). Postfix versions 3.9 and earlier will report a
policy error with "<tt>invalid attribute name</tt>". </p>
<p> The examples in the text below apply to this MTA-STS policy example
given in <a
href="https://datatracker.ietf.org/doc/html/rfc8461#section-3.2">
RFC 8461 Section 3.2</a>: </p>
<blockquote>
<pre>
version: STSv1
mode: enforce
mx: mail.example.com
mx: *.example.net
mx: backupmx.example.com
max_age: 604800
</pre>
</blockquote>
<p> The list of supported attributes is given below. Instead of
<tt>name=value</tt>, specify <tt>{ name = value }</tt> when a value
may contain whitespace. A policy response may contain line breaks.
</p>
<ul>
<li> <p> <tt> policy_type=<i>type</i> </tt> </p>
<p> Specify <tt>sts</tt> or <tt>no-policy-found</tt>. </p>
<p> Example: <tt>policy_type=sts</tt> </p> </li>
<li> <p> <tt> policy_domain=<i>name</i> </tt> </p>
<p> The domain that the MTA-STS policy applies to. </p>
<p> Example: <tt>policy_domain=example.com</tt> </p>
</li>
<li> <p> <tt> { policy_string = <i>value</i> } </tt> </p>
<p> Specify one <tt>policy_string</tt> instance for each MTA-STS
policy feature, enclosed inside "{" and "}" to protect whitespace
in attribute values. <p>
<p> Example: <tt> { policy_string = version: STSv1 } { policy_string
= mode: enforce } ...</tt> </p>
<p> The above form ignores whitespace after the opening "{", around
the "=", and before the closing "}".</p> </li>
<li> <p> <tt> mx_host_pattern=<i>pattern</i> </tt> </p>
<p> Specify one <tt>mx_host_pattern</tt> instance for each "mx:" feature
in the MTA-STS policy. </p>
<p> Example: <tt>mx_host_pattern=mail.example.com
mx_host_pattern=*.example.net ...</tt> </p> </li>
<li> <p> <tt> policy_failure=<i>type</i> </tt> </p>
<p> If specified, forces MTA-STS policy enforcement to fail with
the indicated error, even if a server certificate would satisfy
conventional PKI constraints. Valid errors are <tt>sts-policy-fetch-error,
sts-policy-invalid</tt>, <tt>sts-webpki-invalid</tt>, or the less
informative <tt>validation-failure</tt>. </p>
<p> Example: <tt>policy_failure=sts-webpki-invalid</tt> </p> </li>
<li> <p> <tt> policy_ttl=<i>time</i> </tt> (deprecated) </p>
<p> This attribute is deprecated. The <i>time</i> value is not used,
and support for this attribute will eventually be removed from the
code. </p> </li>
</ul>
<p> Notes: </p>
<ul>
<li> <p> Postfix 3.10 and later will accept these additional
attributes in an MTA-STS response even if Postfix TLSRPT support
is disabled (at build time or at run time). With Postfix TLSRPT
support turned off, Postfix may still use the <tt>policy_failure</tt>
attribute, and will ignore the attributes that are used only for
TLSRPT. </p>
<li> <p> It is an error to specify these attributes for a non-STS
policy. </p>
</ul>
<h2> <a name="limitations"> Limitations </a></h2>
<p> The Postfix TLSRPT implementation reports only TLS handshake
success or failure. It does not report failure to connect, or
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>
<ul>
<li> The TLSRPT client library, and the infrastructure to collect,
fetch, and report TLSRPT information, are implemented and maintained
by sys4. </li>
<li> Wietse Venema implemented the integration with Postfix.
</li>
</ul>
</body>
</html>
|
