<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' []>
<rfc ipr="trust200902" category="std" docName="draft-ietf-uta-smtp-tlsrpt-12">
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private=""?>
<?rfc topblock="yes"?>
<?rfc comments="no"?>
<front>
<title abbrev="SMTP-TLSRPT">SMTP TLS Reporting</title>

<author initials="D." surname="Margolis" fullname="Daniel Margolis">
<organization>Google, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>dmargolis (at) google (dot com)</email>
<uri></uri>
</address>
</author>
<author initials="A." surname="Brotman" fullname="Alexander Brotman">
<organization>Comcast, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>alex_brotman (at) comcast (dot com)</email>
<uri></uri>
</address>
</author>
<author initials="B." surname="Ramakrishnan" fullname="Binu Ramakrishnan">
<organization>Yahoo!, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>rbinu (at) yahoo-inc (dot com)</email>
<uri></uri>
</address>
</author>
<author initials="J." surname="Jones" fullname="Janet Jones">
<organization>Microsoft, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>janet.jones (at) microsoft (dot com)</email>
<uri></uri>
</address>
</author>
<author initials="M." surname="Risher" fullname="Mark Risher">
<organization>Google, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>risher (at) google (dot com)</email>
<uri></uri>
</address>
</author>
<date year="2017" month="December" day="4"/>

<area>Applications</area>
<workgroup>Using TLS in Applications</workgroup>
<keyword></keyword>


<abstract>
<t>A number of protocols exist for establishing encrypted channels between
SMTP Mail Transfer Agents, including STARTTLS, DANE TLSA, and MTA-STS.
These protocols can fail due to misconfiguration or active attack,
leading to undelivered messages or delivery over unencrypted or
unauthenticated channels.  This document describes a reporting mechanism
and format by which sending systems can share statistics and specific
information about potential failures with recipient domains. Recipient
domains can then use this information to both detect potential attackers
and diagnose unintentional misconfigurations.
</t>
</abstract>


</front>

<middle>

<section anchor="introduction" title="Introduction">
<t>The STARTTLS extension to SMTP <xref target="RFC3207"/> allows SMTP clients and hosts
to establish secure SMTP sessions over TLS. The protocol design is based
on &quot;Opportunistic Security&quot; (OS) <xref target="RFC7435"/>, which maintains
interoperability with clients that do not support STARTTLS but means
that any attacker who can delete parts of the SMTP session (such as the
&quot;250 STARTTLS&quot; response) or redirect the entire SMTP session (perhaps by
overwriting the resolved MX record of the delivery domain) can perform a
downgrade or interception attack.
</t>
<t>Because such &quot;downgrade attacks&quot; are not necessarily apparent to the
receiving MTA, this document defines a mechanism for sending domains to
report on failures at multiple stages of the MTA-to-MTA conversation.
</t>
<t>Recipient domains may also use the mechanisms defined by MTA-STS
<xref target="I-D.ietf-uta-mta-sts"/> or DANE <xref target="RFC6698"/> to
publish additional 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.
</t>
<t>Specifically, this document defines a reporting schema that covers
failures in routing, STARTTLS negotiation, and both DANE <xref target="RFC6698"/> and
MTA-STS <xref target="I-D.ietf-uta-mta-sts"/> policy validation errors, and a
standard TXT record that recipient domains can use to indicate where
reports in this format should be sent.
</t>
<t>This document is intended as a companion to the specification for SMTP
MTA Strict Transport Security <xref target="I-D.ietf-uta-mta-sts"/>.
</t>

<section anchor="terminology" title="Terminology">
<t>The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;, &quot;SHALL NOT&quot;,
&quot;SHOULD&quot;, &quot;SHOULD NOT&quot;, &quot;RECOMMENDED&quot;,  &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this
document are to be interpreted as described in <xref target="RFC2119"/>.
</t>
<t>We also define the following terms for further use in this document:
</t>
<t>
<list style="symbols">
<t>MTA-STS Policy: A definition of the expected TLS availability,
behavior, and desired actions for a given domain when a sending MTA
encounters problems in negotiating a secure channel. MTA-STS is
defined in <xref target="I-D.ietf-uta-mta-sts"/>.</t>
<t>DANE Policy: A mechanism by which administrators can supply a record
that can be used to validate the certificate presented by an MTA. DANE
is defined in <xref target="RFC6698"/>.</t>
<t>TLSRPT Policy: A policy specifying the endpoint to which sending MTAs
should deliver reports.</t>
<t>Policy Domain: The domain against which an MTA-STS or DANE Policy is
defined.</t>
<t>Sending MTA: The MTA initiating the delivery of an email message.</t>
</list>
</t>
</section>
</section>

<section anchor="related-technologies" title="Related Technologies">
<t>
<list style="symbols">
<t>This document is intended as a companion to the specification for SMTP
MTA Strict Transport Security <xref target="I-D.ietf-uta-mta-sts"/>.</t>
<t>SMTP-TLSRPT defines a mechanism for sending domains that are
compatible with MTA-STS or DANE to share success and failure
statistics with recipient domains.  DANE is defined in <xref target="RFC6698"/> and
MTA-STS is defined in <xref target="I-D.ietf-uta-mta-sts"/>.</t>
</list>
</t>
</section>

<section anchor="reporting-policy" title="Reporting Policy">
<t>A domain publishes a record to its DNS indicating that it wishes to
receive reports. These SMTP TLSRPT policies are distributed via DNS from
the Policy Domain's zone, as TXT records (similar to DMARC policies)
under the name <spanx style="verb">_smtp-tlsrpt</spanx>. For example, for the Policy Domain
<spanx style="verb">example.com</spanx>, the recipient's TLSRPT policy can be retrieved from
<spanx style="verb">_smtp-tlsrpt.example.com</spanx>.
</t>
<t>Policies consist of the following directives:
</t>
<t>
<list style="symbols">
<t><spanx style="verb">v</spanx>: This value MUST be equal to <spanx style="verb">TLSRPTv1</spanx>.</t>
<t><spanx style="verb">rua</spanx>: A URI specifying the endpoint to which aggregate information
about policy validation results should be sent (see
<xref target="reporting-schema"/>, &quot;Reporting Schema&quot;,  for more information). Two
URI schemes are supported: <spanx style="verb">mailto</spanx> and <spanx style="verb">https</spanx>.  As with DMARC
<xref target="RFC7489"/>, the policy domain can specify a comma-separated list of
URIs.</t>
<t>In the case of <spanx style="verb">https</spanx>, reports should be submitted via POST
(<xref target="RFC7231"/>) to the specified URI.  Report submitters MAY ignore
certificate validation errors when submitting reports via https.</t>
<t>In the case of <spanx style="verb">mailto</spanx>, reports should be submitted to the specified
email address (<xref target="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 in the clear. Additionally, reports
sent via SMTP MUST contain a valid DKIM <xref target="RFC6376"/> signature by the
reporting domain.  Reports lacking such a signature MUST be ignored by
the recipient.  DKIM signatures must not use the &quot;l=&quot; attribute to
limit the body length used in the signature.</t>
</list>
</t>
<t>The formal definition of the <spanx style="verb">_smtp-tlsrpt</spanx> TXT record, defined using
<xref target="RFC5234"/> &amp; <xref target="RFC7405"/>, is as follows:
</t>

<figure align="center"><artwork align="center">
    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) and exclamation 
          ; points (ASCII 0x21) 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
                        ; chars
</artwork></figure>
<t>If multiple TXT records for <spanx style="verb">_smtp-tlsrpt</spanx> are returned by the resolver,
records which do not begin with <spanx style="verb">v=TLSRPTv1;</spanx> are discarded. If the
number of resulting records is not one, senders MUST assume the
recipient domain does not implement TLSRPT. If the resulting TXT record
contains multiple strings, then the record MUST be treated as if those
strings are concatenated together without adding spaces.
</t>
<t>Parsers MUST accept TXT records which are syntactically valid (i.e.
valid key-value pairs separated by semi-colons) and implementing a
superset of this specification, in which case unknown fields SHALL be
ignored.
</t>

<section anchor="example-reporting-policy" title="Example Reporting Policy">

<section anchor="report-using-mailto" title="Report using MAILTO">

<figure align="center"><artwork align="center">
_smtp-tlsrpt.example.com. IN TXT \
	"v=TLSRPTv1;rua=mailto:reports@example.com"
</artwork></figure>
</section>

<section anchor="report-using-https" title="Report using HTTPS">

<figure align="center"><artwork align="center">
_smtp-tlsrpt.example.com. IN TXT \
	"v=TLSRPTv1; \
	rua=https://reporting.example.com/v1/tlsrpt"
</artwork></figure>
</section>
</section>
</section>

<section anchor="reporting-schema" title="Reporting Schema">
<t>The report is composed as a plain text file encoded in the I-JSON format
(<xref target="RFC7493"/>).
</t>
<t>Aggregate reports contain the following fields:
</t>
<t>
<list style="symbols">
<t>Report metadata:
<list style="symbols">
<t>The organization responsible for the report</t>
<t>Contact information for one or more responsible parties for the
contents of the report</t>
<t>A unique identifier for the report</t>
<t>The reporting date range for the report</t>
</list></t>
<t>Policy, consisting of:
<list style="symbols">
<t>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) (3)
The literal string <spanx style="verb">no-policy-found</spanx>, if neither a DANE nor MTA-STS
policy could be found.</t>
<t>The domain for which the policy is applied</t>
<t>The MX host</t>
<t>An identifier for the policy (where applicable)</t>
</list></t>
<t>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.</t>
</list>
</t>
<t>Note that the failure types are non-exclusive; an aggregate report may
contain overlapping <spanx style="verb">counts</spanx> of failure types when a single send attempt
encountered 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); even in the case where only a single policy was
applied, the &quot;policies&quot; field of the report body MUST be an array and
not a singular value.
</t>

<section anchor="report-timeframe" title="Report Time-frame">
<t>The report SHOULD cover a full day, from 0000-2400 UTC.  This should
allow for easier correlation of failure events.  To avoid a Denial of
Service against the system processing the reports, the reports should be
delivered after some delay, perhaps several hours.
</t>
</section>

<section anchor="delivery-summary" title="Delivery Summary">

<section anchor="success-count" title="Success Count">
<t>
<list style="symbols">
<t><spanx style="verb">success-count</spanx>: This indicates that the sending MTA was able to
successfully negotiate a policy-compliant TLS connection, and serves
to provide a &quot;heartbeat&quot; to receiving domains that reporting is
functional and tabulating correctly.  This field contains an aggregate
count of successful connections for the reporting system.

<vspace/></t>
</list>
</t>
</section>

<section anchor="failure-count" title="Failure Count">
<t>
<list style="symbols">
<t><spanx style="verb">failure-count</spanx>: This indicates that the sending MTA was unable to
successfully establish a connection with the receiving platform.
<xref target="result-types"/>, &quot;Result Types&quot;, will elaborate on the failed
negotiation attempts.  This field contains an aggregate count of
failed connections.</t>
</list>
</t>
</section>
</section>

<section anchor="result-types" title="Result Types">
<t>The list of result types will start with the minimal set below, and is
expected to grow over time based on real-world experience. The initial
set is:
</t>

<section anchor="negotiation-failures" title="Negotiation Failures">
<t>
<list style="symbols">
<t><spanx style="verb">starttls-not-supported</spanx>: This indicates that the recipient MX did not
support STARTTLS.</t>
<t><spanx style="verb">certificate-host-mismatch</spanx>: 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 does not match any identities listed
in the Subject Alternate Name (SAN) <xref target="RFC5280"/>.</t>
<t><spanx style="verb">certificate-expired</spanx>: This indicates that the certificate has
expired.</t>
<t><spanx style="verb">certificate-not-trusted</spanx>: This a label that covers multiple
certificate related failures that include, but not limited to errors
such as untrusted/unknown CAs, certificate name constraints,
certificate chain errors etc. When using this declaration, the
reporting MTA SHOULD utilize the <spanx style="verb">failure-reason</spanx> to provide more
information to the receiving entity.</t>
<t><spanx style="verb">validation-failure</spanx>: This indicates a general failure for a reason
not matching a category above.  When using this declaration, the
reporting MTA SHOULD utilize the <spanx style="verb">failure-reason</spanx> to provide more
information to the receiving entity.</t>
</list>
</t>
</section>

<section anchor="policy-failures" title="Policy Failures">

<section anchor="danespecific-policy-failures" title="DANE-specific Policy Failures">
<t>
<list style="symbols">
<t><spanx style="verb">tlsa-invalid</spanx>: 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.</t>
<t><spanx style="verb">dnssec-invalid</spanx>: This would indicate that no valid records were
returned from the recursive resolver.  The request returned with
SERVFAIL for the requested TLSA record.  It should be noted that if
the reporter's systems are having problems resolving destination DNS
records due to DNSSEC failures, it's possible they will also be unable
to resolve the TLSRPT record, therefore these types of reports may be
rare.</t>
</list>
</t>
</section>

<section anchor="mtastsspecific-policy-failures" title="MTA-STS-specific Policy Failures">
<t>
<list style="symbols">
<t><spanx style="verb">sts-policy-invalid</spanx>: This indicates a validation error for the
overall MTA-STS policy.</t>
<t><spanx style="verb">sts-webpki-invalid</spanx>: This indicates that the MTA-STS policy could not
be authenticated using PKIX validation.

<vspace/></t>
</list>
</t>
</section>
</section>

<section anchor="general-failures" title="General Failures">
<t>When a negotiation failure can not be categorized into one of the
&quot;Negotiation Failures&quot; stated above, the reporter SHOULD use the
<spanx style="verb">validation-failure</spanx> category.  As TLS grows and becomes more complex,
new mechanisms may not be easily categorized.  This allows for a generic
feedback category.  When this category is used, the reporter SHOULD also
use the <spanx style="verb">failure-reason-code</spanx> to give some feedback to the receiving
entity.  This is intended to be a short text field, and the contents of
the field should be an error code or error text, such as
&quot;X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION&quot;.
</t>
</section>

<section anchor="transient-failures" title="Transient Failures">
<t>Transient errors due to too-busy network, TCP timeouts, etc. are not
required to be reported.
</t>
</section>
</section>

<section anchor="json-report-schema" title="JSON Report Schema">
<t>The JSON schema is derived from the HPKP JSON schema <xref target="RFC7469"/> (cf.
Section 3)
</t>

<figure align="center" title="JSON Report Format
"><artwork align="center">
{
  "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,
        "failed-session-count": failed-session-count,
        "additional-information": additional-info-uri,
        "failure-reason-code": failure-reason-code
        }
      ]
    }
  ]
}

</artwork></figure>
<t>
<list style="symbols">
<t><spanx style="verb">organization-name</spanx>: The name of the organization responsible for the
report.  It is provided as a string.</t>
<t><spanx style="verb">date-time</spanx>: The date-time indicates the start- and end-times for the
report range. It is provided as a string formatted according to
Section 5.6, &quot;Internet Date/Time Format&quot;, of <xref target="RFC3339"/>.  The report
should be for a full UTC day, 0000-2400.</t>
<t><spanx style="verb">email-address</spanx>: The contact information for a responsible party of
the report. It is provided as a string formatted according to Section
3.4.1, &quot;Addr-Spec&quot;, of <xref target="RFC5321"/>.</t>
<t><spanx style="verb">report-id</spanx>: A unique identifier for the report. Report authors may
use whatever scheme they prefer to generate a unique identifier. It is
provided as a string.</t>
<t><spanx style="verb">policy-type</spanx>: The type of policy that was applied by the sending
domain.  Presently, the only three valid choices are <spanx style="verb">tlsa</spanx>, <spanx style="verb">sts</spanx>,
and the literal string <spanx style="verb">no-policy-found</spanx>. It is provided as a string.</t>
<t><spanx style="verb">policy-string</spanx>: A string representation of the policy, whether TLSA
record (<xref target="RFC6698"/> section 2.3) or MTA-STS policy. Examples: TLSA:
<spanx style="verb">"_25._tcp.mx.example.com. IN TLSA ( 3 0 1 \
1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513D7 47D1D085D )"</spanx>
MTA-STS: <spanx style="verb">"version: STSv1\nmode: report\nmx: mx1.example.com\nmx: \
mx2.example.com\nmx: mx.backup-example.com\nmax_age: 12345678"</spanx></t>
<t><spanx style="verb">domain</spanx>: The Policy Domain is the domain against which the MTA-STS or
DANE policy is defined. In the case of Internationalized Domain Names
(<xref target="RFC5891"/>), the domain is the Punycode-encoded A-label
(<xref target="RFC3492"/>) and not the U-label.</t>
<t><spanx style="verb">mx-host-pattern</spanx>: The pattern of MX hostnames from the applied
policy. It is provided as a string, and is interpreted in the same
manner as the &quot;Checking of Wildcard Certificates&quot; rules in Section
6.4.3 of <xref target="RFC6125"/>.  In the case of Internationalized Domain Names
(<xref target="RFC5891"/>), the domain is the Punycode-encoded A-label
(<xref target="RFC3492"/>) and not the U-label.</t>
<t><spanx style="verb">result-type</spanx>: A value from <xref target="result-types"/>, &quot;Result Types&quot;,  above.</t>
<t><spanx style="verb">ip-address</spanx>: The IP address of the sending MTA that attempted the
STARTTLS connection. It is provided as a string representation of an
IPv4 (see below) or IPv6 (<xref target="RFC5952"/>) address in dot-decimal or
colon-hexadecimal notation.</t>
<t><spanx style="verb">receiving-mx-hostname</spanx>: The hostname of the receiving MTA MX record
with which the sending MTA attempted to negotiate a STARTTLS
connection.</t>
<t><spanx style="verb">receiving-mx-helo</spanx>: (optional) The HELO or EHLO string from the
banner announced during the reported session.</t>
<t><spanx style="verb">total-successful-session-count</spanx>: The aggregate number (integer) of
successfully negotiated TLS-enabled connections to the receiving site.</t>
<t><spanx style="verb">total-failure-session-count</spanx>: The aggregate number (integer) of
failures to negotiate a TLS-enabled connection to the receiving site.</t>
<t><spanx style="verb">failed-session-count</spanx>: The number of (attempted) sessions that match
the relevant <spanx style="verb">result-type</spanx> for this section.</t>
<t><spanx style="verb">additional-info-uri</spanx>: An optional URI <xref target="RFC3986"/> pointing to
additional information around the relevant <spanx style="verb">result-type</spanx>. For example,
this URI might host the complete certificate chain presented during an
attempted STARTTLS session.</t>
<t><spanx style="verb">failure-reason-code</spanx>: A text field to include a TLS-related error
code or error message.

<vspace/></t>
</list>
</t>
<t>For report purposes, an IPv4 Address is defined as:
     IPv4address = dec-octet &quot;.&quot; dec-octet &quot;.&quot; dec-octet &quot;.&quot; dec-octet
<vspace/>
                   dec-octet     = DIGIT                 ; 0-9
                   / %x31-39 DIGIT         ; 10-99
                   / &quot;1&quot; 2DIGIT            ; 100-199
                   / &quot;2&quot; %x30-34 DIGIT     ; 200-249
                   / &quot;25&quot; %x30-35          ; 250-255
</t>
</section>
</section>

<section anchor="report-delivery" title="Report Delivery">
<t>Reports can be delivered either as an email message via SMTP or via HTTP
POST.
</t>

<section anchor="report-filename" title="Report Filename">
<t>The filename is RECOMMENDED to be constructed using the following ABNF:
</t>

<figure align="center"><artwork align="center">
 filename = sender "!" policy-domain "!" begin-timestamp
           "!" end-timestamp [ "!" unique-id ] "." extension

 unique-id = 1*(ALPHA / DIGIT)

 sender = domain        ; From the [@!RFC5321] that is used 
                ; as the domain for the `contact-info`
            ; address in the report body

 policy-domain   = domain

 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"
</artwork></figure>
<t>The extension MUST be &quot;json&quot; for a plain JSON file, or &quot;json.gz&quot; for a
JSON file compressed using GZIP.
</t>
<t>&quot;unique-id&quot; allows an optional unique ID generated by the Sending MTA to
distinguish among multiple reports generated simultaneously by different
sources within the same Policy Domain. For example, this is a possible
filename for the gzip file of a report to the Policy Domain
&quot;example.net&quot; from the Sending MTA &quot;mail.sender.example.com&quot;:
</t>
<t><spanx style="verb">mail.sender.example.com!example.net!1470013207!1470186007!001.json.gz</spanx>
</t>
</section>

<section anchor="compression" title="Compression">
<t>The report SHOULD be subjected to GZIP compression for both email and
HTTPS transport. Declining to apply compression can cause the report to
be too large for a receiver to process (a commonly observed receiver
limit is ten megabytes); compressing the file increases the chances of
acceptance of the report at some compute cost.
</t>
</section>

<section anchor="email-transport" title="Email Transport">
<t>The report MAY be delivered by email. To make the reports
machine-parsable for the receivers, we define a top-level media type
<spanx style="verb">multipart/report</spanx> with a new parameter <spanx style="verb">report-type="tlsrpt"</spanx>. Inside
it, there are two parts: The first part is human readable, typically
<spanx style="verb">text/plain</spanx>, and the second part is machine readable with a new media
type defined called <spanx style="verb">application/tlsrpt+json</spanx>.  If compressed, the
report should use the media type <spanx style="verb">application/tlsrpt+gzip</spanx>.
</t>
<t>In addition, the following two new top level message header fields are
defined:
</t>
<t><spanx style="verb">TLS-Report-Domain: Receiver-Domain TLS-Report-Submitter:
Sender-Domain</spanx> The <spanx style="verb">TLS-Report-Submitter</spanx> value MUST match the value
found in the filename and the <xref target="RFC5321"/> domain from the <spanx style="verb">contact-info</spanx>
from the report body.  These message headers MUST be included and should
allow for easy searching for all reports submitted by a report domain or
a particular submitter, for example in IMAP <xref target="RFC3501"/>:
</t>
<t><spanx style="verb">s SEARCH HEADER "TLS-Report-Domain" "example.com"</spanx>
</t>
<t>It is presumed that the aggregate reporting address will be equipped to
process new message header fields and extract MIME parts with the
prescribed media type and filename, and ignore the rest.  These
additional headers SHOULD be included in the DKIM <xref target="RFC6376"/> signature
for the message.
</t>
<t>The <xref target="RFC5322"/>.Subject field for report submissions SHOULD conform to
the following ABNF:
</t>

<figure align="center"><artwork align="center">
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:
         "&lt;" id-left "@" id-right "&gt;" ; per RFC5322
         [CFWS]                       ; per RFC5322
                                              ; (as with FWS)
</artwork></figure>
<t>The first domain-name indicates the DNS domain name about which the
 report was generated. The second domain-name indicates the DNS domain
 name representing the Sending MTA generating the report.  The purpose
 of the Report-ID: portion of the field is to enable the Policy Domain
 to identify and ignore duplicate reports that might be sent by a
 Sending MTA.
</t>
<t>For instance, this is a possible Subject field for a report to the
 Policy Domain &quot;example.net&quot; from the Sending MTA
 &quot;mail.sender.example.com&quot;.  It is line-wrapped as allowed by
</t>

<figure align="center"><artwork align="center">
     Subject: Report Domain: example.net
         Submitter: mail.sender.example.com
         Report-ID: &lt;735ff.e317+bf22029@mailexample.net&gt;
</artwork></figure>

<section anchor="example-report" title="Example Report">

<figure align="center"><artwork align="center">
 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: &lt;735ff.e317+bf22029@example.net&gt;
     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.gz"

     &lt;gzipped content of report&gt;

------=_NextPart_000_024E_01CC9B0A.AFE54C00--
...
</artwork></figure>
<t>Note that, when sending failure reports via SMTP, sending MTAs MUST NOT
honor MTA-STS or DANE TLSA failures.
</t>
</section>
</section>

<section anchor="https-transport" title="HTTPS Transport">
<t>The report MAY be delivered by POST to HTTPS. If compressed, the report
SHOULD use the media type <spanx style="verb">application/tlsrpt+gzip</spanx>, and
<spanx style="verb">application/tlsrpt+json</spanx> otherwise (see section <xref target="iana-considerations"/>,
&quot;IANA Considerations&quot;).
</t>
<t>A reporting entity SHOULD expect a &quot;successful&quot; response from the
accepting HTTPS server, typically a 200 or 201 HTTP code <xref target="RFC7231"/>.
Other codes could indicate a delivery failure, and may be retried as per
local policy.  The receiving system is not expected to process reports
at receipt time, and MAY store them for processing at a later time.
</t>
</section>

<section anchor="delivery-retry" title="Delivery Retry">
<t>In the event of a delivery failure, regardless of the delivery method, a
sender SHOULD attempt redelivery for up to 24hrs after the initial
attempt.  As previously stated the reports are optional, so while it is
ideal to attempt redelivery, it is not required.  If multiple retries
are attempted, ideally they would be on a logarithmic scale.
</t>
</section>

<section anchor="metadata-variances" title="Metadata Variances">
<t>As stated above, there are a variable number of ways to declare
information about the data therein.  If it should be the case that these
objects were to disagree, then the report data contained within the JSON
body MUST be considered the authoritative source for those data
elements.
</t>
</section>
</section>

<section anchor="iana-considerations" title="IANA Considerations">
<t>The following are the IANA considerations discussed in this document.
</t>

<section anchor="message-headers" title="Message headers">
<t>Below is the Internet Assigned Numbers Authority (IANA) Permanent
Message Header Field registration information per <xref target="RFC3864"/>.
</t>

<figure align="center"><artwork align="center">
 Header field name:           TLS-Report-Domain
 Applicable protocol:         mail
 Status:                      standard
 Author/Change controller:    IETF
 Specification document(s):   this one


 Header field name:           TLS-Report-Submitter
 Applicable protocol:         mail
 Status:                      standard
 Author/Change controller:    IETF
 Specification document(s):   this one
</artwork></figure>
</section>

<section anchor="report-type" title="Report Type">
<t>This document registers a new parameter <spanx style="verb">report-type="tlsrpt"</spanx> under
<spanx style="verb">multipart/report</spanx> top-level media type for use with <xref target="RFC6522"/>.
</t>
<t>The media type suitable for use as a report-type is defined in the
following section.
</t>
</section>

<section anchor="applicationtlsrptjson-media-type" title="application/tlsrpt+json Media Type">
<t>This document registers multiple media types, beginning with Table 1
below.
</t>

<figure align="center"><artwork align="center">
+-------------+----------------+-------------+-------------------+
| Type        | Subtype        | File extn   | Specification     |
+-------------+----------------+-------------+-------------------+
| application | tlsrpt+json    |  .json      | Section 5.3       |
+-------------+----------------+-------------+-------------------+
                Table 1: SMTP TLS Reporting Media Type
</artwork></figure>
<t>Type name: application
</t>
<t>Subtype name: tlsrpt+json
</t>
<t>Required parameters: n/a
</t>
<t>Optional parameters: n/a
</t>
<t>Encoding considerations: Encoding considerations are identical to
      those specified for the <spanx style="verb">application/json</spanx> media type. See
      <xref target="RFC7493"/>.
</t>
<t>Security considerations: Security considerations relating to SMTP
      TLS Reporting are discussed in Section 7.
</t>
<t>Interoperability considerations: This document specifies format of
      conforming messages and the interpretation thereof.
</t>
<t>Published specification: Section 5.3 of this document.
</t>
<t>Applications that use this media type: Mail User Agents (MUA) and
      Mail Transfer Agents.
</t>
<t>Additional information:
</t>

<figure align="center"><artwork align="center">
  Magic number(s):  n/a

  File extension(s):  ".json"

  Macintosh file type code(s):  n/a
</artwork></figure>
<t>Person &amp; email address to contact for further information: See
      Authors' Addresses section.
</t>
<t>Intended usage:  COMMON
</t>
<t>Restrictions on usage:  n/a
</t>
<t>Author:  See Authors' Addresses section.
</t>
<t>Change controller:  Internet Engineering Task Force
      (mailto:iesg@ietf.org).
</t>
</section>

<section anchor="applicationtlsrptgzip-media-type" title="application/tlsrpt+gzip Media Type">

<figure align="center"><artwork align="center">
+-------------+----------------+-------------+-------------------+
| Type        | Subtype        | File extn   | Specification     |
+-------------+----------------+-------------+-------------------+
| application | tlsrpt+gzip    |  .gz        | Section 5.3       |
+-------------+----------------+-------------+-------------------+
                Table 2: SMTP TLS Reporting Media Type
</artwork></figure>
<t>Type name: application
</t>
<t>Subtype name: tlsrpt+gzip
</t>
<t>Required parameters: n/a
</t>
<t>Optional parameters: n/a
</t>
<t>Encoding considerations: Binary
</t>
<t>Security considerations: Security considerations relating to SMTP
      TLS Reporting are discussed in Section 7.
</t>
<t>Interoperability considerations: This document specifies format of
      conforming messages and the interpretation thereof.
</t>
<t>Published specification: Section 5.3 of this document.
</t>
<t>Applications that use this media type: Mail User Agents (MUA) and
      Mail Transfer Agents.
</t>
<t>Additional information:
</t>

<figure align="center"><artwork align="center">
  Magic number(s):  n/a

  File extension(s):  ".gz"

  Macintosh file type code(s):  n/a
</artwork></figure>
<t>Person &amp; email address to contact for further information: See
      Authors' Addresses section.
</t>
<t>Intended usage:  COMMON
</t>
<t>Restrictions on usage:  n/a
</t>
<t>Author:  See Authors' Addresses section.
</t>
<t>Change controller:  Internet Engineering Task Force
      (mailto:iesg@ietf.org).
</t>
</section>

<section anchor="starttls-validation-result-types" title="STARTTLS Validation Result Types">
<t>This document creates a new registry, &quot;STARTTLS Validation Result
Types&quot;. The initial entries in the registry are:
</t>

<figure align="center"><artwork align="center">
+-------------------------------+
| Result Type                   | 
+-------------------------------+
| "starttls-not-supported"      | 
| "certificate-host-mismatch"   | 
| "certificate-expired"         | 
| "tlsa-invalid"                | 
| "dnssec-invalid"              | 
| "sts-policy-invalid"          | 
| "sts-webpki-invalid"          | 
| "validation-failure"          | 
+-------------------------------+
</artwork></figure>
<t>The above entries are described in section <xref target="result-types"/>, &quot;Result
Types.&quot; New result types can be added to this registry using &quot;Expert
Review&quot; IANA registration policy.
</t>
</section>
</section>

<section anchor="security-considerations" title="Security Considerations">
<t>SMTP TLS Reporting provides transparency into misconfigurations or
attempts to intercept or tamper with mail between hosts who support
STARTTLS. There are several security risks presented by the existence of
this reporting channel:
</t>
<t>
<list style="symbols">
<t>Flooding of the Aggregate report URI (rua) endpoint: An attacker could
flood the endpoint with excessive reporting traffic and prevent the
receiving domain from accepting additional reports. This type of
Denial-of-Service attack would limit visibility into STARTTLS
failures, leaving the receiving domain blind to an ongoing attack.</t>
<t>Untrusted content: An attacker could inject malicious code into the
report, opening a vulnerability in the receiving domain. Implementers
are advised to take precautions against evaluating the contents of the
report.</t>
<t>Report snooping: An attacker could create a bogus TLSRPT record to
receive statistics about a domain the attacker does not own. Since an
attacker able to poison DNS is already able to receive counts of SMTP
connections (and, absent DANE or MTA-STS policies, actual SMTP message
payloads), this does not present a significant new vulnerability.</t>
<t>Reports as DDoS: TLSRPT allows specifying destinations for the reports
that are outside the authority of the Policy Domain, which allows
domains to delegate processing of reports to a partner organization.
However, an attacker who controls the Policy Domain DNS could also use
this mechanism to direct the reports to an unwitting victim, flooding
that victim with excessive reports.  DMARC <xref target="RFC7489"/> defines a
solution for verifying delegation to avoid such attacks; the need for
this is greater with DMARC, however, because DMARC allows an attacker
to trigger reports to a target from an innocent third party by sending
that third party mail (which triggers a report from the third party to
the target).  In the case of TLSRPT, the attacker would have to induce
the third party to send the attacker mail in order to trigger reports
from the third party to the victim; this reduces the risk of such an
attack and the need for a verification mechanism.</t>
</list>
</t>
<t>Finally, because TLSRPT is intended to help administrators discover
man-in-the-middle attacks against transport-layer encryption, including
attacks designed to thwart negotiation of encrypted connections (by
downgrading opportunistic encryption or, in the case of MTA-STS,
preventing discovery of a new MTA-STS policy), we must also consider the
risk that an adversary who can induce such a downgrade attack can also
prevent discovery of the TLSRPT TXT record (and thus prevent discovery
of the successful downgrade attack).  Administrators are thus encouraged
to deploy TLSRPT TXT records with a large TTL (reducing the window for
successful attacks against DNS resolution of the record) or to deploy
DNSSEC on the deploying zone.
</t>
</section>

</middle>
<back>
<references title="Normative References">
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-uta-mta-sts.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3339.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3492.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5234.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5280.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5321.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5322.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5891.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5952.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6068.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6125.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6376.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6522.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6698.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7231.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7405.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7493.xml"?>
</references>
<references title="Informative References">
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3207.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3501.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3864.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7435.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7469.xml"?>
<?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7489.xml"?>
</references>

<section anchor="example-reporting-policy-1" title="Example Reporting Policy">

<section anchor="report-using-mailto-1" title="Report using MAILTO">

<figure align="center"><artwork align="center">
_smtp-tlsrpt.mail.example.com. IN TXT \
        "v=TLSRPTv1;rua=mailto:reports@example.com"
</artwork></figure>
</section>

<section anchor="report-using-https-1" title="Report using HTTPS">

<figure align="center"><artwork align="center">
_smtp-tlsrpt.mail.example.com. IN TXT \
        "v=TLSRPTv1; \
        rua=https://reporting.example.com/v1/tlsrpt"
</artwork></figure>
</section>
</section>

<section anchor="example-json-report" title="Example JSON Report">

<figure align="center"><artwork align="center">
{
  "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\r\nmode: report\r\n
                mx: .mail.company-y.example\r\nmax_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": "98.136.216.25",
      "receiving-mx-hostname": "mx1.mail.company-y.example",
      "failed-session-count": 100
    }, {
      "result-type": "starttls-not-supported",
      "sending-mta-ip": "98.22.33.99",
      "receiving-mx-hostname": "mx2.mail.company-y.example",
      "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": "47.97.15.2",
      "receiving-mx-hostname": "mx-backup.mail.company-y.example",
      "failed-session-count": 3,
      "failure-error-code": "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED"
    }]
  }]
}

</artwork></figure>
<t>Figure: Example JSON report for a messages from Company-X to Company-Y,
where 100 sessions were attempted to Company Y servers with an expired
certificate and 200 sessions were attempted to Company Y servers that
did not successfully respond to the <spanx style="verb">STARTTLS</spanx> command.  Additionally 3
sessions failed due to &quot;X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED&quot;.
</t>
</section>

</back>
</rfc>
