idnits 2.17.1 draft-ietf-httpbis-content-disp-04.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC2616, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC2616, updated by this document, for RFC5378 checks: 1997-10-16) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 12, 2010) is 4911 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8859-1' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) -- Obsolete informational reference (is this intentional?): RFC 2388 (Obsoleted by RFC 7578) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group J. Reschke 3 Internet-Draft greenbytes 4 Updates: 2616 (if approved) November 12, 2010 5 Intended status: Standards Track 6 Expires: May 16, 2011 8 Use of the Content-Disposition Header Field in the 9 Hypertext Transfer Protocol (HTTP) 10 draft-ietf-httpbis-content-disp-04 12 Abstract 14 HTTP/1.1 defines the Content-Disposition response header field, but 15 points out that it is not part of the HTTP/1.1 Standard. This 16 specification takes over the definition and registration of Content- 17 Disposition, as used in HTTP, and clarifies internationalization 18 aspects. 20 Editorial Note (To be removed by RFC Editor before publication) 22 This specification is expected to replace the definition of Content- 23 Disposition in the HTTP/1.1 specification, as currently revised by 24 the IETF HTTPbis working group. See also 25 . 27 Discussion of this draft should take place on the HTTPBIS working 28 group mailing list (ietf-http-wg@w3.org). The current issues list is 29 at and related documents (including fancy 31 diffs) can be found at . 33 The changes in this draft are summarized in Appendix D.8. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at http://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on May 16, 2011. 51 Copyright Notice 53 Copyright (c) 2010 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4 70 3. Header Field Definition . . . . . . . . . . . . . . . . . . . 4 71 3.1. Grammar . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.2. Disposition Type . . . . . . . . . . . . . . . . . . . . . 5 73 3.3. Disposition Parameter: 'Filename' . . . . . . . . . . . . 6 74 3.4. Disposition Parameter: Extensions . . . . . . . . . . . . 7 75 3.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 7 76 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 77 5. Internationalization Considerations . . . . . . . . . . . . . 8 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 80 7.1. Registry for Disposition Values and Parameter . . . . . . 8 81 7.2. Header Field Registration . . . . . . . . . . . . . . . . 9 82 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 83 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 84 9.1. Normative References . . . . . . . . . . . . . . . . . . . 9 85 9.2. Informative References . . . . . . . . . . . . . . . . . . 9 86 Appendix A. Changes from the RFC 2616 Definition . . . . . . . . 10 87 Appendix B. Differences compared to RFC 2183 . . . . . . . . . . 11 88 Appendix C. Alternative Approaches to Internationalization . . . 11 89 C.1. RFC 2047 Encoding . . . . . . . . . . . . . . . . . . . . 11 90 C.2. Percent Encoding . . . . . . . . . . . . . . . . . . . . . 11 91 C.3. Encoding Sniffing . . . . . . . . . . . . . . . . . . . . 12 92 C.4. Implementations (to be removed by RFC Editor before 93 publication) . . . . . . . . . . . . . . . . . . . . . . . 12 94 Appendix D. Change Log (to be removed by RFC Editor before 95 publication) . . . . . . . . . . . . . . . . . . . . 12 96 D.1. Since draft-reschke-rfc2183-in-http-00 . . . . . . . . . . 13 97 D.2. Since draft-reschke-rfc2183-in-http-01 . . . . . . . . . . 13 98 D.3. Since draft-reschke-rfc2183-in-http-02 . . . . . . . . . . 13 99 D.4. Since draft-reschke-rfc2183-in-http-03 . . . . . . . . . . 13 100 D.5. Since draft-ietf-httpbis-content-disp-00 . . . . . . . . . 13 101 D.6. Since draft-ietf-httpbis-content-disp-01 . . . . . . . . . 13 102 D.7. Since draft-ietf-httpbis-content-disp-02 . . . . . . . . . 13 103 D.8. Since draft-ietf-httpbis-content-disp-03 . . . . . . . . . 14 104 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 106 1. Introduction 108 HTTP/1.1 defines the Content-Disposition response header field in 109 Section 19.5.1 of [RFC2616], but points out that it is not part of 110 the HTTP/1.1 Standard (Section 15.5): 112 Content-Disposition is not part of the HTTP standard, but since it 113 is widely implemented, we are documenting its use and risks for 114 implementers. 116 This specification takes over the definition and registration of 117 Content-Disposition, as used in HTTP. Based on interoperability 118 testing with existing User Agents, it fully defines a profile of the 119 features defined in the Multipurpose Internet Mail Extensions (MIME) 120 variant ([RFC2183]) of the header field, and also clarifies 121 internationalization aspects. 123 Note: this document does not apply to Content-Disposition header 124 fields appearing in message payloads transmitted over HTTP, such 125 as when using the media type "multipart/form-data" ([RFC2388]). 127 2. Notational Conventions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 This specification uses the augmented BNF notation defined in Section 134 2.1 of [RFC2616], including its rules for implied linear whitespace 135 (LWS). 137 3. Header Field Definition 139 The Content-Disposition response header field is used to convey 140 additional information about how to process the response payload, and 141 also can be used to attach additional metadata, such as the filename 142 to use when saving the response payload locally. 144 3.1. Grammar 146 content-disposition = "Content-Disposition" ":" 147 disposition-type *( ";" disposition-parm ) 149 disposition-type = "inline" | "attachment" | disp-ext-type 150 ; case-insensitive 151 disp-ext-type = token 153 disposition-parm = filename-parm | disp-ext-parm 155 filename-parm = "filename" "=" value 156 | "filename*" "=" ext-value 158 disp-ext-parm = token "=" value 159 | ext-token "=" ext-value 160 ext-token = 162 Defined in [RFC2616]: 164 token = 165 quoted-string = 166 value = 167 ; token | quoted-string 169 Defined in [RFC5987]: 171 ext-value = 173 Senders MUST NOT generate header field values with multiple instances 174 of the same parameter name. Recipients SHOULD treat these values as 175 invalid. 177 Note that due to the rules for implied linear whitespace (Section 2.1 178 of [RFC2616]), OPTIONAL whitespace can appear between words (token or 179 quoted-string) and separator characters. 181 Furthermore note that the format used for ext-value allows specifying 182 a natural language; this is of limited use for filenames and is 183 likely to be ignored by recipients. 185 3.2. Disposition Type 187 If the disposition type matches "attachment" (case-insensitively), 188 this indicates that the user agent should prompt the user to save the 189 response locally, rather than process it normally (as per its media 190 type). 192 On the other hand, if it matches "inline" (case-insensitively), this 193 implies default processing. 195 Unknown or unhandled disposition types SHOULD be handled the same way 196 as "attachment" (see also [RFC2183], Section 2.8). 198 3.3. Disposition Parameter: 'Filename' 200 The parameters "filename" and "filename*", to be matched case- 201 insensitively, provide information on how to construct a filename for 202 storing the message payload. 204 Depending on the disposition type, this information might be used 205 right away (in the "save as..." interaction caused for the 206 "attachment" disposition type), or later on (for instance, when the 207 user decides to save the contents of the current page being 208 displayed). 210 The parameters "filename" and "filename*" differ only in that 211 "filename*" uses the encoding defined in [RFC5987], allowing the use 212 of characters not present in the ISO-8859-1 character set 213 ([ISO-8859-1]). 215 Many user agent implementations predating this specification do not 216 understand the "filename*" parameter. Therefore, when both 217 "filename" and "filename*" are present in a single header field 218 value, recipients SHOULD pick "filename*" and ignore "filename". 219 This way, senders can avoid special-casing specific user agents by 220 sending both the more expressive "filename*" parameter, and the 221 "filename" parameter as fallback for legacy recipients (see Section 4 222 for an example). 224 It is essential that user agents treat the specified filename as 225 advisory only, thus be very careful in extracting the desired 226 information. In particular: 228 o When the value contains path separator characters, all but the 229 last segment SHOULD be ignored. This prevents unintentional 230 overwriting of well-known file system location (such as "/etc/ 231 passwd"). 233 o Many platforms do not use Internet Media Types ([RFC2046]) to hold 234 type information in the file system, but rely on filename 235 extensions instead. Trusting the server-provided file extension 236 could introduce a privilege escalation when the saved file is 237 later opened (consider ".exe"). Thus, recipients need to ensure 238 that a file extension is used that is safe, optimally matching the 239 media type of the received payload. 241 o Recipients are advised to strip or replace character sequences 242 that are known to cause confusion both in user interfaces and in 243 filenames, such as control characters and leading and trailing 244 whitespace. 246 o Other aspects recipients need to be aware of are names that have a 247 special meaning in the file system or in shell commands, such as 248 "." and "..", "~", "|", and also device names. 250 Note: Many user agents do not properly handle escape characters 251 when using the quoted-string form. Furthermore, some user agents 252 erroneously try to perform unescaping of "percent" escapes (see 253 Appendix C.2), and thus might misinterpret filenames containing 254 the percent character followed by two hex digits. 256 3.4. Disposition Parameter: Extensions 258 To enable future extensions, unknown parameters SHOULD be ignored 259 (see also [RFC2183], Section 2.8). 261 3.5. Extensibility 263 Note that Section 9 of [RFC2183] defines IANA registries both for 264 disposition types and disposition parameters. This registry is 265 shared by different protocols using Content-Disposition, such as MIME 266 and HTTP. Therefore, not all registered values may make sense in the 267 context of HTTP. 269 4. Examples 271 Direct UA to show "save as" dialog, with a filename of 272 "example.html": 274 Content-Disposition: Attachment; filename=example.html 276 Direct UA to behave as if the Content-Disposition header field wasn't 277 present, but to remember the filename "an example.html" for a 278 subsequent save operation: 280 Content-Disposition: INLINE; FILENAME= "an example.html" 282 Note: this uses the quoted-string form so that the space character 283 can be included. 285 Direct UA to show "save as" dialog, with a filename containing the 286 Unicode character U+20AC (EURO SIGN): 288 Content-Disposition: attachment; 289 filename*= UTF-8''%e2%82%ac%20rates 291 Here, the encoding defined in [RFC5987] is also used to encode the 292 non-ISO-8859-1 character. 294 Same as above, but adding the "filename" parameter for compatibility 295 with user agents not implementing RFC 5987: 297 Content-Disposition: attachment; 298 filename="EURO rates"; 299 filename*=utf-8''%e2%82%ac%20rates 301 Note: as of November 2010, those user agents that do not support the 302 RFC 5987 encoding ignore "filename*" when it occurs after "filename". 303 Unfortunately, some user agents that do support RFC 5987 do pick the 304 "filename" rather than the "filename*" parameter when it occurs 305 first; it is expected that this situation is going to improve soon. 307 5. Internationalization Considerations 309 The "filename*" parameter (Section 3.3), using the encoding defined 310 in [RFC5987], allows the server to transmit characters outside the 311 ISO-8859-1 character set, and also to optionally specify the language 312 in use. 314 Future parameters might also require internationalization, in which 315 case the same encoding can be used. 317 6. Security Considerations 319 Using server-supplied information for constructing local filenames 320 introduces many risks. These are summarized in Section 3.3. 322 Furthermore, implementers also ought to be aware of the Security 323 Considerations applying to HTTP (see Section 15 of [RFC2616]), and 324 also the parameter encoding defined in [RFC5987] (see Section 5). 326 7. IANA Considerations 328 7.1. Registry for Disposition Values and Parameter 330 This specification does not introduce any changes to the registration 331 procedures for disposition values and parameters that are defined in 332 Section 9 of [RFC2183]. 334 7.2. Header Field Registration 336 This document updates the definition of the Content-Disposition HTTP 337 header field in the permanent HTTP header field registry (see 338 [RFC3864]). 340 Header field name: Content-Disposition 342 Applicable protocol: http 344 Status: standard 346 Author/Change controller: IETF 348 Specification document: this specification (Section 3) 350 8. Acknowledgements 352 Thanks to Adam Barth, Rolf Eike Beer, Bjoern Hoehrmann, Alfred 353 Hoenes, Roar Lauritzsen, Henrik Nordstrom, and Mark Nottingham for 354 their valuable feedback. 356 9. References 358 9.1. Normative References 360 [ISO-8859-1] International Organization for Standardization, 361 "Information technology -- 8-bit single-byte coded 362 graphic character sets -- Part 1: Latin alphabet No. 363 1", ISO/IEC 8859-1:1998, 1998. 365 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 366 Requirement Levels", BCP 14, RFC 2119, March 1997. 368 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 369 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 370 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 372 [RFC5987] Reschke, J., "Character Set and Language Encoding for 373 Hypertext Transfer Protocol (HTTP) Header Field 374 Parameters", RFC 5987, August 2010. 376 9.2. Informative References 378 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet 379 Mail Extensions (MIME) Part Two: Media Types", 380 RFC 2046, November 1996. 382 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail 383 Extensions) Part Three: Message Header Extensions for 384 Non-ASCII Text", RFC 2047, November 1996. 386 [RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating 387 Presentation Information in Internet Messages: The 388 Content-Disposition Header Field", RFC 2183, 389 August 1997. 391 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and 392 Encoded Word Extensions: Character Sets, Languages, and 393 Continuations", RFC 2231, November 1997. 395 [RFC2388] Masinter, L., "Returning Values from Forms: multipart/ 396 form-data", RFC 2388, August 1998. 398 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 399 Procedures for Message Header Fields", BCP 90, 400 RFC 3864, September 2004. 402 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 403 "Uniform Resource Identifier (URI): Generic Syntax", 404 STD 66, RFC 3986, January 2005. 406 Appendix A. Changes from the RFC 2616 Definition 408 Compared to Section 19.5.1 of [RFC2616], the following normative 409 changes reflecting actual implementations have been made: 411 o According to RFC 2616, the disposition type "attachment" only 412 applies to content of type "application/octet-stream". This 413 restriction has been removed, because user agents in practice do 414 not check the content type, and it also discourages properly 415 declaring the media type. 417 o RFC 2616 only allows "quoted-string" for the filename parameter. 418 This would be an exceptional parameter syntax, and also doesn't 419 reflect actual use. 421 o The definition for the disposition type "inline" ([RFC2183], 422 Section 2.1) has been re-added with a suggestion for its 423 processing. 425 o This specification requires support for the extended parameter 426 encoding defined in [RFC5987]. 428 Appendix B. Differences compared to RFC 2183 430 Section 2 of [RFC2183] defines several additional disposition 431 parameters: "creation-date", "modification-date", "quoted-date-time", 432 and "size". The majority of user agents does not implement these, 433 thus they have been omitted from this specification. 435 Appendix C. Alternative Approaches to Internationalization 437 By default, HTTP header field parameters cannot carry characters 438 outside the ISO-8859-1 ([ISO-8859-1]) character encoding (see 439 [RFC2616], Section 2.2). For the "filename" parameter, this of 440 course is an unacceptable restriction. 442 Unfortunately, user agent implementers have not managed to come up 443 with an interoperable approach, although the IETF Standards Track 444 specifies exactly one solution ([RFC2231], clarified and profiled for 445 HTTP in [RFC5987]). 447 For completeness, the sections below describe the various approaches 448 that have been tried, and explains how they are inferior to the RFC 449 5987 encoding used in this specification. 451 C.1. RFC 2047 Encoding 453 RFC 2047 defines an encoding mechanism for header fields, but this 454 encoding is not supposed to be used for header field parameters - see 455 Section 5 of [RFC2047]: 457 An 'encoded-word' MUST NOT appear within a 'quoted-string'. 459 ... 461 An 'encoded-word' MUST NOT be used in parameter of a MIME Content- 462 Type or Content-Disposition field, or in any structured field body 463 except within a 'comment' or 'phrase'. 465 In practice, some user agents implement the encoding, some do not 466 (exposing the encoded string to the user), and some get confused by 467 it. 469 C.2. Percent Encoding 471 Some user agents accept percent encoded ([RFC3986], Section 2.1) 472 sequences of characters. The character encoding being used for 473 decoding depends on various factors, including the encoding of the 474 referring page, the user agent's locale, its configuration, and also 475 the actual value of the parameter. 477 In practice, this is hard to use because those user agents that do 478 not support it will display the escaped character sequence to the 479 user. For those user agents that do implement this it is difficult 480 to predict what character encoding they actually expect. 482 C.3. Encoding Sniffing 484 Some user agents inspect the value (which defaults to ISO-8859-1 for 485 the quoted-string form) and switch to UTF-8 when it seems to be more 486 likely to be the correct interpretation. 488 As with the approaches above, this is not interoperable and 489 furthermore risks misinterpreting the actual value. 491 C.4. Implementations (to be removed by RFC Editor before publication) 493 Unfortunately, as of November 2010, neither the encoding defined in 494 RFCs 2231 and 5987, nor any of the alternate approaches discussed 495 above was implemented interoperably. Thus, this specification 496 recommends the approach defined in RFC 5987, which at least has the 497 advantage of actually being specified properly. 499 The table below shows the implementation support for the various 500 approaches: 502 +---------------+------------+--------+--------------+--------------+ 503 | User Agent | RFC | RFC | Percent | Encoding | 504 | | 2231/5987 | 2047 | Encoding | Sniffing | 505 +---------------+------------+--------+--------------+--------------+ 506 | Chrome | no (*) | yes | yes | yes | 507 | Firefox | yes (**) | yes | no | yes | 508 | Internet | no | no | yes | no | 509 | Explorer | | | | | 510 | Konqueror | yes | no | no | no | 511 | Opera | yes | no | no | no | 512 | Safari | no | no | no | yes | 513 +---------------+------------+--------+--------------+--------------+ 515 (*) But currently being implemented. 517 (**) Does not implement the fallback behavior to "filename" described 518 in Section 3.3. 520 Appendix D. Change Log (to be removed by RFC Editor before publication) 522 Note: the issues names in the change log entries for 523 draft-reschke-rfc2183-in-http refer to . 526 D.1. Since draft-reschke-rfc2183-in-http-00 528 Adjust terminology ("header" -> "header field"). Update rfc2231-in- 529 http reference. 531 D.2. Since draft-reschke-rfc2183-in-http-01 533 Update rfc2231-in-http reference. Actually define the "filename" 534 parameter. Add internationalization considerations. Add examples 535 using the RFC 5987 encoding. Add overview over other approaches, 536 plus a table reporting implementation status. Add and resolve issue 537 "nodep2183". Add issues "asciivsiso", "deplboth", "quoted", and 538 "registry". 540 D.3. Since draft-reschke-rfc2183-in-http-02 542 Add and close issue "docfallback". Close issues "asciivsiso", 543 "deplboth", "quoted", and "registry". 545 D.4. Since draft-reschke-rfc2183-in-http-03 547 Updated to be a Working Draft of the IETF HTTPbis Working Group. 549 D.5. Since draft-ietf-httpbis-content-disp-00 551 Closed issues: 553 o : "handling of 554 unknown disposition types" 556 Slightly updated the notes about the proposed fallback behavior. 558 D.6. Since draft-ietf-httpbis-content-disp-01 560 Various editorial improvements. 562 D.7. Since draft-ietf-httpbis-content-disp-02 564 Closed issues: 566 o : "state that 567 repeating parameters are invalid" 569 o : "warn about 570 %xx in filenames being misinterpreted" 572 o : "mention 573 control chars when talking about postprecessing the filename 574 parameter" 576 Update Appendix C.4; Opera 10.63 RC implements the recommended 577 fallback behavior. 579 D.8. Since draft-ietf-httpbis-content-disp-03 581 Closed issues: 583 o : 584 "'modification-date' *is* implemented in Konq 4.5" 586 o : "clarify what 587 LWS means for the Content-Disp grammar" 589 o : "Avoid passive 590 voice in message requirements" 592 o : "text about 593 historical percent-decoding unclear" 595 o : "add 596 explanation of language tagging" 598 o : "Clarify that 599 C-D spec does not apply to multipart upload" 601 Index 603 C 604 Content-Disposition header 4 606 H 607 Headers 608 Content-Disposition 4 610 Author's Address 612 Julian F. Reschke 613 greenbytes GmbH 614 Hafenweg 16 615 Muenster, NW 48155 616 Germany 618 EMail: julian.reschke@greenbytes.de 619 URI: http://greenbytes.de/tech/webdav/