idnits 2.17.1 draft-ietf-uta-smtp-tlsrpt-05.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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 55 characters in excess of 72. ** The abstract seems to contain references ([RFC6698], [RFC3207]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 3, 2017) is 2543 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: 'TODO' is mentioned on line 161, but not defined == Missing Reference: 'RFC5280' is mentioned on line 321, but not defined ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6713 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Downref: Normative reference to an Informational RFC: RFC 7435 ** Downref: Normative reference to an Informational RFC: RFC 7489 Summary: 8 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). 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: November 4, 2017 Comcast, Inc 6 B. Ramakrishnan 7 Yahoo!, Inc 8 J. Jones 9 Microsoft, Inc 10 M. Risher 11 Google, Inc 12 May 3, 2017 14 SMTP TLS Reporting 15 draft-ietf-uta-smtp-tlsrpt-05 17 Abstract 19 A number of protocols exist for establishing encrypted channels 20 between SMTP Mail Transfer Agents, including STARTTLS [RFC3207], DANE 21 [RFC6698], and MTA-STS (TODO: Add ref). These protocols can fail due 22 to misconfiguration or active attack, leading to undelivered messages 23 or delivery over unencrypted or unauthenticated channels. This 24 document describes a reporting mechanism and format by which sending 25 systems can share statistics and specific information about potential 26 failures with recipient domains. Recipient domains can then use this 27 information to both detect potential attackers and diagnose 28 unintentional 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 November 4, 2017. 47 Copyright Notice 49 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Related Technologies . . . . . . . . . . . . . . . . . . . . 4 67 3. Reporting Policy . . . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Example Reporting Policy . . . . . . . . . . . . . . . . 5 69 3.1.1. Report using MAILTO . . . . . . . . . . . . . . . . . 5 70 3.1.2. Report using HTTPS . . . . . . . . . . . . . . . . . 6 71 4. Reporting Schema . . . . . . . . . . . . . . . . . . . . . . 6 72 4.1. Report Time-frame . . . . . . . . . . . . . . . . . . . . 7 73 4.2. Delivery Summary . . . . . . . . . . . . . . . . . . . . 7 74 4.2.1. Success Count . . . . . . . . . . . . . . . . . . . . 7 75 4.2.2. Failure Count . . . . . . . . . . . . . . . . . . . . 7 76 4.3. Result Types . . . . . . . . . . . . . . . . . . . . . . 7 77 4.3.1. Negotiation Failures . . . . . . . . . . . . . . . . 7 78 4.3.2. Policy Failures . . . . . . . . . . . . . . . . . . . 8 79 4.3.3. General Failures . . . . . . . . . . . . . . . . . . 8 80 4.3.4. Transient Failures . . . . . . . . . . . . . . . . . 8 81 5. Report Delivery . . . . . . . . . . . . . . . . . . . . . . . 9 82 5.1. Report Filename . . . . . . . . . . . . . . . . . . . . . 9 83 5.2. Compression . . . . . . . . . . . . . . . . . . . . . . . 9 84 5.3. Email Transport . . . . . . . . . . . . . . . . . . . . . 10 85 5.4. HTTPS Transport . . . . . . . . . . . . . . . . . . . . . 10 86 5.5. Delivery Retry . . . . . . . . . . . . . . . . . . . . . 11 87 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 88 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 89 8. Appendix 1: Example Reporting Policy . . . . . . . . . . . . 12 90 8.1. Report using MAILTO . . . . . . . . . . . . . . . . . . . 12 91 8.2. Report using HTTPS . . . . . . . . . . . . . . . . . . . 12 92 9. Appendix 2: JSON Report Schema . . . . . . . . . . . . . . . 12 93 10. Appendix 3: Example JSON Report . . . . . . . . . . . . . . . 15 94 11. Normative References . . . . . . . . . . . . . . . . . . . . 16 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 97 1. Introduction 99 The STARTTLS extension to SMTP [RFC3207] allows SMTP clients and 100 hosts to establish secure SMTP sessions over TLS. The protocol 101 design is based on "Opportunistic Security" (OS) [RFC7435], which 102 maintains interoperability with clients that do not support STARTTLS 103 but means that any attacker who can delete parts of the SMTP session 104 (such as the "250 STARTTLS" response) or redirect the entire SMTP 105 session (perhaps by overwriting the resolved MX record of the 106 delivery domain) can perform a downgrade or interception attack. 108 Because such "downgrade attacks" are not necessarily apparent to the 109 receiving MTA, this document defines a mechanism for sending domains 110 to report on failures at multiple stages of the MTA-to-MTA 111 conversation. 113 Recipient domains may also use the mechanisms defined by MTA-STS 114 (TODO: Add ref) or DANE [RFC6698] to publish additional encryption 115 and authentication requirements; this document defines a mechanism 116 for sending domains that are compatible with MTA-STS or DANE to share 117 success and failure statistics with recipient domains. 119 Specifically, this document defines a reporting schema that covers 120 failures in routing, STARTTLS negotiation, and both DANE [RFC6698] 121 and MTA-STS (TODO: Add ref) policy validation errors, and a standard 122 TXT record that recipient domains can use to indicate where reports 123 in this format should be sent. 125 This document is intended as a companion to the specification for 126 SMTP MTA Strict Transport Security (MTA-STS, TODO: Add ref). 128 1.1. Terminology 130 The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, 131 SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this 132 document, are to be interpreted as described in [RFC2119]. 134 We also define the following terms for further use in this document: 136 o MTA-STS Policy: A definition of the expected TLS availability, 137 behavior, and desired actions for a given domain when a sending 138 MTA encounters problems in negotiating a secure channel. MTA-STS 139 is defined in [TODO] 141 o DANE Policy: A mechanism by which administrators can supply a 142 record that can be used to validate the certificate presented by 143 an MTA. DANE is defined in [RFC6698]. 145 o TLSRPT Policy: A policy specifying the endpoint to which sending 146 MTAs should deliver reports. 148 o Policy Domain: The domain against which an MTA-STS or DANE Policy 149 is defined. 151 o Sending MTA: The MTA initiating the delivery of an email message. 153 2. Related Technologies 155 o This document is intended as a companion to the specification for 156 SMTP MTA Strict Transport Security (MTA-STS, TODO: Add ref). 158 o SMTP-TLSRPT defines a mechanism for sending domains that are 159 compatible with MTA-STS or DANE to share success and failure 160 statistics with recipient domains. DANE is defined in [RFC6698] 161 and MTA-STS is defined in [TODO] 163 3. Reporting Policy 165 A domain publishes a record to its DNS indicating that it wishes to 166 receive reports. These SMTP TLSRPT policies are distributed via DNS 167 from the Policy Domain's zone, as TXT records (similar to DMARC 168 policies) under the name "_smtp-tlsrpt". For example, for the Policy 169 Domain "example.com", the recipient's TLSRPT policy can be retrieved 170 from "_smtp-tlsrpt.example.com". 172 Policies consist of the following directives: 174 o "v": This value MUST be equal to "TLSRPTv1". 176 o "rua": A URI specifying the endpoint to which aggregate 177 information about policy failures should be sent (see Section 4, 178 "Reporting Schema", for more information). Two URI schemes are 179 supported: "mailto" and "https". 181 o In the case of "https", reports should be submitted via POST 182 ([RFC2818]) to the specified URI. 184 o In the case of "mailto", reports should be submitted to the 185 specified email address ([RFC6068]). When sending failure reports 186 via SMTP, sending MTAs MUST deliver reports despite any TLS- 187 related failures. This may mean that the reports are delivered in 188 the clear. 190 The formal definition of the "_smtp-tlsrpt" TXT record, defined using 191 [RFC5234], is as follows: 193 tlsrpt-record = tlsrpt-version *WSP field-delim *WSP tlsrpt-rua 194 [field-delim [tlsrpt-extensions]] 196 field-delim = %x3B ; ";" 198 tlsrpt-version = %x76 *WSP "=" *WSP %x54 %x4C %x53 %x52 199 %x50 %x54 %x76 %x31 ; "v=TSRPTv1" 201 tlsrpt-rua = %x72 %x75 %x61 *WSP "=" *WSP tlsrpt-uri ; "rua=..." 203 tlsrpt-uri = URI 204 ; "URI" is imported from [@!RFC3986]; commas (ASCII 205 ; 0x2C) and exclamation points (ASCII 0x21) 206 ; MUST be encoded; the numeric portion MUST fit 207 ; within an unsigned 64-bit integer 209 tlsrpt-extensions = tlsrpt-extension *(field-delim tlsrpt-extension) 210 [field-delim] 211 ; extension fields 213 tlsrpt-extension = tlsrpt-ext-name *WSP "=" *WSP tlsrpt-ext-value 215 tlsrpt-ext-name = (ALPHA / DIGIT) *31(ALPHA / DIGIT / "_" / "-" / ".") 217 tlsrpt-ext-value = 1*(%x21-3A / %x3C / %x3E-7E) ; chars excluding 218 ; "=", ";", SP, and 219 ; control chars 221 If multiple TXT records for "_smtp-tlsrpt" are returned by the 222 resolver, records which do not begin with "v=TLSRPTv1;" are 223 discarded. If the number of resulting records is not one, senders 224 MUST assume the recipient domain does not implement TLSRPT. Parsers 225 MUST accept TXT records which are syntactically valid (i.e. valid 226 key-value pairs seprated by semi-colons) and implementing a superset 227 of this specification, in which case unknown fields SHALL be ignored. 229 3.1. Example Reporting Policy 231 3.1.1. Report using MAILTO 233 _smtp-tlsrpt.example.com. IN TXT \ 234 "v=TLSRPTv1;rua=mailto:reports@example.com" 236 3.1.2. Report using HTTPS 238 _smtp-tlsrpt.example.com. IN TXT \ 239 "v=TLSRPTv1; \ 240 rua=https://reporting.example.com/v1/tlsrpt" 242 4. Reporting Schema 244 The report is composed as a plain text file encoded in the JSON 245 format ([RFC7159]). 247 Aggregate reports contain the following fields: 249 o Report metadata: 251 * The organization responsible for the report 253 * Contact information for one or more responsible parties for the 254 contents of the report 256 * A unique identifier for the report 258 * The reporting date range for the report 260 o Policy, consisting of: 262 * One of the following policy types: (1) The MTA-STS policy 263 applied (as a string) (2) The DANE TLSA record applied (as a 264 string, with each RR entry of the RRset listed and separated by 265 a semicolon) (3) The literal string "no-policy-found", if 266 neither a TLSA nor MTA-STS policy could be found. 268 * The domain for which the policy is applied 270 * The MX host 272 * An identifier for the policy (where applicable) 274 o Aggregate counts, comprising result type, sending MTA IP, 275 receiving MTA hostname, session count, and an optional additional 276 information field containing a URI for recipients to review 277 further information on a failure type. 279 Note that the failure types are non-exclusive; an aggregate report 280 may contain overlapping "counts" of failure types when a single send 281 attempt encountered multiple errors. 283 4.1. Report Time-frame 285 The report SHOULD cover a full day, from 0000-2400 UTC. This should 286 allow for easier correlation of failure events. 288 4.2. Delivery Summary 290 4.2.1. Success Count 292 o "success-count": This indicates that the sending MTA was able to 293 successfully negotiate a policy-compliant TLS connection, and 294 serves to provide a "heartbeat" to receiving domains that 295 reporting is functional and tabulating correctly. This field 296 contains an aggregate count of successful connections for the 297 reporting system. 299 4.2.2. Failure Count 301 o "failure-count": This indicates that the sending MTA was unable to 302 successfully establish a connection with the receiving platform. 303 Section 4.3, "Result Types", will elaborate on the failed 304 negotiation attempts. This field contains an aggregate count of 305 failed connections. 307 4.3. Result Types 309 The list of result types will start with the minimal set below, and 310 is expected to grow over time based on real-world experience. The 311 initial set is: 313 4.3.1. Negotiation Failures 315 o "starttls-not-supported": This indicates that the recipient MX did 316 not support STARTTLS. 318 o "certificate-host-mismatch": This indicates that the certificate 319 presented did not adhere to the constraints specified in the MTA- 320 STS or DANE policy, e.g. if the MX does not match any identities 321 listed in the Subject Alternate Name (SAN) [RFC5280]. 323 o "certificate-expired": This indicates that the certificate has 324 expired. 326 o "certificate-not-trusted": This a label that covers multiple 327 certificate related failures that include, but not limited to 328 errors such as untrusted/unknown CAs, certificate name 329 constraints, certificate chain errors etc. When using this 330 declaration, the reporting MTA SHOULD utilize the "failure-reason" 331 to provide more information to the receiving entity. 333 o "validation-failure": This indicates a general failure for a 334 reason not matching a category above. When using this 335 declaration, the reporting MTA SHOULD utilize the "failure-reason" 336 to provide more information to the receiving entity. 338 4.3.2. Policy Failures 340 4.3.2.1. DANE-specific Policy Failures 342 o "tlsa-invalid": This indicates a validation error in the TLSA 343 record associated with a DANE policy. None of the records in the 344 RRset were found to be valid. 346 o "dnssec-invalid": This would indicate that no valid records were 347 returned from the recursive resolver. The request returned with 348 SERVFAIL for the requested TLSA record. 350 4.3.2.2. MTA-STS-specific Policy Failures 352 o "sts-invalid": This indicates a validation error for the overall 353 MTA-STS policy. 355 o "webpki-invalid": This indicates that the MTA-STS policy could not 356 be authenticated using PKIX validation. 358 4.3.3. General Failures 360 When a negotiation failure can not be categorized into one of the 361 "Negotiation Failures" stated above, the reporter SHOULD use the 362 "validation-failure" category. As TLS grows and becomes more 363 complex, new mechanisms may not be easily categorized. This allows 364 for a generic feedback category. When this category is used, the 365 reporter SHOULD also use the "failure-reason-code" to give some 366 feedback to the receiving entity. This is intended to be a short 367 text field, and the contents of the field should be an error code or 368 error text, such as "X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION". 370 4.3.4. Transient Failures 372 Transient errors due to too-busy network, TCP timeouts, etc. are not 373 required to be reported. 375 5. Report Delivery 377 Reports can be delivered either as an email message via SMTP or via 378 HTTP POST. 380 5.1. Report Filename 382 The filename is typically constructed using the following ABNF: 384 filename = sender "!" policy-domain "!" begin-timestamp 385 "!" end-timestamp [ "!" unique-id ] "." extension 387 unique-id = 1*(ALPHA / DIGIT) 389 sender = domain ; imported from [@!RFC5322] 391 policy-domain = domain 393 begin-timestamp = 1*DIGIT 394 ; seconds since 00:00:00 UTC January 1, 1970 395 ; indicating start of the time range contained 396 ; in the report 398 end-timestamp = 1*DIGIT 399 ; seconds since 00:00:00 UTC January 1, 1970 400 ; indicating end of the time range contained 401 ; in the report 403 extension = "json" / "json.gz" 405 The extension MUST be "json" for a plain JSON file, or "json.gz" for 406 a JSON file compressed using GZIP. 408 "unique-id" allows an optional unique ID generated by the Sending MTA 409 to distinguish among multiple reports generated simultaneously by 410 different sources within the same Policy Domain. For example, this 411 is a possible filename for the gzip file of a report to the Policy 412 Domain "example.net" from the Sending MTA "mail.sender.example.com": 414 `mail.sender.example.com!example.net!1470013207!1470186007!001.json.gz` 416 5.2. Compression 418 The report SHOULD be subjected to GZIP compression for both email and 419 HTTPS transport. Declining to apply compression can cause the report 420 to be too large for a receiver to process (a commonly observed 421 receiver limit is ten megabytes); compressing the file increases the 422 chances of acceptance of the report at some compute cost. 424 5.3. Email Transport 426 The report MAY be delivered by email. No specific MIME message 427 structure is required. It is presumed that the aggregate reporting 428 address will be equipped to extract MIME parts with the prescribed 429 media type and filename and ignore the rest. 431 If compressed, the report should use the media type "application/ 432 gzip" if compressed (see [RFC6713]), and "application/json" 433 otherwise. 435 The [RFC5322].Subject field for individual report submissions SHOULD 436 conform to the following ABNF: 438 tlsrpt-subject = %x52.65.70.6f.72.74 1*FWS ; "Report" 439 %x44.6f.6d.61.69.6e.3a 1*FWS ; "Domain:" 440 domain-name 1*FWS ; from RFC 6376 441 %x53.75.62.6d.69.74.74.65.72.3a ; "Submitter:" 442 1*FWS domain-name 1*FWS 443 %x52.65.70.6f.72.74.2d.49.44.3a ; "Report-ID:" 444 msg-id ; from RFC 5322 446 The first domain-name indicates the DNS domain name about which the 447 report was generated. The second domain-name indicates the DNS 448 domain name representing the Sending MTA generating the report. The 449 purpose of the Report-ID: portion of the field is to enable the 450 Policy Domain to identify and ignore duplicate reports that might be 451 sent by a Sending MTA. 453 For instance, this is a possible Subject field for a report to the 454 Policy Domain "example.net" from the Sending MTA 455 "mail.sender.example.com". It is line-wrapped as allowed by 456 [RFC5322]: 458 Subject: Report Domain: example.net 459 Submitter: mail.sender.example.com 460 Report-ID: <735ff.e317+bf22029@mailexample.net> 462 Note that, when sending failure reports via SMTP, sending MTAs MUST 463 NOT honor MTA-STS or DANE TLSA failures. 465 5.4. HTTPS Transport 467 The report MAY be delivered by POST to HTTPS. If compressed, the 468 report should use the media type "application/gzip" (see [RFC6713]), 469 and "application/json" otherwise. 471 5.5. Delivery Retry 473 In the event of a delivery failure, regardless of the delivery 474 method, a sender SHOULD attempt redelivery for up to 24hrs after the 475 initial attempt. As previously stated the reports are optional, so 476 while it is ideal to attempt redelivery, it is not required. If 477 multiple retries are attempted, they should be on a logarithmic 478 scale. 480 6. IANA Considerations 482 There are no IANA considerations at this time. 484 7. Security Considerations 486 SMTP TLS Reporting provides transparency into misconfigurations or 487 attempts to intercept or tamper with mail between hosts who support 488 STARTTLS. There are several security risks presented by the 489 existence of this reporting channel: 491 o Flooding of the Aggregate report URI (rua) endpoint: An attacker 492 could flood the endpoint and prevent the receiving domain from 493 accepting additional reports. This type of Denial-of-Service 494 attack would limit visibility into STARTTLS failures, leaving the 495 receiving domain blind to an ongoing attack. 497 o Untrusted content: An attacker could inject malicious code into 498 the report, opening a vulnerability in the receiving domain. 499 Implementers are advised to take precautions against evaluating 500 the contents of the report. 502 o Report snooping: An attacker could create a bogus TLSRPT record to 503 receive statistics about a domain the attacker does not own. 504 Since an attacker able to poison DNS is already able to receive 505 counts of SMTP connections (and, absent DANE or MTA-STS policies, 506 actual SMTP message payloads), this does not present a significant 507 new vulnerability. 509 o Reports as DDoS: TLSRPT allows specifying destinations for the 510 reports that are outside the authority of the Policy Domain, which 511 allows domains to delegate processing of reports to a partner 512 organization. However, an attacker who controls the Policy Domain 513 DNS could also use this mechanism to direct the reports to an 514 unwitting victim, flooding that victim with excessive reports. 515 DMARC [RFC7489] defines an elegant solution for verifying 516 delegation; however, since the attacker had less ability to 517 generate large reports than with DMARC failures, and since the 518 reports are generated by the sending MTA, such a delegation 519 mechanism is left for a future version of this specification. 521 8. Appendix 1: Example Reporting Policy 523 8.1. Report using MAILTO 525 _smtp-tlsrpt.mail.example.com. IN TXT \ 526 "v=TLSRPTv1;rua=mailto:reports@example.com" 528 8.2. Report using HTTPS 530 _smtp-tlsrpt.mail.example.com. IN TXT \ 531 "v=TLSRPTv1; \ 532 rua=https://reporting.example.com/v1/tlsrpt" 534 9. Appendix 2: JSON Report Schema 536 The JSON schema is derived from the HPKP JSON schema [RFC7469] (cf. 537 Section 3) 538 { 539 "organization-name": organization-name, 540 "date-range": { 541 "start-datetime": date-time, 542 "end-datetime": date-time 543 }, 544 "contact-info": email-address, 545 "report-id": report-id, 546 "policy": { 547 "policy-type": policy-type, 548 "policy-string": policy-string, 549 "policy-domain": domain, 550 "mx-host": mx-host-pattern 551 }, 552 "summary": { 553 "success-aggregate": total-successful-session-count, 554 "failure-aggregate:" total-failure-session-count 555 } 556 "failure-details": [ 557 { 558 "result-type": result-type, 559 "sending-mta-ip": ip-address, 560 "receiving-mx-hostname": receiving-mx-hostname, 561 "receiving-mx-helo": receiving-mx-helo, 562 "session-count": failed-session-count, 563 "additional-information": additional-info-uri, 564 "failure-reason-code": "Text body" 565 } 566 ] 567 } 569 Figure: JSON Report Format 571 o "organization-name": The name of the organization responsible for 572 the report. It is provided as a string. 574 o "date-time": The date-time indicates the start- and end-times for 575 the report range. It is provided as a string formatted according 576 to Section 5.6, "Internet Date/Time Format", of [RFC3339]. The 577 report should be for a full UTC day, 0000-2400. 579 o "email-address": The contact information for a responsible party 580 of the report. It is provided as a string formatted according to 581 Section 3.4.1, "Addr-Spec", of [RFC5322]. 583 o "report-id": A unique identifier for the report. Report authors 584 may use whatever scheme they prefer to generate a unique 585 identifier. It is provided as a string. 587 o "policy-type": The type of policy that was applied by the sending 588 domain. Presently, the only three valid choices are "tlsa", 589 "sts", and the literal string "no-policy-found". It is provided 590 as a string. 592 o "policy-string": The JSON string serialization ([RFC7159] section 593 7) of the policy, whether TLSA record ([RFC6698] section 2.3) or 594 MTA-STS policy. 596 o "domain": The Policy Domain is the domain against which the MTA- 597 STS or DANE policy is defined. 599 o "mx-host-pattern": The pattern of MX hostnames from the applied 600 policy. It is provided as a string, and is interpreted in the 601 same manner as the "Checking of Wildcard Certificates" rules in 602 Section 6.4.3 of [RFC6125]. 604 o "result-type": A value from Section 4.3, "Result Types", above. 606 o "ip-address": The IP address of the sending MTA that attempted the 607 STARTTLS connection. It is provided as a string representation of 608 an IPv4 or IPv6 address in dot-decimal or colon-hexadecimal 609 notation. 611 o "receiving-mx-hostname": The hostname of the receiving MTA MX 612 record with which the sending MTA attempted to negotiate a 613 STARTTLS connection. 615 o "receiving-mx-helo": (optional) The HELO or EHLO string from the 616 banner announced during the reported session. 618 o "success-aggregate": The aggregate number (integer) of 619 successfully negotiated TLS-enabled connections to the receiving 620 site. 622 o "failure-aggregate": The aggregate number (integer) of failures to 623 negotiate an TLS-enabled connection to the receiving site. 625 o "session-count": The number of (attempted) sessions that match the 626 relevant "result-type" for this section. 628 o "additional-info-uri": An optional URI pointing to additional 629 information around the relevant "result-type". For example, this 630 URI might host the complete certificate chain presented during an 631 attempted STARTTLS session. 633 o "failure-reason-code": A text field to include an TLS-related 634 error code or error message. 636 10. Appendix 3: Example JSON Report 638 { 639 "organization-name": "Company-X", 640 "date-range": { 641 "start-datetime": "2016-04-01T00:00:00Z", 642 "end-datetime": "2016-04-01T23:59:59Z" 643 }, 644 "contact-info": "sts-reporting@company-x.com", 645 "report-id": "5065427c-23d3-47ca-b6e0-946ea0e8c4be", 646 "policy": { 647 "policy-type": "sts", 648 "policy-string": "{ \"version\": \"STSv1\",\"mode\": \"report\", \"mx\": [\"*.mail.company-y.com\"], \"max_age\": 86400 }", 649 "policy-domain": "company-y.com", 650 "mx-host": "*.mail.company-y.com" 651 }, 652 "summary": { 653 "success-aggregate": 5326, 654 "failure-aggregate": 303 655 } 656 "failure-details": [{ 657 "result-type": "certificate-expired", 658 "sending-mta-ip": "98.136.216.25", 659 "receiving-mx-hostname": "mx1.mail.company-y.com", 660 "session-count": 100 661 }, { 662 "result-type": "starttls-not-supported", 663 "sending-mta-ip": "98.22.33.99", 664 "receiving-mx-hostname": "mx2.mail.company-y.com", 665 "session-count": 200, 666 "additional-information": "hxxps://reports.company-x.com/ 667 report_info?id=5065427c-23d3#StarttlsNotSupported" 668 }, { 669 "result-type: "validation-failure", 670 "sending-mta-ip": "47.97.15.2", 671 "receiving-mx-hostname: "mx-backup.mail.company-y.com", 672 "session-count": 3, 673 "failure-error-code": "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED" 674 }] 675 } 677 Figure: Example JSON report for a messages from Company-X to 678 Company-Y, where 100 sessions were attempted to Company Y servers 679 with an expired certificate and 200 sessions were attempted to 680 Company Y servers that did not successfully respond to the "STARTTLS" 681 command. Additionally 3 sessions failed due to 682 "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED". 684 11. Normative References 686 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 687 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 688 RFC2119, March 1997, 689 . 691 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ 692 RFC2818, May 2000, 693 . 695 [RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP over 696 Transport Layer Security", RFC 3207, DOI 10.17487/RFC3207, 697 February 2002, . 699 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 700 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 701 . 703 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 704 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 705 RFC5234, January 2008, 706 . 708 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 709 10.17487/RFC5322, October 2008, 710 . 712 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 713 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, 714 . 716 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 717 Verification of Domain-Based Application Service Identity 718 within Internet Public Key Infrastructure Using X.509 719 (PKIX) Certificates in the Context of Transport Layer 720 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 721 2011, . 723 [RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication 724 of Named Entities (DANE) Transport Layer Security (TLS) 725 Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August 726 2012, . 728 [RFC6713] Levine, J., "The 'application/zlib' and 'application/gzip' 729 Media Types", RFC 6713, DOI 10.17487/RFC6713, August 2012, 730 . 732 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 733 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 734 2014, . 736 [RFC7435] Dukhovni, V., "Opportunistic Security: Some Protection 737 Most of the Time", RFC 7435, DOI 10.17487/RFC7435, 738 December 2014, . 740 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 741 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 742 2015, . 744 [RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based 745 Message Authentication, Reporting, and Conformance 746 (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015, 747 . 749 Authors' Addresses 751 Daniel Margolis 752 Google, Inc 754 Email: dmargolis (at) google.com 756 Alexander Brotman 757 Comcast, Inc 759 Email: alex_brotman (at) comcast.com 761 Binu Ramakrishnan 762 Yahoo!, Inc 764 Email: rbinu (at) yahoo-inc (dot com) 766 Janet Jones 767 Microsoft, Inc 769 Email: janet.jones (at) microsoft (dot com) 771 Mark Risher 772 Google, Inc 774 Email: risher (at) google (dot com)