RFC 8460
SMTP TLS Reporting
Part 1 of 6 is here, bestie 🎀 more parts are coming, so stay tuned!
SMTP TLS Reporting 🦋
- RFC number: 8460
- Category: Standards Track 💅
- Date: September 2018 📅
- Stream: Internet Engineering Task Force (IETF), ISSN
2070-1721🌸 - Authors: D. Margolis (Google, Inc.), A. Brotman (Comcast, Inc.), B. Ramakrishnan (Oath, Inc.), J. Jones (Microsoft, Inc.), and M. Risher (Google, Inc.) 👑
- Obsoletes and updates: the title block doesn't list anything this one obsoletes or updates 🙈
Abstract ✨
Okay so there are a bunch of protocols for setting up encrypted channels between SMTP Mail Transfer Agents (MTAs) 🔐. The big ones are STARTTLS, DNS-Based Authentication of Named Entities (DANE) TLSA, and MTA Strict Transport Security (MTA-STS). These can break because of a misconfiguration or an active attack 😭. When that happens, messages either never get delivered or get delivered over channels that aren't encrypted or aren't authenticated. This document defines a reporting mechanism and format so sending systems can share statistics and specific info about possible failures with recipient domains 💌. Recipient domains can then use those reports to spot potential attacks and to diagnose accidental misconfigurations 🔍. It's giving detective era, honestly.
Status of This Memo 📜
This is an Internet Standards Track document. 🌈
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It received public review and was approved for publication by the Internet Engineering Steering Group (IESG). You can find more about Internet Standards in Section 2 of RFC 7841 📚.
Info about the current status of this document, any errata, and how to give feedback on it lives at https://www.rfc-editor.org/info/rfc8460 🔗.
Copyright Notice 💜
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication of this document. Please read these documents carefully, because they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License 🫶.
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Related Technologies . . . . . . . . . . . . . . . . . . . . 5
3. Reporting Policy . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Example Reporting Policy . . . . . . . . . . . . . . . . 8
3.1.1. Report Using MAILTO . . . . . . . . . . . . . . . . . 8
3.1.2. Report Using HTTPS . . . . . . . . . . . . . . . . . 8
4. Reporting Schema . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Report Time Frame . . . . . . . . . . . . . . . . . . . . 9
4.2. Delivery Summary . . . . . . . . . . . . . . . . . . . . 10
4.2.1. Success Count . . . . . . . . . . . . . . . . . . . . 10
4.2.2. Failure Count . . . . . . . . . . . . . . . . . . . . 10
4.3. Result Types . . . . . . . . . . . . . . . . . . . . . . 10
4.3.1. Negotiation Failures . . . . . . . . . . . . . . . . 10
4.3.2. Policy Failures . . . . . . . . . . . . . . . . . . . 11
4.3.3. General Failures . . . . . . . . . . . . . . . . . . 11
4.3.4. Transient Failures . . . . . . . . . . . . . . . . . 12
4.4. JSON Report Schema . . . . . . . . . . . . . . . . . . . 12
4.5. Policy Samples . . . . . . . . . . . . . . . . . . . . . 15
5. Report Delivery . . . . . . . . . . . . . . . . . . . . . . . 15
5.1. Report Filename . . . . . . . . . . . . . . . . . . . . . 16
5.2. Compression . . . . . . . . . . . . . . . . . . . . . . . 17
5.3. Email Transport . . . . . . . . . . . . . . . . . . . . . 17
5.3.1. Example Report . . . . . . . . . . . . . . . . . . . 19
5.4. HTTPS Transport . . . . . . . . . . . . . . . . . . . . . 19
5.5. Delivery Retry . . . . . . . . . . . . . . . . . . . . . 20
5.6. Metadata Variances . . . . . . . . . . . . . . . . . . . 20
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
6.1. Message Headers . . . . . . . . . . . . . . . . . . . . . 20
6.2. Report Type . . . . . . . . . . . . . . . . . . . . . . . 21
6.3. +gzip Media Type Suffix . . . . . . . . . . . . . . . . . 22
6.4. application/tlsrpt+json Media Type . . . . . . . . . . . 23
6.5. application/tlsrpt+gzip Media Type . . . . . . . . . . . 24
6.6. STARTTLS Validation Result Types . . . . . . . . . . . . 25
7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.1. Normative References . . . . . . . . . . . . . . . . . . 28
9.2. Informative References . . . . . . . . . . . . . . . . . 30
Appendix A. Example Reporting Policy . . . . . . . . . . . . . . 32
A.1. Report Using MAILTO . . . . . . . . . . . . . . . . . . . 32
A.2. Report Using HTTPS . . . . . . . . . . . . . . . . . . . 32
Appendix B. Example JSON Report . . . . . . . . . . . . . . . . 32
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 341. Introduction 🎀
Okay so, the STARTTLS extension to SMTP [RFC3207] lets SMTP clients and hosts set up secure SMTP sessions over TLS 🔒. The design follows an approach people call "Opportunistic Security" (OS) [RFC7435] 🦋. This keeps things working with clients that don't support STARTTLS, but it also means an attacker could potentially eavesdrop on a session 👀. An attacker could do a downgrade or interception attack by deleting parts of the SMTP session (like the "250 STARTTLS" response), or by redirecting the whole session (maybe by overwriting the resolved MX record of the delivery domain) 💀.
Because these "downgrade attacks" aren't necessarily obvious to the receiving MTA, this document defines a mechanism that lets sending domains report failures at multiple stages of the MTA-to-MTA conversation 🕵️♀️.
Recipient domains can also use the mechanisms from MTA-STS [RFC8461] or DANE [RFC6698] to publish extra encryption and authentication requirements 🔐. This document defines a mechanism for sending domains that are compatible with MTA-STS or DANE to share success and failure statistics with recipient domains 📊.
Specifically, this document defines a reporting schema covering failures in routing, DNS resolution, and STARTTLS negotiation, plus policy validation errors for both DANE [RFC6698] and MTA-STS [RFC8461]. It also defines a standard TXT record that recipient domains can use to say where reports in this format should be sent 📬. The report can double as a heartbeat too, showing that systems are successfully negotiating TLS during sessions like they're supposed to 💖.
This document is meant as a companion to the MTA-STS [RFC8461] specification, and it adds reporting abilities for anyone implementing DANE [RFC7672] 🧚.
1.1. Terminology 📖
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🧠.
We also define these terms for use later in this document 🍓:
- MTA-STS Policy: A mechanism that lets administrators specify the expected TLS availability, presented identity, and desired actions for a given email recipient domain. MTA-STS is defined in [RFC8461].
- DANE Policy: A mechanism that lets administrators use DNSSEC to commit an MTA to supporting STARTTLS and to publish the criteria used to validate its presented certificates. DANE for SMTP is defined in [RFC7672], with the base specification defined in [RFC6698] (and updated by [RFC7671]).
- TLSRPT (TLS Reporting) Policy: A policy that specifies the endpoint where Sending MTAs should deliver reports 📨.
- Policy Domain: The domain that a TLSRPT, an MTA-STS, or a DANE policy is defined against. For TLSRPT and MTA-STS, this is typically the same as the envelope recipient domain [RFC5321]. But when mail gets routed to a "smarthost" gateway by local policy, the "smarthost" domain name is used instead. For DANE, the Policy Domain is the "TLSA base domain" of the receiving SMTP server, as described in Section 2.2.3 of RFC 7672 and Section 3 of RFC 6698 🌟.
- Sending MTA: The MTA that initiates the relay of an email message 🚀.
- Aggregate Report URI (rua): A comma-separated list of locations where the report is to be submitted 🗳️.
- ABNF: Augmented Backus-Naur Form, a syntax for formally specifying syntax, defined in [RFC5234] and [RFC7405] 🤓.
2. Related Technologies 🌸
- This document is meant as a companion to the SMTP MTA-STS specification [RFC8461] 💕.
- SMTP TLSRPT defines a mechanism that lets sending domains compatible with MTA-STS or DANE share success and failure statistics with recipient domains. DANE is defined in [RFC6698], and MTA-STS is defined in [RFC8461] ✨.
3. Reporting Policy 📨✨
okay bestie, this is where a domain says "hey world, I want reports!" 💅 A domain publishes a record in its DNS to say it wants to receive them. These SMTP TLSRPT policies get distributed via DNS from the Policy Domain's zone as TXT records (kinda like DMARC policies, iykyk 🦋) under the name "_smtp._tls". So for the Policy Domain "example.com", the recipient's TLSRPT policy can be retrieved from "_smtp._tls.example.com" 🌸
Policies are built from these directives:
- "v": This is version 1 of TLSRPT, and this value MUST be equal to "TLSRPTv1" 🎀 Other versions may be defined in later documents.
- "rua": This is a URI for the endpoint where aggregate info about policy validation results should be sent (see Section 4, "Reporting Schema", for more information) 📬 Two URI schemes are supported: "mailto" and "https". Just like DMARC [RFC7489], the Policy Domain can list multiple URIs, separated by commas.
- In the case of "https", reports should be submitted via POST [RFC7231] to the specified URI. Report submitters MAY ignore certificate validation errors when submitting reports via HTTPS POST.
- In the case of "mailto", reports should be submitted to the specified email address [RFC6068]. When sending failure reports via SMTP, Sending MTAs MUST deliver reports despite any TLS-related failures, and SHOULD NOT include this SMTP session in the next report. This may mean that the reports are delivered unencrypted 🙈 Reports sent via SMTP MUST contain a valid DomainKeys Identified Mail (DKIM) [RFC6376] signature by the reporting domain. Reports lacking such a signature MUST be ignored by the recipient. DKIM signatures MUST NOT use the "l=" attribute to limit the body length used in the signature. This is so attackers can't tack extra or misleading data onto a report without breaking the signature 🔥 The DKIM TXT record SHOULD contain the appropriate service type declaration, "s=tlsrpt". If it's not present, the receiving system MAY ignore reports lacking that service type.
Sample DKIM record:
dkim_selector._domainkey.example.com TXT
"v=DKIM1;k=rsa;s=tlsrpt;p=Mlf4qwSZfase4fa=="The formal definition of the "_smtp._tls" TXT record, defined using [RFC5234] and [RFC7405], looks like this 🧚
tlsrpt-record = tlsrpt-version 1*(field-delim tlsrpt-field)
[field-delim]
field-delim = *WSP ";" *WSP
tlsrpt-field = tlsrpt-rua / ; Note that the
tlsrpt-extension ; tlsrpt-rua record is
; required.
tlsrpt-version = %s"v=TLSRPTv1"
tlsrpt-rua = %s"rua="
tlsrpt-uri *(*WSP "," *WSP tlsrpt-uri)
tlsrpt-uri = URI
; "URI" is imported from [RFC3986];
; commas (ASCII 0x2C), exclamation
; points (ASCII 0x21), and semicolons
; (ASCII 0x3B) MUST be encoded
tlsrpt-extension = tlsrpt-ext-name "=" tlsrpt-ext-value
tlsrpt-ext-name = (ALPHA / DIGIT) *31(ALPHA /
DIGIT / "_" / "-" / ".")
tlsrpt-ext-value = 1*(%x21-3A / %x3C / %x3E-7E)
; chars excluding "=", ";", SP, and control
; charsNow the resolver-side drama 👀 If multiple TXT records for "_smtp._tls" come back, records that don't begin with "v=TLSRPTv1;" get tossed. If the number of resulting records is not one, senders MUST assume the recipient domain does not implement TLSRPT. If the resulting TXT record has multiple strings (as described in Section 3.3 of [RFC7208]), then the record MUST be treated as if those strings are concatenated without adding spaces 🧩
The record can declare more than one rua. If there's more than one, the reporter MAY attempt to deliver to each of the supported rua destinations. A receiver MAY opt to only attempt delivery to one of the endpoints; however, the report SHOULD NOT be considered successfully delivered until one of the endpoints accepts delivery of the report 💜
Parsers MUST accept TXT records that are syntactically valid (i.e., valid key/value pairs separated by semicolons) and implement a superset of this specification, in which case unknown fields SHALL be ignored 🦋
3.1. Example Reporting Policy
3.1.1. Report Using MAILTO
_smtp._tls.example.com. IN TXT \
"v=TLSRPTv1;rua=mailto:reports@example.com"3.1.2. Report Using HTTPS
_smtp._tls.example.com. IN TXT \
"v=TLSRPTv1; \
rua=https://reporting.example.com/v1/tlsrpt"4. Reporting Schema 🗂️
The report is a plaintext file encoded in the Internet JSON (I-JSON) format [RFC7493]. Cute and structured 💖
Aggregate reports contain the following fields:
- Report metadata:
- The organization responsible for the report
- Contact information for one or more responsible parties for the contents of the report
- A unique identifier for the report
- The reporting date range for the report
- Policy, consisting of:
- One of the following policy types: (1) the MTA-STS Policy applied (as a string), (2) the DANE TLSA record applied (as a string, with each RR entry of the RRset listed and separated by a semicolon), and (3) the literal string "no-policy-found", if neither a DANE nor MTA-STS Policy could be found.
- The domain for which the policy is applied
- The MX host
- Aggregate counts, comprising result type, Sending MTA IP, receiving MTA hostname, session count, and an optional additional information field containing a URI for recipients to review further information on a failure type.
Note that the failure types are non-exclusive 👑 An aggregate report may contain overlapping "counts" of failure types when a single send attempt ran into multiple errors. Reporters may report multiple applied policies (for example, an MTA-STS Policy and a DANE TLSA record for the same domain and MX). Because of this, even when only a single policy was applied, the "policies" field of the report body MUST be an array and not a singular value 🫶
In the case of multiple failure types, the "failure-details" array would contain multiple entries. Each entry would have its own set of information about that failure type.
4.1. Report Time Frame
The report SHOULD cover a full day, from 00:00-24:00 UTC. This should make failure events easier to correlate ⏰ To avoid accidentally overloading the system processing the reports, the reports should be delivered after some delay, perhaps several hours.
As an example, a sending site might want to add a random delay of up to four hours 🎀
func generate_sleep_delay() {
min_delay = 1
max_delay = 14400
rand = random(min_delay, max_delay)
return rand
}
func generate_report(policy_domain) {
do_rpt_work(policy_domain)
send_rpt(policy_domain)
}
func generate_tlsrpt() {
sleep(generate_sleep_delay())
for policy_domain in list_of_tlsrpt_enabled_domains {
generate_report(policy_domain)
}
}4.2. Delivery Summary
4.2.1. Success Count
- "total-successful-session-count": This indicates that the Sending MTA was able to successfully negotiate a policy-compliant TLS connection 💚 It serves as a "heartbeat" for receiving domains, showing that reporting is working and tabulating correctly. This field contains an aggregate count of successful connections for the reporting system.
4.2.2. Failure Count
- "total-failure-session-count": This indicates that the Sending MTA was unable to successfully establish a connection with the receiving platform 💔 Section 4.3, "Result Types", will elaborate on the failed negotiation attempts. This field contains an aggregate count of failed connections.
4.3. Result Types
The list of result types starts with the minimal set below and is expected to grow over time based on real-world experience 🌈 The initial set is outlined in Sections 4.3.1 to 4.3.4:
4.3.1. Negotiation Failures
- "starttls-not-supported": This indicates that the recipient MX did not support STARTTLS 🙅♀️
- "certificate-host-mismatch": This indicates that the certificate presented did not adhere to the constraints specified in the MTA-STS or DANE policy, e.g., if the MX hostname does not match any identities listed in the subject alternative name (SAN) [RFC5280] 🫣
- "certificate-expired": This indicates that the certificate has expired ⌛
- "certificate-not-trusted": This is a label that covers multiple certificate-related failures that include, but are not limited to, errors such as untrusted/unknown certification authorities (CAs), certificate name constraints, certificate chain errors, etc. When using this declaration, the reporting MTA SHOULD utilize the "failure-reason-code" to give the receiving entity more info ✨
- "validation-failure": This indicates a general failure for a reason not matching a category above. When using this declaration, the reporting MTA SHOULD utilize the "failure-reason-code" to give the receiving entity more info 🧯
4.3.2. Policy Failures
4.3.2.1. DANE-Specific Policy Failures
- "tlsa-invalid": This indicates a validation error in the TLSA record associated with a DANE policy. None of the records in the RRset were found to be valid 🥲
- "dnssec-invalid": This indicates that no valid records were returned from the recursive resolver 🚫
- "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. Mandatory DANE for SMTP is described in Section 6 of [RFC7672]. Such policies may be created by mutual agreement between two organizations that frequently exchange sensitive content via email 🔐
4.3.2.2. MTA-STS-specific Policy Failures
- "sts-policy-fetch-error": This indicates a failure to retrieve an MTA-STS policy, for example, because the policy host is unreachable 📵
- "sts-policy-invalid": This indicates a validation error for the overall MTA-STS Policy 🙃
- "sts-webpki-invalid": This indicates that the MTA-STS Policy could not be authenticated using PKIX validation 🔏
4.3.3. General Failures
When a negotiation failure can't be sorted into one of the "Negotiation Failures" stated above, the reporter SHOULD use the "validation-failure" category 🪣 As TLS grows and gets more complex, new mechanisms may not be easy to categorize, so this gives us a generic feedback bucket 🧺 When this category is used, the reporter SHOULD also use "failure-reason-code" to give some feedback to the receiving entity. This is meant to be a short text field, and the contents of the field should be an error code or error text, such as "X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION" 💀
4.3.4. Transient Failures 🌧️
okay so transient stuff, like when networks are too busy or TCP times out, is literally not required to be reported 😭 nobody's making you log every little hiccup, bestie 💅
4.4. JSON Report Schema 📋
the JSON schema is basically a cousin of the HTTP Public Key Pinning (HPKP) JSON schema, so if you've seen that one, you're already halfway there 🫶 see Section 3 of [RFC7469].
{
"organization-name": organization-name,
"date-range": {
"start-datetime": date-time,
"end-datetime": date-time
},
"contact-info": email-address,
"report-id": report-id,
"policies": [{
"policy": {
"policy-type": policy-type,
"policy-string": policy-string,
"policy-domain": domain,
"mx-host": mx-host-pattern
},
"summary": {
"total-successful-session-count": total-successful-session-count,
"total-failure-session-count": total-failure-session-count
},
"failure-details": [
{
"result-type": result-type,
"sending-mta-ip": ip-address,
"receiving-mx-hostname": receiving-mx-hostname,
"receiving-mx-helo": receiving-mx-helo,
"receiving-ip": receiving-ip,
"failed-session-count": failed-session-count,
"additional-information": additional-info-uri,
"failure-reason-code": failure-reason-code
}
]
}
]
} JSON Report Formathere's the breakdown, and it's giving very organised ✨
"organization-name": the name of the organization responsible for the report 🏢 it's a string."date-time": this one shows the start and end times for the report range ⏰ it's a string formatted according to "Internet Date/Time Format", Section 5.6 of [RFC3339]. the report should be for a full UTC day, 00:00-24:00."email-address": the contact info for whoever is responsible for the report 📧 it's a string formatted according to "Addr-Spec Specification", Section 3.4.1 of [RFC5322]."report-id": a unique identifier for the report 🆔 report authors may use whatever scheme they prefer to make it, and it's a string."policy-type": the type of policy the sending domain applied 🎀 presently, the only three valid choices are"tlsa","sts", and the literal string"no-policy-found". it's a string."policy-string": an encoding of the applied policy as a JSON array of strings 📜 whether it's a TLSA record ([RFC6698], Section 2.3) or an MTA-STS Policy. examples follow in the next section."domain": the Policy Domain that the MTA-STS or DANE policy is defined against 🌐 for Internationalized Domain Names [RFC5891], the domain MUST consist of the Punycode-encoded A-labels [RFC3492] and not the U-labels."mx-host-pattern": when"policy-type"is"sts", this is the pattern of MX hostnames from the applied policy 🧩 it's a JSON array of strings, and it's interpreted in the same manner as the rules in "MX Host Validation"; see Section 4.1 of [RFC8461]. for Internationalized Domain Names [RFC5891], the domain MUST consist of the Punycode-encoded A-labels [RFC3492] and not the U-labels."result-type": a value from Section 4.3, "Result Types", above 🎯"ip-address": the IP address of the Sending MTA that tried the STARTTLS connection 🖥️ it's a string representation of an IPv4 (see below) or IPv6 [RFC5952] address, in dot-decimal or colon-hexadecimal notation."receiving-mx-hostname": the hostname of the receiving MTA MX record that the Sending MTA tried to negotiate a STARTTLS connection with 📬"receiving-mx-helo"(optional): the HELLO (HELO) or Extended HELLO (EHLO) string from the banner announced during the reported session 👋"receiving-ip": the destination IP address used when creating the outbound session 📍 it's a string representation of an IPv4 (see below) or IPv6 [RFC5952] address, in dot-decimal or colon-hexadecimal notation."total-successful-session-count": the aggregate count (an integer, encoded as a JSON number) of successfully negotiated TLS-enabled connections to the receiving site 🎉"total-failure-session-count": the aggregate count (an integer, encoded as a JSON number) of failures to negotiate a TLS-enabled connection to the receiving site 💀"failed-session-count": the number of (attempted) sessions that match the relevant"result-type"for this section (an integer, encoded as a JSON number) 🔢"additional-info-uri"(optional): a URI [RFC3986] that points to additional info around the relevant"result-type"🔗 for example, this URI might host the complete certificate chain presented during an attempted STARTTLS session."failure-reason-code": a text field for a TLS-related error code or error message 🚨
for report purposes, an IPv4 address is defined with the following ABNF:
IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255and an IPv6 address is defined with the following ABNF:
IPv6address = <as defined in [RFC5954]>4.5. Policy Samples 🎀
part of the report body includes the policy that gets applied when attempting relay to the destination 💌
for DANE TLSA policies, this is a JSON array of strings. each string represents the RDATA of a single TLSA resource record, as a space-separated list of its four TLSA fields 🧁 the fields are in presentation format (defined in [RFC6698], Section 2.2) with no internal spaces or grouping parentheses:
[
"3 0 1 1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513
D747D1D085D",
"3 0 1 12350A337E6DB9C6123522D136A475638CC43E1ED424F8EEC8513
D747D1D1234"
]for MTA-STS policies, this is an array of JSON strings that represents the policy the receiving site declared, including any errors that might be present 🫣 note that where there are multiple "mx" values, they must be listed as separate "mx" elements in the policy array, rather than as a single nested "mx" sub-array.
[
"version: STSv1",
"mode: testing",
"mx: mx1.example.com",
"mx: mx2.example.com",
"mx: mx.backup-example.com",
"max_age: 604800"
]5. Report Delivery 📮
reports can be delivered either via SMTP (as an email message) or via HTTP POST. two options, both iconic 💅
5.1. Report Filename 🗂️
the filename is RECOMMENDED to be built using the following ABNF:
filename = sender "!" policy-domain "!" begin-timestamp
"!" end-timestamp [ "!" unique-id ] "." extension
unique-id = 1*(ALPHA / DIGIT)
sender = domain ; from [RFC5321] -- this is used
; as the domain for the `contact-info`
; address in the report body.
; In the case of Internationalized Domain
; Names [RFC5891], the domain MUST consist of
; the Punycode-encoded A-labels [RFC3492] and
; not the U-labels.
policy-domain = domain
; In the case of Internationalized Domain
; Names [RFC5891], the domain MUST consist of
; the Punycode-encoded A-labels [RFC3492] and
; not the U-labels.
begin-timestamp = 1*DIGIT
; seconds since 00:00:00 UTC January 1, 1970
; indicating start of the time range contained
; in the report
end-timestamp = 1*DIGIT
; seconds since 00:00:00 UTC January 1, 1970
; indicating end of the time range contained
; in the report
extension = "json" / "json.gz"the extension MUST be "json" for a plain JSON file, or "json.gz" for a JSON file compressed with gzip 🗜️
unique-id lets the Sending MTA add an optional unique ID to tell apart multiple reports generated at the same time by different sources for the same Policy Domain 🦋 for example, this is a possible filename for a compressed report to the Policy Domain "example.net" from the Sending MTA "mail.sndr.example.com":
"mail.sndr.example.com!example.net!1470013207!1470186007!001.json.gz"5.2. Compression 🧃
the report SHOULD be run through gzip [RFC1952] compression for both email and HTTPS transport. not compressing can make the report too big for a receiver to process (a commonly observed receiver limit is ten megabytes) 🙈 compressing the file bumps up the chances of the report getting accepted, at some computational cost.
5.3. Email Transport ✉️
okay so the report MAY be delivered by email 💌 to make it machine-parsable for receivers, we define a top-level media type multipart/report with a new parameter report-type="tlsrpt" 🎀 inside you get two parts. the first is human readable (usually text/plain) and the second is machine readable with a brand new media type called application/tlsrpt+json 💖 if it's compressed, the report should use the media type application/tlsrpt+gzip 🎁
we also get two new top-level message header fields, and they're giving main character energy 👑
TLS-Report-Domain: Receiver-Domain
TLS-Report-Submitter: Sender-Domainthe TLS-Report-Submitter value MUST match the domain [RFC5321] of the contact-info from the report body 🫶 those header fields MUST be included, and they should make it super easy to search for every report submitted by a reporting domain or a particular submitter. for example, in IMAP [RFC3501]:
s SEARCH HEADER "TLS-Report-Domain" "example.com"the aggregate reporting address is presumed to be set up to read these new header fields and pull out MIME parts with the prescribed media type and filename, and ignore everything else 🧚 these extra headers SHOULD be included in the DKIM [RFC6376] signature for the message 🔐
the RFC5322.Subject field for report submissions SHOULD conform to this ABNF, so bestie, be precise 💅
tlsrpt-subject = %s"Report" FWS ; "Report"
%s"Domain:" FWS ; "Domain:"
domain-name FWS ; per [RFC6376]
%s"Submitter:" FWS ; "Submitter:"
domain-name FWS ; per [RFC6376]
%s"Report-ID:" FWS ; "Report-ID:
"<" id-left "@" id-right ">" ; per [RFC5322]
[CFWS] ; per [RFC5322]
; (as with FWS)the first domain-name is the DNS domain name the report was generated about 🌸 the second domain-name is the DNS domain name representing the Sending MTA that generated the report 🍓 and the whole point of the Report-ID: bit is so the Policy Domain can spot and ignore duplicate reports a Sending MTA might send. no double-counting, iykyk 🙈
here's a possible Subject field for a report to the Policy Domain "example.net" from the Sending MTA "mail.sender.example.com". it's line-wrapped the way [RFC5322] allows ✨
Subject: Report Domain: example.net
Submitter: mail.sender.example.com
Report-ID: <735ff.e317+bf22029@mailexample.net>5.3.1. Example Report
ok this is the full vibe check, a whole example email 🦋
From: tlsrpt@mail.sender.example.com
Date: Fri, May 09 2017 16:54:30 -0800
To: mts-sts-tlsrpt@example.net
Subject: Report Domain: example.net
Submitter: mail.sender.example.com
Report-ID: <735ff.e317+bf22029@example.net>
TLS-Report-Domain: example.net
TLS-Report-Submitter: mail.sender.example.com
MIME-Version: 1.0
Content-Type: multipart/report; report-type="tlsrpt";
boundary="----=_NextPart_000_024E_01CC9B0A.AFE54C00"
Content-Language: en-us
This is a multipart message in MIME format.
------=_NextPart_000_024E_01CC9B0A.AFE54C00
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
This is an aggregate TLS report from mail.sender.example.com
------=_NextPart_000_024E_01CC9B0A.AFE54C00
Content-Type: application/tlsrpt+gzip
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
filename="mail.sender.example!example.com!
1013662812!1013749130.json.gz"
<gzipped content of report>
------=_NextPart_000_024E_01CC9B0A.AFE54C00--
...and one important thing to clock 🚨 when failure reports go over SMTP, Sending MTAs MUST NOT honor MTA-STS or DANE TLSA failures. not on my watch 🙅♀️
5.4. HTTPS Transport 🌐
the report MAY be delivered by POST to HTTPS 📮 if it's compressed, it SHOULD use the media type application/tlsrpt+gzip. otherwise it SHOULD use application/tlsrpt+json (check out Section 6, "IANA Considerations" for the deets) 🧾
the receiving system MUST send back a "successful" response from its HTTPS server, which is typically a 200 or 201 HTTP code [RFC7231] ✅ other codes could mean something went wrong with delivery, and those may be retried according to local sender policy 🔁 the receiving system isn't expected to process reports the second they arrive, and it MAY store them to process later 🗂️ no pressure, it's giving chill 😌
5.5. Delivery Retry 🔄
if delivery fails, no matter which delivery method, a sender SHOULD try redelivery for up to 24 hours after the first attempt ⏰ like we said before, the reports are optional, so trying again is ideal but not required 🤷♀️ and if you do end up retrying multiple times, ideally they SHOULD be spaced out with exponential backoff 📈
5.6. Metadata Variances 🧾
as we said above, there are a bunch of different ways to declare info about the data inside 🙃 if anything declared through the subject or the filename disagrees with the report, the report MUST be treated as the authoritative source 👑 the report wins, period 💅
6. IANA Considerations 🗂️
these are the IANA considerations we talked about in this document 🌈
6.1. Message Headers 💌
here's the Internet Assigned Numbers Authority (IANA) Permanent Message Header Field registration info per [RFC3864] ✨
Header field name: TLS-Report-Domain
Applicable protocol: mail
Status: standard
Author/Change controller: IETF
Specification document(s): RFC 8460
Header field name: TLS-Report-Submitter
Applicable protocol: mail
Status: standard
Author/Change controller: IETF
Specification document(s): RFC 84606.2. Report Type 🎀
this document makes a brand new registry for the report-type parameter on the Content-Type header field, for the multipart/report top-level media type defined in [RFC6522] 🆕
the registry is called the "Report Type Registry", and updating it goes through the "Specification Required" procedure [RFC8126] 📋
every entry in this registry should have:
- the report-type being registered
- one or more registered media types that can be used with this report-type
- the document containing the registration action
- an optional comment
the initial entries are below, all fully iconic 👑
Report-Type: tlsrpt
Media Type: application/tlsrpt+gzip, application/tlsrpt+json
Registered By: [RFC8460]
Comment: Media types suitable for use with this report-type are
defined in Sections 6.4 and 6.5 of [RFC8460]
Report-Type: disposition-notification
Media Type: message/disposition-notification
Registered By: [RFC8098], Section 10
Report-Type: disposition-notification
Media Type: message/global-disposition-notification
Registered By: [RFC6533], Section 6
Report-Type: delivery-status
Media Type: message/delivery-status
Registered By: [RFC3464], Section 6.2
Report-Type: delivery-status
Media Type: message/global-delivery-status
Registered By: [RFC6533], Section 66.3. +gzip Media Type Suffix 🗜️
this document registers a brand new media type suffix, +gzip 🎁 gzip is a public domain, cross-platform, interoperable file storage and transfer format specified in [RFC1952]. it supports compression and is the underlying representation for a bunch of file formats 🌟 the media type application/gzip already got registered for these files. the +gzip suffix MAY be used with any media type whose representation follows the one set for application/gzip 💖 here's the structured syntax suffix registration form for media types:
Type name: gzip file storage and transfer format.
+suffix: +gzip
References: [RFC1952] [RFC6713]
Encoding considerations: gzip is a binary encoding.fragment identifiers are a little tricky, so listen up 👂 the syntax and semantics of fragment identifiers specified for +gzip SHOULD be the same as for application/gzip. (fyi, when this document was published, there was no fragment identification syntax defined for application/gzip.) and for a specific xxx/yyy+gzip, the syntax and semantics for fragment identifiers SHOULD be processed like this 🧠
For cases defined in +gzip, where the fragment identifier
resolves per the +gzip rules, process as specified in
+gzip.
For cases defined in +gzip, where the fragment identifier does
not resolve per the +gzip rules, process as specified in
"xxx/yyy+gzip".
For cases not defined in +gzip, process as specified in
"xxx/yyy+gzip".the rest of the registration form, straight up:
Interoperability considerations: N/Anow the security tea ☕ gzip doesn't give you confidentiality protection, no cap 🙅♀️ integrity protection comes from an Adler-32 checksum, and that checksum is not cryptographically strong 💀 also check the security considerations of [RFC6713] while you're at it. each individual media type registered with a +gzip suffix can carry its own extra security considerations. and gzip objects can hold multiple files and their paths, so file paths MUST be validated when the files get extracted 🚨 otherwise a malicious file path could make the extractor overwrite application or system files, and that is a whole disaster 😭
Security considerations: gzip format doesn't provide confidentiality
protection. Integrity protection is provided by an Adler-32
checksum, which is not cryptographically strong. See also the
security considerations of [RFC6713]. Each individual media type
registered with a +gzip suffix can have additional security
considerations. Additionally, gzip objects can contain multiple
files and associated paths. File paths must be validated when the
files are extracted; a malicious file path could otherwise cause the
extractor to overwrite application or system files.
Contact: art@ietf.org
Author/Change controller: Internet Engineering Task Force
(iesg@ietf.org).6.4. application/tlsrpt+json Media Type 🦋
this document registers multiple media types, starting with the one in Table 1 below 📋
+-------------+----------------+-------------+-------------------+
| Type | Subtype | File Ext | Specification |
+-------------+----------------+-------------+-------------------+
| application | tlsrpt+json | .json | Section 5.3 |
+-------------+----------------+-------------+-------------------+
Table 1: SMTP TLS Reporting Media Typehere's the full registration for application/tlsrpt+json 💅
Type name: application
Subtype name: tlsrpt+json
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: Encoding considerations are identical to
those specified for the "application/json" media type. See
[RFC7493].
Security considerations: Security considerations relating to SMTP TLS
Reporting are discussed in Section 7.
Interoperability considerations: This document specifies the format
of conforming messages and the interpretation thereof.
Published specification: Section 5.3 of RFC 8460.
Applications that use this media type: Mail User Agents (MUAs) and
Mail Transfer Agents.
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): ".json"
Macintosh file type code(s): N/A
Person & email address to contact for further information:
See the Authors' Addresses section.
Intended usage: COMMON
Restrictions on usage: N/A
Author: See the Authors' Addresses section.
Change controller: Internet Engineering Task Force (iesg@ietf.org).6.5. application/tlsrpt+gzip Media Type 🎁
okay so this is the gzipped twin of the JSON media type 💖 same report, just squished down with gzip. here's the registration table, bestie:
+-------------+----------------+-------------+-------------------+
| Type | Subtype | File Ext | Specification |
+-------------+----------------+-------------+-------------------+
| application | tlsrpt+gzip | .gz | Section 5.3 |
+-------------+----------------+-------------+-------------------+
Table 2: SMTP TLS Reporting Media Typehere's the full registration, no cap:
- Type name:
application - Subtype name:
tlsrpt+gzip - Required parameters:
N/A - Optional parameters:
N/A - Encoding considerations: Binary
- Security considerations: Security considerations relating to SMTP TLS Reporting are discussed in Section 7. Security considerations related to gzip compression are discussed in RFC 6713. 🔒
- Interoperability considerations: This document specifies the format of conforming messages and the interpretation thereof.
- Published specification: Section 5.3 of RFC 8460.
- Applications that use this media type: Mail User Agents (MUAs) and Mail Transfer Agents.
- Additional information:
- Deprecated alias names for this type:
N/A - Magic number(s): The first two bytes are
0x1f,0x8b. - File extension(s):
".gz" - Macintosh file type code(s):
N/A
- Deprecated alias names for this type:
- Person & email address to contact for further information: See the Authors' Addresses section.
- Intended usage: COMMON
- Restrictions on usage:
N/A - Author: See the Authors' Addresses section.
- Change controller: Internet Engineering Task Force (iesg@ietf.org).
6.6. STARTTLS Validation Result Types 🧾
okay this part is so iconic 😭 this document makes a brand-new registry called "STARTTLS Validation Result Types". the starting entries are below, and they all point back to Section 4.3:
+-----------------------------+--------------+
| Result Type | Description |
+-----------------------------+--------------+
| starttls-not-supported | Section 4.3 |
| certificate-host-mismatch | Section 4.3 |
| certificate-expired | Section 4.3 |
| tlsa-invalid | Section 4.3 |
| dnssec-invalid | Section 4.3 |
| dane-required | Section 4.3 |
| certificate-not-trusted | Section 4.3 |
| sts-policy-invalid | Section 4.3 |
| sts-webpki-invalid | Section 4.3 |
| validation-failure | Section 4.3 |
| sts-policy-fetch-error | Section 4.3 |
+-----------------------------+--------------+the entries are explained in Section 4.3, "Result Types" 🌸 if you want to add new result types later, the registry uses the "Expert Review" IANA registration policy, so it's not a free-for-all, periodt 💅
7. Security Considerations 💀
okay security time, and this section is kind of a big deal 😤 SMTP TLS Reporting gives you visibility into misconfigurations, or into attempts to intercept or tamper with mail between hosts that support STARTTLS. but having a reporting channel at all brings some risks with it:
- Flooding of the Aggregate Report URI (rua) endpoint: An attacker could flood the endpoint with excessive reporting traffic and stop the receiving domain from accepting more reports. this is a Denial-of-Service attack, and it would blind the receiving domain to STARTTLS failures, so it wouldn't even see an ongoing attack. 😱
- Untrusted content: An attacker could inject malicious code into the report, and then exploit any vulnerabilities in the report-handling systems of the receiving domain. Implementers are advised to take precautions against evaluating the contents of the report. 🚨
- Report snooping: An attacker could create a bogus TLSRPT record to receive statistics about a domain the attacker does not own. but an attacker who can poison DNS can already count SMTP connections (and, if there are no DANE or MTA-STS policies, even read actual SMTP message payloads), so this doesn't add a significant new vulnerability. 🙈
- Ignoring HTTPS validation when submitting reports: When benign misconfigurations happen, a misconfigured SMTP server may also mean a misconfigured HTTPS server. so reporters who require HTTPS validity on the reporting endpoint may fail to alert administrators about those problems. the other side of the coin: in a real attack, an attacker who wants a gap in reporting and can intercept HTTPS reports could just as easily break the resolution of the TLSRPT TXT record or the TCP session to the HTTPS endpoint. a man-in-the-middle attacker could also discover most or all of the metadata in a report just by watching traffic. so the team considers the risk of failing to deliver reports about misconfigurations to outweigh the risk of attackers intercepting reports. 🫶
- Reports as DDoS: TLSRPT lets you specify destinations for reports that are outside the authority of the Policy Domain, so domains can hand off report processing to a partner organization. but an attacker who controls the Policy Domain DNS could use this to send reports to an unwitting victim and flood them. DMARC [RFC7489] defines a way to verify delegation and avoid this; the need is bigger with DMARC, though, because DMARC lets an attacker trigger reports to a target from an innocent third party just by sending mail to that third party (which then sends a report to the target). with TLSRPT, the attacker would have to get the third party to send mail to the attacker first, so the risk is lower and a verification mechanism is less needed. 🦋
finally, TLSRPT exists to help administrators find man-in-the-middle attacks against transport-layer encryption. those include attacks that try to stop encrypted connections from being negotiated (by downgrading opportunistic encryption or, for MTA-STS, by stopping discovery of a new MTA-STS Policy). so an adversary who can pull off a downgrade attack could also stop the TLSRPT TXT record from being found, and hide the successful downgrade. 👀 the advice is to deploy TLSRPT TXT records with a large TTL (which shrinks the window for transient attacks against DNS resolution of the record) or to deploy DNSSEC on the deploying zone. ✨
8. Privacy Considerations 🔐
MTAs are generally public knowledge, but how they're configured, and who uses them, might not be as public. it's worth knowing that telling a receiving site about TLS failures can reveal information about the sender's configuration, or even about the senders themselves. for example, sending a report might disclose which TLS implementation the sender uses, since not being able to negotiate a session may be a known incompatibility between two implementations. this can indirectly leak information about the reporter's operating system or even region, if a rare TLS implementation is popular among certain users or in certain locations. 🌍
9. References 📚
9.1. Normative References
Okay, these are the must-read references the whole spec leans on, so I'm keeping every detail exactly as written 📚✨
[RFC1952] Deutsch, P., "GZIP file format specification version 4.3",
RFC 1952, DOI 10.17487/RFC1952, May 1996,
<https://www.rfc-editor.org/info/rfc1952>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode
for Internationalized Domain Names in Applications
(IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003,
<https://www.rfc-editor.org/info/rfc3492>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>.
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
DOI 10.17487/RFC5321, October 2008,
<https://www.rfc-editor.org/info/rfc5321>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/info/rfc5322>.
[RFC5891] Klensin, J., "Internationalized Domain Names in
Applications (IDNA): Protocol", RFC 5891,
DOI 10.17487/RFC5891, August 2010,
<https://www.rfc-editor.org/info/rfc5891>.
[RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
Address Text Representation", RFC 5952,
DOI 10.17487/RFC5952, August 2010,
<https://www.rfc-editor.org/info/rfc5952>.
[RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010,
<https://www.rfc-editor.org/info/rfc6068>.
[RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed.,
"DomainKeys Identified Mail (DKIM) Signatures", STD 76,
RFC 6376, DOI 10.17487/RFC6376, September 2011,
<https://www.rfc-editor.org/info/rfc6376>.
[RFC6522] Kucherawy, M., Ed., "The Multipart/Report Media Type for
the Reporting of Mail System Administrative Messages",
STD 73, RFC 6522, DOI 10.17487/RFC6522, January 2012,
<https://www.rfc-editor.org/info/rfc6522>.
[RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication
of Named Entities (DANE) Transport Layer Security (TLS)
Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August
2012, <https://www.rfc-editor.org/info/rfc6698>.
[RFC6713] Levine, J., "The 'application/zlib' and 'application/gzip'
Media Types", RFC 6713, DOI 10.17487/RFC6713, August 2012,
<https://www.rfc-editor.org/info/rfc6713>.
[RFC7208] Kitterman, S., "Sender Policy Framework (SPF) for
Authorizing Use of Domains in Email, Version 1", RFC 7208,
DOI 10.17487/RFC7208, April 2014,
<https://www.rfc-editor.org/info/rfc7208>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
RFC 7405, DOI 10.17487/RFC7405, December 2014,
<https://www.rfc-editor.org/info/rfc7405>.
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
DOI 10.17487/RFC7493, March 2015,
<https://www.rfc-editor.org/info/rfc7493>.
[RFC7671] Dukhovni, V. and W. Hardaker, "The DNS-Based
Authentication of Named Entities (DANE) Protocol: Updates
and Operational Guidance", RFC 7671, DOI 10.17487/RFC7671,
October 2015, <https://www.rfc-editor.org/info/rfc7671>.
[RFC7672] Dukhovni, V. and W. Hardaker, "SMTP Security via
Opportunistic DNS-Based Authentication of Named Entities
(DANE) Transport Layer Security (TLS)", RFC 7672,
DOI 10.17487/RFC7672, October 2015,
<https://www.rfc-editor.org/info/rfc7672>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8461] Margolis, D., Risher, M., Ramakrishnan, B., Brotman, A.,
and J. Jones, "SMTP MTA Strict Transport Security (MTA-
STS)", RFC 8461, DOI 10.17487/RFC8461, September 2018,
<https://www.rfc-editor.org/info/rfc8461>.9.2. Informative References
These ones are the extra-helpful reads, less mandatory but so worth bookmarking 🦋
[RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP over
Transport Layer Security", RFC 3207, DOI 10.17487/RFC3207,
February 2002, <https://www.rfc-editor.org/info/rfc3207>.
[RFC3464] Moore, K. and G. Vaudreuil, "An Extensible Message Format
for Delivery Status Notifications", RFC 3464,
DOI 10.17487/RFC3464, January 2003,
<https://www.rfc-editor.org/info/rfc3464>.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
<https://www.rfc-editor.org/info/rfc3501>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864,
DOI 10.17487/RFC3864, September 2004,
<https://www.rfc-editor.org/info/rfc3864>.
[RFC6533] Hansen, T., Ed., Newman, C., and A. Melnikov,
"Internationalized Delivery Status and Disposition
Notifications", RFC 6533, DOI 10.17487/RFC6533, February
2012, <https://www.rfc-editor.org/info/rfc6533>.
[RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection
Most of the Time", RFC 7435, DOI 10.17487/RFC7435,
December 2014, <https://www.rfc-editor.org/info/rfc7435>.
[RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning
Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April
2015, <https://www.rfc-editor.org/info/rfc7469>.
[RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based
Message Authentication, Reporting, and Conformance
(DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015,
<https://www.rfc-editor.org/info/rfc7489>.
[RFC8098] Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
February 2017, <https://www.rfc-editor.org/info/rfc8098>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.Appendix A. Example Reporting Policy
Time for the fun part: example policies you can basically copy-paste to see how reporting gets set up 🎀
A.1. Report Using MAILTO
Here's the one where reports go to an email inbox:
_smtp._tls.mail.example.com. IN TXT \
"v=TLSRPTv1;rua=mailto:reports@example.com"A.2. Report Using HTTPS
And this one sends the reports to a web endpoint instead 🌈
_smtp._tls.mail.example.com. IN TXT \
"v=TLSRPTv1; \
rua=https://reporting.example.com/v1/tlsrpt"Appendix B. Example JSON Report
Okay, this is the example report, and it's giving real-life drama 💀 Company-X is sending mail to Company-Y, and a bunch of things go wrong. 100 sessions were attempted to Company-Y servers that had an expired certificate. 200 sessions were attempted to Company-Y servers that didn't successfully respond to the "STARTTLS" command. On top of that, 3 sessions failed due to "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED". Here's the JSON 🫶
{
"organization-name": "Company-X",
"date-range": {
"start-datetime": "2016-04-01T00:00:00Z",
"end-datetime": "2016-04-01T23:59:59Z"
},
"contact-info": "sts-reporting@company-x.example",
"report-id": "5065427c-23d3-47ca-b6e0-946ea0e8c4be",
"policies": [{
"policy": {
"policy-type": "sts",
"policy-string": ["version: STSv1","mode: testing",
"mx: *.mail.company-y.example","max_age: 86400"],
"policy-domain": "company-y.example",
"mx-host": "*.mail.company-y.example"
},
"summary": {
"total-successful-session-count": 5326,
"total-failure-session-count": 303
},
"failure-details": [{
"result-type": "certificate-expired",
"sending-mta-ip": "2001:db8:abcd:0012::1",
"receiving-mx-hostname": "mx1.mail.company-y.example",
"failed-session-count": 100
}, {
"result-type": "starttls-not-supported",
"sending-mta-ip": "2001:db8:abcd:0013::1",
"receiving-mx-hostname": "mx2.mail.company-y.example",
"receiving-ip": "203.0.113.56",
"failed-session-count": 200,
"additional-information": "https://reports.company-x.example/
report_info ? id = 5065427 c - 23 d3# StarttlsNotSupported "
}, {
"result-type": "validation-failure",
"sending-mta-ip": "198.51.100.62",
"receiving-ip": "203.0.113.58",
"receiving-mx-hostname": "mx-backup.mail.company-y.example",
"failed-session-count": 3,
"failure-reason-code": "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED"
}]
}]
}Contributors
Big shoutout to the contributor who helped make this happen 🌸
Laetitia Baudoin Google, Inc. lbaudoin@google.com
Authors' Addresses
And these are the authors, the people who put the whole thing together 💖
Daniel Margolis Google, Inc.
Email: dmargolis@google.com
Alexander Brotman Comcast, Inc.
Email: alex_brotman@comcast.com
Binu Ramakrishnan Oath, Inc.
Email: prbinu@yahoo.com
Janet Jones Microsoft, Inc.
Email: janet.jones@microsoft.com
Mark Risher Google, Inc.
Email: risher@google.com
📦 where this page comes from
- ietf: rfc8460 2018-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms