├── .gitattributes ├── LICENSE ├── Makefile ├── README.md ├── git-merge-keep-theirs.sh ├── mta-sts.md ├── mta-sts.txt ├── mta-sts.xml ├── reporting.md ├── reporting.txt └── reporting.xml /.gitattributes: -------------------------------------------------------------------------------- 1 | reporting.txt -diff 2 | reporting.xml -diff 3 | mta-sts.txt -diff 4 | mta-sts.xml -diff 5 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | 203 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | MMARK=mmark 2 | XML2RFC=xml2rfc 3 | SOURCES=mta-sts.md reporting.md 4 | XML=$(SOURCES:.md=.xml) 5 | TXT=$(SOURCES:.md=.txt) 6 | 7 | all: $(XML) $(TXT) 8 | 9 | %.xml : %.md 10 | $(MMARK) -xml2 -page $< > $@ 11 | 12 | %.txt : %.xml 13 | $(XML2RFC) $< --text $@ 14 | 15 | clean: 16 | rm $(XML) 17 | rm $(TXT) 18 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # SMTP Strict Transport Security and TLS Reporting 2 | 3 | Working drafts for https://datatracker.ietf.org/doc/draft-ietf-uta-mta-sts/ and https://datatracker.ietf.org/doc/draft-ietf-uta-smtp-tlsrpt/ 4 | 5 | ## Contributing 6 | 7 | Be aware that all contributions to the specification fall under the "NOTE WELL" 8 | terms outlined below. 9 | 10 | * Questions and larger design issues: Email the authors and/or the IETF [UTA 11 | mailing list](https://www.ietf.org/mailman/listinfo/uta). 12 | * Editorial suggestions: Fork the repository and submit a pull request, or open 13 | an issue on Github. 14 | 15 | ## Editing and Building 16 | 17 | The RFC XML and TXT files are generated from the master Markdown documents 18 | `mta-sts.md` and `reporting.md`. Please make all edits in those master documents, 19 | then regenerate the formatted files by running `make`. 20 | 21 | The Makefile depends upon [mmark](https://github.com/miekg/mmark) and 22 | [xml2rfc](https://pypi.python.org/pypi/xml2rfc/). 23 | 24 | ## NOTE WELL 25 | 26 | Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor 27 | for publication as all or part of an IETF Internet-Draft or RFC and any 28 | statement made within the context of an IETF activity is considered an "IETF 29 | Contribution". Such statements include oral statements in IETF sessions, as 30 | well as written and electronic communications made at any time or place, which 31 | are addressed to: 32 | 33 | * The IETF plenary session 34 | * The IESG, or any member thereof on behalf of the IESG 35 | * Any IETF mailing list, including the IETF list itself, any working group 36 | or design team list, or any other list functioning under IETF auspices 37 | * Any IETF working group or portion thereof 38 | * Any Birds of a Feather (BOF) session 39 | * The IAB or any member thereof on behalf of the IAB 40 | * The RFC Editor or the Internet-Drafts function 41 | * All IETF Contributions are subject to the rules of 42 | [RFC 5378](https://tools.ietf.org/html/rfc5378) and 43 | [RFC 3979](https://tools.ietf.org/html/rfc3979) 44 | (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). 45 | 46 | Statements made outside of an IETF session, mailing list or other function, 47 | that are clearly not intended to be input to an IETF activity, group or 48 | function, are not IETF Contributions in the context of this notice. 49 | 50 | Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 51 | 3979](https://tools.ietf.org/html/rfc3979) for details. 52 | 53 | A participant in any IETF activity is deemed to accept all IETF rules of 54 | process, as documented in Best Current Practices RFCs and IESG Statements. 55 | 56 | A participant in any IETF activity acknowledges that written, audio and video 57 | records of meetings may be made and may be available to the public. 58 | -------------------------------------------------------------------------------- /git-merge-keep-theirs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # I want to keep THEIR version when there is a conflict 3 | # Swap files: %A (the second parameter) contains my version 4 | cp -f $3 $2 5 | 6 | # Indicate the merge has been successfully "resolved" with the exit 7 | # status 8 | exit 0 9 | -------------------------------------------------------------------------------- /mta-sts.md: -------------------------------------------------------------------------------- 1 | %%% 2 | 3 | Title = "SMTP MTA Strict Transport Security (MTA-STS)" 4 | abbrev = "MTA-STS" 5 | category = "std" 6 | docName = "draft-ietf-uta-mta-sts-21" 7 | ipr = "trust200902" 8 | area = "Applications" 9 | workgroup = "Using TLS in Applications" 10 | keyword = [""] 11 | 12 | date = 2018-06-16T00:00:00Z 13 | 14 | [[author]] 15 | initials="D." 16 | surname="Margolis" 17 | fullname="Daniel Margolis" 18 | organization="Google, Inc" 19 | [author.address] 20 | email="dmargolis@google.com" 21 | [[author]] 22 | initials="M." 23 | surname="Risher" 24 | fullname="Mark Risher" 25 | organization="Google, Inc" 26 | [author.address] 27 | email="risher@google.com" 28 | [[author]] 29 | initials="B." 30 | surname="Ramakrishnan" 31 | fullname="Binu Ramakrishnan" 32 | organization="Yahoo!, Inc" 33 | [author.address] 34 | email="rbinu@yahoo-inc.com" 35 | [[author]] 36 | initials="A." 37 | surname="Brotman" 38 | fullname="Alexander Brotman" 39 | organization="Comcast, Inc" 40 | [author.address] 41 | email="alex_brotman@comcast.com" 42 | [[author]] 43 | initials="J." 44 | surname="Jones" 45 | fullname="Janet Jones" 46 | organization="Microsoft, Inc" 47 | [author.address] 48 | email="janet.jones@microsoft.com" 49 | 50 | %%% 51 | 52 | .# Abstract 53 | 54 | SMTP Mail Transfer Agent Strict Transport Security (MTA-STS) is a mechanism 55 | enabling mail service providers to declare their ability to receive Transport 56 | Layer Security (TLS) secure SMTP connections, and to specify whether sending 57 | SMTP servers should refuse to deliver to MX hosts that do not offer TLS with a 58 | trusted server certificate. 59 | 60 | 61 | {mainmatter} 62 | 63 | # Introduction 64 | 65 | The STARTTLS extension to SMTP [@!RFC3207] allows SMTP clients and hosts to 66 | negotiate the use of a TLS channel for encrypted mail transmission. 67 | 68 | While this opportunistic encryption protocol by itself provides a high barrier 69 | against passive man-in-the-middle traffic interception, any attacker who can 70 | delete parts of the SMTP session (such as the "250 STARTTLS" response) or who 71 | can redirect the entire SMTP session (perhaps by overwriting the resolved MX 72 | record of the delivery domain) can perform downgrade or interception attacks. 73 | 74 | This document defines a mechanism for recipient domains to publish policies, via 75 | a combination of DNS and HTTPS, specifying: 76 | 77 | * whether MTAs sending mail to this domain can expect PKIX-authenticated TLS 78 | support 79 | * what a conforming client should do with messages when TLS cannot be 80 | successfully negotiated 81 | 82 | ## Terminology 83 | 84 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 85 | "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 86 | document are to be interpreted as described in [BCP 14] [@!RFC2119] 87 | [@!RFC8174] when, and only when, they appear in all capitals, as shown here. 88 | 89 | We also define the following terms for further use in this document: 90 | 91 | * MTA-STS Policy: A commitment by the Policy Domain to support PKIX [@?RFC5280] 92 | authenticated TLS for the specified MX hosts. 93 | * Policy Domain: The domain for which an MTA-STS Policy is defined. This is the 94 | next-hop domain; when sending mail to "alice@example.com" this would 95 | ordinarily be "example.com", but this may be overridden by explicit routing 96 | rules (as described in (#policy-selection-for-smart-hosts-and-subdomains), 97 | "Policy Selection for Smart Hosts and Subdomains"). 98 | * Policy Host: The HTTPS host which serves the MTA-STS Policy for a Policy 99 | Domain. Rules for constructing the hostname are described in 100 | (#mtasts-policies), "MTA-STS Policies". 101 | * Sender: The SMTP Mail Transfer Agent sending an email message. 102 | * ABNF: Augmented Backus-Naur Form, a syntax for formally specifying syntax, 103 | defined in [@!RFC5234] and [@!RFC7405]. 104 | 105 | # Related Technologies 106 | 107 | The DANE TLSA record [@?RFC7672] is similar, in that DANE is also designed to 108 | upgrade unauthenticated encryption or plaintext transmission into authenticated, 109 | downgrade-resistant encrypted transmission. DANE requires DNSSEC [@?RFC4033] 110 | for authentication; the mechanism described here instead relies on certificate 111 | authorities (CAs) and does not require DNSSEC, at a cost of risking malicious 112 | downgrades. For a thorough discussion of this trade-off, see 113 | (#security-considerations), "Security Considerations". 114 | 115 | In addition, MTA-STS provides an optional testing-only mode, enabling soft 116 | deployments to detect policy failures; partial deployments can be achieved in 117 | DANE by deploying TLSA records only for some of a domain's MXs, but such a 118 | mechanism is not possible for the per-domain policies used by MTA-STS. 119 | 120 | The primary motivation of MTA-STS is to provide a mechanism for domains to 121 | ensure transport security even when deploying DNSSEC is undesirable or 122 | impractical. However, MTA-STS is designed not to interfere with DANE 123 | deployments when the two overlap; in particular, senders who implement MTA-STS 124 | validation MUST NOT allow a "valid" or "testing"-only MTA-STS validation to 125 | override a failing DANE validation. 126 | 127 | # Policy Discovery 128 | 129 | MTA-STS policies are distributed via HTTPS from a "well-known" [@!RFC5785] path 130 | served within the Policy Domain, and their presence and current version are 131 | indicated by a TXT record at the Policy Domain. These TXT records additionally 132 | contain a policy `id` field, allowing sending MTAs to check the currency of a 133 | cached policy without performing an HTTPS request. 134 | 135 | To discover if a recipient domain implements MTA-STS, a sender need only resolve 136 | a single TXT record. To see if an updated policy is available for a domain for 137 | which the sender has a previously cached policy, the sender need only check the 138 | TXT record's version `id` against the cached value. 139 | 140 | ## MTA-STS TXT Records 141 | 142 | The MTA-STS TXT record is a TXT record with the name `_mta-sts` at the Policy 143 | Domain. For the domain `example.com`, this record would be 144 | `_mta-sts.example.com`. MTA-STS TXT records MUST be US-ASCII, 145 | semicolon-separated key/value pairs containing the following fields: 146 | 147 | * `v`: (plain-text, required). Currently only "STSv1" is supported. 148 | * `id`: (plain-text, required). A short string used to track policy updates. 149 | This string MUST uniquely identify a given instance of a policy, such that 150 | senders can determine when the policy has been updated by comparing to the 151 | `id` of a previously seen policy. There is no implied ordering of `id` fields 152 | between revisions. 153 | 154 | An example TXT record is as below: 155 | 156 | _mta-sts.example.com. IN TXT "v=STSv1; id=20160831085700Z;" 157 | 158 | The formal definition of the `_mta-sts` TXT record, defined using ABNF 159 | ([@!RFC7405]), is as follows: 160 | 161 | sts-text-record = sts-version 1*(sts-field-delim sts-field) 162 | [sts-field-delim] 163 | 164 | sts-field = sts-id / ; Note that sts-id record 165 | sts-extension ; is required. 166 | 167 | sts-field-delim = *WSP ";" *WSP 168 | 169 | sts-version = %s"v=STSv1" 170 | 171 | sts-id = %s"id=" 1*32(ALPHA / DIGIT) ; id=... 172 | 173 | sts-extension = sts-ext-name "=" sts-ext-value ; name=value 174 | 175 | sts-ext-name = (ALPHA / DIGIT) 176 | *31(ALPHA / DIGIT / "_" / "-" / ".") 177 | 178 | sts-ext-value = 1*(%x21-3A / %x3C / %x3E-7E) 179 | ; chars excluding "=", ";", SP, and CTLs 180 | 181 | The TXT record MUST begin with sts-version field, and the order of other fields 182 | is not significant. If multiple TXT records for `_mta-sts` are returned by the 183 | resolver, records which do not begin with `v=STSv1;` are discarded. If the 184 | number of resulting records is not one, or if the resulting record is 185 | syntactically invalid, senders MUST assume the recipient domain does not 186 | have an available MTA-STS policy and skip the remaining steps of policy 187 | discovery. (Note that absence of a usable TXT record is not by itself 188 | sufficient to remove a sender's previously cached policy for the Policy Domain, 189 | as discussed in (#policy-application-control-flow), "Policy Application Control 190 | Flow".) If the resulting TXT record contains multiple strings, then the record 191 | MUST be treated as if those strings are concatenated together without adding 192 | spaces. 193 | 194 | ## MTA-STS Policies 195 | 196 | The policy itself is a set of key/value pairs (similar to [@?RFC5322] header 197 | fields) served via the HTTPS GET method from the fixed [@!RFC5785] "well-known" 198 | path of `.well-known/mta-sts.txt` served by the Policy Host. The Policy Host 199 | DNS name is constructed by prepending `mta-sts` to the Policy Domain. 200 | 201 | Thus for a Policy Domain of `example.com` the full URL is 202 | `https://mta-sts.example.com/.well-known/mta-sts.txt`. 203 | 204 | When fetching a policy, senders SHOULD validate that the media type is 205 | "text/plain" to guard against cases where webservers allow untrusted users to 206 | host non-text content (typically, HTML or images) at a user-defined path. All 207 | parameters other than charset=utf-8 or charset=us-ascii are ignored. Additional 208 | "Content-Type" parameters are also ignored. 209 | 210 | This resource contains the following CRLF-separated key/value pairs: 211 | 212 | * `version`: Currently only "STSv1" is supported. 213 | * `mode`: One of "enforce", "testing", or "none", indicating the expected 214 | behavior of a sending MTA in the case of a policy validation failure. See 215 | (#policy-application), "Policy Application." for more details about the three 216 | modes. 217 | * `max_age`: Max lifetime of the policy (plain-text non-negative integer 218 | seconds, maximum value of 31557600). Well-behaved clients SHOULD cache a 219 | policy for up to this value from last policy fetch time. To mitigate the 220 | risks of attacks at policy refresh time, it is expected that this value 221 | typically be in the range of weeks or greater. 222 | * `mx`: Allowed MX patterns. One or more patterns matching allowed MX hosts for 223 | the Policy Domain. As an example, 224 | 225 | ``` 226 | mx: mail.example.com 227 | mx: *.example.net 228 | ``` 229 | 230 | indicates that mail for this domain might be handled by MX `mail.example.com` 231 | or any MX at `example.net`. Valid patterns can be either fully specified 232 | names (`example.com`) or suffixes prefixed by a wildcard (`*.example.net`). 233 | If a policy specifies more than one MX, each MX MUST have its own `mx:` key, 234 | and each MX key/value pair MUST be on its own line in the policy file. In the 235 | case of Internationalized Domain Names ([@?RFC5891]), the `mx` value MUST 236 | specify the Punycode-encoded A-label [@!RFC3492] to match against, and not the 237 | Unicode-encoded U-label. The full semantics of certificate validation 238 | (including the use of wildcard patterns) are described in 239 | (#mx-host-validation), "MX Host Validation." 240 | 241 | An example policy is as below: 242 | 243 | ``` 244 | version: STSv1 245 | mode: enforce 246 | mx: mail.example.com 247 | mx: *.example.net 248 | mx: backupmx.example.com 249 | max_age: 604800 250 | ``` 251 | 252 | The formal definition of the policy resource, defined using [@!RFC7405], is as 253 | follows: 254 | 255 | sts-policy-record = sts-policy-field *WSP 256 | *(sts-policy-term sts-policy-field *WSP) 257 | [sts-policy-term] 258 | 259 | sts-policy-field = sts-policy-version / ; required once 260 | sts-policy-mode / ; required once 261 | sts-policy-max-age / ; required once 262 | 263 | sts-policy-term / 264 | ; required at least once, except when 265 | ; mode is "none" 266 | 267 | sts-policy-extension ; other fields 268 | 269 | sts-policy-field-delim = ":" *WSP 270 | 271 | sts-policy-version = sts-policy-version-field sts-policy-field-delim 272 | sts-policy-version-value 273 | 274 | sts-policy-version-field = %s"version" 275 | 276 | sts-policy-version-value = %s"STSv1" 277 | 278 | sts-policy-mode = sts-policy-mode-field sts-policy-field-delim 279 | sts-policy-mode-value 280 | 281 | sts-policy-mode-field = %s"mode" 282 | 283 | sts-policy-mode-value = %s"testing" / %s"enforce" / %s"none" 284 | 285 | sts-policy-mx = sts-policy-mx-field sts-policy-field-delim 286 | sts-policy-mx-value 287 | 288 | sts-policy-mx-field = %s"mx" 289 | 290 | sts-policy-mx-value = ["*."] Domain 291 | 292 | sts-policy-max-age = sts-policy-max-age-field sts-policy-field-delim 293 | sts-policy-max-age-value 294 | 295 | sts-policy-max-age-field = %s"max_age" 296 | 297 | sts-policy-max-age-value = 1*10(DIGIT) 298 | 299 | sts-policy-extension = sts-policy-ext-name ; additional 300 | sts-policy-field-delim ; extension 301 | sts-policy-ext-value ; fields 302 | 303 | sts-policy-ext-name = (sts-policy-alphanum) 304 | *31(sta-policy-alphanum / "_" / "-" / ".") 305 | 306 | sts-policy-term = LF / CRLF 307 | 308 | sts-policy-ext-value = sts-policy-vchar 309 | [*(%x20 / sts-policy-vchar) 310 | sts-policy-vchar] 311 | ; chars, including UTF-8 [@!RFC3629], 312 | ; excluding CTLs and no 313 | ; leading/trailing spaces 314 | 315 | sts-policy-alphanum = ALPHA / DIGIT 316 | 317 | sts-policy-vchar = %x21-7E / UTF8-2 / UTF8-3 / UTF8-4 318 | 319 | UTF8-2 = 320 | 321 | UTF8-3 = 322 | 323 | UTF8-4 = 324 | 325 | Domain = 326 | 327 | 328 | Parsers MUST accept TXT records and policy files which are syntactically valid 329 | (i.e., valid key/value pairs separated by semi-colons for TXT records), possibly 330 | containing additional key/value pairs not specified in this document, in which 331 | case unknown fields SHALL be ignored. If any non-repeated field--i.e., all 332 | fields excepting `mx`--is duplicated, all entries except for the first SHALL be 333 | ignored. 334 | 335 | ## HTTPS Policy Fetching 336 | 337 | Policy bodies are, as described above, retrieved by sending MTAs via HTTPS 338 | [@!RFC2818]. During the TLS handshake initiated to fetch a new or updated 339 | policy from the Policy Host, the Policy Host HTTPS server MUST present a X.509 340 | certificate which is valid for the `mta-sts` DNS-ID ([@?RFC6125]) (e.g., 341 | `mta-sts.example.com`) as described below, chain to a root CA that is trusted by 342 | the sending MTA, and be non-expired. It is expected that sending MTAs use a set 343 | of trusted CAs similar to those in widely deployed Web browsers and operating 344 | systems. See [@?RFC5280] for more details about certificate verification. 345 | 346 | The certificate is valid for the Policy Host (i.e., `mta-sts` prepended to the 347 | Policy Domain) with respect to the rules described in [@!RFC6125], with the 348 | following application-specific considerations: 349 | 350 | * Matching is performed only against the DNS-ID identifiers. 351 | 352 | * DNS domain names in server certificates MAY contain the wildcard character 353 | '\*' as the complete left-most label within the identifier. 354 | 355 | The certificate MAY be checked for revocation via the Online Certificate Status 356 | Protocol (OCSP) [@?RFC6960], certificate revocation lists (CRLs), or some other 357 | mechanism. 358 | 359 | Policies fetched via HTTPS are only valid if the HTTP response code is 200 (OK). 360 | HTTP 3xx redirects MUST NOT be followed, and HTTP caching (as specified in 361 | [@?RFC7234]) MUST NOT be used. 362 | 363 | Senders may wish to rate-limit the frequency of attempts to fetch the HTTPS 364 | endpoint even if a valid TXT record for the recipient domain exists. In the 365 | case that the HTTPS GET fails, implementers SHOULD limit further attempts to 366 | a period of five minutes or longer per version ID, to avoid overwhelming 367 | resource-constrained recipients with cascading failures. 368 | 369 | Senders MAY impose a timeout on the HTTPS GET and/or a limit on the maximum size 370 | of the response body to avoid long delays or resource exhaustion during 371 | attempted policy updates. A suggested timeout is one minute, and a suggested 372 | maximum policy size 64 kilobytes; policy hosts SHOULD respond to requests with a 373 | complete policy body within that timeout and size limit. 374 | 375 | If a valid TXT record is found but no policy can be fetched via HTTPS (for any 376 | reason), and there is no valid (non-expired) previously-cached policy, senders 377 | MUST continue with delivery as though the domain has not implemented MTA-STS. 378 | 379 | Conversely, if no "live" policy can be discovered via DNS or fetched via HTTPS, 380 | but a valid (non-expired) policy exists in the sender's cache, the sender MUST 381 | apply that cached policy. 382 | 383 | Finally, to mitigate the risk of persistent interference with policy refresh, as 384 | discussed in-depth in (#security-considerations), MTAs SHOULD proactively 385 | refresh cached policies before they expire; a suggested refresh frequency is 386 | once per day. To enable administrators to discover problems with policy 387 | refresh, MTAs SHOULD alert administrators (through the use of logs or similar) 388 | when such attempts fail, unless the cached policy mode is `none`. 389 | 390 | ## Policy Selection for Smart Hosts and Subdomains 391 | 392 | When sending mail via a "smart host"--an administratively configured 393 | intermediate SMTP relay, which is different from the message recipient's server 394 | as determined from DNS --compliant senders MUST treat the smart host domain as 395 | the policy domain for the purposes of policy discovery and application. This 396 | specification does not provide a means of associating policies with email 397 | addresses that employ Address Literals [@!RFC5321]. 398 | 399 | When sending mail to a mailbox at a subdomain, compliant senders MUST NOT 400 | attempt to fetch a policy from the parent zone. Thus for mail sent to 401 | "user@mail.example.com", the policy can be fetched only from "mail.example.com", 402 | not "example.com". 403 | 404 | # Policy Validation 405 | 406 | When sending to an MX at a domain for which the sender has a valid and 407 | non-expired MTA-STS policy, a sending MTA honoring MTA-STS MUST check whether: 408 | 409 | 1. At least one of the policy's "mx" patterns matches the selected MX host, 410 | as described in (#mx-host-validation), "MX Host Validation". 411 | 412 | 2. The recipient mail server supports STARTTLS and offers a PKIX-based TLS 413 | certificate, during TLS handshake, which is valid for that host, as described 414 | in (#recipient-mta-certificate-validation), "Recipient MTA Certificate 415 | Validation". 416 | 417 | When these conditions are not met, a policy is said to fail to validate. This 418 | section does not dictate the behavior of sending MTAs when the above conditions 419 | are not met; see (#policy-application), "Policy Application" for a description 420 | of sending MTA behavior when policy validation fails. 421 | 422 | ## MX Host Validation 423 | 424 | A receiving candidate MX host is valid according to an applied MTA-STS policy if 425 | the MX record name matches one or more of the `mx` fields in the applied policy. 426 | Matching is identical to the rules given in [@!RFC6125], with restriction that 427 | the wildcard character `*` may only be used to match the entire left-most label 428 | in the presented identifier. Thus the mx pattern `*.example.com` matches 429 | `mail.example.com` but not `example.com` or `foo.bar.example.com`. 430 | 431 | ## Recipient MTA Certificate Validation 432 | 433 | The certificate presented by the receiving MTA MUST not be expired, and MUST 434 | chain to a root CA that is trusted by the sending MTA. The certificate MUST 435 | have a subject alternative name (SAN, [@!RFC5280]) with a DNS-ID ([@?RFC6125]) 436 | matching the host name, per the rules given in [@!RFC6125]. The MX's 437 | certificate MAY also be checked for revocation via OCSP [@?RFC6960], CRLs 438 | [@?RFC6818], or some other mechanism. 439 | 440 | # Policy Application 441 | 442 | When sending to an MX at a domain for which the sender has a valid, non-expired 443 | MTA-STS policy, a sending MTA honoring MTA-STS applies the result of a policy 444 | validation failure one of two ways, depending on the value of the policy `mode` 445 | field: 446 | 447 | 1. `enforce`: In this mode, sending MTAs MUST NOT deliver the message to hosts 448 | which fail MX matching or certificate validation, or do not support STARTTLS. 449 | 450 | 2. `testing`: In this mode, sending MTAs which also implement the TLSRPT 451 | specification [@!I-D.ietf-uta-smtp-tlsrpt] merely send a report indicating 452 | policy application failures (so long as TLSRPT is also implemented by the 453 | recipient domain). 454 | 455 | 3. `none`: In this mode, sending MTAs should treat the policy domain as though 456 | it does not have any active policy; see (#removing-mtasts), "Removing 457 | MTA-STS", for use of this mode value. 458 | 459 | When a message fails to deliver due to an `enforce` policy, a compliant MTA MUST 460 | NOT permanently fail to deliver messages before checking, via DNS, for the 461 | presence of an updated policy at the Policy Domain. (In all cases, MTAs SHOULD 462 | treat such failures as transient errors and retry delivery later.) This allows 463 | implementing domains to update long-lived policies on the fly. 464 | 465 | ## Policy Application Control Flow 466 | 467 | An example control flow for a compliant sender consists of the following steps: 468 | 469 | 1. Check for a cached policy whose time-since-fetch has not exceeded its 470 | `max_age`. If none exists, attempt to fetch a new policy (perhaps 471 | asynchronously, so as not to block message delivery). Optionally, sending 472 | MTAs may unconditionally check for a new policy at this step. 473 | 2. For each candidate MX, in order of MX priority, attempt to deliver the 474 | message. If a policy is present with an `enforce` mode, when attempting to 475 | deliver to each candidate MX, ensure STARTTLS support and host identity 476 | validity as described in (#policy-validation), "Policy Validation". If a 477 | candidate fails validation, continue to the next candidate (if there is one). 478 | 3. A message delivery MUST NOT be permanently failed until the sender has first 479 | checked for the presence of a new policy (as indicated by the `id` field in 480 | the `_mta-sts` TXT record). If a new policy is not found, existing rules for 481 | the case of temporary message delivery failures apply (as discussed in 482 | [@!RFC5321] section 4.5.4.1). 483 | 484 | # Reporting Failures 485 | 486 | MTA-STS is intended to be used along with TLSRPT [@!I-D.ietf-uta-smtp-tlsrpt] in 487 | order to ensure implementing domains can detect cases of both benign and 488 | malicious failures, and to ensure that failures that indicate an active attack 489 | are discoverable. As such, senders who also implement TLSRPT SHOULD treat the 490 | following events as reportable failures: 491 | 492 | * HTTPS policy fetch failures when a valid TXT record is present. 493 | 494 | * Policy fetch failures of any kind when a valid policy exists in the policy 495 | cache, except if that policy's mode is `none`. 496 | 497 | * Delivery attempts in which a contacted MX does not support STARTTLS or does 498 | not present a certificate which validates according to the applied policy, 499 | except if that policy's mode is `none`. 500 | 501 | # Interoperability Considerations 502 | 503 | ## SNI Support 504 | 505 | To ensure that the server sends the right certificate chain, the SMTP client 506 | MUST have support for the TLS SNI extension [@!RFC6066]. When connecting to a 507 | HTTP server to retrieve the MTA-STS policy, the SNI extension MUST contain the 508 | name of the policy host (e.g., `mta-sts.example.com`). When connecting to an 509 | SMTP server, the SNI extension MUST contain the MX hostname. 510 | 511 | HTTP servers used to deliver MTA-STS policies MAY rely on SNI to determine which 512 | certificate chain to present to the client. HTTP servers MUST respond with a 513 | certificate chain that matches the policy hostname or abort the TLS handshake if 514 | unable to do so. Clients that do not send SNI information may not see the 515 | expected certificate chain. 516 | 517 | SMTP servers MAY rely on SNI to determine which certificate chain to present to 518 | the client. However servers that have one identity and a single matching 519 | certificate do not require SNI support. Servers MUST NOT enforce the use of SNI 520 | by clients, as the client may be using unauthenticated opportunistic TLS and may 521 | not expect any particular certificate from the server. If the client sends no 522 | SNI extension or sends an SNI extension for an unsupported server name, the 523 | server MUST simply send a fallback certificate chain of its choice. The reason 524 | for not enforcing strict matching of the requested SNI hostname is that MTA-STS 525 | TLS clients may be typically willing to accept multiple server names but can 526 | only send one name in the SNI extension. The server's fallback certificate may 527 | match a different name that is acceptable to the client, e.g., the original 528 | next-hop domain. 529 | 530 | ## Minimum TLS Version Support 531 | 532 | MTAs supporting MTA-STS MUST have support for TLS version 1.2 [@!RFC5246] or 533 | higher. The general TLS usage guidance in [@!RFC7525] SHOULD be followed. 534 | 535 | # Operational Considerations 536 | 537 | ## Policy Updates 538 | 539 | Updating the policy requires that the owner make changes in two places: the 540 | `_mta-sts` TXT record in the Policy Domain's DNS zone and at the corresponding 541 | HTTPS endpoint. As a result, recipients should expect a policy will continue to 542 | be used by senders until both the HTTPS and TXT endpoints are updated and the 543 | TXT record's TTL has passed. 544 | 545 | In other words, a sender who is unable to successfully deliver a message while 546 | applying a cache of the recipient's now-outdated policy may be unable to 547 | discover that a new policy exists until the DNS TTL has passed. Recipients 548 | SHOULD therefore ensure that old policies continue to work for message delivery 549 | during this period of time, or risk message delays. 550 | 551 | Recipients SHOULD also update the HTTPS policy body before updating the TXT 552 | record; this ordering avoids the risk that senders, seeing a new TXT record, 553 | mistakenly cache the old policy from HTTPS. 554 | 555 | ## Policy Delegation 556 | 557 | Domain owners commonly delegate SMTP hosting to a different organization, such 558 | as an ISP or a Web host. In such a case, they may wish to also delegate the 559 | MTA-STS policy to the same organization which can be accomplished with two 560 | changes. 561 | 562 | First, the Policy Domain must point the `_mta-sts` record, via CNAME, to the 563 | `_mta-sts` record maintained by the hosting organization. This allows the 564 | hosting organization to control update signaling. 565 | 566 | Second, the Policy Domain must point the "well-known" policy location to the 567 | hosting organization. This can be done either by setting the `mta-sts` record 568 | to an IP address or CNAME specified by the hosting organization and by giving 569 | the hosting organization a TLS certificate which is valid for that host, or by 570 | setting up a "reverse proxy" (also known as a "gateway") server that serves as 571 | the Policy Domain's policy the policy currently served by the hosting 572 | organization. 573 | 574 | For example, given a user domain `user.example` hosted by a mail provider 575 | `provider.example`, the following configuration would allow policy delegation: 576 | 577 | DNS: 578 | ~~~ 579 | _mta-sts.user.example. IN CNAME _mta-sts.provider.example. 580 | ~~~ 581 | 582 | Policy: 583 | ~~~ 584 | > GET /.well-known/mta-sts.txt Host: mta-sts.user.example 585 | < HTTP/1.1 200 OK # Response proxies content from 586 | # https://mta-sts.provider.example 587 | ~~~ 588 | 589 | Note that in all such cases, the policy endpoint 590 | (`https://mta-sts.user.example/.well-known/mta-sts.txt` in this example) must 591 | still present a certificate valid for the Policy Host (`mta-sts.user.example`), 592 | and not for that host at the provider's domain (`mta-sts.provider.example`). 593 | 594 | Note that while sending MTAs MUST NOT use HTTP caching when fetching policies 595 | via HTTPS, such caching may nonetheless be useful to a reverse proxy configured 596 | as described in this section. An HTTPS policy endpoint expecting to be proxied 597 | for multiple hosted domains--as with a large mail hosting provider or 598 | similar--may wish to indicate an HTTP Cache-Control `max-age` response directive 599 | (as specified in [@?RFC7234]) of 60 seconds as a reasonable value to save 600 | reverse proxies an unnecessarily high-rate of proxied policy fetching. 601 | 602 | ## Removing MTA-STS 603 | 604 | In order to facilitate clean opt-out of MTA-STS by implementing policy domains, 605 | and to distinguish clearly between failures which indicate attacks and those 606 | which indicate such opt-outs, MTA-STS implements the `none` mode, which allows 607 | validated policies to indicate authoritatively that the policy domain wishes to 608 | no longer implement MTA-STS and may, in the future, remove the MTA-STS TXT and 609 | policy endpoints entirely. 610 | 611 | A suggested workflow to implement such an opt out is as follows: 612 | 613 | 1. Publish a new policy with `mode` equal to `none` and a small `max_age` (e.g., 614 | one day). 615 | 2. Publish a new TXT record to trigger fetching of the new policy. 616 | 3. When all previously served policies have expired--normally this is the time 617 | the previously published policy was last served plus that policy's `max_age`, 618 | but note that older policies may have been served with a greater `max_age`, 619 | allowing overlapping policy caches--safely remove the TXT record and HTTPS 620 | endpoint. 621 | 622 | ## Preserving MX Candidate Traversal 623 | 624 | Implementors of send-time MTA-STS validation in mail transfer agents should take 625 | note of the risks of modifying the logic of traversing MX candidate lists. 626 | Because an MTA-STS policy can be used to prefilter invalid MX candidates from 627 | the MX candidate list, it is tempting to implement a "two-pass" model, where MX 628 | candidates are first filtered for possible validity according to the MTA-STS 629 | policy, and then the remaining candidates attempted in order as without an 630 | MTA-STS policy. This may lead to incorrect implementations, such a message 631 | loops; implementors are instead recommended to traverse the MX candidate list as 632 | usual, and treat invalid candidates as though they were unreachable (i.e., as 633 | though there were some transient error when trying to deliver to that 634 | candidate). 635 | 636 | One consequence of validating MX hosts in order of ordinary candidate traversal 637 | is that, in the event that a higher-priority MX is MTA-STS valid and a 638 | lower-priority MX is not, senders may never encounter the lower-priority MX, 639 | leading to a risk that policy misconfigurations that apply only to "backup" MXes 640 | may only be discovered in the case of primary MX failure. 641 | 642 | # IANA Considerations 643 | 644 | ## Well-Known URIs Registry 645 | 646 | A new "well-known" URI as described in (#policy-discovery) will be registered in 647 | the Well-Known URIs registry as described below: 648 | 649 | URI Suffix: mta-sts.txt Change Controller: IETF 650 | 651 | ## MTA-STS TXT Record Fields 652 | 653 | IANA is requested to create a new registry titled "MTA-STS TXT Record Fields". 654 | The initial entries in the registry are: 655 | 656 | Field Name | Description | Reference 657 | ------------|----------------|----------- 658 | v | Record version | (#mtasts-txt-records) of RFC XXX 659 | id | Policy instance ID | (#mtasts-txt-records) of RFC XXX 660 | 661 | New fields are added to this registry using IANA's "Expert Review" policy. 662 | 663 | ## MTA-STS Policy Fields 664 | 665 | IANA is requested to create a new registry titled "MTA-STS Policy Fields". The 666 | initial entries in the registry are: 667 | 668 | Field Name | Description | Reference 669 | ------------|----------------------|----------- 670 | version | Policy version | (#mtasts-policies) of RFC XXX 671 | mode | Enforcement behavior | (#mtasts-policies) of RFC XXX 672 | max_age | Policy lifetime | (#mtasts-policies) of RFC XXX 673 | mx | MX identities | (#mtasts-policies) of RFC XXX 674 | 675 | New fields are added to this registry using IANA's "Expert Review" 676 | policy. 677 | 678 | # Security Considerations 679 | 680 | SMTP MTA Strict Transport Security attempts to protect against an active 681 | attacker trying to intercept or tamper with mail between hosts that support 682 | STARTTLS. There are two classes of attacks considered: 683 | 684 | * Foiling TLS negotiation, for example by deleting the "250 STARTTLS" response 685 | from a server or altering TLS session negotiation. This would result in the 686 | SMTP session occurring over plaintext, despite both parties supporting TLS. 687 | 688 | * Impersonating the destination mail server, whereby the sender might deliver 689 | the message to an impostor, who could then monitor and/or modify messages 690 | despite opportunistic TLS. This impersonation could be accomplished by 691 | spoofing the DNS MX record for the recipient domain, or by redirecting client 692 | connections intended for the legitimate recipient server (for example, by 693 | altering BGP routing tables). 694 | 695 | MTA-STS can thwart such attacks only if the sender is able to previously obtain 696 | and cache a policy for the recipient domain, and only if the attacker is unable 697 | to obtain a valid certificate that complies with that policy. Below, we 698 | consider specific attacks on this model. 699 | 700 | ## Obtaining a Signed Certificate 701 | 702 | SMTP MTA-STS relies on certificate validation via PKIX based TLS identity 703 | checking [@?RFC6125]. Attackers who are able to obtain a valid certificate for 704 | the targeted recipient mail service (e.g., by compromising a certificate 705 | authority) are thus able to circumvent STS authentication. 706 | 707 | ## Preventing Policy Discovery 708 | 709 | Since MTA-STS uses DNS TXT records for policy discovery, an attacker who is able 710 | to block DNS responses can suppress the discovery of an MTA-STS Policy, making 711 | the Policy Domain appear not to have an MTA-STS Policy. The sender policy cache 712 | is designed to resist this attack by decreasing the frequency of policy 713 | discovery and thus reducing the window of vulnerability; it is nonetheless a 714 | risk that attackers who can predict or induce policy discovery--for example, by 715 | inducing a sending domain to send mail to a never-before-contacted recipient 716 | while carrying out a man-in-the-middle attack--may be able to foil policy 717 | discovery and effectively downgrade the security of the message delivery. 718 | 719 | Since this attack depends upon intercepting initial policy discovery, 720 | implementers SHOULD prefer policy `max_age` values to be as long as is 721 | practical. 722 | 723 | Because this attack is also possible upon refresh of a cached policy, 724 | implementors SHOULD NOT wait until a cached policy has expired before checking 725 | for an update; if senders attempt to refresh the cache regularly (for example, 726 | by fetching currently live policy in a background task that runs daily or 727 | weekly, regardless of the state of the `_mta-sts` TXT record, and updating their 728 | cache's "max age" accordingly), an attacker would have to foil policy discovery 729 | consistently over the lifetime of a cached policy to prevent a successful 730 | refresh. 731 | 732 | Additionally, MTAs SHOULD alert administrators to repeated policy refresh 733 | failures long before cached policies expire (through warning logs or similar 734 | applicable mechanisms), allowing administrators to detect such a persistent 735 | attack on policy refresh. (However, they should not implement such alerts if 736 | the cached policy has a `none` mode, to allow clean MTA-STS removal, as 737 | described in (#removing-mtasts).) 738 | 739 | Resistance to downgrade attacks of this nature--due to the ability to 740 | authoritatively determine "lack of a record" even for non-participating 741 | recipients--is a feature of DANE, due to its use of DNSSEC for policy discovery. 742 | 743 | ## Denial of Service 744 | 745 | We additionally consider the Denial of Service risk posed by an attacker who can 746 | modify the DNS records for a recipient domain. Absent MTA-STS, such an attacker 747 | can cause a sending MTA to cache invalid MX records, but only for however long 748 | the sending resolver caches those records. With MTA-STS, the attacker can 749 | additionally advertise a new, long-`max_age` MTA-STS policy with `mx` 750 | constraints that validate the malicious MX record, causing senders to cache the 751 | policy and refuse to deliver messages once the victim has resecured the MX 752 | records. 753 | 754 | This attack is mitigated in part by the ability of a victim domain to (at any 755 | time) publish a new policy updating the cached, malicious policy, though this 756 | does require the victim domain to both obtain a valid CA-signed certificate and 757 | to understand and properly configure MTA-STS. 758 | 759 | Similarly, we consider the possibility of domains that deliberately allow 760 | untrusted users to serve untrusted content on user-specified subdomains. In 761 | some cases (e.g., the service Tumblr.com) this takes the form of providing HTTPS 762 | hosting of user-registered subdomains; in other cases (e.g. dynamic DNS 763 | providers) this takes the form of allowing untrusted users to register custom 764 | DNS records at the provider's domain. 765 | 766 | In these cases, there is a risk that untrusted users would be able to serve 767 | custom content at the `mta-sts` host, including serving an illegitimate MTA-STS 768 | policy. We believe this attack is rendered more difficult by the need for the 769 | attacker to also serve the `_mta-sts` TXT record on the same domain--something 770 | not, to our knowledge, widely provided to untrusted users. This attack is 771 | additionally mitigated by the aforementioned ability for a victim domain to 772 | update an invalid policy at any future date. 773 | 774 | ## Weak Policy Constraints 775 | 776 | Even if an attacker cannot modify a served policy, the potential exists for 777 | configurations that allow attackers on the same domain to receive mail for that 778 | domain. For example, an easy configuration option when authoring an MTA-STS 779 | Policy for `example.com` is to set the `mx` equal to `*.example.com`; recipient 780 | domains must consider in this case the risk that any user possessing a valid 781 | hostname and CA-signed certificate (for example, `dhcp-123.example.com`) will, 782 | from the perspective of MTA-STS Policy validation, be a valid MX host for that 783 | domain. 784 | 785 | ## Compromise of the Web PKI System 786 | 787 | A host of risks apply to the PKI system used for certificate authentication, 788 | both of the `mta-sts` HTTPS host's certificate and the SMTP servers' 789 | certificates. These risks are broadly applicable within the Web PKI ecosystem 790 | and are not specific to MTA-STS; nonetheless, they deserve some consideration in 791 | this context. 792 | 793 | Broadly speaking, attackers may compromise the system by obtaining certificates 794 | under fraudulent circumstances (i.e., by impersonating the legitimate owner of 795 | the victim domain), by compromising a Certificate Authority or Delegate 796 | Authority's private keys, by obtaining a legitimate certificate issued to the 797 | victim domain, and similar. 798 | 799 | One approach commonly employed by Web browsers to help mitigate against some of 800 | these attacks is to allow for revocation of compromised or fraudulent 801 | certificates via OCSP [@?RFC6960] or CRLs [@?RFC6818]. Such mechanisms 802 | themselves represent tradeoffs and are not universally implemented; we 803 | nonetheless recommend implementors of MTA-STS to implement revocation mechanisms 804 | which are most applicable to their implementations. 805 | 806 | # Contributors 807 | 808 | Wei Chuang 809 | Google, Inc 810 | weihaw@google.com 811 | 812 | Viktor Dukhovni 813 | ietf-dane@dukhovni.de 814 | 815 | Markus Laber 816 | 1&1 Mail & Media Development & Technology GmbH 817 | markus.laber@1und1.de 818 | 819 | Nicolas Lidzborski 820 | Google, Inc 821 | nlidz@google.com 822 | 823 | Brandon Long 824 | Google, Inc 825 | blong@google.com 826 | 827 | Franck Martin 828 | LinkedIn, Inc 829 | fmartin@linkedin.com 830 | 831 | Klaus Umbach 832 | 1&1 Mail & Media Development & Technology GmbH 833 | klaus.umbach@1und1.de 834 | 835 | {backmatter} 836 | 837 | # MTA-STS example record & policy 838 | 839 | The owner of `example.com` wishes to begin using MTA-STS with a policy that will 840 | solicit reports from senders without affecting how the messages are processed, 841 | in order to verify the identity of MXs that handle mail for `example.com`, 842 | confirm that TLS is correctly used, and ensure that certificates presented by 843 | the recipient MX validate. 844 | 845 | MTA-STS policy indicator TXT RR: 846 | ~~~~~~~~~ 847 | _mta-sts.example.com. IN TXT "v=STSv1; id=20160831085700Z;" 848 | ~~~~~~~~~ 849 | 850 | MTA-STS Policy file served as the response body at 851 | `https://mta-sts.example.com/.well-known/mta-sts.txt`: 852 | ~~~~~~~~~ 853 | version: STSv1 854 | mode: testing 855 | mx: mx1.example.com 856 | mx: mx2.example.com 857 | mx: mx.backup-example.com 858 | max_age: 1296000 859 | ~~~~~~~~~ 860 | 861 | # Message delivery pseudocode 862 | 863 | Below is pseudocode demonstrating the logic of a compliant sending MTA. 864 | 865 | While this pseudocode implementation suggests synchronous policy retrieval in 866 | the delivery path, in a working implementation that may be undesirable, and we 867 | expect some implementers to instead prefer a background fetch that does not 868 | block delivery if no cached policy is present. 869 | 870 | ~~~~~~~~~ 871 | 872 | func isEnforce(policy) { 873 | // Return true if the policy mode is "enforce". 874 | } 875 | 876 | func isNonExpired(policy) { 877 | // Return true if the policy is not expired. 878 | } 879 | 880 | func tryStartTls(connection) { 881 | // Attempt to open an SMTP connection with STARTTLS with the MX. 882 | } 883 | 884 | func certMatches(connection, host) { 885 | // Assume a handy function to return check if the server certificate presented 886 | // in "connection" is valid for "host". 887 | } 888 | 889 | func policyMatches(candidate, policy) { 890 | for mx in policy.mx { 891 | // Literal match. 892 | if mx == candidate { 893 | return true 894 | } 895 | // Wildcard matches only the leftmost label. 896 | // Wildcards must always be followed by a '.'. 897 | if mx[0] == '*' { 898 | parts = SplitN(candidate, '.', 2) // Split on the first '.'. 899 | if len(parts) > 1 && parts[1] == mx[2:] { 900 | return true 901 | } 902 | } 903 | } 904 | return false 905 | } 906 | 907 | func tryDeliverMail(connection, message) { 908 | // Attempt to deliver "message" via "connection". 909 | } 910 | 911 | func tryGetNewPolicy(domain) { 912 | // Check for an MTA-STS TXT record for "domain" in DNS, and return the 913 | // indicated policy. 914 | } 915 | 916 | func cachePolicy(domain, policy) { 917 | // Store "policy" as the cached policy for "domain". 918 | } 919 | 920 | func tryGetCachedPolicy(domain) { 921 | // Return a cached policy for "domain". 922 | } 923 | 924 | func reportError(error) { 925 | // Report an error via TLSRPT. 926 | } 927 | 928 | func tryMxAccordingTo(message, mx, policy) { 929 | connection := connect(mx) 930 | if !connection { 931 | return false // Can't connect to the MX so it's not an MTA-STS 932 | // error. 933 | } 934 | secure := true 935 | if !policyMatches(mx, policy) { 936 | secure = false 937 | reportError(E_HOST_MISMATCH) 938 | } else if !tryStartTls(connection) { 939 | secure = false 940 | reportError(E_NO_VALID_TLS) 941 | } else if !certMatches(connection, policy) { 942 | secure = false 943 | reportError(E_CERT_MISMATCH) 944 | } 945 | if secure || !isEnforce(policy) { 946 | return tryDeliverMail(connection, message) 947 | } 948 | return false 949 | } 950 | 951 | func tryWithPolicy(message, domain, policy) { 952 | mxes := getMxForDomain(domain) 953 | for mx in mxes { 954 | if tryMxAccordingTo(message, mx, policy) { 955 | return true 956 | } 957 | } 958 | return false 959 | } 960 | 961 | func handleMessage(message) { 962 | domain := ... // domain part after '@' from recipient 963 | policy := tryGetNewPolicy(domain) 964 | if policy { 965 | cachePolicy(domain, policy) 966 | } else { 967 | policy = tryGetCachedPolicy(domain) 968 | } 969 | if policy { 970 | return tryWithPolicy(message, domain, policy) 971 | } 972 | // Try to deliver the message normally (i.e., without MTA-STS). 973 | } 974 | 975 | ~~~~~~~~~ 976 | -------------------------------------------------------------------------------- /mta-sts.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | SMTP MTA Strict Transport Security (MTA-STS) 14 | 15 | 16 | Google, Inc 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | dmargolis@google.com 27 | 28 |
29 | 30 | 31 | Google, Inc 32 |
33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | risher@google.com 42 | 43 |
44 | 45 | 46 | Yahoo!, Inc 47 |
48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | rbinu@yahoo-inc.com 57 | 58 |
59 | 60 | 61 | Comcast, Inc 62 |
63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | alex_brotman@comcast.com 72 | 73 |
74 | 75 | 76 | Microsoft, Inc 77 |
78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | janet.jones@microsoft.com 87 | 88 |
89 | 90 | 91 | 92 | Applications 93 | Using TLS in Applications 94 | 95 | 96 | 97 | 98 | SMTP Mail Transfer Agent Strict Transport Security (MTA-STS) is a mechanism 99 | enabling mail service providers to declare their ability to receive Transport 100 | Layer Security (TLS) secure SMTP connections, and to specify whether sending 101 | SMTP servers should refuse to deliver to MX hosts that do not offer TLS with a 102 | trusted server certificate. 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 |
112 | The STARTTLS extension to SMTP allows SMTP clients and hosts to 113 | negotiate the use of a TLS channel for encrypted mail transmission. 114 | 115 | While this opportunistic encryption protocol by itself provides a high barrier 116 | against passive man-in-the-middle traffic interception, any attacker who can 117 | delete parts of the SMTP session (such as the "250 STARTTLS" response) or who 118 | can redirect the entire SMTP session (perhaps by overwriting the resolved MX 119 | record of the delivery domain) can perform downgrade or interception attacks. 120 | 121 | This document defines a mechanism for recipient domains to publish policies, via 122 | a combination of DNS and HTTPS, specifying: 123 | 124 | 125 | 126 | whether MTAs sending mail to this domain can expect PKIX-authenticated TLS 127 | support 128 | what a conforming client should do with messages when TLS cannot be 129 | successfully negotiated 130 | 131 | 132 | 133 |
134 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 135 | "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 136 | document are to be interpreted as described in [BCP 14] 137 | when, and only when, they appear in all capitals, as shown here. 138 | 139 | We also define the following terms for further use in this document: 140 | 141 | 142 | 143 | MTA-STS Policy: A commitment by the Policy Domain to support PKIX 144 | authenticated TLS for the specified MX hosts. 145 | Policy Domain: The domain for which an MTA-STS Policy is defined. This is the 146 | next-hop domain; when sending mail to "alice@example.com" this would 147 | ordinarily be "example.com", but this may be overridden by explicit routing 148 | rules (as described in , 149 | "Policy Selection for Smart Hosts and Subdomains"). 150 | Policy Host: The HTTPS host which serves the MTA-STS Policy for a Policy 151 | Domain. Rules for constructing the hostname are described in 152 | , "MTA-STS Policies". 153 | Sender: The SMTP Mail Transfer Agent sending an email message. 154 | ABNF: Augmented Backus-Naur Form, a syntax for formally specifying syntax, 155 | defined in and . 156 | 157 | 158 |
159 |
160 | 161 |
162 | The DANE TLSA record is similar, in that DANE is also designed to 163 | upgrade unauthenticated encryption or plaintext transmission into authenticated, 164 | downgrade-resistant encrypted transmission. DANE requires DNSSEC 165 | for authentication; the mechanism described here instead relies on certificate 166 | authorities (CAs) and does not require DNSSEC, at a cost of risking malicious 167 | downgrades. For a thorough discussion of this trade-off, see 168 | , "Security Considerations". 169 | 170 | In addition, MTA-STS provides an optional testing-only mode, enabling soft 171 | deployments to detect policy failures; partial deployments can be achieved in 172 | DANE by deploying TLSA records only for some of a domain's MXs, but such a 173 | mechanism is not possible for the per-domain policies used by MTA-STS. 174 | 175 | The primary motivation of MTA-STS is to provide a mechanism for domains to 176 | ensure transport security even when deploying DNSSEC is undesirable or 177 | impractical. However, MTA-STS is designed not to interfere with DANE 178 | deployments when the two overlap; in particular, senders who implement MTA-STS 179 | validation MUST NOT allow a "valid" or "testing"-only MTA-STS validation to 180 | override a failing DANE validation. 181 | 182 |
183 | 184 |
185 | MTA-STS policies are distributed via HTTPS from a "well-known" path 186 | served within the Policy Domain, and their presence and current version are 187 | indicated by a TXT record at the Policy Domain. These TXT records additionally 188 | contain a policy id field, allowing sending MTAs to check the currency of a 189 | cached policy without performing an HTTPS request. 190 | 191 | To discover if a recipient domain implements MTA-STS, a sender need only resolve 192 | a single TXT record. To see if an updated policy is available for a domain for 193 | which the sender has a previously cached policy, the sender need only check the 194 | TXT record's version id against the cached value. 195 | 196 | 197 |
198 | The MTA-STS TXT record is a TXT record with the name _mta-sts at the Policy 199 | Domain. For the domain example.com, this record would be 200 | _mta-sts.example.com. MTA-STS TXT records MUST be US-ASCII, 201 | semicolon-separated key/value pairs containing the following fields: 202 | 203 | 204 | 205 | v: (plain-text, required). Currently only "STSv1" is supported. 206 | id: (plain-text, required). A short string used to track policy updates. 207 | This string MUST uniquely identify a given instance of a policy, such that 208 | senders can determine when the policy has been updated by comparing to the 209 | id of a previously seen policy. There is no implied ordering of id fields 210 | between revisions. 211 | 212 | 213 | An example TXT record is as below: 214 | 215 | _mta-sts.example.com. IN TXT "v=STSv1; id=20160831085700Z;" 216 | 217 | The formal definition of the _mta-sts TXT record, defined using ABNF 218 | (), is as follows: 219 | 220 | 221 |
222 | sts-text-record = sts-version 1*(sts-field-delim sts-field) 223 | [sts-field-delim] 224 | 225 | sts-field = sts-id / ; Note that sts-id record 226 | sts-extension ; is required. 227 | 228 | sts-field-delim = *WSP ";" *WSP 229 | 230 | sts-version = %s"v=STSv1" 231 | 232 | sts-id = %s"id=" 1*32(ALPHA / DIGIT) ; id=... 233 | 234 | sts-extension = sts-ext-name "=" sts-ext-value ; name=value 235 | 236 | sts-ext-name = (ALPHA / DIGIT) 237 | *31(ALPHA / DIGIT / "_" / "-" / ".") 238 | 239 | sts-ext-value = 1*(%x21-3A / %x3C / %x3E-7E) 240 | ; chars excluding "=", ";", SP, and CTLs 241 |
242 | The TXT record MUST begin with sts-version field, and the order of other fields 243 | is not significant. If multiple TXT records for _mta-sts are returned by the 244 | resolver, records which do not begin with v=STSv1; are discarded. If the 245 | number of resulting records is not one, or if the resulting record is 246 | syntactically invalid, senders MUST assume the recipient domain does not 247 | have an available MTA-STS policy and skip the remaining steps of policy 248 | discovery. (Note that absence of a usable TXT record is not by itself 249 | sufficient to remove a sender's previously cached policy for the Policy Domain, 250 | as discussed in , "Policy Application Control 251 | Flow".) If the resulting TXT record contains multiple strings, then the record 252 | MUST be treated as if those strings are concatenated together without adding 253 | spaces. 254 | 255 |
256 | 257 |
258 | The policy itself is a set of key/value pairs (similar to header 259 | fields) served via the HTTPS GET method from the fixed "well-known" 260 | path of .well-known/mta-sts.txt served by the Policy Host. The Policy Host 261 | DNS name is constructed by prepending mta-sts to the Policy Domain. 262 | 263 | Thus for a Policy Domain of example.com the full URL is 264 | https://mta-sts.example.com/.well-known/mta-sts.txt. 265 | 266 | When fetching a policy, senders SHOULD validate that the media type is 267 | "text/plain" to guard against cases where webservers allow untrusted users to 268 | host non-text content (typically, HTML or images) at a user-defined path. All 269 | parameters other than charset=utf-8 or charset=us-ascii are ignored. Additional 270 | "Content-Type" parameters are also ignored. 271 | 272 | This resource contains the following CRLF-separated key/value pairs: 273 | 274 | 275 | 276 | version: Currently only "STSv1" is supported. 277 | mode: One of "enforce", "testing", or "none", indicating the expected 278 | behavior of a sending MTA in the case of a policy validation failure. See 279 | , "Policy Application." for more details about the three 280 | modes. 281 | max_age: Max lifetime of the policy (plain-text non-negative integer 282 | seconds, maximum value of 31557600). Well-behaved clients SHOULD cache a 283 | policy for up to this value from last policy fetch time. To mitigate the 284 | risks of attacks at policy refresh time, it is expected that this value 285 | typically be in the range of weeks or greater. 286 | mx: Allowed MX patterns. One or more patterns matching allowed MX hosts for 287 | the Policy Domain. As an example, 288 | 289 | 290 | 291 |
292 | mx: mail.example.com <CRLF> 293 | mx: *.example.net 294 |
295 | indicates that mail for this domain might be handled by MX mail.example.com 296 | or any MX at example.net. Valid patterns can be either fully specified 297 | names (example.com) or suffixes prefixed by a wildcard (*.example.net). 298 | If a policy specifies more than one MX, each MX MUST have its own mx: key, 299 | and each MX key/value pair MUST be on its own line in the policy file. In the 300 | case of Internationalized Domain Names (), the mx value MUST 301 | specify the Punycode-encoded A-label to match against, and not the 302 | Unicode-encoded U-label. The full semantics of certificate validation 303 | (including the use of wildcard patterns) are described in 304 | , "MX Host Validation." 305 | 306 | An example policy is as below: 307 | 308 | 309 |
310 | version: STSv1 311 | mode: enforce 312 | mx: mail.example.com 313 | mx: *.example.net 314 | mx: backupmx.example.com 315 | max_age: 604800 316 |
317 | The formal definition of the policy resource, defined using , is as 318 | follows: 319 | 320 | 321 |
322 | sts-policy-record = sts-policy-field *WSP 323 | *(sts-policy-term sts-policy-field *WSP) 324 | [sts-policy-term] 325 | 326 | sts-policy-field = sts-policy-version / ; required once 327 | sts-policy-mode / ; required once 328 | sts-policy-max-age / ; required once 329 | 330 | sts-policy-term / 331 | ; required at least once, except when 332 | ; mode is "none" 333 | 334 | sts-policy-extension ; other fields 335 | 336 | sts-policy-field-delim = ":" *WSP 337 | 338 | sts-policy-version = sts-policy-version-field sts-policy-field-delim 339 | sts-policy-version-value 340 | 341 | sts-policy-version-field = %s"version" 342 | 343 | sts-policy-version-value = %s"STSv1" 344 | 345 | sts-policy-mode = sts-policy-mode-field sts-policy-field-delim 346 | sts-policy-mode-value 347 | 348 | sts-policy-mode-field = %s"mode" 349 | 350 | sts-policy-mode-value = %s"testing" / %s"enforce" / %s"none" 351 | 352 | sts-policy-mx = sts-policy-mx-field sts-policy-field-delim 353 | sts-policy-mx-value 354 | 355 | sts-policy-mx-field = %s"mx" 356 | 357 | sts-policy-mx-value = ["*."] Domain 358 | 359 | sts-policy-max-age = sts-policy-max-age-field sts-policy-field-delim 360 | sts-policy-max-age-value 361 | 362 | sts-policy-max-age-field = %s"max_age" 363 | 364 | sts-policy-max-age-value = 1*10(DIGIT) 365 | 366 | sts-policy-extension = sts-policy-ext-name ; additional 367 | sts-policy-field-delim ; extension 368 | sts-policy-ext-value ; fields 369 | 370 | sts-policy-ext-name = (sts-policy-alphanum) 371 | *31(sta-policy-alphanum / "_" / "-" / ".") 372 | 373 | sts-policy-term = LF / CRLF 374 | 375 | sts-policy-ext-value = sts-policy-vchar 376 | [*(%x20 / sts-policy-vchar) 377 | sts-policy-vchar] 378 | ; chars, including UTF-8 [@!RFC3629], 379 | ; excluding CTLs and no 380 | ; leading/trailing spaces 381 | 382 | sts-policy-alphanum = ALPHA / DIGIT 383 | 384 | sts-policy-vchar = %x21-7E / UTF8-2 / UTF8-3 / UTF8-4 385 | 386 | UTF8-2 = <Defined in Section 4 of [@!RFC3629]> 387 | 388 | UTF8-3 = <Defined in Section 4 of [@!RFC3629]> 389 | 390 | UTF8-4 = <Defined in Section 4 of [@!RFC3629]> 391 | 392 | Domain = <see RFC 5321 4.1.2> 393 |
394 | Parsers MUST accept TXT records and policy files which are syntactically valid 395 | (i.e., valid key/value pairs separated by semi-colons for TXT records), possibly 396 | containing additional key/value pairs not specified in this document, in which 397 | case unknown fields SHALL be ignored. If any non-repeated field--i.e., all 398 | fields excepting mx--is duplicated, all entries except for the first SHALL be 399 | ignored. 400 | 401 |
402 | 403 |
404 | Policy bodies are, as described above, retrieved by sending MTAs via HTTPS 405 | . During the TLS handshake initiated to fetch a new or updated 406 | policy from the Policy Host, the Policy Host HTTPS server MUST present a X.509 407 | certificate which is valid for the mta-sts DNS-ID () (e.g., 408 | mta-sts.example.com) as described below, chain to a root CA that is trusted by 409 | the sending MTA, and be non-expired. It is expected that sending MTAs use a set 410 | of trusted CAs similar to those in widely deployed Web browsers and operating 411 | systems. See for more details about certificate verification. 412 | 413 | The certificate is valid for the Policy Host (i.e., mta-sts prepended to the 414 | Policy Domain) with respect to the rules described in , with the 415 | following application-specific considerations: 416 | 417 | 418 | 419 | Matching is performed only against the DNS-ID identifiers. 420 | DNS domain names in server certificates MAY contain the wildcard character 421 | '*' as the complete left-most label within the identifier. 422 | 423 | 424 | The certificate MAY be checked for revocation via the Online Certificate Status 425 | Protocol (OCSP) , certificate revocation lists (CRLs), or some other 426 | mechanism. 427 | 428 | Policies fetched via HTTPS are only valid if the HTTP response code is 200 (OK). 429 | HTTP 3xx redirects MUST NOT be followed, and HTTP caching (as specified in 430 | ) MUST NOT be used. 431 | 432 | Senders may wish to rate-limit the frequency of attempts to fetch the HTTPS 433 | endpoint even if a valid TXT record for the recipient domain exists. In the 434 | case that the HTTPS GET fails, implementers SHOULD limit further attempts to 435 | a period of five minutes or longer per version ID, to avoid overwhelming 436 | resource-constrained recipients with cascading failures. 437 | 438 | Senders MAY impose a timeout on the HTTPS GET and/or a limit on the maximum size 439 | of the response body to avoid long delays or resource exhaustion during 440 | attempted policy updates. A suggested timeout is one minute, and a suggested 441 | maximum policy size 64 kilobytes; policy hosts SHOULD respond to requests with a 442 | complete policy body within that timeout and size limit. 443 | 444 | If a valid TXT record is found but no policy can be fetched via HTTPS (for any 445 | reason), and there is no valid (non-expired) previously-cached policy, senders 446 | MUST continue with delivery as though the domain has not implemented MTA-STS. 447 | 448 | Conversely, if no "live" policy can be discovered via DNS or fetched via HTTPS, 449 | but a valid (non-expired) policy exists in the sender's cache, the sender MUST 450 | apply that cached policy. 451 | 452 | Finally, to mitigate the risk of persistent interference with policy refresh, as 453 | discussed in-depth in , MTAs SHOULD proactively 454 | refresh cached policies before they expire; a suggested refresh frequency is 455 | once per day. To enable administrators to discover problems with policy 456 | refresh, MTAs SHOULD alert administrators (through the use of logs or similar) 457 | when such attempts fail, unless the cached policy mode is none. 458 | 459 |
460 | 461 |
462 | When sending mail via a "smart host"--an administratively configured 463 | intermediate SMTP relay, which is different from the message recipient's server 464 | as determined from DNS --compliant senders MUST treat the smart host domain as 465 | the policy domain for the purposes of policy discovery and application. This 466 | specification does not provide a means of associating policies with email 467 | addresses that employ Address Literals . 468 | 469 | When sending mail to a mailbox at a subdomain, compliant senders MUST NOT 470 | attempt to fetch a policy from the parent zone. Thus for mail sent to 471 | "user@mail.example.com", the policy can be fetched only from "mail.example.com", 472 | not "example.com". 473 | 474 |
475 |
476 | 477 |
478 | When sending to an MX at a domain for which the sender has a valid and 479 | non-expired MTA-STS policy, a sending MTA honoring MTA-STS MUST check whether: 480 | 481 | 482 | 483 | At least one of the policy's "mx" patterns matches the selected MX host, 484 | as described in , "MX Host Validation". 485 | The recipient mail server supports STARTTLS and offers a PKIX-based TLS 486 | certificate, during TLS handshake, which is valid for that host, as described 487 | in , "Recipient MTA Certificate 488 | Validation". 489 | 490 | 491 | When these conditions are not met, a policy is said to fail to validate. This 492 | section does not dictate the behavior of sending MTAs when the above conditions 493 | are not met; see , "Policy Application" for a description 494 | of sending MTA behavior when policy validation fails. 495 | 496 | 497 |
498 | A receiving candidate MX host is valid according to an applied MTA-STS policy if 499 | the MX record name matches one or more of the mx fields in the applied policy. 500 | Matching is identical to the rules given in , with restriction that 501 | the wildcard character * may only be used to match the entire left-most label 502 | in the presented identifier. Thus the mx pattern *.example.com matches 503 | mail.example.com but not example.com or foo.bar.example.com. 504 | 505 |
506 | 507 |
508 | The certificate presented by the receiving MTA MUST not be expired, and MUST 509 | chain to a root CA that is trusted by the sending MTA. The certificate MUST 510 | have a subject alternative name (SAN, ) with a DNS-ID () 511 | matching the host name, per the rules given in . The MX's 512 | certificate MAY also be checked for revocation via OCSP , CRLs 513 | , or some other mechanism. 514 | 515 |
516 |
517 | 518 |
519 | When sending to an MX at a domain for which the sender has a valid, non-expired 520 | MTA-STS policy, a sending MTA honoring MTA-STS applies the result of a policy 521 | validation failure one of two ways, depending on the value of the policy mode 522 | field: 523 | 524 | 525 | 526 | enforce: In this mode, sending MTAs MUST NOT deliver the message to hosts 527 | which fail MX matching or certificate validation, or do not support STARTTLS. 528 | testing: In this mode, sending MTAs which also implement the TLSRPT 529 | specification merely send a report indicating 530 | policy application failures (so long as TLSRPT is also implemented by the 531 | recipient domain). 532 | none: In this mode, sending MTAs should treat the policy domain as though 533 | it does not have any active policy; see , "Removing 534 | MTA-STS", for use of this mode value. 535 | 536 | 537 | When a message fails to deliver due to an enforce policy, a compliant MTA MUST 538 | NOT permanently fail to deliver messages before checking, via DNS, for the 539 | presence of an updated policy at the Policy Domain. (In all cases, MTAs SHOULD 540 | treat such failures as transient errors and retry delivery later.) This allows 541 | implementing domains to update long-lived policies on the fly. 542 | 543 | 544 |
545 | An example control flow for a compliant sender consists of the following steps: 546 | 547 | 548 | 549 | Check for a cached policy whose time-since-fetch has not exceeded its 550 | max_age. If none exists, attempt to fetch a new policy (perhaps 551 | asynchronously, so as not to block message delivery). Optionally, sending 552 | MTAs may unconditionally check for a new policy at this step. 553 | For each candidate MX, in order of MX priority, attempt to deliver the 554 | message. If a policy is present with an enforce mode, when attempting to 555 | deliver to each candidate MX, ensure STARTTLS support and host identity 556 | validity as described in , "Policy Validation". If a 557 | candidate fails validation, continue to the next candidate (if there is one). 558 | A message delivery MUST NOT be permanently failed until the sender has first 559 | checked for the presence of a new policy (as indicated by the id field in 560 | the _mta-sts TXT record). If a new policy is not found, existing rules for 561 | the case of temporary message delivery failures apply (as discussed in 562 | section 4.5.4.1). 563 | 564 | 565 |
566 |
567 | 568 |
569 | MTA-STS is intended to be used along with TLSRPT in 570 | order to ensure implementing domains can detect cases of both benign and 571 | malicious failures, and to ensure that failures that indicate an active attack 572 | are discoverable. As such, senders who also implement TLSRPT SHOULD treat the 573 | following events as reportable failures: 574 | 575 | 576 | 577 | HTTPS policy fetch failures when a valid TXT record is present. 578 | Policy fetch failures of any kind when a valid policy exists in the policy 579 | cache, except if that policy's mode is none. 580 | Delivery attempts in which a contacted MX does not support STARTTLS or does 581 | not present a certificate which validates according to the applied policy, 582 | except if that policy's mode is none. 583 | 584 | 585 |
586 | 587 |
588 | 589 |
590 | To ensure that the server sends the right certificate chain, the SMTP client 591 | MUST have support for the TLS SNI extension . When connecting to a 592 | HTTP server to retrieve the MTA-STS policy, the SNI extension MUST contain the 593 | name of the policy host (e.g., mta-sts.example.com). When connecting to an 594 | SMTP server, the SNI extension MUST contain the MX hostname. 595 | 596 | HTTP servers used to deliver MTA-STS policies MAY rely on SNI to determine which 597 | certificate chain to present to the client. HTTP servers MUST respond with a 598 | certificate chain that matches the policy hostname or abort the TLS handshake if 599 | unable to do so. Clients that do not send SNI information may not see the 600 | expected certificate chain. 601 | 602 | SMTP servers MAY rely on SNI to determine which certificate chain to present to 603 | the client. However servers that have one identity and a single matching 604 | certificate do not require SNI support. Servers MUST NOT enforce the use of SNI 605 | by clients, as the client may be using unauthenticated opportunistic TLS and may 606 | not expect any particular certificate from the server. If the client sends no 607 | SNI extension or sends an SNI extension for an unsupported server name, the 608 | server MUST simply send a fallback certificate chain of its choice. The reason 609 | for not enforcing strict matching of the requested SNI hostname is that MTA-STS 610 | TLS clients may be typically willing to accept multiple server names but can 611 | only send one name in the SNI extension. The server's fallback certificate may 612 | match a different name that is acceptable to the client, e.g., the original 613 | next-hop domain. 614 | 615 |
616 | 617 |
618 | MTAs supporting MTA-STS MUST have support for TLS version 1.2 or 619 | higher. The general TLS usage guidance in SHOULD be followed. 620 | 621 |
622 |
623 | 624 |
625 | 626 |
627 | Updating the policy requires that the owner make changes in two places: the 628 | _mta-sts TXT record in the Policy Domain's DNS zone and at the corresponding 629 | HTTPS endpoint. As a result, recipients should expect a policy will continue to 630 | be used by senders until both the HTTPS and TXT endpoints are updated and the 631 | TXT record's TTL has passed. 632 | 633 | In other words, a sender who is unable to successfully deliver a message while 634 | applying a cache of the recipient's now-outdated policy may be unable to 635 | discover that a new policy exists until the DNS TTL has passed. Recipients 636 | SHOULD therefore ensure that old policies continue to work for message delivery 637 | during this period of time, or risk message delays. 638 | 639 | Recipients SHOULD also update the HTTPS policy body before updating the TXT 640 | record; this ordering avoids the risk that senders, seeing a new TXT record, 641 | mistakenly cache the old policy from HTTPS. 642 | 643 |
644 | 645 |
646 | Domain owners commonly delegate SMTP hosting to a different organization, such 647 | as an ISP or a Web host. In such a case, they may wish to also delegate the 648 | MTA-STS policy to the same organization which can be accomplished with two 649 | changes. 650 | 651 | First, the Policy Domain must point the _mta-sts record, via CNAME, to the 652 | _mta-sts record maintained by the hosting organization. This allows the 653 | hosting organization to control update signaling. 654 | 655 | Second, the Policy Domain must point the "well-known" policy location to the 656 | hosting organization. This can be done either by setting the mta-sts record 657 | to an IP address or CNAME specified by the hosting organization and by giving 658 | the hosting organization a TLS certificate which is valid for that host, or by 659 | setting up a "reverse proxy" (also known as a "gateway") server that serves as 660 | the Policy Domain's policy the policy currently served by the hosting 661 | organization. 662 | 663 | For example, given a user domain user.example hosted by a mail provider 664 | provider.example, the following configuration would allow policy delegation: 665 | 666 | DNS: 667 | 668 | 669 |
670 | _mta-sts.user.example. IN CNAME _mta-sts.provider.example. 671 |
672 | Policy: 673 | 674 | 675 |
676 | > GET /.well-known/mta-sts.txt Host: mta-sts.user.example 677 | < HTTP/1.1 200 OK # Response proxies content from 678 | # https://mta-sts.provider.example 679 |
680 | Note that in all such cases, the policy endpoint 681 | (https://mta-sts.user.example/.well-known/mta-sts.txt in this example) must 682 | still present a certificate valid for the Policy Host (mta-sts.user.example), 683 | and not for that host at the provider's domain (mta-sts.provider.example). 684 | 685 | Note that while sending MTAs MUST NOT use HTTP caching when fetching policies 686 | via HTTPS, such caching may nonetheless be useful to a reverse proxy configured 687 | as described in this section. An HTTPS policy endpoint expecting to be proxied 688 | for multiple hosted domains--as with a large mail hosting provider or 689 | similar--may wish to indicate an HTTP Cache-Control max-age response directive 690 | (as specified in ) of 60 seconds as a reasonable value to save 691 | reverse proxies an unnecessarily high-rate of proxied policy fetching. 692 | 693 |
694 | 695 |
696 | In order to facilitate clean opt-out of MTA-STS by implementing policy domains, 697 | and to distinguish clearly between failures which indicate attacks and those 698 | which indicate such opt-outs, MTA-STS implements the none mode, which allows 699 | validated policies to indicate authoritatively that the policy domain wishes to 700 | no longer implement MTA-STS and may, in the future, remove the MTA-STS TXT and 701 | policy endpoints entirely. 702 | 703 | A suggested workflow to implement such an opt out is as follows: 704 | 705 | 706 | 707 | Publish a new policy with mode equal to none and a small max_age (e.g., 708 | one day). 709 | Publish a new TXT record to trigger fetching of the new policy. 710 | When all previously served policies have expired--normally this is the time 711 | the previously published policy was last served plus that policy's max_age, 712 | but note that older policies may have been served with a greater max_age, 713 | allowing overlapping policy caches--safely remove the TXT record and HTTPS 714 | endpoint. 715 | 716 | 717 |
718 | 719 |
720 | Implementors of send-time MTA-STS validation in mail transfer agents should take 721 | note of the risks of modifying the logic of traversing MX candidate lists. 722 | Because an MTA-STS policy can be used to prefilter invalid MX candidates from 723 | the MX candidate list, it is tempting to implement a "two-pass" model, where MX 724 | candidates are first filtered for possible validity according to the MTA-STS 725 | policy, and then the remaining candidates attempted in order as without an 726 | MTA-STS policy. This may lead to incorrect implementations, such a message 727 | loops; implementors are instead recommended to traverse the MX candidate list as 728 | usual, and treat invalid candidates as though they were unreachable (i.e., as 729 | though there were some transient error when trying to deliver to that 730 | candidate). 731 | 732 | One consequence of validating MX hosts in order of ordinary candidate traversal 733 | is that, in the event that a higher-priority MX is MTA-STS valid and a 734 | lower-priority MX is not, senders may never encounter the lower-priority MX, 735 | leading to a risk that policy misconfigurations that apply only to "backup" MXes 736 | may only be discovered in the case of primary MX failure. 737 | 738 |
739 |
740 | 741 |
742 | 743 |
744 | A new "well-known" URI as described in will be registered in 745 | the Well-Known URIs registry as described below: 746 | 747 | URI Suffix: mta-sts.txt Change Controller: IETF 748 | 749 |
750 | 751 |
752 | IANA is requested to create a new registry titled "MTA-STS TXT Record Fields". 753 | The initial entries in the registry are: 754 | 755 | 756 | Field Name 757 | Description 758 | Reference 759 | 760 | vRecord version of RFC XXX 761 | idPolicy instance ID of RFC XXX 762 | 763 | New fields are added to this registry using IANA's "Expert Review" policy. 764 | 765 |
766 | 767 |
768 | IANA is requested to create a new registry titled "MTA-STS Policy Fields". The 769 | initial entries in the registry are: 770 | 771 | 772 | Field Name 773 | Description 774 | Reference 775 | 776 | versionPolicy version of RFC XXX 777 | modeEnforcement behavior of RFC XXX 778 | max_agePolicy lifetime of RFC XXX 779 | mxMX identities of RFC XXX 780 | 781 | New fields are added to this registry using IANA's "Expert Review" 782 | policy. 783 | 784 |
785 |
786 | 787 |
788 | SMTP MTA Strict Transport Security attempts to protect against an active 789 | attacker trying to intercept or tamper with mail between hosts that support 790 | STARTTLS. There are two classes of attacks considered: 791 | 792 | 793 | 794 | Foiling TLS negotiation, for example by deleting the "250 STARTTLS" response 795 | from a server or altering TLS session negotiation. This would result in the 796 | SMTP session occurring over plaintext, despite both parties supporting TLS. 797 | Impersonating the destination mail server, whereby the sender might deliver 798 | the message to an impostor, who could then monitor and/or modify messages 799 | despite opportunistic TLS. This impersonation could be accomplished by 800 | spoofing the DNS MX record for the recipient domain, or by redirecting client 801 | connections intended for the legitimate recipient server (for example, by 802 | altering BGP routing tables). 803 | 804 | 805 | MTA-STS can thwart such attacks only if the sender is able to previously obtain 806 | and cache a policy for the recipient domain, and only if the attacker is unable 807 | to obtain a valid certificate that complies with that policy. Below, we 808 | consider specific attacks on this model. 809 | 810 | 811 |
812 | SMTP MTA-STS relies on certificate validation via PKIX based TLS identity 813 | checking . Attackers who are able to obtain a valid certificate for 814 | the targeted recipient mail service (e.g., by compromising a certificate 815 | authority) are thus able to circumvent STS authentication. 816 | 817 |
818 | 819 |
820 | Since MTA-STS uses DNS TXT records for policy discovery, an attacker who is able 821 | to block DNS responses can suppress the discovery of an MTA-STS Policy, making 822 | the Policy Domain appear not to have an MTA-STS Policy. The sender policy cache 823 | is designed to resist this attack by decreasing the frequency of policy 824 | discovery and thus reducing the window of vulnerability; it is nonetheless a 825 | risk that attackers who can predict or induce policy discovery--for example, by 826 | inducing a sending domain to send mail to a never-before-contacted recipient 827 | while carrying out a man-in-the-middle attack--may be able to foil policy 828 | discovery and effectively downgrade the security of the message delivery. 829 | 830 | Since this attack depends upon intercepting initial policy discovery, 831 | implementers SHOULD prefer policy max_age values to be as long as is 832 | practical. 833 | 834 | Because this attack is also possible upon refresh of a cached policy, 835 | implementors SHOULD NOT wait until a cached policy has expired before checking 836 | for an update; if senders attempt to refresh the cache regularly (for example, 837 | by fetching currently live policy in a background task that runs daily or 838 | weekly, regardless of the state of the _mta-sts TXT record, and updating their 839 | cache's "max age" accordingly), an attacker would have to foil policy discovery 840 | consistently over the lifetime of a cached policy to prevent a successful 841 | refresh. 842 | 843 | Additionally, MTAs SHOULD alert administrators to repeated policy refresh 844 | failures long before cached policies expire (through warning logs or similar 845 | applicable mechanisms), allowing administrators to detect such a persistent 846 | attack on policy refresh. (However, they should not implement such alerts if 847 | the cached policy has a none mode, to allow clean MTA-STS removal, as 848 | described in .) 849 | 850 | Resistance to downgrade attacks of this nature--due to the ability to 851 | authoritatively determine "lack of a record" even for non-participating 852 | recipients--is a feature of DANE, due to its use of DNSSEC for policy discovery. 853 | 854 |
855 | 856 |
857 | We additionally consider the Denial of Service risk posed by an attacker who can 858 | modify the DNS records for a recipient domain. Absent MTA-STS, such an attacker 859 | can cause a sending MTA to cache invalid MX records, but only for however long 860 | the sending resolver caches those records. With MTA-STS, the attacker can 861 | additionally advertise a new, long-max_age MTA-STS policy with mx 862 | constraints that validate the malicious MX record, causing senders to cache the 863 | policy and refuse to deliver messages once the victim has resecured the MX 864 | records. 865 | 866 | This attack is mitigated in part by the ability of a victim domain to (at any 867 | time) publish a new policy updating the cached, malicious policy, though this 868 | does require the victim domain to both obtain a valid CA-signed certificate and 869 | to understand and properly configure MTA-STS. 870 | 871 | Similarly, we consider the possibility of domains that deliberately allow 872 | untrusted users to serve untrusted content on user-specified subdomains. In 873 | some cases (e.g., the service Tumblr.com) this takes the form of providing HTTPS 874 | hosting of user-registered subdomains; in other cases (e.g. dynamic DNS 875 | providers) this takes the form of allowing untrusted users to register custom 876 | DNS records at the provider's domain. 877 | 878 | In these cases, there is a risk that untrusted users would be able to serve 879 | custom content at the mta-sts host, including serving an illegitimate MTA-STS 880 | policy. We believe this attack is rendered more difficult by the need for the 881 | attacker to also serve the _mta-sts TXT record on the same domain--something 882 | not, to our knowledge, widely provided to untrusted users. This attack is 883 | additionally mitigated by the aforementioned ability for a victim domain to 884 | update an invalid policy at any future date. 885 | 886 |
887 | 888 |
889 | Even if an attacker cannot modify a served policy, the potential exists for 890 | configurations that allow attackers on the same domain to receive mail for that 891 | domain. For example, an easy configuration option when authoring an MTA-STS 892 | Policy for example.com is to set the mx equal to *.example.com; recipient 893 | domains must consider in this case the risk that any user possessing a valid 894 | hostname and CA-signed certificate (for example, dhcp-123.example.com) will, 895 | from the perspective of MTA-STS Policy validation, be a valid MX host for that 896 | domain. 897 | 898 |
899 | 900 |
901 | A host of risks apply to the PKI system used for certificate authentication, 902 | both of the mta-sts HTTPS host's certificate and the SMTP servers' 903 | certificates. These risks are broadly applicable within the Web PKI ecosystem 904 | and are not specific to MTA-STS; nonetheless, they deserve some consideration in 905 | this context. 906 | 907 | Broadly speaking, attackers may compromise the system by obtaining certificates 908 | under fraudulent circumstances (i.e., by impersonating the legitimate owner of 909 | the victim domain), by compromising a Certificate Authority or Delegate 910 | Authority's private keys, by obtaining a legitimate certificate issued to the 911 | victim domain, and similar. 912 | 913 | One approach commonly employed by Web browsers to help mitigate against some of 914 | these attacks is to allow for revocation of compromised or fraudulent 915 | certificates via OCSP or CRLs . Such mechanisms 916 | themselves represent tradeoffs and are not universally implemented; we 917 | nonetheless recommend implementors of MTA-STS to implement revocation mechanisms 918 | which are most applicable to their implementations. 919 | 920 |
921 |
922 | 923 |
924 | Wei Chuang 925 | Google, Inc 926 | weihaw@google.com 927 | 928 | Viktor Dukhovni 929 | ietf-dane@dukhovni.de 930 | 931 | Markus Laber 932 | 1&1 Mail & Media Development & Technology GmbH 933 | markus.laber@1und1.de 934 | 935 | Nicolas Lidzborski 936 | Google, Inc 937 | nlidz@google.com 938 | 939 | Brandon Long 940 | Google, Inc 941 | blong@google.com 942 | 943 | Franck Martin 944 | LinkedIn, Inc 945 | fmartin@linkedin.com 946 | 947 | Klaus Umbach 948 | 1&1 Mail & Media Development & Technology GmbH 949 | klaus.umbach@1und1.de 950 | 951 |
952 | 953 | 954 | 955 | 956 | 957 | 958 | 959 | 960 | 961 | 962 | 963 | 964 | 965 | 966 | 967 | 968 | 969 | 970 | 971 | 972 | 973 | 974 | 975 | 976 | 977 | 978 | 979 | 980 | 981 | 982 |
983 | The owner of example.com wishes to begin using MTA-STS with a policy that will 984 | solicit reports from senders without affecting how the messages are processed, 985 | in order to verify the identity of MXs that handle mail for example.com, 986 | confirm that TLS is correctly used, and ensure that certificates presented by 987 | the recipient MX validate. 988 | 989 | MTA-STS policy indicator TXT RR: 990 | 991 | 992 |
993 | _mta-sts.example.com. IN TXT "v=STSv1; id=20160831085700Z;" 994 |
995 | MTA-STS Policy file served as the response body at 996 | https://mta-sts.example.com/.well-known/mta-sts.txt: 997 | 998 | 999 |
1000 | version: STSv1 1001 | mode: testing 1002 | mx: mx1.example.com 1003 | mx: mx2.example.com 1004 | mx: mx.backup-example.com 1005 | max_age: 1296000 1006 |
1007 |
1008 | 1009 |
1010 | Below is pseudocode demonstrating the logic of a compliant sending MTA. 1011 | 1012 | While this pseudocode implementation suggests synchronous policy retrieval in 1013 | the delivery path, in a working implementation that may be undesirable, and we 1014 | expect some implementers to instead prefer a background fetch that does not 1015 | block delivery if no cached policy is present. 1016 | 1017 | 1018 |
1019 | 1020 | func isEnforce(policy) { 1021 | // Return true if the policy mode is "enforce". 1022 | } 1023 | 1024 | func isNonExpired(policy) { 1025 | // Return true if the policy is not expired. 1026 | } 1027 | 1028 | func tryStartTls(connection) { 1029 | // Attempt to open an SMTP connection with STARTTLS with the MX. 1030 | } 1031 | 1032 | func certMatches(connection, host) { 1033 | // Assume a handy function to return check if the server certificate presented 1034 | // in "connection" is valid for "host". 1035 | } 1036 | 1037 | func policyMatches(candidate, policy) { 1038 | for mx in policy.mx { 1039 | // Literal match. 1040 | if mx == candidate { 1041 | return true 1042 | } 1043 | // Wildcard matches only the leftmost label. 1044 | // Wildcards must always be followed by a '.'. 1045 | if mx[0] == '*' { 1046 | parts = SplitN(candidate, '.', 2) // Split on the first '.'. 1047 | if len(parts) > 1 && parts[1] == mx[2:] { 1048 | return true 1049 | } 1050 | } 1051 | } 1052 | return false 1053 | } 1054 | 1055 | func tryDeliverMail(connection, message) { 1056 | // Attempt to deliver "message" via "connection". 1057 | } 1058 | 1059 | func tryGetNewPolicy(domain) { 1060 | // Check for an MTA-STS TXT record for "domain" in DNS, and return the 1061 | // indicated policy. 1062 | } 1063 | 1064 | func cachePolicy(domain, policy) { 1065 | // Store "policy" as the cached policy for "domain". 1066 | } 1067 | 1068 | func tryGetCachedPolicy(domain) { 1069 | // Return a cached policy for "domain". 1070 | } 1071 | 1072 | func reportError(error) { 1073 | // Report an error via TLSRPT. 1074 | } 1075 | 1076 | func tryMxAccordingTo(message, mx, policy) { 1077 | connection := connect(mx) 1078 | if !connection { 1079 | return false // Can't connect to the MX so it's not an MTA-STS 1080 | // error. 1081 | } 1082 | secure := true 1083 | if !policyMatches(mx, policy) { 1084 | secure = false 1085 | reportError(E_HOST_MISMATCH) 1086 | } else if !tryStartTls(connection) { 1087 | secure = false 1088 | reportError(E_NO_VALID_TLS) 1089 | } else if !certMatches(connection, policy) { 1090 | secure = false 1091 | reportError(E_CERT_MISMATCH) 1092 | } 1093 | if secure || !isEnforce(policy) { 1094 | return tryDeliverMail(connection, message) 1095 | } 1096 | return false 1097 | } 1098 | 1099 | func tryWithPolicy(message, domain, policy) { 1100 | mxes := getMxForDomain(domain) 1101 | for mx in mxes { 1102 | if tryMxAccordingTo(message, mx, policy) { 1103 | return true 1104 | } 1105 | } 1106 | return false 1107 | } 1108 | 1109 | func handleMessage(message) { 1110 | domain := ... // domain part after '@' from recipient 1111 | policy := tryGetNewPolicy(domain) 1112 | if policy { 1113 | cachePolicy(domain, policy) 1114 | } else { 1115 | policy = tryGetCachedPolicy(domain) 1116 | } 1117 | if policy { 1118 | return tryWithPolicy(message, domain, policy) 1119 | } 1120 | // Try to deliver the message normally (i.e., without MTA-STS). 1121 | } 1122 | 1123 |
1124 |
1125 | 1126 | 1127 | 1128 | -------------------------------------------------------------------------------- /reporting.md: -------------------------------------------------------------------------------- 1 | %%% 2 | 3 | Title = "SMTP TLS Reporting" 4 | abbrev = "SMTP-TLSRPT" 5 | category = "std" 6 | docName = "draft-ietf-uta-smtp-tlsrpt-23" 7 | ipr = "trust200902" 8 | area = "Applications" 9 | workgroup = "Using TLS in Applications" 10 | keyword = [""] 11 | 12 | date = 2018-06-14T00:00:00Z 13 | 14 | [[author]] 15 | initials="D." 16 | surname="Margolis" 17 | fullname="Daniel Margolis" 18 | organization="Google, Inc" 19 | [author.address] 20 | email="dmargolis@google.com" 21 | [[author]] 22 | initials="A." 23 | surname="Brotman" 24 | fullname="Alexander Brotman" 25 | organization="Comcast, Inc" 26 | [author.address] 27 | email="alex_brotman@comcast.com" 28 | [[author]] 29 | initials="B." 30 | surname="Ramakrishnan" 31 | fullname="Binu Ramakrishnan" 32 | organization="Yahoo!, Inc" 33 | [author.address] 34 | email="rbinu@oath.com" 35 | [[author]] 36 | initials="J." 37 | surname="Jones" 38 | fullname="Janet Jones" 39 | organization="Microsoft, Inc" 40 | [author.address] 41 | email="janet.jones@microsoft.com" 42 | [[author]] 43 | initials="M." 44 | surname="Risher" 45 | fullname="Mark Risher" 46 | organization="Google, Inc" 47 | [author.address] 48 | email="risher@google.com" 49 | 50 | %%% 51 | 52 | .# Abstract 53 | 54 | A number of protocols exist for establishing encrypted channels between 55 | SMTP Mail Transfer Agents, including STARTTLS, DANE TLSA, and MTA-STS. 56 | These protocols can fail due to misconfiguration or active attack, 57 | leading to undelivered messages or delivery over unencrypted or 58 | unauthenticated channels. This document describes a reporting mechanism 59 | and format by which sending systems can share statistics and specific 60 | information about potential failures with recipient domains. Recipient 61 | domains can then use this information to both detect potential attacks and 62 | diagnose unintentional misconfigurations. 63 | 64 | {mainmatter} 65 | 66 | # Introduction 67 | 68 | The STARTTLS extension to SMTP [@?RFC3207] allows SMTP clients and hosts 69 | to establish secure SMTP sessions over TLS. The protocol design uses an 70 | approach that has come to be known as "Opportunistic Security" (OS) 71 | [@?RFC7435]. This method maintains interoperability with clients that do 72 | not support STARTTLS, but means that any attacker could potentially 73 | eavesdrop on a session. An attacker could perform a downgrade or 74 | interception attack by deleting parts of the SMTP session (such as the 75 | "250 STARTTLS" response) or redirect the entire SMTP session (perhaps 76 | by overwriting the resolved MX record of the delivery domain). 77 | 78 | Because such "downgrade attacks" are not necessarily apparent to the 79 | receiving MTA, this document defines a mechanism for sending domains to 80 | report on failures at multiple stages of the MTA-to-MTA conversation. 81 | 82 | Recipient domains may also use the mechanisms defined by MTA-STS 83 | [@!I-D.ietf-uta-mta-sts] or DANE [@!RFC6698] to 84 | publish additional encryption and authentication requirements; this 85 | document defines a mechanism for sending domains that are compatible 86 | with MTA-STS or DANE to share success and failure statistics with 87 | recipient domains. 88 | 89 | Specifically, this document defines a reporting schema that covers 90 | failures in routing, DNS resolution, STARTTLS negotiation, and both 91 | DANE [@!RFC6698] and MTA-STS [@!I-D.ietf-uta-mta-sts] policy validation 92 | errors, and a standard TXT record that recipient domains can use to 93 | indicate where reports in this format should be sent. The report can 94 | also serve as a heartbeat that systems are successfully negotiating 95 | TLS during sessions as expected. 96 | 97 | This document is intended as a companion to the specification for SMTP 98 | MTA Strict Transport Security [@!I-D.ietf-uta-mta-sts], as well as adds 99 | reporting abilities for those implementing DANE [@!RFC7672]. 100 | 101 | ## Terminology 102 | 103 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 104 | "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 105 | document are to be interpreted as described in [BCP 14] [@!RFC2119] 106 | [@!RFC8174] when, and only when, they appear in all capitals, as shown here. 107 | 108 | We also define the following terms for further use in this document: 109 | 110 | * MTA-STS Policy: A mechanism by which administrators can specify the expected 111 | TLS availability, presented identity, and desired actions for a given 112 | email recipient domain. MTA-STS is defined in [@!I-D.ietf-uta-mta-sts]. 113 | * DANE Policy: A mechanism by which administrators can use DNSSEC 114 | to commit an MTA to support STARTTLS and to publish criteria to 115 | be used to validate its presented certificates. DANE for SMTP 116 | is defined in [RFC7672], with the base specification in [RFC6698] 117 | (updated in [RFC7671]. 118 | * TLSRPT Policy: A policy specifying the endpoint to which sending MTAs 119 | should deliver reports. 120 | * Policy Domain: The domain against which an MTA-STS or DANE Policy 121 | is defined. For MTA-STS this is typically the same as the envelope 122 | recipient domain [RFC5321], but when mail is routed to a "smarthost" 123 | gateway by local policy, the "smarthost" domain name is used instead. 124 | For DANE the Policy Domain is the "TLSA base domain" of the receiving 125 | SMTP server as described in [RFC7672] (Section 2.2.3) and [RFC6698] 126 | (Section 3). 127 | * Sending MTA: The MTA initiating the relay of an email message. 128 | * Aggregate Report URI (rua): A comma-separated list of locations where 129 | the report is to be submitted. 130 | 131 | # Related Technologies 132 | 133 | * This document is intended as a companion to the specification for SMTP 134 | MTA Strict Transport Security [@!I-D.ietf-uta-mta-sts]. 135 | * SMTP-TLSRPT defines a mechanism for sending domains that are 136 | compatible with MTA-STS or DANE to share success and failure 137 | statistics with recipient domains. DANE is defined in [@!RFC6698] and 138 | MTA-STS is defined in [@!I-D.ietf-uta-mta-sts]. 139 | 140 | # Reporting Policy 141 | 142 | A domain publishes a record to its DNS indicating that it wishes to 143 | receive reports. These SMTP TLSRPT policies are distributed via DNS from 144 | the Policy Domain's zone, as TXT records (similar to DMARC policies) 145 | under the name `_smtp._tls`. For example, for the Policy Domain 146 | `example.com`, the recipient's TLSRPT policy can be retrieved from 147 | `_smtp._tls.example.com`. 148 | 149 | Policies consist of the following directives: 150 | 151 | * `v`: This document defines version 1 of TLSRPT, for which this value MUST be 152 | equal to `TLSRPTv1`. Other versions may be defined in later documents. 153 | * `rua`: A URI specifying the endpoint to which aggregate information 154 | about policy validation results should be sent (see 155 | (#reporting-schema), "Reporting Schema", for more information). Two 156 | URI schemes are supported: `mailto` and `https`. As with DMARC 157 | [@?RFC7489], the policy domain can specify a comma-separated list of 158 | URIs. 159 | * In the case of `https`, reports should be submitted via POST 160 | ([@!RFC7231]) to the specified URI. Report submitters MAY ignore 161 | certificate validation errors when submitting reports via https. 162 | * In the case of `mailto`, reports should be submitted to the specified email 163 | address ([@!RFC6068]). When sending failure reports via SMTP, sending MTAs 164 | MUST deliver reports despite any TLS-related failures and SHOULD NOT include 165 | this SMTP session in the next report. When sending failure reports via HTTPS, 166 | sending MTAs MAY deliver reports despite any TLS-related faliures. This may 167 | mean that the reports are delivered in the clear. Reports sent via SMTP MUST 168 | contain a valid DKIM [@!RFC6376] signature by the reporting domain. Reports 169 | lacking such a signature MUST be ignored by the recipient. DKIM signatures 170 | must not use the "l=" attribute to limit the body length used in the 171 | signature. The DKIM TXT record must contain the appropriate service type 172 | declaration, `s=tlsrpt`, and if not present the receiving system SHOULD ignore 173 | reports signed using this record. 174 | 175 | The formal definition of the `_smtp._tls` TXT record, defined using 176 | [@!RFC5234] & [@!RFC7405], is as follows: 177 | 178 | tlsrpt-record = tlsrpt-version 1*(field-delim tlsrpt-field) 179 | [field-delim] 180 | 181 | field-delim = *WSP ";" *WSP 182 | 183 | tlsrpt-field = tlsrpt-rua / ; Note that the 184 | tlsrpt-extension ; tlsrpt-rua record is 185 | ; required. 186 | 187 | tlsrpt-version = %s"v=TLSRPTv1" 188 | 189 | tlsrpt-rua = %s"rua=" 190 | tlsrpt-uri *(*WSP "," *WSP tlsrpt-uri) 191 | 192 | tlsrpt-uri = URI 193 | ; "URI" is imported from [RFC3986]; 194 | ; commas (ASCII 0x2C), exclamation 195 | ; points (ASCII 0x21), and semicolons 196 | ; (ASCII 0x3B) MUST be encoded 197 | 198 | tlsrpt-extension = tlsrpt-ext-name "=" tlsrpt-ext-value 199 | 200 | tlsrpt-ext-name = (ALPHA / DIGIT) *31(ALPHA / 201 | DIGIT / "_" / "-" / ".") 202 | 203 | tlsrpt-ext-value = 1*(%x21-3A / %x3C / %x3E-7E) 204 | ; chars excluding "=", ";", SP, and control 205 | ; chars 206 | 207 | 208 | If multiple TXT records for `_smtp._tls` are returned by the resolver, 209 | records which do not begin with `v=TLSRPTv1;` are discarded. If the 210 | number of resulting records is not one, senders MUST assume the 211 | recipient domain does not implement TLSRPT. If the resulting TXT record 212 | contains multiple strings (as described in Section 3.1.3 of [@!RFC4408]), 213 | then the record MUST be treated as if those strings are concatenated 214 | together without adding spaces. 215 | 216 | The record supports the abillity to declare more than one rua, and if 217 | there exists more than one, the reporter MAY attempt to deliver to 218 | each of the supported rua destinations. A receiver MAY opt to only 219 | attempt delivery to one of the endpoints, however the report SHOULD NOT 220 | be considered successfully delivered until one of the endpoints accepts 221 | delivery of the report. 222 | 223 | Parsers MUST accept TXT records which are syntactically valid (i.e. 224 | valid key-value pairs separated by semi-colons) and implementing a 225 | superset of this specification, in which case unknown fields SHALL be 226 | ignored. 227 | 228 | ## Example Reporting Policy 229 | 230 | ### Report using MAILTO 231 | 232 | ``` 233 | _smtp._tls.example.com. IN TXT \ 234 | "v=TLSRPTv1;rua=mailto:reports@example.com" 235 | ``` 236 | 237 | ### Report using HTTPS 238 | 239 | ``` 240 | _smtp._tls.example.com. IN TXT \ 241 | "v=TLSRPTv1; \ 242 | rua=https://reporting.example.com/v1/tlsrpt" 243 | ``` 244 | 245 | # Reporting Schema 246 | 247 | The report is composed as a plain text file encoded in the I-JSON format 248 | ([@!RFC7493]). 249 | 250 | Aggregate reports contain the following fields: 251 | 252 | * Report metadata: 253 | * The organization responsible for the report 254 | * Contact information for one or more responsible parties for the 255 | contents of the report 256 | * A unique identifier for the report 257 | * The reporting date range for the report 258 | * Policy, consisting of: 259 | * One of the following policy types: (1) The MTA-STS policy applied 260 | (as a string) (2) The DANE TLSA record applied (as a string, with 261 | each RR entry of the RRset listed and separated by a semicolon) (3) 262 | The literal string `no-policy-found`, if neither a DANE nor MTA-STS 263 | policy could be found. 264 | * The domain for which the policy is applied 265 | * The MX host 266 | * Aggregate counts, comprising result type, sending MTA IP, receiving 267 | MTA hostname, session count, and an optional additional information 268 | field containing a URI for recipients to review further information on 269 | a failure type. 270 | 271 | Note that the failure types are non-exclusive; an aggregate report may 272 | contain overlapping `counts` of failure types when a single send attempt 273 | encountered multiple errors. Reporters may report multiple applied 274 | policies (for example, an MTA-STS policy and a DANE TLSA record for the 275 | same domain and MX). Because of this, even in the case where only a single 276 | policy was applied, the "policies" field of the report body MUST be an array and 277 | not a singular value. 278 | 279 | In the case of multiple failure types, the `failure-details` array 280 | would contain multiple entries. Each entry would have its own set of 281 | infomation pertaining to that failure type. 282 | 283 | ## Report Time-frame 284 | 285 | The report SHOULD cover a full day, from 0000-2400 UTC. This should 286 | allow for easier correlation of failure events. To avoid a Denial of 287 | Service against the system processing the reports, the reports should be 288 | delivered after some delay, perhaps several hours. 289 | 290 | As an example, a sending site might want to introduce a random delay of up 291 | to four hours: 292 | 293 | ``` 294 | func generate_sleep_delay() { 295 | min_delay = 1 296 | max_delay = 14400 297 | rand = random(min_delay,max_delay) 298 | return rand 299 | } 300 | 301 | func generate_report(policy_domain) { 302 | do_rpt_work(policy_domain) 303 | send_rpt(policy_domain) 304 | } 305 | 306 | func generate_tlsrpt() { 307 | sleep(generate_sleep_delay()) 308 | for policy_domain in list_of_tlsrpt_enabled_domains { 309 | generate_report(policy_domain) 310 | } 311 | } 312 | ``` 313 | 314 | A sending site might wish to introduce a random delay per destination 315 | site, up to four hours: 316 | 317 | ``` 318 | func generate_sleep_delay() { 319 | min_delay = 1 320 | max_delay = 14400 321 | rand = random(min_delay,max_delay) 322 | return rand 323 | } 324 | 325 | func generate_report(policy_domain) { 326 | sleep(generate_sleep_delay()) 327 | do_rpt_work(policy_domain) 328 | send_rpt(policy_domain) 329 | } 330 | 331 | func generate_tlsrpt() { 332 | for policy_domain in list_of_tlsrpt_enabled_domains { 333 | generate_report(policy_domain) 334 | } 335 | } 336 | ``` 337 | 338 | ## Delivery Summary 339 | 340 | ### Success Count 341 | 342 | * `total-successful-session-count`: This indicates that the sending MTA 343 | was able to successfully negotiate a policy-compliant TLS connection, 344 | and serves to provide a "heartbeat" to receiving domains that reporting 345 | is functional and tabulating correctly. This field contains an 346 | aggregate count of successful connections for the reporting system. 347 | 348 | ### Failure Count 349 | 350 | * `total-failure-session-count`: This indicates that the sending MTA was 351 | unable to successfully establish a connection with the receiving platform. 352 | (#result-types), "Result Types", will elaborate on the failed 353 | negotiation attempts. This field contains an aggregate count of 354 | failed connections. 355 | 356 | ## Result Types 357 | 358 | The list of result types will start with the minimal set below, and is 359 | expected to grow over time based on real-world experience. The initial 360 | set is: 361 | 362 | ### Negotiation Failures 363 | 364 | * `starttls-not-supported`: This indicates that the recipient MX did not 365 | support STARTTLS. 366 | * `certificate-host-mismatch`: This indicates that the certificate 367 | presented did not adhere to the constraints specified in the MTA-STS 368 | or DANE policy, e.g. if the MX hostname does not match any identities 369 | listed in the Subject Alternate Name (SAN) [@!RFC5280]. 370 | * `certificate-expired`: This indicates that the certificate has 371 | expired. 372 | * `certificate-not-trusted`: This a label that covers multiple 373 | certificate related failures that include, but not limited to errors 374 | such as untrusted/unknown CAs, certificate name constraints, 375 | certificate chain errors etc. When using this declaration, the 376 | reporting MTA SHOULD utilize the `failure-reason-code` to provide more 377 | information to the receiving entity. 378 | * `validation-failure`: This indicates a general failure for a reason 379 | not matching a category above. When using this declaration, the 380 | reporting MTA SHOULD utilize the `failure-reason-code` to provide more 381 | information to the receiving entity. 382 | 383 | ### Policy Failures 384 | 385 | #### DANE-specific Policy Failures 386 | 387 | * `tlsa-invalid`: This indicates a validation error in the TLSA record 388 | associated with a DANE policy. None of the records in the RRset were 389 | found to be valid. 390 | * `dnssec-invalid`: This would indicate that no valid records were 391 | returned from the recursive resolver. The request returned with 392 | SERVFAIL for the requested TLSA record. 393 | * `dane-required`: This indicates that the sending system is 394 | configured to require DANE TLSA records for all the MX hosts 395 | of the destination domain, but no DNSSEC-validated TLSA records 396 | were present for the MX host that is the subject of the report. 397 | Mandatory DANE for SMTP is described in section 6 of [@?RFC7672]. 398 | Such policies may be created by mutual agreement between two 399 | organizations that frequently exchange sensitive content via 400 | email. 401 | 402 | 403 | #### MTA-STS-specific Policy Failures 404 | 405 | * `sts-policy-invalid`: This indicates a validation error for the 406 | overall MTA-STS policy. 407 | * `sts-webpki-invalid`: This indicates that the MTA-STS policy could not 408 | be authenticated using PKIX validation. 409 | 410 | ### General Failures 411 | 412 | When a negotiation failure can not be categorized into one of the 413 | "Negotiation Failures" stated above, the reporter SHOULD use the 414 | `validation-failure` category. As TLS grows and becomes more complex, 415 | new mechanisms may not be easily categorized. This allows for a generic 416 | feedback category. When this category is used, the reporter SHOULD also 417 | use the `failure-reason-code` to give some feedback to the receiving 418 | entity. This is intended to be a short text field, and the contents of 419 | the field should be an error code or error text, such as 420 | "X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION". 421 | 422 | ### Transient Failures 423 | 424 | Transient errors due to too-busy network, TCP timeouts, etc. are not 425 | required to be reported. 426 | 427 | ## JSON Report Schema 428 | 429 | The JSON schema is derived from the HPKP JSON schema [@?RFC7469] (cf. 430 | Section 3) 431 | 432 | ``` 433 | { 434 | "organization-name": organization-name, 435 | "date-range": { 436 | "start-datetime": date-time, 437 | "end-datetime": date-time 438 | }, 439 | "contact-info": email-address, 440 | "report-id": report-id, 441 | "policies": [{ 442 | "policy": { 443 | "policy-type": policy-type, 444 | "policy-string": policy-string, 445 | "policy-domain": domain, 446 | "mx-host": mx-host-pattern 447 | }, 448 | "summary": { 449 | "total-successful-session-count": total-successful-session-count, 450 | "total-failure-session-count": total-failure-session-count 451 | }, 452 | "failure-details": [ 453 | { 454 | "result-type": result-type, 455 | "sending-mta-ip": ip-address, 456 | "receiving-mx-hostname": receiving-mx-hostname, 457 | "receiving-mx-helo": receiving-mx-helo, 458 | "receiving-ip": receiving-ip, 459 | "failed-session-count": failed-session-count, 460 | "additional-information": additional-info-uri, 461 | "failure-reason-code": failure-reason-code 462 | } 463 | ] 464 | } 465 | ] 466 | } 467 | 468 | ``` 469 | Figure: JSON Report Format 470 | 471 | * `organization-name`: The name of the organization responsible for the 472 | report. It is provided as a string. 473 | * `date-time`: The date-time indicates the start- and end-times for the 474 | report range. It is provided as a string formatted according to 475 | Section 5.6, "Internet Date/Time Format", of [@!RFC3339]. The report 476 | should be for a full UTC day, 0000-2400. 477 | * `email-address`: The contact information for a responsible party of 478 | the report. It is provided as a string formatted according to Section 479 | 3.4.1, "Addr-Spec", of [@!RFC5321]. 480 | * `report-id`: A unique identifier for the report. Report authors may 481 | use whatever scheme they prefer to generate a unique identifier. It is 482 | provided as a string. 483 | * `policy-type`: The type of policy that was applied by the sending 484 | domain. Presently, the only three valid choices are `tlsa`, `sts`, 485 | and the literal string `no-policy-found`. It is provided as a string. 486 | * `policy-string`: An encoding of the applied policy as a JSON array of 487 | strings, whether TLSA record ([@!RFC6698] section 2.3) or MTA-STS 488 | policy. Examples follow in the next section. 489 | * `domain`: The Policy Domain is the domain against which the MTA-STS or 490 | DANE policy is defined. In the case of Internationalized Domain Names 491 | ([@?RFC5891]), the domain MUST consist of the Punycode-encoded 492 | A-labels ([@!RFC3492]) and not the U-labels. 493 | * `mx-host-pattern`: The pattern of MX hostnames from the applied 494 | policy. It is provided as a string, and is interpreted in the same 495 | manner as the "Checking of Wildcard Certificates" rules in Section 496 | 6.4.3 of [@!RFC6125]. In the case of Internationalized Domain Names 497 | ([@!RFC5891]), the domain MUST consist of the Punycode-encoded 498 | A-labels ([@!RFC3492]) and not the U-labels. 499 | * `result-type`: A value from (#result-types), "Result Types", above. 500 | * `ip-address`: The IP address of the sending MTA that attempted the 501 | STARTTLS connection. It is provided as a string representation of an 502 | IPv4 (see below) or IPv6 ([@!RFC5952]) address in dot-decimal or 503 | colon-hexadecimal notation. 504 | * `receiving-mx-hostname`: The hostname of the receiving MTA MX record 505 | with which the sending MTA attempted to negotiate a STARTTLS 506 | connection. 507 | * `receiving-mx-helo`: (optional) The HELO or EHLO string from the 508 | banner announced during the reported session. 509 | * `receiving-ip`: The destination IP address that was using when 510 | creating the outbound session. It is provided as a string 511 | representation of an IPv4 (see below) or IPv6 ([@!RFC5952]) address 512 | in dot-decimal or colon-hexadecimal notation. 513 | * `total-successful-session-count`: The aggregate count (integer, encoded as a 514 | JSON number) of successfully negotiated TLS-enabled connections to the 515 | receiving site. 516 | * `total-failure-session-count`: The aggregate count (integer, encoded as a JSON 517 | number) of failures to negotiate a TLS-enabled connection to the receiving 518 | site. 519 | * `failed-session-count`: The number of (attempted) sessions that match 520 | the relevant `result-type` for this section (integer, encoded as a JSON 521 | number). 522 | * `additional-info-uri`: An optional URI [@!RFC3986] pointing to 523 | additional information around the relevant `result-type`. For example, 524 | this URI might host the complete certificate chain presented during an 525 | attempted STARTTLS session. 526 | * `failure-reason-code`: A text field to include a TLS-related error 527 | code or error message. 528 | 529 | For report purposes, an IPv4 Address is defined via the following ABNF: 530 | 531 | IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet 532 | dec-octet = DIGIT ; 0-9 533 | / %x31-39 DIGIT ; 10-99 534 | / "1" 2DIGIT ; 100-199 535 | / "2" %x30-34 DIGIT ; 200-249 536 | / "25" %x30-35 ; 250-255 537 | 538 | 539 | ## Policy Samples 540 | 541 | Part of the report body includes the policy that is applied when attemping 542 | relay to the destination. 543 | 544 | For DANE TLSA policies, this is a JSON array of strings each representing the 545 | RDATA of a single TLSA resource record as a space-separated list of its four 546 | TLSA fields; the fields are in presentation format (defined in [@!RFC6698] 547 | Section 2.2) with no internal spaces or grouping parentheses: 548 | 549 | ``` 550 | [ 551 | "3 0 1 1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513D747D1D085D", 552 | "3 0 1 12350A337E6DB9C6123522D136A475638CC43E1ED424F8EEC8513D747D1D1234" 553 | ] 554 | ``` 555 | 556 | For MTA-STS policies, this is an array of JSON strings that represents the 557 | policy that is declared by the receiving site, including any errors that may be 558 | present. Note that where there are multiple "mx" values, they must be listed 559 | as separate "mx" elements in the policy array, rather as a single nested "mx" 560 | sub-array. 561 | 562 | ``` 563 | [ 564 | "version: STSv1", 565 | "mode: testing", 566 | "mx: mx1.example.com", 567 | "mx: mx2.example.com", 568 | "mx: mx.backup-example.com", 569 | "max_age: 604800" 570 | ] 571 | ``` 572 | # Report Delivery 573 | 574 | Reports can be delivered either as an email message via SMTP or via HTTP 575 | POST. 576 | 577 | ## Report Filename 578 | 579 | The filename is RECOMMENDED to be constructed using the following ABNF: 580 | 581 | filename = sender "!" policy-domain "!" begin-timestamp 582 | "!" end-timestamp [ "!" unique-id ] "." extension 583 | 584 | unique-id = 1*(ALPHA / DIGIT) 585 | 586 | sender = domain ; From the [RFC5321] that is used 587 | ; as the domain for the `contact-info` 588 | ; address in the report body. 589 | ; In the case of Internationalized Domain 590 | ; Names ([@?RFC5891]), the domain MUST consist of 591 | ; the Punycode-encoded A-labels ([@!RFC3492]) and 592 | ; not the U-labels. 593 | 594 | 595 | policy-domain = domain 596 | ; In the case of Internationalized Domain 597 | ; Names ([@?RFC5891]), the domain MUST consist of 598 | ; the Punycode-encoded A-labels ([@!RFC3492]) and 599 | ; not the U-labels. 600 | 601 | begin-timestamp = 1*DIGIT 602 | ; seconds since 00:00:00 UTC January 1, 1970 603 | ; indicating start of the time range contained 604 | ; in the report 605 | 606 | end-timestamp = 1*DIGIT 607 | ; seconds since 00:00:00 UTC January 1, 1970 608 | ; indicating end of the time range contained 609 | ; in the report 610 | 611 | extension = "json" / "json.gz" 612 | 613 | 614 | The extension MUST be "json" for a plain JSON file, or "json.gz" for a 615 | JSON file compressed using GZIP. 616 | 617 | "unique-id" allows an optional unique ID generated by the Sending MTA to 618 | distinguish among multiple reports generated simultaneously by different 619 | sources within the same Policy Domain. For example, this is a possible 620 | filename for a compressed report to the Policy Domain "example.net" 621 | from the Sending MTA "mail.sndr.example.com": 622 | 623 | `mail.sndr.example.com!example.net!1470013207!1470186007!001.json.gz` 624 | 625 | ## Compression 626 | 627 | The report SHOULD be subjected to GZIP [@!RFC1952] compression for both email 628 | and HTTPS transport. Declining to apply compression can cause the report to 629 | be too large for a receiver to process (a commonly observed receiver 630 | limit is ten megabytes); compressing the file increases the chances of 631 | acceptance of the report at some compute cost. 632 | 633 | ## Email Transport 634 | 635 | The report MAY be delivered by email. To make the reports 636 | machine-parsable for the receivers, we define a top-level media type 637 | `multipart/report` with a new parameter `report-type="tlsrpt"`. Inside 638 | it, there are two parts: The first part is human readable, typically 639 | `text/plain`, and the second part is machine readable with a new media 640 | type defined called `application/tlsrpt+json`. If compressed, the 641 | report should use the media type `application/tlsrpt+gzip`. 642 | 643 | In addition, the following two new top level message header fields are 644 | defined: 645 | 646 | `TLS-Report-Domain: Receiver-Domain` 647 | 648 | `TLS-Report-Submitter: Sender-Domain` 649 | 650 | The `TLS-Report-Submitter` value MUST match the value found in the 651 | [@!RFC5321] domain from the `contact-info` from the report body. These 652 | message headers MUST be included and should allow for easy searching 653 | for all reports submitted by a report domain or a particular submitter, 654 | for example in IMAP [@?RFC3501]: 655 | 656 | `s SEARCH HEADER "TLS-Report-Domain" "example.com"` 657 | 658 | It is presumed that the aggregate reporting address will be equipped to 659 | process new message header fields and extract MIME parts with the 660 | prescribed media type and filename, and ignore the rest. These 661 | additional headers SHOULD be included in the DKIM [@!RFC6376] signature 662 | for the message. 663 | 664 | The [@!RFC5322].Subject field for report submissions SHOULD conform to 665 | the following ABNF: 666 | 667 | tlsrpt-subject = %s"Report" FWS ; "Report" 668 | %s"Domain:" FWS ; "Domain:" 669 | domain-name FWS ; per [RFC6376] 670 | %s"Submitter:" FWS ; "Submitter:" 671 | domain-name FWS ; per [RFC6376] 672 | %s"Report-ID:" FWS ; "Report-ID: 673 | "<" id-left "@" id-right ">" ; per [RFC5322] 674 | [CFWS] ; per [RFC5322] 675 | ; (as with FWS) 676 | 677 | The first domain-name indicates the DNS domain name about which the 678 | report was generated. The second domain-name indicates the DNS domain 679 | name representing the Sending MTA generating the report. The purpose 680 | of the Report-ID: portion of the field is to enable the Policy Domain 681 | to identify and ignore duplicate reports that might be sent by a 682 | Sending MTA. 683 | 684 | For instance, this is a possible Subject field for a report to the 685 | Policy Domain "example.net" from the Sending MTA 686 | "mail.sender.example.com". It is line-wrapped as allowed 687 | by [@!RFC5322]: 688 | 689 | ``` 690 | Subject: Report Domain: example.net 691 | Submitter: mail.sender.example.com 692 | Report-ID: <735ff.e317+bf22029@mailexample.net> 693 | ``` 694 | 695 | ### Example Report 696 | ``` 697 | From: tlsrpt@mail.sender.example.com 698 | Date: Fri, May 09 2017 16:54:30 -0800 699 | To: mts-sts-tlsrpt@example.net 700 | Subject: Report Domain: example.net 701 | Submitter: mail.sender.example.com 702 | Report-ID: <735ff.e317+bf22029@example.net> 703 | TLS-Report-Domain: example.net 704 | TLS-Report-Submitter: mail.sender.example.com 705 | MIME-Version: 1.0 706 | Content-Type: multipart/report; report-type="tlsrpt"; 707 | boundary="----=_NextPart_000_024E_01CC9B0A.AFE54C00" 708 | Content-Language: en-us 709 | 710 | This is a multipart message in MIME format. 711 | 712 | ------=_NextPart_000_024E_01CC9B0A.AFE54C00 713 | Content-Type: text/plain; charset="us-ascii" 714 | Content-Transfer-Encoding: 7bit 715 | 716 | This is an aggregate TLS report from mail.sender.example.com 717 | 718 | ------=_NextPart_000_024E_01CC9B0A.AFE54C00 719 | Content-Type: application/tlsrpt+gzip 720 | Content-Transfer-Encoding: base64 721 | Content-Disposition: attachment; 722 | filename="mail.sender.example!example.com! 723 | 1013662812!1013749130.json.gz" 724 | 725 | 726 | 727 | ------=_NextPart_000_024E_01CC9B0A.AFE54C00-- 728 | ... 729 | ``` 730 | 731 | Note that, when sending failure reports via SMTP, sending MTAs MUST NOT 732 | honor MTA-STS or DANE TLSA failures. 733 | 734 | ## HTTPS Transport 735 | 736 | The report MAY be delivered by POST to HTTPS. If compressed, the report 737 | SHOULD use the media type `application/tlsrpt+gzip`, and 738 | `application/tlsrpt+json` otherwise (see section (#iana-considerations), 739 | "IANA Considerations"). 740 | 741 | The receiving system MUST return a "successful" response from its HTTPS 742 | server, typically a 200 or 201 HTTP code [@?RFC7321]. Other codes could 743 | indicate a delivery failure, and may be retried as per local sender policy. 744 | The receiving system is not expected to process reports at receipt time, and 745 | MAY store them for processing at a later time. 746 | 747 | ## Delivery Retry 748 | 749 | In the event of a delivery failure, regardless of the delivery method, a 750 | sender SHOULD attempt redelivery for up to 24hrs after the initial 751 | attempt. As previously stated the reports are optional, so while it is 752 | ideal to attempt redelivery, it is not required. If multiple retries 753 | are attempted, ideally they SHOULD be done with exponential backoff. 754 | 755 | ## Metadata Variances 756 | 757 | As stated above, there are a variable number of ways to declare 758 | information about the data therein. If any of items declared via 759 | subject or filename disagree with the report, the report MUST be 760 | considered the authoritative source. 761 | 762 | # IANA Considerations 763 | 764 | The following are the IANA considerations discussed in this document. 765 | 766 | ## Message headers 767 | 768 | Below is the Internet Assigned Numbers Authority (IANA) Permanent 769 | Message Header Field registration information per [@?RFC3864]. 770 | 771 | Header field name: TLS-Report-Domain 772 | Applicable protocol: mail 773 | Status: standard 774 | Author/Change controller: IETF 775 | Specification document(s): this one 776 | 777 | 778 | Header field name: TLS-Report-Submitter 779 | Applicable protocol: mail 780 | Status: standard 781 | Author/Change controller: IETF 782 | Specification document(s): this one 783 | 784 | ## Report Type 785 | 786 | This document creates a new registry for "report-type" parameter to 787 | the Content-Type header field for the "multipart/report" top-level media 788 | type defined in [@!RFC6522]. 789 | 790 | The registry name is "Report Type Registry", and the procedure for 791 | updating the registry will be "Specification Required". 792 | 793 | An entry in this registry should contain: 794 | 795 | * the report-type being registered 796 | 797 | * one or more registered media-types that can be used with this report-type 798 | 799 | * the document containing the registration action 800 | 801 | * an optional comment 802 | 803 | The initial entries are: 804 | 805 | Report-Type: tlsrpt 806 | Media Type: application/tlsrpt+gzip, application/tlsrpt+json 807 | Registered By: [RFCXXXX] 808 | Comment: Media types suitable for use with this report-type are defined in Sections 6.4 and 6.5 of [RFCXXXX] 809 | 810 | Report-Type: disposition-notification 811 | Media Type: message/disposition-notification 812 | Registered By: [@?RFC8098] Section 10 813 | 814 | Report-Type: disposition-notification 815 | Media Type: message/global-disposition-notification 816 | Registered By: [@?RFC6533] Section 6 817 | 818 | Report-Type: delivery-status 819 | Media Type: message/delivery-status 820 | Registered By: [@?RFC3464] Appendix D 821 | 822 | Report-Type: delivery-status 823 | Media Type: message/global-delivery-status 824 | Registered By: [@?RFC6533] Section 6 825 | 826 | ## +gzip Media Type Suffix 827 | 828 | This document registers a new media type suffix "+gzip". The GZIP 829 | format is a public domain, cross-platform, interoperable file 830 | storage and transfer format, specified in [@!RFC1952]; it 831 | supports compression and is used as the underlying representation 832 | by a variety of file formats. The media type "application/gzip" 833 | has been registered for such files. The suffix "+gzip" MAY be 834 | used with any media type whose representation follows that 835 | established for "application/gzip". The media type structured 836 | syntax suffix registration form follows: 837 | 838 | Type name: GZIP file storage and transfer format 839 | 840 | +suffix: +gzip 841 | 842 | References: [@!RFC1952][@!RFC6713] 843 | 844 | Encoding considerations: GZIP is a binary encoding. 845 | 846 | Fragment identifier considerations: The syntax and semantics 847 | of fragment identifiers specified for 848 | +gzip SHOULD be as specified for "application/gzip". (At 849 | publication of this document, there is no fragment identification 850 | syntax defined for "application/gzip".) The syntax and semantics 851 | for fragment identifiers for a specific "xxx/yyy+gzip" SHOULD be 852 | processed as follows: 853 | 854 | For cases defined in +gzip, where the fragment identifier 855 | resolves per the +gzip rules, then process as specified in 856 | +gzip. 857 | 858 | For cases defined in +gzip, where the fragment identifier does 859 | not resolve per the +gzip rules, then process as specified in 860 | "xxx/yyy+gzip". 861 | 862 | For cases not defined in +gzip, then process as specified in 863 | "xxx/yyy+gzip". 864 | 865 | Interoperability considerations: n/a 866 | 867 | Security considerations: GZIP format doesn't provide confidentiality protection. 868 | Integrity protection is provided by an Adler-32 checksum, which is not 869 | cryptographically strong. See also security considerations of [@?RFC6713]. 870 | Each individual media type registered with a +gzip suffix can have additional 871 | security considerations. Additionally, GZIP objects can contain multiple 872 | files and associated paths. File paths must be validated when the files 873 | are extracted; a malicious file path could otherwise cause the extractor 874 | to overwrite application or system files. 875 | 876 | Contact: art@ietf.org 877 | 878 | Author/Change controller: Internet Engineering Task Force 879 | (mailto:iesg@ietf.org). 880 | 881 | ## application/tlsrpt+json Media Type 882 | 883 | This document registers multiple media types, beginning with Table 1 884 | below. 885 | 886 | +-------------+----------------+-------------+-------------------+ 887 | | Type | Subtype | File extn | Specification | 888 | +-------------+----------------+-------------+-------------------+ 889 | | application | tlsrpt+json | .json | Section 5.3 | 890 | +-------------+----------------+-------------+-------------------+ 891 | Table 1: SMTP TLS Reporting Media Type 892 | 893 | Type name: application 894 | 895 | Subtype name: tlsrpt+json 896 | 897 | Required parameters: n/a 898 | 899 | Optional parameters: n/a 900 | 901 | Encoding considerations: Encoding considerations are identical to 902 | those specified for the `application/json` media type. See 903 | [@!RFC7493]. 904 | 905 | Security considerations: Security considerations relating to SMTP 906 | TLS Reporting are discussed in Section 7. 907 | 908 | Interoperability considerations: This document specifies format of 909 | conforming messages and the interpretation thereof. 910 | 911 | Published specification: Section 5.3 of this document. 912 | 913 | Applications that use this media type: Mail User Agents (MUA) and 914 | Mail Transfer Agents. 915 | 916 | Additional information: 917 | 918 | Magic number(s): n/a 919 | 920 | File extension(s): ".json" 921 | 922 | Macintosh file type code(s): n/a 923 | 924 | Person & email address to contact for further information: See 925 | Authors' Addresses section. 926 | 927 | Intended usage: COMMON 928 | 929 | Restrictions on usage: n/a 930 | 931 | Author: See Authors' Addresses section. 932 | 933 | Change controller: Internet Engineering Task Force 934 | (mailto:iesg@ietf.org). 935 | 936 | ## application/tlsrpt+gzip Media Type 937 | 938 | 939 | +-------------+----------------+-------------+-------------------+ 940 | | Type | Subtype | File extn | Specification | 941 | +-------------+----------------+-------------+-------------------+ 942 | | application | tlsrpt+gzip | .gz | Section 5.3 | 943 | +-------------+----------------+-------------+-------------------+ 944 | Table 2: SMTP TLS Reporting Media Type 945 | 946 | Type name: application 947 | 948 | Subtype name: tlsrpt+gzip 949 | 950 | Required parameters: n/a 951 | 952 | Optional parameters: n/a 953 | 954 | Encoding considerations: Binary 955 | 956 | Security considerations: Security considerations relating to SMTP 957 | TLS Reporting are discussed in Section 7. Security 958 | considerations related to gzip compression are discussed 959 | in [RFC6713]. 960 | 961 | Interoperability considerations: This document specifies format of 962 | conforming messages and the interpretation thereof. 963 | 964 | Published specification: Section 5.3 of this document. 965 | 966 | Applications that use this media type: Mail User Agents (MUA) and 967 | Mail Transfer Agents. 968 | 969 | Additional information: 970 | 971 | Magic number(s): The first two bytes are 0x1f, 0x8b. 972 | 973 | File extension(s): ".gz" 974 | 975 | Macintosh file type code(s): n/a 976 | 977 | Person & email address to contact for further information: See 978 | Authors' Addresses section. 979 | 980 | Intended usage: COMMON 981 | 982 | Restrictions on usage: n/a 983 | 984 | Author: See Authors' Addresses section. 985 | 986 | Change controller: Internet Engineering Task Force 987 | (mailto:iesg@ietf.org). 988 | 989 | ## STARTTLS Validation Result Types 990 | 991 | This document creates a new registry, "STARTTLS Validation Result 992 | Types". The initial entries in the registry are: 993 | 994 | +-------------------------------+-----------+ 995 | | Result Type | Desc | 996 | +-------------------------------+-----------+ 997 | | "starttls-not-supported" | 4.3 | 998 | | "certificate-host-mismatch" | 4.3 | 999 | | "certificate-expired" | 4.3 | 1000 | | "tlsa-invalid" | 4.3 | 1001 | | "dnssec-invalid" | 4.3 | 1002 | | "dane-required" | 4.3 | 1003 | | "certificate-not-trusted" | 4.3 | 1004 | | "sts-policy-invalid" | 4.3 | 1005 | | "sts-webpki-invalid" | 4.3 | 1006 | | "validation-failure" | 4.3 | 1007 | +-------------------------------+-----------+ 1008 | 1009 | The above entries are described in section (#result-types), "Result 1010 | Types." New result types can be added to this registry using "Expert 1011 | Review" IANA registration policy. 1012 | 1013 | # Security Considerations 1014 | 1015 | SMTP TLS Reporting provides transparency into misconfigurations or 1016 | attempts to intercept or tamper with mail between hosts who support 1017 | STARTTLS. There are several security risks presented by the existence of 1018 | this reporting channel: 1019 | 1020 | * Flooding of the Aggregate report URI (rua) endpoint: An attacker could 1021 | flood the endpoint with excessive reporting traffic and prevent the 1022 | receiving domain from accepting additional reports. This type of 1023 | Denial-of-Service attack would limit visibility into STARTTLS 1024 | failures, leaving the receiving domain blind to an ongoing attack. 1025 | 1026 | * Untrusted content: An attacker could inject malicious code into the 1027 | report, opening a vulnerability in the receiving domain. Implementers 1028 | are advised to take precautions against evaluating the contents of the 1029 | report. 1030 | 1031 | * Report snooping: An attacker could create a bogus TLSRPT record to 1032 | receive statistics about a domain the attacker does not own. Since an 1033 | attacker able to poison DNS is already able to receive counts of SMTP 1034 | connections (and, absent DANE or MTA-STS policies, actual SMTP message 1035 | payloads), this does not present a significant new vulnerability. 1036 | 1037 | * Ignoring HTTPS validation when submitting reports: When reporting benign 1038 | misconfigurations, it is likely that a misconfigured SMTP server may also 1039 | mean a misconfigured HTTPS server; as a result, reporters who required 1040 | HTTPS validity on the reporting endpoint may fail to alert administrators 1041 | about such misconfigurations. Conversely, in the event of an actual attack, 1042 | an attacker who wished to create a gap in reporting and could intercept 1043 | HTTPS reports could, just as easily, simply thwart the resolution of the 1044 | TLSRPT TXT record or establishment of the TCP session to the HTTPS endpoint. 1045 | Furthermore, such a man-in-the-middle attacker could discover most or all of 1046 | the metadata exposed in a report merely through passive observation. As a 1047 | result, we consider the risks of failure to deliver reports on 1048 | misconfigurations to outweigh those of attackers intercepting reports. 1049 | 1050 | * Reports as DDoS: TLSRPT allows specifying destinations for the reports 1051 | that are outside the authority of the Policy Domain, which allows 1052 | domains to delegate processing of reports to a partner organization. 1053 | However, an attacker who controls the Policy Domain DNS could also use 1054 | this mechanism to direct the reports to an unwitting victim, flooding 1055 | that victim with excessive reports. DMARC [@?RFC7489] defines a 1056 | solution for verifying delegation to avoid such attacks; the need for 1057 | this is greater with DMARC, however, because DMARC allows an attacker 1058 | to trigger reports to a target from an innocent third party by sending 1059 | that third party mail (which triggers a report from the third party to 1060 | the target). In the case of TLSRPT, the attacker would have to induce 1061 | the third party to send the attacker mail in order to trigger reports 1062 | from the third party to the victim; this reduces the risk of such an 1063 | attack and the need for a verification mechanism. 1064 | 1065 | Finally, because TLSRPT is intended to help administrators discover 1066 | man-in-the-middle attacks against transport-layer encryption, including 1067 | attacks designed to thwart negotiation of encrypted connections (by 1068 | downgrading opportunistic encryption or, in the case of MTA-STS, 1069 | preventing discovery of a new MTA-STS policy), we must also consider the 1070 | risk that an adversary who can induce such a downgrade attack can also 1071 | prevent discovery of the TLSRPT TXT record (and thus prevent discovery 1072 | of the successful downgrade attack). Administrators are thus encouraged 1073 | to deploy TLSRPT TXT records with a large TTL (reducing the window for 1074 | successful application of transient attacks against DNS resolution of the 1075 | record) or to deploy DNSSEC on the deploying zone. 1076 | 1077 | # Privacy Considerations 1078 | 1079 | MTAs are generally considered public knowledge, however, the internals 1080 | of how those MTAs are configured and the users of those MTAs may not be 1081 | as public. It should be noted that when providing a receiving site with 1082 | information, it may reveal information about the sender's configuration, 1083 | or even information about the senders themselves. Consider that by sending 1084 | a report, it might disclose your SSL library version as the inability to 1085 | negotiate a session may be a known incompatbility between two library 1086 | versions, or perhaps commonly used in a operating system release that is 1087 | centered in a certain region. The risk may be minimal, but should be 1088 | considered. 1089 | 1090 | {backmatter} 1091 | 1092 | # Example Reporting Policy 1093 | 1094 | ## Report using MAILTO 1095 | 1096 | ``` 1097 | _smtp._tls.mail.example.com. IN TXT \ 1098 | "v=TLSRPTv1;rua=mailto:reports@example.com" 1099 | ``` 1100 | 1101 | ## Report using HTTPS 1102 | 1103 | ``` 1104 | _smtp._tls.mail.example.com. IN TXT \ 1105 | "v=TLSRPTv1; \ 1106 | rua=https://reporting.example.com/v1/tlsrpt" 1107 | ``` 1108 | 1109 | # Example JSON Report 1110 | 1111 | Below is an example JSON report for messages from Company-X to Company-Y, 1112 | where 100 sessions were attempted to Company Y servers with an expired 1113 | certificate and 200 sessions were attempted to Company Y servers that 1114 | did not successfully respond to the `STARTTLS` command. Additionally 3 1115 | sessions failed due to "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED". 1116 | 1117 | ``` 1118 | { 1119 | "organization-name": "Company-X", 1120 | "date-range": { 1121 | "start-datetime": "2016-04-01T00:00:00Z", 1122 | "end-datetime": "2016-04-01T23:59:59Z" 1123 | }, 1124 | "contact-info": "sts-reporting@company-x.example", 1125 | "report-id": "5065427c-23d3-47ca-b6e0-946ea0e8c4be", 1126 | "policies": [{ 1127 | "policy": { 1128 | "policy-type": "sts", 1129 | "policy-string": ["version: STSv1","mode: testing", 1130 | "mx: *.mail.company-y.example","max_age: 86400"], 1131 | "policy-domain": "company-y.example", 1132 | "mx-host": "*.mail.company-y.example" 1133 | }, 1134 | "summary": { 1135 | "total-successful-session-count": 5326, 1136 | "total-failure-session-count": 303 1137 | }, 1138 | "failure-details": [{ 1139 | "result-type": "certificate-expired", 1140 | "sending-mta-ip": "2001:db8:abcd:0012::1", 1141 | "receiving-mx-hostname": "mx1.mail.company-y.example", 1142 | "failed-session-count": 100 1143 | }, { 1144 | "result-type": "starttls-not-supported", 1145 | "sending-mta-ip": "2001:db8:abcd:0013::1", 1146 | "receiving-mx-hostname": "mx2.mail.company-y.example", 1147 | "receiving-ip": "203.0.113.56", 1148 | "failed-session-count": 200, 1149 | "additional-information": "https://reports.company-x.example/ 1150 | report_info ? id = 5065427 c - 23 d3# StarttlsNotSupported " 1151 | }, { 1152 | "result-type": "validation-failure", 1153 | "sending-mta-ip": "198.51.100.62", 1154 | "receiving-ip": "203.0.113.58", 1155 | "receiving-mx-hostname": "mx-backup.mail.company-y.example", 1156 | "failed-session-count": 3, 1157 | "failure-reason-code": "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED" 1158 | }] 1159 | }] 1160 | } 1161 | 1162 | ``` 1163 | 1164 | -------------------------------------------------------------------------------- /reporting.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | SMTP TLS Reporting 14 | 15 | 16 | Google, Inc 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | dmargolis@google.com 27 | 28 |
29 | 30 | 31 | Comcast, Inc 32 |
33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | alex_brotman@comcast.com 42 | 43 |
44 | 45 | 46 | Yahoo!, Inc 47 |
48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | rbinu@oath.com 57 | 58 |
59 | 60 | 61 | Microsoft, Inc 62 |
63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | janet.jones@microsoft.com 72 | 73 |
74 | 75 | 76 | Google, Inc 77 |
78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | risher@google.com 87 | 88 |
89 | 90 | 91 | 92 | Applications 93 | Using TLS in Applications 94 | 95 | 96 | 97 | 98 | A number of protocols exist for establishing encrypted channels between 99 | SMTP Mail Transfer Agents, including STARTTLS, DANE TLSA, and MTA-STS. 100 | These protocols can fail due to misconfiguration or active attack, 101 | leading to undelivered messages or delivery over unencrypted or 102 | unauthenticated channels. This document describes a reporting mechanism 103 | and format by which sending systems can share statistics and specific 104 | information about potential failures with recipient domains. Recipient 105 | domains can then use this information to both detect potential attacks and 106 | diagnose unintentional misconfigurations. 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 |
116 | The STARTTLS extension to SMTP allows SMTP clients and hosts 117 | to establish secure SMTP sessions over TLS. The protocol design uses an 118 | approach that has come to be known as "Opportunistic Security" (OS) 119 | . This method maintains interoperability with clients that do 120 | not support STARTTLS, but means that any attacker could potentially 121 | eavesdrop on a session. An attacker could perform a downgrade or 122 | interception attack by deleting parts of the SMTP session (such as the 123 | "250 STARTTLS" response) or redirect the entire SMTP session (perhaps 124 | by overwriting the resolved MX record of the delivery domain). 125 | 126 | Because such "downgrade attacks" are not necessarily apparent to the 127 | receiving MTA, this document defines a mechanism for sending domains to 128 | report on failures at multiple stages of the MTA-to-MTA conversation. 129 | 130 | Recipient domains may also use the mechanisms defined by MTA-STS 131 | or DANE to 132 | publish additional encryption and authentication requirements; this 133 | document defines a mechanism for sending domains that are compatible 134 | with MTA-STS or DANE to share success and failure statistics with 135 | recipient domains. 136 | 137 | Specifically, this document defines a reporting schema that covers 138 | failures in routing, DNS resolution, STARTTLS negotiation, and both 139 | DANE and MTA-STS policy validation 140 | errors, and a standard TXT record that recipient domains can use to 141 | indicate where reports in this format should be sent. The report can 142 | also serve as a heartbeat that systems are successfully negotiating 143 | TLS during sessions as expected. 144 | 145 | This document is intended as a companion to the specification for SMTP 146 | MTA Strict Transport Security , as well as adds 147 | reporting abilities for those implementing DANE . 148 | 149 | 150 |
151 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 152 | "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 153 | document are to be interpreted as described in [BCP 14] 154 | when, and only when, they appear in all capitals, as shown here. 155 | 156 | We also define the following terms for further use in this document: 157 | 158 | 159 | 160 | MTA-STS Policy: A mechanism by which administrators can specify the expected 161 | TLS availability, presented identity, and desired actions for a given 162 | email recipient domain. MTA-STS is defined in . 163 | DANE Policy: A mechanism by which administrators can use DNSSEC 164 | to commit an MTA to support STARTTLS and to publish criteria to 165 | be used to validate its presented certificates. DANE for SMTP 166 | is defined in [RFC7672], with the base specification in [RFC6698] 167 | (updated in [RFC7671]. 168 | TLSRPT Policy: A policy specifying the endpoint to which sending MTAs 169 | should deliver reports. 170 | Policy Domain: The domain against which an MTA-STS or DANE Policy 171 | is defined. For MTA-STS this is typically the same as the envelope 172 | recipient domain [RFC5321], but when mail is routed to a "smarthost" 173 | gateway by local policy, the "smarthost" domain name is used instead. 174 | For DANE the Policy Domain is the "TLSA base domain" of the receiving 175 | SMTP server as described in RFC7672 and RFC6698. 176 | Sending MTA: The MTA initiating the relay of an email message. 177 | Aggregate Report URI (rua): A comma-separated list of locations where 178 | the report is to be submitted. 179 | 180 | 181 |
182 |
183 | 184 |
185 | 186 | 187 | This document is intended as a companion to the specification for SMTP 188 | MTA Strict Transport Security . 189 | SMTP-TLSRPT defines a mechanism for sending domains that are 190 | compatible with MTA-STS or DANE to share success and failure 191 | statistics with recipient domains. DANE is defined in and 192 | MTA-STS is defined in . 193 | 194 | 195 |
196 | 197 |
198 | A domain publishes a record to its DNS indicating that it wishes to 199 | receive reports. These SMTP TLSRPT policies are distributed via DNS from 200 | the Policy Domain's zone, as TXT records (similar to DMARC policies) 201 | under the name _smtp._tls. For example, for the Policy Domain 202 | example.com, the recipient's TLSRPT policy can be retrieved from 203 | _smtp._tls.example.com. 204 | 205 | Policies consist of the following directives: 206 | 207 | 208 | 209 | v: This document defines version 1 of TLSRPT, for which this value MUST be 210 | equal to TLSRPTv1. Other versions may be defined in later documents. 211 | rua: A URI specifying the endpoint to which aggregate information 212 | about policy validation results should be sent (see 213 | , "Reporting Schema", for more information). Two 214 | URI schemes are supported: mailto and https. As with DMARC 215 | , the policy domain can specify a comma-separated list of 216 | URIs. 217 | In the case of https, reports should be submitted via POST 218 | () to the specified URI. Report submitters MAY ignore 219 | certificate validation errors when submitting reports via https. 220 | In the case of mailto, reports should be submitted to the specified email 221 | address (). When sending failure reports via SMTP, sending MTAs 222 | MUST deliver reports despite any TLS-related failures and SHOULD NOT include 223 | this SMTP session in the next report. When sending failure reports via HTTPS, 224 | sending MTAs MAY deliver reports despite any TLS-related faliures. This may 225 | mean that the reports are delivered in the clear. Reports sent via SMTP MUST 226 | contain a valid DKIM signature by the reporting domain. Reports 227 | lacking such a signature MUST be ignored by the recipient. DKIM signatures 228 | must not use the "l=" attribute to limit the body length used in the 229 | signature. The DKIM TXT record must contain the appropriate service type 230 | declaration, s=tlsrpt, and if not present the receiving system SHOULD ignore 231 | reports signed using this record. 232 | 233 | 234 | The formal definition of the _smtp._tls TXT record, defined using 235 | & , is as follows: 236 | 237 | 238 |
239 | tlsrpt-record = tlsrpt-version 1*(field-delim tlsrpt-field) 240 | [field-delim] 241 | 242 | field-delim = *WSP ";" *WSP 243 | 244 | tlsrpt-field = tlsrpt-rua / ; Note that the 245 | tlsrpt-extension ; tlsrpt-rua record is 246 | ; required. 247 | 248 | tlsrpt-version = %s"v=TLSRPTv1" 249 | 250 | tlsrpt-rua = %s"rua=" 251 | tlsrpt-uri *(*WSP "," *WSP tlsrpt-uri) 252 | 253 | tlsrpt-uri = URI 254 | ; "URI" is imported from [RFC3986]; 255 | ; commas (ASCII 0x2C), exclamation 256 | ; points (ASCII 0x21), and semicolons 257 | ; (ASCII 0x3B) MUST be encoded 258 | 259 | tlsrpt-extension = tlsrpt-ext-name "=" tlsrpt-ext-value 260 | 261 | tlsrpt-ext-name = (ALPHA / DIGIT) *31(ALPHA / 262 | DIGIT / "_" / "-" / ".") 263 | 264 | tlsrpt-ext-value = 1*(%x21-3A / %x3C / %x3E-7E) 265 | ; chars excluding "=", ";", SP, and control 266 | ; chars 267 |
268 | If multiple TXT records for _smtp._tls are returned by the resolver, 269 | records which do not begin with v=TLSRPTv1; are discarded. If the 270 | number of resulting records is not one, senders MUST assume the 271 | recipient domain does not implement TLSRPT. If the resulting TXT record 272 | contains multiple strings (as described in Section 3.1.3 of ), 273 | then the record MUST be treated as if those strings are concatenated 274 | together without adding spaces. 275 | 276 | The record supports the abillity to declare more than one rua, and if 277 | there exists more than one, the reporter MAY attempt to deliver to 278 | each of the supported rua destinations. A receiver MAY opt to only 279 | attempt delivery to one of the endpoints, however the report SHOULD NOT 280 | be considered successfully delivered until one of the endpoints accepts 281 | delivery of the report. 282 | 283 | Parsers MUST accept TXT records which are syntactically valid (i.e. 284 | valid key-value pairs separated by semi-colons) and implementing a 285 | superset of this specification, in which case unknown fields SHALL be 286 | ignored. 287 | 288 | 289 |
290 | 291 |
292 | 293 |
294 | _smtp._tls.example.com. IN TXT \ 295 | "v=TLSRPTv1;rua=mailto:reports@example.com" 296 |
297 |
298 | 299 |
300 | 301 |
302 | _smtp._tls.example.com. IN TXT \ 303 | "v=TLSRPTv1; \ 304 | rua=https://reporting.example.com/v1/tlsrpt" 305 |
306 |
307 |
308 |
309 | 310 |
311 | The report is composed as a plain text file encoded in the I-JSON format 312 | (). 313 | 314 | Aggregate reports contain the following fields: 315 | 316 | 317 | 318 | Report metadata: 319 | 320 | The organization responsible for the report 321 | Contact information for one or more responsible parties for the 322 | contents of the report 323 | A unique identifier for the report 324 | The reporting date range for the report 325 | 326 | Policy, consisting of: 327 | 328 | One of the following policy types: (1) The MTA-STS policy applied 329 | (as a string) (2) The DANE TLSA record applied (as a string, with 330 | each RR entry of the RRset listed and separated by a semicolon) (3) 331 | The literal string no-policy-found, if neither a DANE nor MTA-STS 332 | policy could be found. 333 | The domain for which the policy is applied 334 | The MX host 335 | 336 | Aggregate counts, comprising result type, sending MTA IP, receiving 337 | MTA hostname, session count, and an optional additional information 338 | field containing a URI for recipients to review further information on 339 | a failure type. 340 | 341 | 342 | Note that the failure types are non-exclusive; an aggregate report may 343 | contain overlapping counts of failure types when a single send attempt 344 | encountered multiple errors. Reporters may report multiple applied 345 | policies (for example, an MTA-STS policy and a DANE TLSA record for the 346 | same domain and MX). Because of this, even in the case where only a single 347 | policy was applied, the "policies" field of the report body MUST be an array and 348 | not a singular value. 349 | 350 | In the case of multiple failure types, the failure-details array 351 | would contain multiple entries. Each entry would have its own set of 352 | infomation pertaining to that failure type. 353 | 354 | 355 |
356 | The report SHOULD cover a full day, from 0000-2400 UTC. This should 357 | allow for easier correlation of failure events. To avoid a Denial of 358 | Service against the system processing the reports, the reports should be 359 | delivered after some delay, perhaps several hours. 360 | 361 | As an example, a sending site might want to introduce a random delay of up 362 | to four hours: 363 | 364 | 365 |
366 | func generate_sleep_delay() { 367 | min_delay = 1 368 | max_delay = 14400 369 | rand = random(min_delay,max_delay) 370 | return rand 371 | } 372 | 373 | func generate_report(policy_domain) { 374 | do_rpt_work(policy_domain) 375 | send_rpt(policy_domain) 376 | } 377 | 378 | func generate_tlsrpt() { 379 | sleep(generate_sleep_delay()) 380 | for policy_domain in list_of_tlsrpt_enabled_domains { 381 | generate_report(policy_domain) 382 | } 383 | } 384 |
385 | A sending site might wish to introduce a random delay per destination 386 | site, up to four hours: 387 | 388 | 389 |
390 | func generate_sleep_delay() { 391 | min_delay = 1 392 | max_delay = 14400 393 | rand = random(min_delay,max_delay) 394 | return rand 395 | } 396 | 397 | func generate_report(policy_domain) { 398 | sleep(generate_sleep_delay()) 399 | do_rpt_work(policy_domain) 400 | send_rpt(policy_domain) 401 | } 402 | 403 | func generate_tlsrpt() { 404 | for policy_domain in list_of_tlsrpt_enabled_domains { 405 | generate_report(policy_domain) 406 | } 407 | } 408 |
409 |
410 | 411 |
412 | 413 |
414 | 415 | 416 | total-successful-session-count: This indicates that the sending MTA 417 | was able to successfully negotiate a policy-compliant TLS connection, 418 | and serves to provide a "heartbeat" to receiving domains that reporting 419 | is functional and tabulating correctly. This field contains an 420 | aggregate count of successful connections for the reporting system. 421 | 422 | 423 | 424 | 425 |
426 | 427 |
428 | 429 | 430 | total-failure-session-count: This indicates that the sending MTA was 431 | unable to successfully establish a connection with the receiving platform. 432 | , "Result Types", will elaborate on the failed 433 | negotiation attempts. This field contains an aggregate count of 434 | failed connections. 435 | 436 | 437 |
438 |
439 | 440 |
441 | The list of result types will start with the minimal set below, and is 442 | expected to grow over time based on real-world experience. The initial 443 | set is: 444 | 445 | 446 |
447 | 448 | 449 | starttls-not-supported: This indicates that the recipient MX did not 450 | support STARTTLS. 451 | certificate-host-mismatch: This indicates that the certificate 452 | presented did not adhere to the constraints specified in the MTA-STS 453 | or DANE policy, e.g. if the MX hostname does not match any identities 454 | listed in the Subject Alternate Name (SAN) . 455 | certificate-expired: This indicates that the certificate has 456 | expired. 457 | certificate-not-trusted: This a label that covers multiple 458 | certificate related failures that include, but not limited to errors 459 | such as untrusted/unknown CAs, certificate name constraints, 460 | certificate chain errors etc. When using this declaration, the 461 | reporting MTA SHOULD utilize the failure-reason-code to provide more 462 | information to the receiving entity. 463 | validation-failure: This indicates a general failure for a reason 464 | not matching a category above. When using this declaration, the 465 | reporting MTA SHOULD utilize the failure-reason-code to provide more 466 | information to the receiving entity. 467 | 468 | 469 |
470 | 471 |
472 | 473 |
474 | 475 | 476 | tlsa-invalid: This indicates a validation error in the TLSA record 477 | associated with a DANE policy. None of the records in the RRset were 478 | found to be valid. 479 | dnssec-invalid: This would indicate that no valid records were 480 | returned from the recursive resolver. The request returned with 481 | SERVFAIL for the requested TLSA record. 482 | dane-required: This indicates that the sending system is 483 | configured to require DANE TLSA records for all the MX hosts 484 | of the destination domain, but no DNSSEC-validated TLSA records 485 | were present for the MX host that is the subject of the report. 486 | Mandatory DANE for SMTP is described in section 6 of . 487 | Such policies may be created by mutual agreement between two 488 | organizations that frequently exchange sensitive content via 489 | email. 490 | 491 | 492 |
493 | 494 |
495 | 496 | 497 | sts-policy-invalid: This indicates a validation error for the 498 | overall MTA-STS policy. 499 | sts-webpki-invalid: This indicates that the MTA-STS policy could not 500 | be authenticated using PKIX validation. 501 | 502 | 503 | 504 | 505 |
506 |
507 | 508 |
509 | When a negotiation failure can not be categorized into one of the 510 | "Negotiation Failures" stated above, the reporter SHOULD use the 511 | validation-failure category. As TLS grows and becomes more complex, 512 | new mechanisms may not be easily categorized. This allows for a generic 513 | feedback category. When this category is used, the reporter SHOULD also 514 | use the failure-reason-code to give some feedback to the receiving 515 | entity. This is intended to be a short text field, and the contents of 516 | the field should be an error code or error text, such as 517 | "X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION". 518 | 519 |
520 | 521 |
522 | Transient errors due to too-busy network, TCP timeouts, etc. are not 523 | required to be reported. 524 | 525 |
526 |
527 | 528 |
529 | The JSON schema is derived from the HPKP JSON schema (cf. 530 | Section 3) 531 | 532 | 533 |
535 | { 536 | "organization-name": organization-name, 537 | "date-range": { 538 | "start-datetime": date-time, 539 | "end-datetime": date-time 540 | }, 541 | "contact-info": email-address, 542 | "report-id": report-id, 543 | "policies": [{ 544 | "policy": { 545 | "policy-type": policy-type, 546 | "policy-string": policy-string, 547 | "policy-domain": domain, 548 | "mx-host": mx-host-pattern 549 | }, 550 | "summary": { 551 | "total-successful-session-count": total-successful-session-count, 552 | "total-failure-session-count": total-failure-session-count 553 | }, 554 | "failure-details": [ 555 | { 556 | "result-type": result-type, 557 | "sending-mta-ip": ip-address, 558 | "receiving-mx-hostname": receiving-mx-hostname, 559 | "receiving-mx-helo": receiving-mx-helo, 560 | "receiving-ip": receiving-ip, 561 | "failed-session-count": failed-session-count, 562 | "additional-information": additional-info-uri, 563 | "failure-reason-code": failure-reason-code 564 | } 565 | ] 566 | } 567 | ] 568 | } 569 | 570 |
571 | 572 | 573 | organization-name: The name of the organization responsible for the 574 | report. It is provided as a string. 575 | date-time: The date-time indicates the start- and end-times for the 576 | report range. It is provided as a string formatted according to 577 | Section 5.6, "Internet Date/Time Format", of . The report 578 | should be for a full UTC day, 0000-2400. 579 | email-address: The contact information for a responsible party of 580 | the report. It is provided as a string formatted according to Section 581 | 3.4.1, "Addr-Spec", of . 582 | report-id: A unique identifier for the report. Report authors may 583 | use whatever scheme they prefer to generate a unique identifier. It is 584 | provided as a string. 585 | policy-type: The type of policy that was applied by the sending 586 | domain. Presently, the only three valid choices are tlsa, sts, 587 | and the literal string no-policy-found. It is provided as a string. 588 | policy-string: An encoding of the applied policy as a JSON array of 589 | strings, whether TLSA record ( section 2.3) or MTA-STS 590 | policy. Examples follow in the next section. 591 | domain: The Policy Domain is the domain against which the MTA-STS or 592 | DANE policy is defined. In the case of Internationalized Domain Names 593 | (), the domain MUST consist of the Punycode-encoded 594 | A-labels () and not the U-labels. 595 | mx-host-pattern: The pattern of MX hostnames from the applied 596 | policy. It is provided as a string, and is interpreted in the same 597 | manner as the "Checking of Wildcard Certificates" rules in Section 598 | 6.4.3 of . In the case of Internationalized Domain Names 599 | (), the domain MUST consist of the Punycode-encoded 600 | A-labels () and not the U-labels. 601 | result-type: A value from , "Result Types", above. 602 | ip-address: The IP address of the sending MTA that attempted the 603 | STARTTLS connection. It is provided as a string representation of an 604 | IPv4 (see below) or IPv6 () address in dot-decimal or 605 | colon-hexadecimal notation. 606 | receiving-mx-hostname: The hostname of the receiving MTA MX record 607 | with which the sending MTA attempted to negotiate a STARTTLS 608 | connection. 609 | receiving-mx-helo: (optional) The HELO or EHLO string from the 610 | banner announced during the reported session. 611 | receiving-ip: The destination IP address that was using when 612 | creating the outbound session. It is provided as a string 613 | representation of an IPv4 (see below) or IPv6 () address 614 | in dot-decimal or colon-hexadecimal notation. 615 | total-successful-session-count: The aggregate count (integer, encoded as a 616 | JSON number) of successfully negotiated TLS-enabled connections to the 617 | receiving site. 618 | total-failure-session-count: The aggregate count (integer, encoded as a JSON 619 | number) of failures to negotiate a TLS-enabled connection to the receiving 620 | site. 621 | failed-session-count: The number of (attempted) sessions that match 622 | the relevant result-type for this section (integer, encoded as a JSON 623 | number). 624 | additional-info-uri: An optional URI pointing to 625 | additional information around the relevant result-type. For example, 626 | this URI might host the complete certificate chain presented during an 627 | attempted STARTTLS session. 628 | failure-reason-code: A text field to include a TLS-related error 629 | code or error message. 630 | 631 | 632 | 633 | 634 | For report purposes, an IPv4 Address is defined via the following ABNF: 635 | 636 | 637 |
638 | IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet 639 | dec-octet = DIGIT ; 0-9 640 | / %x31-39 DIGIT ; 10-99 641 | / "1" 2DIGIT ; 100-199 642 | / "2" %x30-34 DIGIT ; 200-249 643 | / "25" %x30-35 ; 250-255 644 |
645 |
646 | 647 |
648 | Part of the report body includes the policy that is applied when attemping 649 | relay to the destination. 650 | 651 | For DANE TLSA policies, this is a JSON array of strings each representing the 652 | RDATA of a single TLSA resource record as a space-separated list of its four 653 | TLSA fields; the fields are in presentation format (defined in 654 | Section 2.2) with no internal spaces or grouping parentheses: 655 | 656 | 657 |
658 | [ 659 | "3 0 1 1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513D747D1D085D", 660 | "3 0 1 12350A337E6DB9C6123522D136A475638CC43E1ED424F8EEC8513D747D1D1234" 661 | ] 662 |
663 | For MTA-STS policies, this is an array of JSON strings that represents the 664 | policy that is declared by the receiving site, including any errors that may be 665 | present. Note that where there are multiple "mx" values, they must be listed 666 | as separate "mx" elements in the policy array, rather as a single nested "mx" 667 | sub-array. 668 | 669 | 670 |
671 | [ 672 | "version: STSv1", 673 | "mode: testing", 674 | "mx: mx1.example.com", 675 | "mx: mx2.example.com", 676 | "mx: mx.backup-example.com", 677 | "max_age: 604800" 678 | ] 679 |
680 |
681 |
682 | 683 |
684 | Reports can be delivered either as an email message via SMTP or via HTTP 685 | POST. 686 | 687 | 688 |
689 | The filename is RECOMMENDED to be constructed using the following ABNF: 690 | 691 | 692 |
693 | filename = sender "!" policy-domain "!" begin-timestamp 694 | "!" end-timestamp [ "!" unique-id ] "." extension 695 | 696 | unique-id = 1*(ALPHA / DIGIT) 697 | 698 | sender = domain ; From the [RFC5321] that is used 699 | ; as the domain for the `contact-info` 700 | ; address in the report body 701 | 702 | policy-domain = domain 703 | 704 | begin-timestamp = 1*DIGIT 705 | ; seconds since 00:00:00 UTC January 1, 1970 706 | ; indicating start of the time range contained 707 | ; in the report 708 | 709 | end-timestamp = 1*DIGIT 710 | ; seconds since 00:00:00 UTC January 1, 1970 711 | ; indicating end of the time range contained 712 | ; in the report 713 | 714 | extension = "json" / "json.gz" 715 |
716 | The extension MUST be "json" for a plain JSON file, or "json.gz" for a 717 | JSON file compressed using GZIP. 718 | 719 | "unique-id" allows an optional unique ID generated by the Sending MTA to 720 | distinguish among multiple reports generated simultaneously by different 721 | sources within the same Policy Domain. For example, this is a possible 722 | filename for a compressed report to the Policy Domain "example.net" 723 | from the Sending MTA "mail.sndr.example.com": 724 | 725 | mail.sndr.example.com!example.net!1470013207!1470186007!001.json.gz 726 | 727 |
728 | 729 |
730 | The report SHOULD be subjected to GZIP compression for both email 731 | and HTTPS transport. Declining to apply compression can cause the report to 732 | be too large for a receiver to process (a commonly observed receiver 733 | limit is ten megabytes); compressing the file increases the chances of 734 | acceptance of the report at some compute cost. 735 | 736 |
737 | 738 |
739 | The report MAY be delivered by email. To make the reports 740 | machine-parsable for the receivers, we define a top-level media type 741 | multipart/report with a new parameter report-type="tlsrpt". Inside 742 | it, there are two parts: The first part is human readable, typically 743 | text/plain, and the second part is machine readable with a new media 744 | type defined called application/tlsrpt+json. If compressed, the 745 | report should use the media type application/tlsrpt+gzip. 746 | 747 | In addition, the following two new top level message header fields are 748 | defined: 749 | 750 | TLS-Report-Domain: Receiver-Domain 751 | 752 | TLS-Report-Submitter: Sender-Domain 753 | 754 | The TLS-Report-Submitter value MUST match the value found in the 755 | domain from the contact-info from the report body. These 756 | message headers MUST be included and should allow for easy searching 757 | for all reports submitted by a report domain or a particular submitter, 758 | for example in IMAP : 759 | 760 | s SEARCH HEADER "TLS-Report-Domain" "example.com" 761 | 762 | It is presumed that the aggregate reporting address will be equipped to 763 | process new message header fields and extract MIME parts with the 764 | prescribed media type and filename, and ignore the rest. These 765 | additional headers SHOULD be included in the DKIM signature 766 | for the message. 767 | 768 | The .Subject field for report submissions SHOULD conform to 769 | the following ABNF: 770 | 771 | 772 |
773 | tlsrpt-subject = %s"Report" FWS ; "Report" 774 | %s"Domain:" FWS ; "Domain:" 775 | domain-name FWS ; per [RFC6376] 776 | %s"Submitter:" FWS ; "Submitter:" 777 | domain-name FWS ; per [RFC6376] 778 | %s"Report-ID:" FWS ; "Report-ID: 779 | "<" id-left "@" id-right ">" ; per [RFC5322] 780 | [CFWS] ; per [RFC5322] 781 | ; (as with FWS) 782 |
783 | The first domain-name indicates the DNS domain name about which the 784 | report was generated. The second domain-name indicates the DNS domain 785 | name representing the Sending MTA generating the report. The purpose 786 | of the Report-ID: portion of the field is to enable the Policy Domain 787 | to identify and ignore duplicate reports that might be sent by a 788 | Sending MTA. 789 | 790 | For instance, this is a possible Subject field for a report to the 791 | Policy Domain "example.net" from the Sending MTA 792 | "mail.sender.example.com". It is line-wrapped as allowed 793 | by : 794 | 795 | 796 |
797 | Subject: Report Domain: example.net 798 | Submitter: mail.sender.example.com 799 | Report-ID: <735ff.e317+bf22029@mailexample.net> 800 |
801 | 802 |
803 | 804 |
805 | From: tlsrpt@mail.sender.example.com 806 | Date: Fri, May 09 2017 16:54:30 -0800 807 | To: mts-sts-tlsrpt@example.net 808 | Subject: Report Domain: example.net 809 | Submitter: mail.sender.example.com 810 | Report-ID: <735ff.e317+bf22029@example.net> 811 | TLS-Report-Domain: example.net 812 | TLS-Report-Submitter: mail.sender.example.com 813 | MIME-Version: 1.0 814 | Content-Type: multipart/report; report-type="tlsrpt"; 815 | boundary="----=_NextPart_000_024E_01CC9B0A.AFE54C00" 816 | Content-Language: en-us 817 | 818 | This is a multipart message in MIME format. 819 | 820 | ------=_NextPart_000_024E_01CC9B0A.AFE54C00 821 | Content-Type: text/plain; charset="us-ascii" 822 | Content-Transfer-Encoding: 7bit 823 | 824 | This is an aggregate TLS report from mail.sender.example.com 825 | 826 | ------=_NextPart_000_024E_01CC9B0A.AFE54C00 827 | Content-Type: application/tlsrpt+gzip 828 | Content-Transfer-Encoding: base64 829 | Content-Disposition: attachment; 830 | filename="mail.sender.example!example.com! 831 | 1013662812!1013749130.json.gz" 832 | 833 | <gzipped content of report> 834 | 835 | ------=_NextPart_000_024E_01CC9B0A.AFE54C00-- 836 | ... 837 |
838 | Note that, when sending failure reports via SMTP, sending MTAs MUST NOT 839 | honor MTA-STS or DANE TLSA failures. 840 | 841 |
842 |
843 | 844 |
845 | The report MAY be delivered by POST to HTTPS. If compressed, the report 846 | SHOULD use the media type application/tlsrpt+gzip, and 847 | application/tlsrpt+json otherwise (see section , 848 | "IANA Considerations"). 849 | 850 | The receiving system MUST return a "successful" response from its HTTPS 851 | server, typically a 200 or 201 HTTP code . Other codes could 852 | indicate a delivery failure, and may be retried as per local sender policy. 853 | The receiving system is not expected to process reports at receipt time, and 854 | MAY store them for processing at a later time. 855 | 856 |
857 | 858 |
859 | In the event of a delivery failure, regardless of the delivery method, a 860 | sender SHOULD attempt redelivery for up to 24hrs after the initial 861 | attempt. As previously stated the reports are optional, so while it is 862 | ideal to attempt redelivery, it is not required. If multiple retries 863 | are attempted, ideally they SHOULD be done with exponential backoff. 864 | 865 |
866 | 867 |
868 | As stated above, there are a variable number of ways to declare 869 | information about the data therein. If any of items declared via 870 | subject or filename disagree with the report, the report MUST be 871 | considered the authoritative source. 872 | 873 |
874 |
875 | 876 |
877 | The following are the IANA considerations discussed in this document. 878 | 879 | 880 |
881 | Below is the Internet Assigned Numbers Authority (IANA) Permanent 882 | Message Header Field registration information per . 883 | 884 | 885 |
886 | Header field name: TLS-Report-Domain 887 | Applicable protocol: mail 888 | Status: standard 889 | Author/Change controller: IETF 890 | Specification document(s): this one 891 | 892 | 893 | Header field name: TLS-Report-Submitter 894 | Applicable protocol: mail 895 | Status: standard 896 | Author/Change controller: IETF 897 | Specification document(s): this one 898 |
899 |
900 | 901 |
902 | This document creates a new registry for "report-type" parameter to 903 | the Content-Type header field for the "multipart/report" top-level media 904 | type defined in . 905 | 906 | The registry name is "Report Type Registry", and the procedure for 907 | updating the registry will be "Specification Required". 908 | 909 | An entry in this registry should contain: 910 | 911 | 912 | 913 | the report-type being registered 914 | one or more registered media-types that can be used with this report-type 915 | the document containing the registration action 916 | an optional comment 917 | 918 | 919 | The initial entries are: 920 | 921 | Report-Type: tlsrpt 922 | Media Type: application/tlsrpt+gzip, application/tlsrpt+json 923 | Registered By: [RFCXXXX] 924 | Comment: Media types suitable for use with this report-type are defined in Sections 6.4 and 6.5 of [RFCXXXX] 925 | 926 | Report-Type: disposition-notification 927 | Media Type: message/disposition-notification 928 | Registered By: Section 10 929 | 930 | Report-Type: disposition-notification 931 | Media Type: message/global-disposition-notification 932 | Registered By: Section 6 933 | 934 | Report-Type: delivery-status 935 | Media Type: message/delivery-status 936 | Registered By: Appendix D 937 | 938 | Report-Type: delivery-status 939 | Media Type: message/global-delivery-status 940 | Registered By: Section 6 941 | 942 |
943 | 944 |
945 | This document registers a new media type suffix "+gzip". The GZIP 946 | format is a public domain, cross-platform, interoperable file 947 | storage and transfer format, specified in ; it 948 | supports compression and is used as the underlying representation 949 | by a variety of file formats. The media type "application/gzip" 950 | has been registered for such files. The suffix "+gzip" MAY be 951 | used with any media type whose representation follows that 952 | established for "application/gzip". The media type structured 953 | syntax suffix registration form follows: 954 | 955 | Type name: GZIP file storage and transfer format 956 | 957 | +suffix: +gzip 958 | 959 | References: 960 | 961 | Encoding considerations: GZIP is a binary encoding. 962 | 963 | Fragment identifier considerations: The syntax and semantics 964 | of fragment identifiers specified for 965 | +gzip SHOULD be as specified for "application/gzip". (At 966 | publication of this document, there is no fragment identification 967 | syntax defined for "application/gzip".) The syntax and semantics 968 | for fragment identifiers for a specific "xxx/yyy+gzip" SHOULD be 969 | processed as follows: 970 | 971 | 972 |
973 | For cases defined in +gzip, where the fragment identifier 974 | resolves per the +gzip rules, then process as specified in 975 | +gzip. 976 | 977 | For cases defined in +gzip, where the fragment identifier does 978 | not resolve per the +gzip rules, then process as specified in 979 | "xxx/yyy+gzip". 980 | 981 | For cases not defined in +gzip, then process as specified in 982 | "xxx/yyy+gzip". 983 |
984 | Interoperability considerations: n/a 985 | 986 | Security considerations: GZIP format doesn't provide confidentiality protection. 987 | Integrity protection is provided by an Adler-32 checksum, which is not 988 | cryptographically strong. See also security considerations of . 989 | Each individual media type registered with a +gzip suffix can have additional 990 | security considerations. Additionally, GZIP objects can contain multiple 991 | files and associated paths. File paths must be validated when the files 992 | are extracted; a malicious file path could otherwise cause the extractor 993 | to overwrite application or system files. 994 | 995 | Contact: art@ietf.org 996 | 997 | Author/Change controller: Internet Engineering Task Force 998 | (mailto:iesg@ietf.org). 999 | 1000 |
1001 | 1002 |
1003 | This document registers multiple media types, beginning with Table 1 1004 | below. 1005 | 1006 | 1007 |
1008 | +-------------+----------------+-------------+-------------------+ 1009 | | Type | Subtype | File extn | Specification | 1010 | +-------------+----------------+-------------+-------------------+ 1011 | | application | tlsrpt+json | .json | Section 5.3 | 1012 | +-------------+----------------+-------------+-------------------+ 1013 | Table 1: SMTP TLS Reporting Media Type 1014 |
1015 | Type name: application 1016 | 1017 | Subtype name: tlsrpt+json 1018 | 1019 | Required parameters: n/a 1020 | 1021 | Optional parameters: n/a 1022 | 1023 | Encoding considerations: Encoding considerations are identical to 1024 | those specified for the application/json media type. See 1025 | . 1026 | 1027 | Security considerations: Security considerations relating to SMTP 1028 | TLS Reporting are discussed in Section 7. 1029 | 1030 | Interoperability considerations: This document specifies format of 1031 | conforming messages and the interpretation thereof. 1032 | 1033 | Published specification: Section 5.3 of this document. 1034 | 1035 | Applications that use this media type: Mail User Agents (MUA) and 1036 | Mail Transfer Agents. 1037 | 1038 | Additional information: 1039 | 1040 | 1041 |
1042 | Magic number(s): n/a 1043 | 1044 | File extension(s): ".json" 1045 | 1046 | Macintosh file type code(s): n/a 1047 |
1048 | Person & email address to contact for further information: See 1049 | Authors' Addresses section. 1050 | 1051 | Intended usage: COMMON 1052 | 1053 | Restrictions on usage: n/a 1054 | 1055 | Author: See Authors' Addresses section. 1056 | 1057 | Change controller: Internet Engineering Task Force 1058 | (mailto:iesg@ietf.org). 1059 | 1060 |
1061 | 1062 |
1063 | 1064 |
1065 | +-------------+----------------+-------------+-------------------+ 1066 | | Type | Subtype | File extn | Specification | 1067 | +-------------+----------------+-------------+-------------------+ 1068 | | application | tlsrpt+gzip | .gz | Section 5.3 | 1069 | +-------------+----------------+-------------+-------------------+ 1070 | Table 2: SMTP TLS Reporting Media Type 1071 |
1072 | Type name: application 1073 | 1074 | Subtype name: tlsrpt+gzip 1075 | 1076 | Required parameters: n/a 1077 | 1078 | Optional parameters: n/a 1079 | 1080 | Encoding considerations: Binary 1081 | 1082 | Security considerations: Security considerations relating to SMTP 1083 | TLS Reporting are discussed in Section 7. Security 1084 | considerations related to gzip compression are discussed 1085 | in [RFC6713]. 1086 | 1087 | Interoperability considerations: This document specifies format of 1088 | conforming messages and the interpretation thereof. 1089 | 1090 | Published specification: Section 5.3 of this document. 1091 | 1092 | Applications that use this media type: Mail User Agents (MUA) and 1093 | Mail Transfer Agents. 1094 | 1095 | Additional information: 1096 | 1097 | 1098 |
1099 | Magic number(s): The first two bytes are 0x1f, 0x8b. 1100 | 1101 | File extension(s): ".gz" 1102 | 1103 | Macintosh file type code(s): n/a 1104 |
1105 | Person & email address to contact for further information: See 1106 | Authors' Addresses section. 1107 | 1108 | Intended usage: COMMON 1109 | 1110 | Restrictions on usage: n/a 1111 | 1112 | Author: See Authors' Addresses section. 1113 | 1114 | Change controller: Internet Engineering Task Force 1115 | (mailto:iesg@ietf.org). 1116 | 1117 |
1118 | 1119 |
1120 | This document creates a new registry, "STARTTLS Validation Result 1121 | Types". The initial entries in the registry are: 1122 | 1123 | 1124 |
1125 | +-------------------------------+-----------+ 1126 | | Result Type | Desc | 1127 | +-------------------------------+-----------+ 1128 | | "starttls-not-supported" | 4.3 | 1129 | | "certificate-host-mismatch" | 4.3 | 1130 | | "certificate-expired" | 4.3 | 1131 | | "tlsa-invalid" | 4.3 | 1132 | | "dnssec-invalid" | 4.3 | 1133 | | "dane-required" | 4.3 | 1134 | | "certificate-not-trusted" | 4.3 | 1135 | | "sts-policy-invalid" | 4.3 | 1136 | | "sts-webpki-invalid" | 4.3 | 1137 | | "validation-failure" | 4.3 | 1138 | +-------------------------------+-----------+ 1139 |
1140 | The above entries are described in section , "Result 1141 | Types." New result types can be added to this registry using "Expert 1142 | Review" IANA registration policy. 1143 | 1144 |
1145 |
1146 | 1147 |
1148 | SMTP TLS Reporting provides transparency into misconfigurations or 1149 | attempts to intercept or tamper with mail between hosts who support 1150 | STARTTLS. There are several security risks presented by the existence of 1151 | this reporting channel: 1152 | 1153 | 1154 | 1155 | Flooding of the Aggregate report URI (rua) endpoint: An attacker could 1156 | flood the endpoint with excessive reporting traffic and prevent the 1157 | receiving domain from accepting additional reports. This type of 1158 | Denial-of-Service attack would limit visibility into STARTTLS 1159 | failures, leaving the receiving domain blind to an ongoing attack. 1160 | Untrusted content: An attacker could inject malicious code into the 1161 | report, opening a vulnerability in the receiving domain. Implementers 1162 | are advised to take precautions against evaluating the contents of the 1163 | report. 1164 | Report snooping: An attacker could create a bogus TLSRPT record to 1165 | receive statistics about a domain the attacker does not own. Since an 1166 | attacker able to poison DNS is already able to receive counts of SMTP 1167 | connections (and, absent DANE or MTA-STS policies, actual SMTP message 1168 | payloads), this does not present a significant new vulnerability. 1169 | Ignoring HTTPS validation when submitting reports: When reporting benign 1170 | misconfigurations, it is likely that a misconfigured SMTP server may also 1171 | mean a misconfigured HTTPS server; as a result, reporters who required 1172 | HTTPS validity on the reporting endpoint may fail to alert administrators 1173 | about such misconfigurations. Conversely, in the event of an actual attack, 1174 | an attacker who wished to create a gap in reporting and could intercept 1175 | HTTPS reports could, just as easily, simply thwart the resolution of the 1176 | TLSRPT TXT record or establishment of the TCP session to the HTTPS endpoint. 1177 | Furthermore, such a man-in-the-middle attacker could discover most or all of 1178 | the metadata exposed in a report merely through passive observation. As a 1179 | result, we consider the risks of failure to deliver reports on 1180 | misconfigurations to outweigh those of attackers intercepting reports. 1181 | Reports as DDoS: TLSRPT allows specifying destinations for the reports 1182 | that are outside the authority of the Policy Domain, which allows 1183 | domains to delegate processing of reports to a partner organization. 1184 | However, an attacker who controls the Policy Domain DNS could also use 1185 | this mechanism to direct the reports to an unwitting victim, flooding 1186 | that victim with excessive reports. DMARC defines a 1187 | solution for verifying delegation to avoid such attacks; the need for 1188 | this is greater with DMARC, however, because DMARC allows an attacker 1189 | to trigger reports to a target from an innocent third party by sending 1190 | that third party mail (which triggers a report from the third party to 1191 | the target). In the case of TLSRPT, the attacker would have to induce 1192 | the third party to send the attacker mail in order to trigger reports 1193 | from the third party to the victim; this reduces the risk of such an 1194 | attack and the need for a verification mechanism. 1195 | 1196 | 1197 | Finally, because TLSRPT is intended to help administrators discover 1198 | man-in-the-middle attacks against transport-layer encryption, including 1199 | attacks designed to thwart negotiation of encrypted connections (by 1200 | downgrading opportunistic encryption or, in the case of MTA-STS, 1201 | preventing discovery of a new MTA-STS policy), we must also consider the 1202 | risk that an adversary who can induce such a downgrade attack can also 1203 | prevent discovery of the TLSRPT TXT record (and thus prevent discovery 1204 | of the successful downgrade attack). Administrators are thus encouraged 1205 | to deploy TLSRPT TXT records with a large TTL (reducing the window for 1206 | successful application of transient attacks against DNS resolution of the 1207 | record) or to deploy DNSSEC on the deploying zone. 1208 | 1209 |
1210 | 1211 |
1212 | MTAs are generally considered public knowledge, however, the internals 1213 | of how those MTAs are configured and the users of those MTAs may not be 1214 | as public. It should be noted that when providing a receiving site with 1215 | information, it may reveal information about the sender's configuration, 1216 | or even information about the senders themselves. Consider that by sending 1217 | a report, it might disclose your SSL library version as the inability to 1218 | negotiate a session may be a known incompatbility between two library 1219 | versions, or perhaps commonly used in a operating system release that is 1220 | centered in a certain region. The risk may be minimal, but should be 1221 | considered. 1222 | 1223 |
1224 | 1225 | 1226 | 1227 | 1228 | 1229 | 1230 | 1231 | 1232 | 1233 | 1234 | 1235 | 1236 | 1237 | 1238 | 1239 | 1240 | 1241 | 1242 | 1243 | 1244 | 1245 | 1246 | 1247 | 1248 | 1249 | 1250 | 1251 | 1252 | 1253 | 1254 | 1255 | 1256 | 1257 | 1258 | 1259 | 1260 | 1261 | 1262 | 1263 | 1264 | 1265 | 1266 |
1267 | 1268 |
1269 | 1270 |
1271 | _smtp._tls.mail.example.com. IN TXT \ 1272 | "v=TLSRPTv1;rua=mailto:reports@example.com" 1273 |
1274 |
1275 | 1276 |
1277 | 1278 |
1279 | _smtp._tls.mail.example.com. IN TXT \ 1280 | "v=TLSRPTv1; \ 1281 | rua=https://reporting.example.com/v1/tlsrpt" 1282 |
1283 |
1284 |
1285 | 1286 |
1287 | Below is an example JSON report for messages from Company-X to Company-Y, 1288 | where 100 sessions were attempted to Company Y servers with an expired 1289 | certificate and 200 sessions were attempted to Company Y servers that 1290 | did not successfully respond to the STARTTLS command. Additionally 3 1291 | sessions failed due to "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED". 1292 | 1293 | 1294 |
1295 | { 1296 | "organization-name": "Company-X", 1297 | "date-range": { 1298 | "start-datetime": "2016-04-01T00:00:00Z", 1299 | "end-datetime": "2016-04-01T23:59:59Z" 1300 | }, 1301 | "contact-info": "sts-reporting@company-x.example", 1302 | "report-id": "5065427c-23d3-47ca-b6e0-946ea0e8c4be", 1303 | "policies": [{ 1304 | "policy": { 1305 | "policy-type": "sts", 1306 | "policy-string": ["version: STSv1","mode: testing", 1307 | "mx: *.mail.company-y.example","max_age: 86400"], 1308 | "policy-domain": "company-y.example", 1309 | "mx-host": "*.mail.company-y.example" 1310 | }, 1311 | "summary": { 1312 | "total-successful-session-count": 5326, 1313 | "total-failure-session-count": 303 1314 | }, 1315 | "failure-details": [{ 1316 | "result-type": "certificate-expired", 1317 | "sending-mta-ip": "2001:db8:abcd:0012::1", 1318 | "receiving-mx-hostname": "mx1.mail.company-y.example", 1319 | "failed-session-count": 100 1320 | }, { 1321 | "result-type": "starttls-not-supported", 1322 | "sending-mta-ip": "2001:db8:abcd:0013::1", 1323 | "receiving-mx-hostname": "mx2.mail.company-y.example", 1324 | "receiving-ip": "203.0.113.56", 1325 | "failed-session-count": 200, 1326 | "additional-information": "https://reports.company-x.example/ 1327 | report_info ? id = 5065427 c - 23 d3# StarttlsNotSupported " 1328 | }, { 1329 | "result-type": "validation-failure", 1330 | "sending-mta-ip": "198.51.100.62", 1331 | "receiving-ip": "203.0.113.58", 1332 | "receiving-mx-hostname": "mx-backup.mail.company-y.example", 1333 | "failed-session-count": 3, 1334 | "failure-error-code": "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED" 1335 | }] 1336 | }] 1337 | } 1338 | 1339 |
1340 |
1341 | 1342 | 1343 | 1344 | --------------------------------------------------------------------------------