Index

TLS-RPT

TL;DR

TLS Reporting (TLS-RPT) is a reporting standard for email delivery. The reports contain information on the use of secure email transport (SMTP over TLS) to your domain from the sender's perspective.

TLS reporting is especially useful in combination with MTA-STS, as enforced mode in MTA-STS will result in undeliverable email if there is a problem with TLS.

Why TLS reporting is needed

When the SMTP email protocol was first defined in the early 80's, it did not support encrypted transport of email. Encryption using TLS was later added as the RFC3207 standard, implemented as the STARTTLS SMTP command.

To retain backwards compatibility, the MTAs will negotiate if STARTTLS is supported by both sides before the command is issued. So, the SMTP session always starts in plain text, and only switches to encrypted communication after the STARTTLS command is issued. Because TLS can fail in more ways than plain text connections, most MTAs will fall back to plain text if for some reason the TLS connection does not work.

With the introduction of MTA-STS in RFC8461, it is now possible to enforce the use of TLS when receiving email. The plain-text fallback will no longer be allowed, so if TLS fails the email will not be delivered and returned to its sender.

It is therefore important for the domain owner to be notified when TLS issues occur during email delivery. TLS-RPT makes that monitoring possible.

The TLS-RPT standard is defined in RFC8460.

The TLS-RPT DNS record

To enable TLS-RPT, a DNS record of type TXT must be added to subdomain _smtp._tls.[domain] (note the use of underscores). For example: _smtp._tls.mailhardener.com

A typical TLS-RPT DNS records looks like this:

v=TLSRPTv1; rua=mailto:tlsrpt@mailhardener.com

If you worked with DMARC before, you will be familiar with the syntax of the record.

The TLS-RPT records is a key-value string, where the key and values are separated with an equal (=) character, and the key-value pairs are separated with a semicolon. Any whitespace is ignored.

Only 2 directives are specified:

key value
v The version indicator, must be the first key-value pair in the record and only value TLSRPTv1 is supported.
rua The address where the reports should be send to. Multiple values are allowed and should be separated by a comma.

The rua value must specify the used scheme, for TLS-RPT this must either be mailto: or https:. The mailto: scheme is similar to that used in DMARC, is specifies an email address where the reports should be send to. Using the https: scheme requires a HTTPS enabled web server with a valid certificate for the domain, the reporting MTA will POST the report over HTTPS.

The rua value can contain multiple delivery endpoints by separating them with a comma. Both delivery schemes can used together. However, a reporter is not obligated to deliver the report to more than one endpoint. A combined rua scheme looks like this:

v=TLSRPTv1; rua=mailto:tlsrpt@mailhardener.com,https://tlsrpt.mailhardener.com/v1

Since TLS-RPT is designed to work in conjunction with MTA-STS, the MTA should be able to connect to a web server over HTTPS (port 443), this made the https: scheme viable for TLS-RPT.

You can use our TLS-RPT record validator to check if your domain is correctly configured to receive TLS reports.

The report format

The TLS reports are sent in JSON format. Although JSON is considered a human readable the reports are not meant to be read in JSON format by a human.

Typically, a log aggregator service such as Mailhardener is used to combine the reports that are received from various MTAs, enrich the data and present them in a human friendly matter.

Error types

TLS-RPT is used to report failures for both MTA-STS, and DANE. Although DANE adoption is still very limited as of 2019.

The error types that can be reported are divided into 3 categories: TLS negotiation failures, DANE policy failures, and STS-MTA failures.

Negotiation failures

error description
starttls-not-supported The receiving MTA did not support the STARTTLS command
certificate-host-mismatch The certificate supplied by the receiving MTA did not match its hostname
certificate-not-trusted The certificate supplied by the receiving MTA was not trusted by the sender
certificate-expired The certificate supplied by the receiving MTA was expired
validation-failure Any general validation failure not matching any category above.
error description
tlsa-invalid This indicates a validation error in the TLSA record associated with a DANE policy.
dnssec-invalid This indicates that the recursive resolver was not returning any valid record
dane-required This indicates that the sending system is configured to require DANE TLSA records for all the MX hosts of the destination domain, but no DNSSEC-validated TLSA records were present for the MX host that is the subject of the report.
error description
sts-policy-fetch-error The MTA-STS policy could not be fetched over HTTPS by the sender.
sts-policy-invalid The MTA-STS policy could be fetched, but not validated. This usually indicates some syntax error in the policy.
sts-webpki-invalid The MTA-STS policy could not be fetched due to a PKI validation issue. This indicates a problem with the certificate supplied by the web server that hosts the MTA-STS policy file.

TLS reporting at Mailhardener

Mailhardener offers TLS-RPT aggregation service that will combine, enrich and analyse TLS-RPT reports. When anomalies are detected, you will automatically be informed.

screenshot showing TLS report breakboard in Mailhardener dashboard
Example of a TLS report breakdown in Mailhardener dashboard

Conclusion

TLS-RPT is a powerful reporting standard which is invaluable when using MTA-STS. It can be used to detect TLS related issues from the sender's perspective.

The number of email services that send TLS reports is still limited (as of writing in 2019), but expected to grow quickly.

TLS reports can be aggregated by services such as Mailhardener.

Tools

Further reading