idnits 2.17.1 draft-ietf-uta-smtp-tlsrpt-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 13) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 4 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 5, 2018) is 2244 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'CFWS' is mentioned on line 658, but not defined == Outdated reference: A later version (-21) exists of draft-ietf-uta-mta-sts-14 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 3501 (Obsoleted by RFC 9051) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Using TLS in Applications D. Margolis 3 Internet-Draft Google, Inc 4 Intended status: Standards Track A. Brotman 5 Expires: September 6, 2018 Comcast, Inc 6 B. Ramakrishnan 7 Yahoo!, Inc 8 J. Jones 9 Microsoft, Inc 10 M. Risher 11 Google, Inc 12 March 5, 2018 14 SMTP TLS Reporting 15 draft-ietf-uta-smtp-tlsrpt-17 17 Abstract 19 A number of protocols exist for establishing encrypted channels 20 between SMTP Mail Transfer Agents, including STARTTLS, DANE TLSA, and 21 MTA-STS. These protocols can fail due to misconfiguration or active 22 attack, leading to undelivered messages or delivery over unencrypted 23 or unauthenticated channels. This document describes a reporting 24 mechanism and format by which sending systems can share statistics 25 and specific information about potential failures with recipient 26 domains. Recipient domains can then use this information to both 27 detect potential attackers and diagnose unintentional 28 misconfigurations. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 6, 2018. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. Related Technologies . . . . . . . . . . . . . . . . . . . . 4 67 3. Reporting Policy . . . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Example Reporting Policy . . . . . . . . . . . . . . . . 6 69 3.1.1. Report using MAILTO . . . . . . . . . . . . . . . . . 6 70 3.1.2. Report using HTTPS . . . . . . . . . . . . . . . . . 7 71 4. Reporting Schema . . . . . . . . . . . . . . . . . . . . . . 7 72 4.1. Report Time-frame . . . . . . . . . . . . . . . . . . . . 8 73 4.2. Delivery Summary . . . . . . . . . . . . . . . . . . . . 8 74 4.2.1. Success Count . . . . . . . . . . . . . . . . . . . . 8 75 4.2.2. Failure Count . . . . . . . . . . . . . . . . . . . . 8 76 4.3. Result Types . . . . . . . . . . . . . . . . . . . . . . 8 77 4.3.1. Negotiation Failures . . . . . . . . . . . . . . . . 8 78 4.3.2. Policy Failures . . . . . . . . . . . . . . . . . . . 9 79 4.3.3. General Failures . . . . . . . . . . . . . . . . . . 9 80 4.3.4. Transient Failures . . . . . . . . . . . . . . . . . 10 81 4.4. JSON Report Schema . . . . . . . . . . . . . . . . . . . 10 82 4.5. Policy Samples . . . . . . . . . . . . . . . . . . . . . 13 83 5. Report Delivery . . . . . . . . . . . . . . . . . . . . . . . 14 84 5.1. Report Filename . . . . . . . . . . . . . . . . . . . . . 14 85 5.2. Compression . . . . . . . . . . . . . . . . . . . . . . . 15 86 5.3. Email Transport . . . . . . . . . . . . . . . . . . . . . 15 87 5.3.1. Example Report . . . . . . . . . . . . . . . . . . . 16 88 5.4. HTTPS Transport . . . . . . . . . . . . . . . . . . . . . 17 89 5.5. Delivery Retry . . . . . . . . . . . . . . . . . . . . . 18 90 5.6. Metadata Variances . . . . . . . . . . . . . . . . . . . 18 91 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 92 6.1. Message headers . . . . . . . . . . . . . . . . . . . . . 18 93 6.2. Report Type . . . . . . . . . . . . . . . . . . . . . . . 19 94 6.3. application/tlsrpt+json Media Type . . . . . . . . . . . 19 95 6.4. application/tlsrpt+gzip Media Type . . . . . . . . . . . 20 96 6.5. STARTTLS Validation Result Types . . . . . . . . . . . . 21 97 7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 98 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 99 8.1. Normative References . . . . . . . . . . . . . . . . . . 23 100 8.2. Informative References . . . . . . . . . . . . . . . . . 25 101 Appendix A. Example Reporting Policy . . . . . . . . . . . . . . 25 102 A.1. Report using MAILTO . . . . . . . . . . . . . . . . . . . 26 103 A.2. Report using HTTPS . . . . . . . . . . . . . . . . . . . 26 104 Appendix B. Example JSON Report . . . . . . . . . . . . . . . . 26 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 107 1. Introduction 109 The STARTTLS extension to SMTP [RFC3207] allows SMTP clients and 110 hosts to establish secure SMTP sessions over TLS. The protocol 111 design is based on "Opportunistic Security" (OS) [RFC7435], which 112 maintains interoperability with clients that do not support STARTTLS 113 but means that any attacker who can delete parts of the SMTP session 114 (such as the "250 STARTTLS" response) or redirect the entire SMTP 115 session (perhaps by overwriting the resolved MX record of the 116 delivery domain) can perform a downgrade or interception attack. 118 Because such "downgrade attacks" are not necessarily apparent to the 119 receiving MTA, this document defines a mechanism for sending domains 120 to report on failures at multiple stages of the MTA-to-MTA 121 conversation. 123 Recipient domains may also use the mechanisms defined by MTA-STS 124 [I-D.ietf-uta-mta-sts] or DANE [RFC6698] to publish additional 125 encryption and authentication requirements; this document defines a 126 mechanism for sending domains that are compatible with MTA-STS or 127 DANE to share success and failure statistics with recipient domains. 129 Specifically, this document defines a reporting schema that covers 130 failures in routing, DNS resolution, STARTTLS negotiation, and both 131 DANE [RFC6698] and MTA-STS [I-D.ietf-uta-mta-sts] policy validation 132 errors, and a standard TXT record that recipient domains can use to 133 indicate where reports in this format should be sent. 135 This document is intended as a companion to the specification for 136 SMTP MTA Strict Transport Security [I-D.ietf-uta-mta-sts], as well as 137 adds reporting abilities for those implementing DANE [RFC7672]. 139 1.1. Terminology 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in [RFC2119]. 145 We also define the following terms for further use in this document: 147 o MTA-STS Policy: A definition of the expected TLS availability, 148 behavior, and desired actions for a given domain when a sending 149 MTA encounters problems in negotiating a secure channel. MTA-STS 150 is defined in [I-D.ietf-uta-mta-sts]. 152 o DANE Policy: A mechanism by which administrators can supply a 153 record that can be used to validate the certificate presented by 154 an MTA. DANE is defined in [RFC6698] and [RFC7672]. 156 o TLSRPT Policy: A policy specifying the endpoint to which sending 157 MTAs should deliver reports. 159 o Policy Domain: The domain against which an MTA-STS or DANE Policy 160 is defined. 162 o Sending MTA: The MTA initiating the relay of an email message. 164 2. Related Technologies 166 o This document is intended as a companion to the specification for 167 SMTP MTA Strict Transport Security [I-D.ietf-uta-mta-sts]. 169 o SMTP-TLSRPT defines a mechanism for sending domains that are 170 compatible with MTA-STS or DANE to share success and failure 171 statistics with recipient domains. DANE is defined in [RFC6698] 172 and MTA-STS is defined in [I-D.ietf-uta-mta-sts]. 174 3. Reporting Policy 176 A domain publishes a record to its DNS indicating that it wishes to 177 receive reports. These SMTP TLSRPT policies are distributed via DNS 178 from the Policy Domain's zone, as TXT records (similar to DMARC 179 policies) under the name "_smtp-tlsrpt". For example, for the Policy 180 Domain "example.com", the recipient's TLSRPT policy can be retrieved 181 from "_smtp-tlsrpt.example.com". 183 Policies consist of the following directives: 185 o "v": This value MUST be equal to "TLSRPTv1". 187 o "rua": A URI specifying the endpoint to which aggregate 188 information about policy validation results should be sent (see 189 Section 4, "Reporting Schema", for more information). Two URI 190 schemes are supported: "mailto" and "https". As with DMARC 191 [RFC7489], the policy domain can specify a comma-separated list of 192 URIs. 194 o In the case of "https", reports should be submitted via POST 195 ([RFC7231]) to the specified URI. Report submitters MAY ignore 196 certificate validation errors when submitting reports via https. 198 o In the case of "mailto", reports should be submitted to the 199 specified email address ([RFC6068]). When sending failure reports 200 via SMTP, sending MTAs MUST deliver reports despite any TLS- 201 related failures and SHOULD NOT include this SMTP session in the 202 next report. This may mean that the reports are delivered in the 203 clear. Additionally, reports sent via SMTP MUST contain a valid 204 DKIM [RFC6376] signature by the reporting domain. Reports lacking 205 such a signature MUST be ignored by the recipient. DKIM 206 signatures must not use the "l=" attribute to limit the body 207 length used in the signature. 209 The formal definition of the "_smtp-tlsrpt" TXT record, defined using 210 [RFC5234] & [RFC7405], is as follows: 212 tlsrpt-record = tlsrpt-version 1*(field-delim tlsrpt-field) 213 [field-delim] 215 field-delim = *WSP ";" *WSP 217 tlsrpt-field = tlsrpt-rua / ; Note that the 218 tlsrpt-extension ; tlsrpt-rua record is 219 ; required. 221 tlsrpt-version = %s"v=TLSRPTv1" 223 tlsrpt-rua = %s"rua=" 224 tlsrpt-uri *(*WSP "," *WSP tlsrpt-uri) 226 tlsrpt-uri = URI 227 ; "URI" is imported from [RFC3986]; 228 ; commas (ASCII 0x2C) and exclamation 229 ; points (ASCII 0x21) MUST be encoded 231 tlsrpt-extension = tlsrpt-ext-name "=" tlsrpt-ext-value 233 tlsrpt-ext-name = (ALPHA / DIGIT) *31(ALPHA / 234 DIGIT / "_" / "-" / ".") 236 tlsrpt-ext-value = 1*(%x21-3A / %x3C / %x3E-7E) 237 ; chars excluding "=", ";", SP, and control 238 ; chars 240 If multiple TXT records for "_smtp-tlsrpt" are returned by the 241 resolver, records which do not begin with "v=TLSRPTv1;" are 242 discarded. If the number of resulting records is not one, senders 243 MUST assume the recipient domain does not implement TLSRPT. If the 244 resulting TXT record contains multiple strings, then the record MUST 245 be treated as if those strings are concatenated together without 246 adding spaces. 248 Parsers MUST accept TXT records which are syntactically valid (i.e. 249 valid key-value pairs separated by semi-colons) and implementing a 250 superset of this specification, in which case unknown fields SHALL be 251 ignored. 253 3.1. Example Reporting Policy 255 3.1.1. Report using MAILTO 257 _smtp-tlsrpt.example.com. IN TXT \ 258 "v=TLSRPTv1;rua=mailto:reports@example.com" 260 3.1.2. Report using HTTPS 262 _smtp-tlsrpt.example.com. IN TXT \ 263 "v=TLSRPTv1; \ 264 rua=https://reporting.example.com/v1/tlsrpt" 266 4. Reporting Schema 268 The report is composed as a plain text file encoded in the I-JSON 269 format ([RFC7493]). 271 Aggregate reports contain the following fields: 273 o Report metadata: 275 * The organization responsible for the report 277 * Contact information for one or more responsible parties for the 278 contents of the report 280 * A unique identifier for the report 282 * The reporting date range for the report 284 o Policy, consisting of: 286 * One of the following policy types: (1) The MTA-STS policy 287 applied (as a string) (2) The DANE TLSA record applied (as a 288 string, with each RR entry of the RRset listed and separated by 289 a semicolon) (3) The literal string "no-policy-found", if 290 neither a DANE nor MTA-STS policy could be found. 292 * The domain for which the policy is applied 294 * The MX host 296 o Aggregate counts, comprising result type, sending MTA IP, 297 receiving MTA hostname, session count, and an optional additional 298 information field containing a URI for recipients to review 299 further information on a failure type. 301 Note that the failure types are non-exclusive; an aggregate report 302 may contain overlapping "counts" of failure types when a single send 303 attempt encountered multiple errors. Reporters may report multiple 304 applied policies (for example, an MTA-STS policy and a DANE TLSA 305 record for the same domain and MX); even in the case where only a 306 single policy was applied, the "policies" field of the report body 307 MUST be an array and not a singular value. 309 4.1. Report Time-frame 311 The report SHOULD cover a full day, from 0000-2400 UTC. This should 312 allow for easier correlation of failure events. To avoid a Denial of 313 Service against the system processing the reports, the reports should 314 be delivered after some delay, perhaps several hours. 316 4.2. Delivery Summary 318 4.2.1. Success Count 320 o "success-count": This indicates that the sending MTA was able to 321 successfully negotiate a policy-compliant TLS connection, and 322 serves to provide a "heartbeat" to receiving domains that 323 reporting is functional and tabulating correctly. This field 324 contains an aggregate count of successful connections for the 325 reporting system. 327 4.2.2. Failure Count 329 o "failure-count": This indicates that the sending MTA was unable to 330 successfully establish a connection with the receiving platform. 331 Section 4.3, "Result Types", will elaborate on the failed 332 negotiation attempts. This field contains an aggregate count of 333 failed connections. 335 4.3. Result Types 337 The list of result types will start with the minimal set below, and 338 is expected to grow over time based on real-world experience. The 339 initial set is: 341 4.3.1. Negotiation Failures 343 o "starttls-not-supported": This indicates that the recipient MX did 344 not support STARTTLS. 346 o "certificate-host-mismatch": This indicates that the certificate 347 presented did not adhere to the constraints specified in the MTA- 348 STS or DANE policy, e.g. if the MX hostname does not match any 349 identities listed in the Subject Alternate Name (SAN) [RFC5280]. 351 o "certificate-expired": This indicates that the certificate has 352 expired. 354 o "certificate-not-trusted": This a label that covers multiple 355 certificate related failures that include, but not limited to 356 errors such as untrusted/unknown CAs, certificate name 357 constraints, certificate chain errors etc. When using this 358 declaration, the reporting MTA SHOULD utilize the "failure-reason- 359 code" to provide more information to the receiving entity. 361 o "validation-failure": This indicates a general failure for a 362 reason not matching a category above. When using this 363 declaration, the reporting MTA SHOULD utilize the "failure-reason- 364 code" to provide more information to the receiving entity. 366 4.3.2. Policy Failures 368 4.3.2.1. DANE-specific Policy Failures 370 o "tlsa-invalid": This indicates a validation error in the TLSA 371 record associated with a DANE policy. None of the records in the 372 RRset were found to be valid. 374 o "dnssec-invalid": This would indicate that no valid records were 375 returned from the recursive resolver. The request returned with 376 SERVFAIL for the requested TLSA record. 378 o "dane-required": This indicates that the sending system is 379 configured to require DANE TLSA records for all the MX hosts of 380 the destination domain, but no DNSSEC-validated TLSA records were 381 present for the MX host that is the subject of the report. 382 Mandatory DANE for SMTP is described in section 6 of [RFC7672]. 383 Such policies may be created by mutual agreement between two 384 organizations that frequently exchange sensitive content via 385 email. 387 4.3.2.2. MTA-STS-specific Policy Failures 389 o "sts-policy-invalid": This indicates a validation error for the 390 overall MTA-STS policy. 392 o "sts-webpki-invalid": This indicates that the MTA-STS policy could 393 not be authenticated using PKIX validation. 395 4.3.3. General Failures 397 When a negotiation failure can not be categorized into one of the 398 "Negotiation Failures" stated above, the reporter SHOULD use the 399 "validation-failure" category. As TLS grows and becomes more 400 complex, new mechanisms may not be easily categorized. This allows 401 for a generic feedback category. When this category is used, the 402 reporter SHOULD also use the "failure-reason-code" to give some 403 feedback to the receiving entity. This is intended to be a short 404 text field, and the contents of the field should be an error code or 405 error text, such as "X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION". 407 4.3.4. Transient Failures 409 Transient errors due to too-busy network, TCP timeouts, etc. are not 410 required to be reported. 412 4.4. JSON Report Schema 414 The JSON schema is derived from the HPKP JSON schema [RFC7469] (cf. 415 Section 3) 417 { 418 "organization-name": organization-name, 419 "date-range": { 420 "start-datetime": date-time, 421 "end-datetime": date-time 422 }, 423 "contact-info": email-address, 424 "report-id": report-id, 425 "policies": [{ 426 "policy": { 427 "policy-type": policy-type, 428 "policy-string": policy-string, 429 "policy-domain": domain, 430 "mx-host": mx-host-pattern 431 }, 432 "summary": { 433 "total-successful-session-count": total-successful-session-count, 434 "total-failure-session-count": total-failure-session-count 435 }, 436 "failure-details": [ 437 { 438 "result-type": result-type, 439 "sending-mta-ip": ip-address, 440 "receiving-mx-hostname": receiving-mx-hostname, 441 "receiving-mx-helo": receiving-mx-helo, 442 "receiving-ip": receiving-ip, 443 "failed-session-count": failed-session-count, 444 "additional-information": additional-info-uri, 445 "failure-reason-code": failure-reason-code 446 } 447 ] 448 } 449 ] 450 } 452 JSON Report Format 454 o "organization-name": The name of the organization responsible for 455 the report. It is provided as a string. 457 o "date-time": The date-time indicates the start- and end-times for 458 the report range. It is provided as a string formatted according 459 to Section 5.6, "Internet Date/Time Format", of [RFC3339]. The 460 report should be for a full UTC day, 0000-2400. 462 o "email-address": The contact information for a responsible party 463 of the report. It is provided as a string formatted according to 464 Section 3.4.1, "Addr-Spec", of [RFC5321]. 466 o "report-id": A unique identifier for the report. Report authors 467 may use whatever scheme they prefer to generate a unique 468 identifier. It is provided as a string. 470 o "policy-type": The type of policy that was applied by the sending 471 domain. Presently, the only three valid choices are "tlsa", 472 "sts", and the literal string "no-policy-found". It is provided 473 as a string. 475 o "policy-string": An encoding of the applied policy as a JSON array 476 of strings, whether TLSA record ([RFC6698] section 2.3) or MTA-STS 477 policy. Examples follow in the next section. 479 o "domain": The Policy Domain is the domain against which the MTA- 480 STS or DANE policy is defined. In the case of Internationalized 481 Domain Names ([RFC5891]), the domain MUST consist of the Punycode- 482 encoded A-labels ([RFC3492]) and not the U-labels. 484 o "mx-host-pattern": The pattern of MX hostnames from the applied 485 policy. It is provided as a string, and is interpreted in the 486 same manner as the "Checking of Wildcard Certificates" rules in 487 Section 6.4.3 of [RFC6125]. In the case of Internationalized 488 Domain Names ([RFC5891]), the domain MUST consist of the Punycode- 489 encoded A-labels ([RFC3492]) and not the U-labels. 491 o "result-type": A value from Section 4.3, "Result Types", above. 493 o "ip-address": The IP address of the sending MTA that attempted the 494 STARTTLS connection. It is provided as a string representation of 495 an IPv4 (see below) or IPv6 ([RFC5952]) address in dot-decimal or 496 colon-hexadecimal notation. 498 o "receiving-mx-hostname": The hostname of the receiving MTA MX 499 record with which the sending MTA attempted to negotiate a 500 STARTTLS connection. 502 o "receiving-mx-helo": (optional) The HELO or EHLO string from the 503 banner announced during the reported session. 505 o "receiving-ip": The destination IP address that was using when 506 creating the outbound session. It is provided as a string 507 representation of an IPv4 (see below) or IPv6 ([RFC5952]) address 508 in dot-decimal or colon-hexadecimal notation. 510 o "total-successful-session-count": The aggregate number (integer) 511 of successfully negotiated TLS-enabled connections to the 512 receiving site. 514 o "total-failure-session-count": The aggregate number (integer) of 515 failures to negotiate a TLS-enabled connection to the receiving 516 site. 518 o "failed-session-count": The number of (attempted) sessions that 519 match the relevant "result-type" for this section. 521 o "additional-info-uri": An optional URI [RFC3986] pointing to 522 additional information around the relevant "result-type". For 523 example, this URI might host the complete certificate chain 524 presented during an attempted STARTTLS session. 526 o "failure-reason-code": A text field to include a TLS-related error 527 code or error message. 529 For report purposes, an IPv4 Address is defined as: IPv4address = 530 dec-octet "." dec-octet "." dec-octet "." dec-octet 531 dec-octet = DIGIT ; 0-9 / %x31-39 DIGIT ; 10-99 / "1" 2DIGIT ; 532 100-199 / "2" %x30-34 DIGIT ; 200-249 / "25" %x30-35 ; 250-255 534 4.5. Policy Samples 536 Part of the report body includes the policy that is applied when 537 attemping relay to the destination. 539 For DANE TLSA policies, a JSON array of strings each representing the 540 RDATA of a single TLSA resource record as a space-separated list of 541 its four TLSA fields; the fields are in presentation format (defined 542 in RFC6698 Section 2.2) with no internal spaces or grouping 543 parentheses: 545 [ 546 "3 0 1 1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513D747D1D085D", 547 "3 0 1 12350A337E6DB9C6123522D136A475638CC43E1ED424F8EEC8513D747D1D1234" 548 ] 550 For the MTA-STS policy, an array of JSON strings that represents the 551 policy that is declared by the receiving site, including any errors 552 that may be present. Note that where there are multiple "mx" values, 553 they must be listed as separate "mx" elements in the policy array, 554 rather as a single nested "mx" sub-array. 556 [ 557 "version: STSv1", 558 "mode: report", 559 "mx: mx1.example.com", 560 "mx: mx2.example.com", 561 "mx: mx.backup-example.com", 562 "max_age: 12345678" 563 ] 565 5. Report Delivery 567 Reports can be delivered either as an email message via SMTP or via 568 HTTP POST. 570 5.1. Report Filename 572 The filename is RECOMMENDED to be constructed using the following 573 ABNF: 575 filename = sender "!" policy-domain "!" begin-timestamp 576 "!" end-timestamp [ "!" unique-id ] "." extension 578 unique-id = 1*(ALPHA / DIGIT) 580 sender = domain ; From the [RFC5321] that is used 581 ; as the domain for the `contact-info` 582 ; address in the report body 584 policy-domain = domain 586 begin-timestamp = 1*DIGIT 587 ; seconds since 00:00:00 UTC January 1, 1970 588 ; indicating start of the time range contained 589 ; in the report 591 end-timestamp = 1*DIGIT 592 ; seconds since 00:00:00 UTC January 1, 1970 593 ; indicating end of the time range contained 594 ; in the report 596 extension = "json" / "json.gz" 598 The extension MUST be "json" for a plain JSON file, or "json.gz" for 599 a JSON file compressed using GZIP. 601 "unique-id" allows an optional unique ID generated by the Sending MTA 602 to distinguish among multiple reports generated simultaneously by 603 different sources within the same Policy Domain. For example, this 604 is a possible filename for a compressed report to the Policy Domain 605 "example.net" from the Sending MTA "mail.sndr.example.com": 607 "mail.sndr.example.com!example.net!1470013207!1470186007!001.json.gz" 609 5.2. Compression 611 The report SHOULD be subjected to GZIP compression for both email and 612 HTTPS transport. Declining to apply compression can cause the report 613 to be too large for a receiver to process (a commonly observed 614 receiver limit is ten megabytes); compressing the file increases the 615 chances of acceptance of the report at some compute cost. 617 5.3. Email Transport 619 The report MAY be delivered by email. To make the reports machine- 620 parsable for the receivers, we define a top-level media type 621 "multipart/report" with a new parameter "report-type="tlsrpt"". 622 Inside it, there are two parts: The first part is human readable, 623 typically "text/plain", and the second part is machine readable with 624 a new media type defined called "application/tlsrpt+json". If 625 compressed, the report should use the media type "application/ 626 tlsrpt+gzip". 628 In addition, the following two new top level message header fields 629 are defined: 631 "TLS-Report-Domain: Receiver-Domain" 632 "TLS-Report-Submitter: Sender-Domain" 634 The "TLS-Report-Submitter" value MUST match the value found in the 635 [RFC5321] domain from the "contact-info" from the report body. These 636 message headers MUST be included and should allow for easy searching 637 for all reports submitted by a report domain or a particular 638 submitter, for example in IMAP [RFC3501]: 640 "s SEARCH HEADER "TLS-Report-Domain" "example.com"" 642 It is presumed that the aggregate reporting address will be equipped 643 to process new message header fields and extract MIME parts with the 644 prescribed media type and filename, and ignore the rest. These 645 additional headers SHOULD be included in the DKIM [RFC6376] signature 646 for the message. 648 The [RFC5322].Subject field for report submissions SHOULD conform to 649 the following ABNF: 651 tlsrpt-subject = %s"Report" FWS ; "Report" 652 %s"Domain:" FWS ; "Domain:" 653 domain-name FWS ; per [RFC6376] 654 %s"Submitter:" FWS ; "Submitter:" 655 domain-name FWS ; per [RFC6376] 656 %s"Report-ID:" FWS ; "Report-ID: 657 "<" id-left "@" id-right ">" ; per [RFC5322] 658 [CFWS] ; per [RFC5322] 659 ; (as with FWS) 661 The first domain-name indicates the DNS domain name about which the 662 report was generated. The second domain-name indicates the DNS 663 domain name representing the Sending MTA generating the report. The 664 purpose of the Report-ID: portion of the field is to enable the 665 Policy Domain to identify and ignore duplicate reports that might be 666 sent by a Sending MTA. 668 For instance, this is a possible Subject field for a report to the 669 Policy Domain "example.net" from the Sending MTA 670 "mail.sender.example.com". It is line-wrapped as allowed by 671 [RFC5322]: 673 Subject: Report Domain: example.net 674 Submitter: mail.sender.example.com 675 Report-ID: <735ff.e317+bf22029@mailexample.net> 677 5.3.1. Example Report 678 From: tlsrpt@mail.sender.example.com 679 Date: Fri, May 09 2017 16:54:30 -0800 680 To: mts-sts-tlsrpt@example.net 681 Subject: Report Domain: example.net 682 Submitter: mail.sender.example.com 683 Report-ID: <735ff.e317+bf22029@example.net> 684 TLS-Report-Domain: example.net 685 TLS-Report-Submitter: mail.sender.example.com 686 MIME-Version: 1.0 687 Content-Type: multipart/report; report-type="tlsrpt"; 688 boundary="----=_NextPart_000_024E_01CC9B0A.AFE54C00" 689 Content-Language: en-us 691 This is a multipart message in MIME format. 693 ------=_NextPart_000_024E_01CC9B0A.AFE54C00 694 Content-Type: text/plain; charset="us-ascii" 695 Content-Transfer-Encoding: 7bit 697 This is an aggregate TLS report from mail.sender.example.com 699 ------=_NextPart_000_024E_01CC9B0A.AFE54C00 700 Content-Type: application/tlsrpt+gzip 701 Content-Transfer-Encoding: base64 702 Content-Disposition: attachment; 703 filename="mail.sender.example!example.com! 704 1013662812!1013749130.json.gz" 706 708 ------=_NextPart_000_024E_01CC9B0A.AFE54C00-- 709 ... 711 Note that, when sending failure reports via SMTP, sending MTAs MUST 712 NOT honor MTA-STS or DANE TLSA failures. 714 5.4. HTTPS Transport 716 The report MAY be delivered by POST to HTTPS. If compressed, the 717 report SHOULD use the media type "application/tlsrpt+gzip", and 718 "application/tlsrpt+json" otherwise (see section Section 6, "IANA 719 Considerations"). 721 A reporting entity SHOULD expect a "successful" response from the 722 accepting HTTPS server, typically a 200 or 201 HTTP code [RFC7231]. 723 Other codes could indicate a delivery failure, and may be retried as 724 per local policy. The receiving system is not expected to process 725 reports at receipt time, and MAY store them for processing at a later 726 time. 728 Alternately, if a receiving system offers "Accept-Encoding" value of 729 "gzip", the sending system MAY use "Content-Encoding: gzip" as an 730 HTTP header as appropriate. This can be used in place of delivering 731 a compressed file as the payload. 733 5.5. Delivery Retry 735 In the event of a delivery failure, regardless of the delivery 736 method, a sender SHOULD attempt redelivery for up to 24hrs after the 737 initial attempt. As previously stated the reports are optional, so 738 while it is ideal to attempt redelivery, it is not required. If 739 multiple retries are attempted, ideally they SHOULD be done with 740 exponential backoff. 742 5.6. Metadata Variances 744 As stated above, there are a variable number of ways to declare 745 information about the data therein. If any of items declared via 746 subject or filename disagree with the report, the report MUST be 747 considered the authoritative source. 749 6. IANA Considerations 751 The following are the IANA considerations discussed in this document. 753 6.1. Message headers 755 Below is the Internet Assigned Numbers Authority (IANA) Permanent 756 Message Header Field registration information per [RFC3864]. 758 Header field name: TLS-Report-Domain 759 Applicable protocol: mail 760 Status: standard 761 Author/Change controller: IETF 762 Specification document(s): this one 764 Header field name: TLS-Report-Submitter 765 Applicable protocol: mail 766 Status: standard 767 Author/Change controller: IETF 768 Specification document(s): this one 770 6.2. Report Type 772 This document registers a new parameter "report-type="tlsrpt"" under 773 "multipart/report" top-level media type for use with [RFC6522]. 775 The media type suitable for use as a report-type is defined in the 776 following section. 778 6.3. application/tlsrpt+json Media Type 780 This document registers multiple media types, beginning with Table 1 781 below. 783 +-------------+----------------+-------------+-------------------+ 784 | Type | Subtype | File extn | Specification | 785 +-------------+----------------+-------------+-------------------+ 786 | application | tlsrpt+json | .json | Section 5.3 | 787 +-------------+----------------+-------------+-------------------+ 788 Table 1: SMTP TLS Reporting Media Type 790 Type name: application 792 Subtype name: tlsrpt+json 794 Required parameters: n/a 796 Optional parameters: n/a 798 Encoding considerations: Encoding considerations are identical to 799 those specified for the "application/json" media type. See 800 [RFC7493]. 802 Security considerations: Security considerations relating to SMTP TLS 803 Reporting are discussed in Section 7. 805 Interoperability considerations: This document specifies format of 806 conforming messages and the interpretation thereof. 808 Published specification: Section 5.3 of this document. 810 Applications that use this media type: Mail User Agents (MUA) and 811 Mail Transfer Agents. 813 Additional information: 815 Magic number(s): n/a 817 File extension(s): ".json" 819 Macintosh file type code(s): n/a 821 Person & email address to contact for further information: See 822 Authors' Addresses section. 824 Intended usage: COMMON 826 Restrictions on usage: n/a 828 Author: See Authors' Addresses section. 830 Change controller: Internet Engineering Task Force 831 (mailto:iesg@ietf.org). 833 6.4. application/tlsrpt+gzip Media Type 835 +-------------+----------------+-------------+-------------------+ 836 | Type | Subtype | File extn | Specification | 837 +-------------+----------------+-------------+-------------------+ 838 | application | tlsrpt+gzip | .gz | Section 5.3 | 839 +-------------+----------------+-------------+-------------------+ 840 Table 2: SMTP TLS Reporting Media Type 842 Type name: application 844 Subtype name: tlsrpt+gzip 846 Required parameters: n/a 848 Optional parameters: n/a 850 Encoding considerations: Binary 852 Security considerations: Security considerations relating to SMTP TLS 853 Reporting are discussed in Section 7. 855 Interoperability considerations: This document specifies format of 856 conforming messages and the interpretation thereof. 858 Published specification: Section 5.3 of this document. 860 Applications that use this media type: Mail User Agents (MUA) and 861 Mail Transfer Agents. 863 Additional information: 865 Magic number(s): n/a 867 File extension(s): ".gz" 869 Macintosh file type code(s): n/a 871 Person & email address to contact for further information: See 872 Authors' Addresses section. 874 Intended usage: COMMON 876 Restrictions on usage: n/a 878 Author: See Authors' Addresses section. 880 Change controller: Internet Engineering Task Force 881 (mailto:iesg@ietf.org). 883 6.5. STARTTLS Validation Result Types 885 This document creates a new registry, "STARTTLS Validation Result 886 Types". The initial entries in the registry are: 888 +-------------------------------+ 889 | Result Type | 890 +-------------------------------+ 891 | "starttls-not-supported" | 892 | "certificate-host-mismatch" | 893 | "certificate-expired" | 894 | "tlsa-invalid" | 895 | "dnssec-invalid" | 896 | "dane-required" | 897 | "certificate-not-trusted" | 898 | "sts-policy-invalid" | 899 | "sts-webpki-invalid" | 900 | "validation-failure" | 901 +-------------------------------+ 903 The above entries are described in section Section 4.3, "Result 904 Types." New result types can be added to this registry using "Expert 905 Review" IANA registration policy. 907 7. Security Considerations 909 SMTP TLS Reporting provides transparency into misconfigurations or 910 attempts to intercept or tamper with mail between hosts who support 911 STARTTLS. There are several security risks presented by the 912 existence of this reporting channel: 914 o Flooding of the Aggregate report URI (rua) endpoint: An attacker 915 could flood the endpoint with excessive reporting traffic and 916 prevent the receiving domain from accepting additional reports. 917 This type of Denial-of-Service attack would limit visibility into 918 STARTTLS failures, leaving the receiving domain blind to an 919 ongoing attack. 921 o Untrusted content: An attacker could inject malicious code into 922 the report, opening a vulnerability in the receiving domain. 923 Implementers are advised to take precautions against evaluating 924 the contents of the report. 926 o Report snooping: An attacker could create a bogus TLSRPT record to 927 receive statistics about a domain the attacker does not own. 928 Since an attacker able to poison DNS is already able to receive 929 counts of SMTP connections (and, absent DANE or MTA-STS policies, 930 actual SMTP message payloads), this does not present a significant 931 new vulnerability. 933 o Reports as DDoS: TLSRPT allows specifying destinations for the 934 reports that are outside the authority of the Policy Domain, which 935 allows domains to delegate processing of reports to a partner 936 organization. However, an attacker who controls the Policy Domain 937 DNS could also use this mechanism to direct the reports to an 938 unwitting victim, flooding that victim with excessive reports. 939 DMARC [RFC7489] defines a solution for verifying delegation to 940 avoid such attacks; the need for this is greater with DMARC, 941 however, because DMARC allows an attacker to trigger reports to a 942 target from an innocent third party by sending that third party 943 mail (which triggers a report from the third party to the target). 944 In the case of TLSRPT, the attacker would have to induce the third 945 party to send the attacker mail in order to trigger reports from 946 the third party to the victim; this reduces the risk of such an 947 attack and the need for a verification mechanism. 949 Finally, because TLSRPT is intended to help administrators discover 950 man-in-the-middle attacks against transport-layer encryption, 951 including attacks designed to thwart negotiation of encrypted 952 connections (by downgrading opportunistic encryption or, in the case 953 of MTA-STS, preventing discovery of a new MTA-STS policy), we must 954 also consider the risk that an adversary who can induce such a 955 downgrade attack can also prevent discovery of the TLSRPT TXT record 956 (and thus prevent discovery of the successful downgrade attack). 957 Administrators are thus encouraged to deploy TLSRPT TXT records with 958 a large TTL (reducing the window for successful attacks against DNS 959 resolution of the record) or to deploy DNSSEC on the deploying zone. 961 8. References 963 8.1. Normative References 965 [I-D.ietf-uta-mta-sts] 966 Margolis, D., Risher, M., Ramakrishnan, B., Brotman, A., 967 and J. Jones, "SMTP MTA Strict Transport Security (MTA- 968 STS)", draft-ietf-uta-mta-sts-14 (work in progress), 969 January 2018. 971 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 972 Requirement Levels", BCP 14, RFC 2119, 973 DOI 10.17487/RFC2119, March 1997, . 976 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 977 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 978 . 980 [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode 981 for Internationalized Domain Names in Applications 982 (IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003, 983 . 985 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 986 Resource Identifier (URI): Generic Syntax", STD 66, 987 RFC 3986, DOI 10.17487/RFC3986, January 2005, 988 . 990 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 991 Specifications: ABNF", STD 68, RFC 5234, 992 DOI 10.17487/RFC5234, January 2008, . 995 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 996 Housley, R., and W. Polk, "Internet X.509 Public Key 997 Infrastructure Certificate and Certificate Revocation List 998 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 999 . 1001 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 1002 DOI 10.17487/RFC5321, October 2008, . 1005 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1006 DOI 10.17487/RFC5322, October 2008, . 1009 [RFC5891] Klensin, J., "Internationalized Domain Names in 1010 Applications (IDNA): Protocol", RFC 5891, 1011 DOI 10.17487/RFC5891, August 2010, . 1014 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1015 Address Text Representation", RFC 5952, 1016 DOI 10.17487/RFC5952, August 2010, . 1019 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 1020 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, 1021 . 1023 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1024 Verification of Domain-Based Application Service Identity 1025 within Internet Public Key Infrastructure Using X.509 1026 (PKIX) Certificates in the Context of Transport Layer 1027 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1028 2011, . 1030 [RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 1031 "DomainKeys Identified Mail (DKIM) Signatures", STD 76, 1032 RFC 6376, DOI 10.17487/RFC6376, September 2011, 1033 . 1035 [RFC6522] Kucherawy, M., Ed., "The Multipart/Report Media Type for 1036 the Reporting of Mail System Administrative Messages", 1037 STD 73, RFC 6522, DOI 10.17487/RFC6522, January 2012, 1038 . 1040 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 1041 of Named Entities (DANE) Transport Layer Security (TLS) 1042 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 1043 2012, . 1045 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1046 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1047 DOI 10.17487/RFC7231, June 2014, . 1050 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1051 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1052 . 1054 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 1055 DOI 10.17487/RFC7493, March 2015, . 1058 [RFC7672] Dukhovni, V. and W. Hardaker, "SMTP Security via 1059 Opportunistic DNS-Based Authentication of Named Entities 1060 (DANE) Transport Layer Security (TLS)", RFC 7672, 1061 DOI 10.17487/RFC7672, October 2015, . 1064 8.2. Informative References 1066 [RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP over 1067 Transport Layer Security", RFC 3207, DOI 10.17487/RFC3207, 1068 February 2002, . 1070 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 1071 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 1072 . 1074 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1075 Procedures for Message Header Fields", BCP 90, RFC 3864, 1076 DOI 10.17487/RFC3864, September 2004, . 1079 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 1080 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 1081 December 2014, . 1083 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 1084 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 1085 2015, . 1087 [RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based 1088 Message Authentication, Reporting, and Conformance 1089 (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015, 1090 . 1092 Appendix A. Example Reporting Policy 1093 A.1. Report using MAILTO 1095 _smtp-tlsrpt.mail.example.com. IN TXT \ 1096 "v=TLSRPTv1;rua=mailto:reports@example.com" 1098 A.2. Report using HTTPS 1100 _smtp-tlsrpt.mail.example.com. IN TXT \ 1101 "v=TLSRPTv1; \ 1102 rua=https://reporting.example.com/v1/tlsrpt" 1104 Appendix B. Example JSON Report 1106 Below is an example JSON report for messages from Company-X to 1107 Company-Y, where 100 sessions were attempted to Company Y servers 1108 with an expired certificate and 200 sessions were attempted to 1109 Company Y servers that did not successfully respond to the "STARTTLS" 1110 command. Additionally 3 sessions failed due to 1111 "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED". 1113 { 1114 "organization-name": "Company-X", 1115 "date-range": { 1116 "start-datetime": "2016-04-01T00:00:00Z", 1117 "end-datetime": "2016-04-01T23:59:59Z" 1118 }, 1119 "contact-info": "sts-reporting@company-x.example", 1120 "report-id": "5065427c-23d3-47ca-b6e0-946ea0e8c4be", 1121 "policies": [{ 1122 "policy": { 1123 "policy-type": "sts", 1124 "policy-string": ["version: STSv1","mode: report", 1125 "mx: .mail.company-y.example","max_age: 86400"], 1126 "policy-domain": "company-y.example", 1127 "mx-host": ".mail.company-y.example" 1128 }, 1129 "summary": { 1130 "total-successful-session-count": 5326, 1131 "total-failure-session-count": 303 1132 }, 1133 "failure-details": [{ 1134 "result-type": "certificate-expired", 1135 "sending-mta-ip": "98.136.216.25", 1136 "receiving-mx-hostname": "mx1.mail.company-y.example", 1137 "failed-session-count": 100 1138 }, { 1139 "result-type": "starttls-not-supported", 1140 "sending-mta-ip": "98.22.33.99", 1141 "receiving-mx-hostname": "mx2.mail.company-y.example", 1142 "receiving-ip": "192.168.14.72", 1143 "failed-session-count": 200, 1144 "additional-information": "https://reports.company-x.example/ 1145 report_info ? id = 5065427 c - 23 d3# StarttlsNotSupported " 1146 }, { 1147 "result-type": "validation-failure", 1148 "sending-mta-ip": "47.97.15.2", 1149 "receiving-ip": "10.72.84.12", 1150 "receiving-mx-hostname": "mx-backup.mail.company-y.example", 1151 "failed-session-count": 3, 1152 "failure-error-code": "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED" 1153 }] 1154 }] 1155 } 1157 Authors' Addresses 1159 Daniel Margolis 1160 Google, Inc 1162 Email: dmargolis@google.com 1164 Alexander Brotman 1165 Comcast, Inc 1167 Email: alex_brotman@comcast.com 1169 Binu Ramakrishnan 1170 Yahoo!, Inc 1172 Email: rbinu@oath.com 1174 Janet Jones 1175 Microsoft, Inc 1177 Email: janet.jones@microsoft.com 1179 Mark Risher 1180 Google, Inc 1182 Email: risher@google.com