idnits 2.17.1 draft-kucherawy-dkim-transform-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 5, 2015) is 3302 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'FWS' is mentioned on line 149, but not defined ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Kucherawy 3 Internet-Draft April 5, 2015 4 Intended status: Experimental 5 Expires: October 7, 2015 7 Recognized Transformations of Messages Bearing DomainKeys Identified 8 Mail (DKIM) Signatures 9 draft-kucherawy-dkim-transform-00 11 Abstract 13 DomainKeys Identified Mail (DKIM) introduced a mechanism whereby a 14 mail operator can affix a signature to a message that validates at 15 the level of the signer's domain name. It specified two possible 16 ways of converting the message body to a canonical form, one 17 intolerant of changes and the other tolerant of simple changes to 18 whitespace within the message body. 20 The provided canonicalization schemes do not tolerate changes in a 21 message such as conversion between transfer encodings or addition of 22 new message content. It is useful to have these capabilities to 23 allow for transport through gateways, and also for transport through 24 handlers (such as mailing list services) that might add content that 25 would invalidate a signature generated using the existing 26 canonicalization schemes. 28 This document presents a mechanism for declaring that a message 29 underwent one of a handful of well-defined transformations, so that a 30 verifier might rewind such a modification and thereby confirm that 31 the signature still verifies against the original content. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on October 7, 2015. 50 Copyright Notice 52 Copyright (c) 2015 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3. The 'tf' DKIM Signature Tag . . . . . . . . . . . . . . . . . 4 70 4. DKIM Operational Flow . . . . . . . . . . . . . . . . . . . . 4 71 4.1. Detail . . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 5. The 'mimeify' Transformation . . . . . . . . . . . . . . . . . 6 73 6. The 'add-part' Transformation . . . . . . . . . . . . . . . . 7 74 7. The 'mime-wrap' Transformation . . . . . . . . . . . . . . . . 8 75 8. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 77 9.1. Imported from DKIM . . . . . . . . . . . . . . . . . . . . 9 78 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 79 10.1. DKIM Transformations Registry . . . . . . . . . . . . . . 10 80 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 11.1. Normative References . . . . . . . . . . . . . . . . . . . 11 82 11.2. Informative References . . . . . . . . . . . . . . . . . . 11 83 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11 84 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 11 85 Appendix C. To-Do List . . . . . . . . . . . . . . . . . . . . . 11 86 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 12 88 1. Background 90 DomainKeys Identified Mail (DKIM) [RFC6376] defines a mechanism 91 whereby a verified domain name can be attached to a message, or 92 portion of a message, using a cryptographic signature. It presents 93 two possible schemes for converting the header block to a canonical 94 form, and similarly two schemes for canonicalizing the body. In each 95 case, one scheme permits no changes whatsoever, and the other permits 96 limited changes restricted to areas such as whitespace munging, case 97 changing, and header field wrapping. 99 Some agents deliberately, but innocently, modify content in transit. 100 A prime example of this is mailing lists, which might add a prefix to 101 the Subject field of a message, add list-specific information to the 102 header (in the form of new header fields), or append administrivia to 103 the body of messages before they are re-mailed to the list 104 subscribers. Use of mailing lists with respect to DKIM, and a 105 discussion of related challenges, can be found in [RFC6377]. The 106 urgency to solve this family of problems increased dramatically with 107 the large-scale introduction of Domain-based Message Authentication, 108 Reporting, and Conformance (DMARC) [RFC7489]. 110 There is a desire to have DKIM signatures survive transit through 111 lists. One way to do this is to make use of DKIM's "l=" tag which 112 limits the portion of the body that is signed. This exposes an 113 attack vector, however, since one can simply append any content to a 114 partly-signed message and the signature will continue to verify. 115 (See Section 8.2 of [RFC6376].) 117 This document defines an incremental mechanism to declare that a 118 signature is being applied to message content after one of a small 119 set of well-defined, reversible, content transformations. The 120 message verifier can then reverse the effect of the claimed 121 transformation and, theoretically, recover the original content and 122 confirm its integrity. 124 The utility of this mechanism is predicated on the notion that agents 125 that modify signed messages will do so in one of the known 126 (registered) transformations, and that common transformations will be 127 registered as they are developed. 129 2. Definitions 131 Numerous terms used here, especially "Author" and "Mediator", are 132 defined in [RFC5598]. 134 3. The 'tf' DKIM Signature Tag 136 This section defines the 'tf' DKIM signature tag. 138 The presence of this tag is an indication to a verifier that the 139 agent adding this signature transformed the original message between 140 receipt (and verification of any previously-applied signature) and 141 retransmission, and that such transmission was one of a set that are 142 common, well-defined, and reversible. 144 The value of this tag is one of the transformations registered in the 145 DKIM Message Transformations registry. See Section 10. 147 Using ABNF, as defined in [RFC5234]: 149 sig-tf-tag = %x74.66 [FWS] "=" [FWS] sig-tf-tag-trans 150 sig-tf-tag-trans = Token 151 ; expected to be a transformation name found 152 ; in the DKIM Message Transformations 153 ; registry 155 "Token" is imported from [RFC2045], and "FWS" is imported from 156 [RFC6376]. 158 A verifier finding a signature with the "tf" tag present but bearing 159 a value it does not recognize ignores its presence (other than 160 including it in hash computation). 162 4. DKIM Operational Flow 164 In all cases, DKIM operations involving this tag begin with a message 165 author generating content and submitting it to the appropriate 166 Message Submission Agent (MSA). The MSA is presumed to have some 167 kind of DKIM signature generation capability, and thus the message 168 will have an author domain signature attached to it. 170 When a message arrives at a Mediator or other intermediary that 171 wishes to distribute an altered form of the author's content, such as 172 a Mailing List Manager (MLM) configured to do so, it generates an 173 additional DKIM signature with the new form of the content as input. 174 This second includes the "tf" tag, announcing which known 175 transformation was applied to the message prior to creation of the 176 Mediator's signature. Importantly, the original signature is not 177 removed from the message nor is it altered in any way. 179 Since DKIM-compliant verifiers ignore signature tags of which they 180 are not aware, this is a purely incremental change as it will not 181 interfere with the deployed DKIM infrastructure. 183 A DKIM verifier aware of this tag will first confirm that the 184 Mediator's signature is valid. On doing so, it can then apply the 185 reverse of the claimed transformation. This will restore the message 186 to the form and content originally submitted by the Author, and the 187 Author's signature will then be valid over the restored content. 189 This might be used to confirm that a message which passed through a 190 Mediator can still be considered to have a valid Author signature, 191 satisfying policy checks such as those described in [RFC7489]. 193 4.1. Detail 195 1. Author A generates message M, addressed to recipient R, which is 196 a Mediator (a mailing list manager, for example). 198 2. Author submits M to its MSA. 200 3. MSA generates and attaches DKIM signature S(M), and sends the 201 message toward its destination, which is the servers accepting 202 messages for R. 204 4. The message arrives at R. R might verify signature S(M) and apply 205 any local policy if the verification fails. 207 5. R selects one of the registered, reversible transformations, T, 208 to be applied to M. (The reverse operation will be called T'.) R 209 thus generates T(M) as the new content. The new content 210 necessarily includes S(M). 212 6. R also generates a signature of T(M), which is S(T(M)). This new 213 signature includes the "tf" tag defined above, identifying the 214 transformation T that was used in the previous step. It then 215 sends the message toward its final destination(s). For a mailing 216 list manager, this would be all of the current list subscribers. 218 7. The Mediator version of the message arrives at ultimate recipient 219 Z. Assuming no unexpected damage to the message in transit, Z 220 will be able to validate S(T(M)). 222 8. If the verifier is not aware of this tag and its meaning, or if 223 the verifier is not aware of how to reverse the identified 224 transformation, normal DKIM verification continues from here, and 225 this modified algorithm terminates. It would be expected that 226 S(T(M)) would be valid, but S(M) would not. 228 9. The compliant verifier applies T' to the validated message 229 content. By definition, T'(T(M)) is M. Since the Mediator 230 preserved Author signature S(M), the verifier can now attempt to 231 validate the Author signature against the recovered original 232 content. 234 5. The 'mimeify' Transformation 236 The "mimeify" transformation converts a message that is not formatted 237 according to Multipurpose Internet Mail Extensions (MIME) [RFC2045], 238 and converts it to that form. This allows a Mediator to place the 239 original content in one MIME part, and its own additional content in 240 a second MIME part. The reverse transformation is to remove the 241 second MIME part altogether, and then strip away all MIME structure, 242 leaving only the original author content. 244 More specifically, the transformation follows these steps: 246 1. A "MIME-Version" header field is added, as described in 247 [RFC2045]. 249 2. A "Content-Type" header field is added, also as described in 250 [RFC2045]. The media type is "multipart/mixed". A unique 251 compliant boundary is also generated. 253 3. Two MIME parts are created. The first MIME part is of type 254 "text/plain", and contains the body of the original message. The 255 second MIME part contains whatever content the Mediator is 256 configured to add, and uses a media type appropriate to that 257 content. 259 4. The body of the message is replaced with the following, in a 260 manner compliant with [RFC2045], namely: 262 A. the boundary; 264 B. an optional "Content-Type" header field indicating the 265 original content used the default "text/plain" media type, 266 and the optional "charset" parameter; 268 C. a line break; 270 D. the body of the original message; 272 E. a line break; 274 F. the boundary; 276 G. any MIME header fields needed to introduce the content the 277 Mediator wishes to add; 279 H. a line break; 281 I. the Mediator's content; 283 J. the terminating boundary. 285 The reverse of this transformation is as follows: 287 1. Extract the full content of the first MIME part. 289 2. Discard the entire message body, and replace it with the 290 extracted content above. 292 3. Remove the "Content-Type" and "MIME-Version" header fields. 294 6. The 'add-part' Transformation 296 The "add-part" transformation augments a multipart message that is 297 already formatted according to MIME by appending an additonal part 298 that includes the content the Mediator wishes to add. 300 This transformation cannot be used unless the media type of the 301 message as a whole (the one named in the Content-Type field in the 302 header of the message itself) is "multipart/mixed". Simply put, a 303 new part within the existing set of parts is added at the end, 304 containing the Mediator's content. 306 More specifically, the transformation follows these steps: 308 1. Determine the MIME boundary used to separate parts, found in the 309 top-level Content-Type header field. 311 2. At the point of the terminating boundary in the original message, 312 insert a non-terminating instance of the same boundary. 314 3. After the new boundary, write any MIME fields needed to introduce 315 the content the Mediator wishes to add. 317 4. Insert a line break, followed by the Mediator's content, and an 318 additional line break. 320 The reverse of this transformation is as follows: 322 1. Locate the last instance of the boundary found in the Content- 323 Type header field of the message itself. 325 2. Delete the content from that point in the message until the 326 terminating instance of the boundary. 328 7. The 'mime-wrap' Transformation 330 The "mime-wrap" transformation augments a message that is already 331 formatted according to MIME by enclosing the existing MIME structure 332 in a new layer. This new layer contains two parts: the original MIME 333 structure in its first part, and the Mediator content in its second 334 part. 336 More specifically, the transformation follows these steps: 338 1. Remove the Content-Type header field from the message. 340 2. Generate a new Content-Type header field, compliant with 341 [RFC2045], with media type "multipart/mixed", and a boundary. 343 3. The body of the message is replaced with the following, in a 344 manner compliant with [RFC2045], namely: 346 A. the new boundary; 348 B. the previously deleted Content-Type header field; 350 C. a line break; 352 D. the entire original content of the message; 354 E. a line break; 356 F. the new boundary; 358 G. any MIME header fields needed to introduce the content the 359 Mediator wishes to add; 361 H. a line break; 363 I. the Mediator's content; 365 J. the terminating instance of the new boundary. 367 This leaves the new message as a MIME message with two parts at the 368 outermost layer; the original message appears as the first part, and 369 the Mediator's content is the second part. 371 The reverse of this transformation is as follows: 373 1. Extract the Content-Type header field from the first MIME part in 374 the message. This appears immediately after the first MIME 375 boundary in the message. 377 2. Replace the Content-Type header field of the message with the one 378 extracted above. 380 3. Extract the content of the first MIME part in the message. This 381 appears between the first two instances of the outermost MIME 382 boundary. 384 4. Replace the entire message body with the extracted MIME part. 386 8. Discussion 388 Section 3.5 of [RFC6376] defined an optional DKIM signature tag 389 ("z=") that can be used to reconstruct the header field set that was 390 signed by the author. When a signature fails to verify, this 391 information could conceivably be used to replay the correct 392 (original) header fields through canonicalization and possibly yield 393 a passing result. 395 Doing this augmented replay blindly would allow a signature to pass 396 when it failed because some alteration correctly rendered the 397 original content invalid or even dangerous. This is manifestly not 398 an error. Identifying which mutations of the original content ought 399 to be permissible necessarily relies on heuristics and possibly local 400 knowledge. However, a mutation universally considered to be 401 tolerable should become part of the canonicalization process rather 402 than being identified and handled in this manner. Moreover, if two 403 implementations apply different heuristics, the result of 404 verification is no longer deterministic. As a result, [RFC6376] 405 asserts that use of the "z=" content, if present, can only be used 406 for diagnostic purposes. 408 In contrast, the proposal here enumerates a handful of specific 409 mutations known to be safe, and in common use, that are also 410 reversible, which means the Author's original content can be 411 unambiguously recovered and subjected to the usual signature 412 verification process even though the message has been legitimately 413 modified by a Mediator. 415 9. Security Considerations 417 9.1. Imported from DKIM 419 Section 8 of [RFC6376] discusses numerous security considerations 420 relevant to DKIM. Of particular interest here is Section 8.2, which 421 discusses concerns regarding signatures that sill verify in the 422 presence of added message content. 424 10. IANA Considerations 426 10.1. DKIM Transformations Registry 428 IANA is requested to create a new registry in the DomainKeys 429 Identified Mail (DKIM) Parameters group called the "DKIM 430 Transformations Registry". This registry will enumerate known 431 reversible content transformations that might be made by Mediators to 432 messages bearing DKIM signatures. 434 Entries in this registry include all of the following: 436 Name: A simple name for a reversible message transformation; 438 Description: A terse description for the transformation; 440 Specification: A reference to a stable specification in which this 441 transformation and its inverse are clearly described; 443 Status: Must be one of: 445 * "active", meaning the transformation is in current use; 447 * "deprecated", meaning the transformation is not in current use. 449 An entry may be added or updated in this registry only when it meets 450 the requirements of the "Specification Required" rules found in 451 [RFC5226]. The Designated Expert will confirm that the referenced 452 specification is clear and complete, and that the transformation and 453 its inverse are not ambiguous. 455 The initial entries in this registry are as follows, all with status 456 "active": 458 add-part: Defined in Section 6 of this document. The simple 459 description is "append an extra text MIME part to a MIME-formatted 460 message". 462 mime-wrap: Defined in Section 7 of this document. The simple 463 description is "wrap a MIME-formatted message in a new multipart 464 layer". 466 mimeify: Defined in Section 5 of this document. The simple 467 description is "convert a non-MIME message to a MIME message". 469 11. References 470 11.1. Normative References 472 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 473 Extensions (MIME) Part One: Format of Internet Message 474 Bodies", RFC 2045, November 1996. 476 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 477 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 478 May 2008. 480 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 481 Specifications: ABNF", STD 68, RFC 5234, January 2008. 483 [RFC6376] Crocker, D., Hansen, T., and M. Kucherawy, "DomainKeys 484 Identified Mail (DKIM) Signatures", STD 76, RFC 6376, 485 September 2011. 487 11.2. Informative References 489 [RFC5598] Crocker, D., "Internet Mail Architecture", RFC 5598, 490 July 2009. 492 [RFC6377] Kucherawy, M., "DomainKeys Identified Mail (DKIM) and 493 Mailing Lists", BCP 167, RFC 6377, September 2011. 495 [RFC7489] Kucherawy, M. and E. Zwicky, "Domain-based Message 496 Authentication, Reporting, and Conformance (DMARC)", 497 RFC 7489, March 2015. 499 Appendix A. Examples 501 TODO: Show at least one example. 503 Appendix B. Acknowledgements 505 The original team developing this concept included Michael Adkins and 506 Wez Furlong. 508 The author wishes to acknowledge (names) for their comments during 509 the development of this document. 511 Appendix C. To-Do List 513 o Examples. 515 Appendix D. Change Log 517 00: Initial revision. 519 Author's Address 521 Murray S. Kucherawy 523 EMail: superuser@gmail.com