idnits 2.17.1 draft-ietf-httpbis-content-disp-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 : ---------------------------------------------------------------------------- -- 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 (September 3, 2010) is 4984 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) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 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) September 3, 2010 5 Intended status: Standards Track 6 Expires: March 7, 2011 8 Use of the Content-Disposition Header Field in the 9 Hypertext Transfer Protocol (HTTP) 10 draft-ietf-httpbis-content-disp-00 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 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 March 7, 2011. 50 Copyright Notice 52 Copyright (c) 2010 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. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4 69 3. Header Field Definition . . . . . . . . . . . . . . . . . . . 4 70 3.1. Grammar . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 3.2. Disposition Type . . . . . . . . . . . . . . . . . . . . . 5 72 3.3. Disposition Parameter: 'Filename' . . . . . . . . . . . . 5 73 3.4. Disposition Parameter: Extensions . . . . . . . . . . . . 6 74 3.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 6 75 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 5. Internationalization Considerations . . . . . . . . . . . . . 7 77 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 78 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 79 7.1. Registry for Disposition Values and Parameter . . . . . . 8 80 7.2. Header Field Registration . . . . . . . . . . . . . . . . 8 81 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8 82 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 83 9.1. Normative References . . . . . . . . . . . . . . . . . . . 8 84 9.2. Informative References . . . . . . . . . . . . . . . . . . 9 85 Appendix A. Changes from the RFC 2616 Definition . . . . . . . . 9 86 Appendix B. Differences compared to RFC 2183 . . . . . . . . . . 10 87 Appendix C. Alternative Approaches to Internationalization . . . 10 88 C.1. RFC 2047 Encoding . . . . . . . . . . . . . . . . . . . . 10 89 C.2. Percent Encoding . . . . . . . . . . . . . . . . . . . . . 11 90 C.3. Encoding Sniffing . . . . . . . . . . . . . . . . . . . . 11 91 C.4. Implementations . . . . . . . . . . . . . . . . . . . . . 11 92 Appendix D. Change Log (to be removed by RFC Editor before 93 publication) . . . . . . . . . . . . . . . . . . . . 12 94 D.1. Since draft-reschke-rfc2183-in-http-00 . . . . . . . . . . 12 95 D.2. Since draft-reschke-rfc2183-in-http-01 . . . . . . . . . . 12 96 D.3. Since draft-reschke-rfc2183-in-http-02 . . . . . . . . . . 12 97 D.4. Since draft-reschke-rfc2183-in-http-03 . . . . . . . . . . 12 99 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 101 1. Introduction 103 HTTP/1.1 defines the Content-Disposition response header field in 104 Section 19.5.1 of [RFC2616], but points out that it is not part of 105 the HTTP/1.1 Standard (Section 15.5): 107 Content-Disposition is not part of the HTTP standard, but since it 108 is widely implemented, we are documenting its use and risks for 109 implementers. 111 This specification takes over the definition and registration of 112 Content-Disposition, as used in HTTP. Based on interoperability 113 testing with existing User Agents, it fully defines a profile of the 114 features defined in the Multipurpose Internet Mail Extensions (MIME) 115 variant ([RFC2183]) of the header field, and also clarifies 116 internationalization aspects. 118 2. Notational Conventions 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 122 document are to be interpreted as described in [RFC2119]. 124 This specification uses the augmented BNF notation defined in Section 125 2.1 of [RFC2616], including its rules for linear whitespace (LWS). 127 3. Header Field Definition 129 The Content-Disposition response header field is used to convey 130 additional information about how to process the response payload, and 131 also can be used to attach additional metadata, such as the filename. 133 3.1. Grammar 135 content-disposition = "Content-Disposition" ":" 136 disposition-type *( ";" disposition-parm ) 138 disposition-type = "inline" | "attachment" | disp-ext-type 139 ; case-insensitive 140 disp-ext-type = token 142 disposition-parm = filename-parm | disp-ext-parm 144 filename-parm = "filename" "=" value 145 | "filename*" "=" ext-value 147 disp-ext-parm = token "=" value 148 | ext-token "=" ext-value 149 ext-token = 151 Defined in [RFC2616]: 153 token = 154 value = 156 Defined in [RFC5987]: 158 ext-value = 160 3.2. Disposition Type 162 If the disposition type matches "attachment" (case-insensitively), 163 this indicates that the user agent should not display the response, 164 but directly enter a "save as..." dialog. 166 On the other hand, if it matches "inline" (case-insensitively), this 167 implies default processing. 169 Other disposition types SHOULD be handled the same way as 170 "attachment" (see also [RFC2183], Section 2.8). 172 3.3. Disposition Parameter: 'Filename' 174 The parameters "filename" and "filename*", to be matched case- 175 insensitively, provide information on how to construct a filename for 176 storing the message payload. 178 Depending on the disposition type, this information might be used 179 right away (in the "save as..." interaction caused for the 180 "attachment" disposition type), or later on (for instance, when the 181 user decides to save the contents of the current page being 182 displayed). 184 "filename" and "filename*" behave the same, except that "filename*" 185 uses the encoding defined in [RFC5987], allowing the use of 186 characters not present in the ISO-8859-1 character set 187 ([ISO-8859-1]). When both "filename" and "filename*" are present, a 188 recipient SHOULD pick "filename*" and ignore "filename" - this will 189 make it possible to send the same header value to clients that do not 190 support "filename*". 192 It is essential that user agents treat the specified filename as 193 advisory only, thus be very careful in extracting the desired 194 information. In particular: 196 o When the value contains path separator characters, all but the 197 last segment SHOULD be ignored. This prevents unintentional 198 overwriting of well-known file system location (such as "/etc/ 199 passwd"). 201 o Many platforms do not use Internet Media Types ([RFC2046]) to hold 202 type information in the file system, but rely on filename 203 extensions instead. Trusting the server-provided file extension 204 could introduce a privilege escalation when later on the file is 205 opened locally (consider ".exe"). Thus, recipients need to ensure 206 that a file extension is used that is safe, optimally matching the 207 media type of the received payload. 209 o Other aspects recipients need to be aware of are names that have a 210 special meaning in the filesystem or in shell commands, such as 211 "." and "..", "~", "|", and also device names. 213 3.4. Disposition Parameter: Extensions 215 To enable future extensions, unknown parameters SHOULD be ignored 216 (see also [RFC2183], Section 2.8). 218 3.5. Extensibility 220 Note that Section 9 of [RFC2183] defines IANA registries both for 221 disposition types and disposition parameters. This registry is 222 shared by different protocols using Content-Disposition, such as MIME 223 and HTTP. Therefore, not all registered values may make sense in the 224 context of HTTP. 226 4. Examples 228 Direct UA to show "save as" dialog, with a filename of "foo.html": 230 Content-Disposition: Attachment; filename=foo.html 232 Direct UA to behave as if the Content-Disposition header field wasn't 233 present, but to remember the filename "foo.html" for a subsequent 234 save operation: 236 Content-Disposition: INLINE; FILENAME= "foo.html" 238 Direct UA to show "save as" dialog, with a filename of "an example": 240 Content-Disposition: Attachment; Filename*=UTF-8'en'an%20example 242 Note that this example uses the extended encoding defined in 243 [RFC5987] to specify that the natural language of the filename is 244 English, and also to encode the space character which is not allowed 245 in the token production. 247 Direct UA to show "save as" dialog, with a filename containing the 248 Unicode character U+20AC (EURO SIGN): 250 Content-Disposition: attachment; filename*= UTF-8''%e2%82%ac%20rates 252 Here, the encoding defined in [RFC5987] is also used to encode the 253 non-ISO-8859-1 character. 255 Same as above, but adding the "filename" parameter for compatibility 256 with user agents not implementing RFC 5987: 258 Content-Disposition: attachment; filename="EURO rates"; 259 filename*=utf-8''%e2%82%ac%20rates 261 Note: as of August 2010, many user agents unfortunately did not 262 properly handle unexpected parameters, and some that implement RFC 263 5987 did not pick the extended parameter when both were present. 265 5. Internationalization Considerations 267 The "filename*" parameter (Section 3.3), using the encoding defined 268 in [RFC5987], allows the server to transmit characters outside the 269 ISO-8859-1 character set, and also to optionally specify the language 270 in use. 272 Future parameters might also require internationalization, in which 273 case the same encoding can be used. 275 6. Security Considerations 277 Using server-supplied information for constructing local filenames 278 introduces many risks. These are summarized in Section 3.3. 280 Furthermore, implementers also ought to be aware of the Security 281 Considerations applying to HTTP (see Section 15 of [RFC2616]), and 282 also the parameter encoding defined in [RFC5987] (see Appendix ). 284 7. IANA Considerations 286 7.1. Registry for Disposition Values and Parameter 288 This specification does not introduce any changes to the registration 289 procedures for disposition values and parameters that are defined in 290 Section 9 of [RFC2183]. 292 7.2. Header Field Registration 294 This document updates the definition of the Content-Disposition HTTP 295 header field in the permanent HTTP header field registry (see 296 [RFC3864]). 298 Header field name: Content-Disposition 300 Applicable protocol: http 302 Status: standard 304 Author/Change controller: IETF 306 Specification document: this specification (Section 3) 308 8. Acknowledgements 310 Thanks to Rolf Eike Beer, Alfred Hoenes, and Roar Lauritzsen for 311 their valuable feedback. 313 9. References 315 9.1. Normative References 317 [ISO-8859-1] International Organization for Standardization, 318 "Information technology -- 8-bit single-byte coded 319 graphic character sets -- Part 1: Latin alphabet No. 320 1", ISO/IEC 8859-1:1998, 1998. 322 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 323 Requirement Levels", BCP 14, RFC 2119, March 1997. 325 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 326 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 327 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 329 [RFC5987] Reschke, J., "Applicability of RFC 2231 Encoding to 330 Hypertext Transfer Protocol (HTTP) Headers", RFC 5987, 331 August 2010. 333 9.2. Informative References 335 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet 336 Mail Extensions (MIME) Part Two: Media Types", 337 RFC 2046, November 1996. 339 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail 340 Extensions) Part Three: Message Header Extensions for 341 Non-ASCII Text", RFC 2047, November 1996. 343 [RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating 344 Presentation Information in Internet Messages: The 345 Content-Disposition Header Field", RFC 2183, 346 August 1997. 348 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and 349 Encoded Word Extensions: Character Sets, Languages, and 350 Continuations", RFC 2231, November 1997. 352 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 353 10646", RFC 3629, STD 63, November 2003. 355 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 356 Procedures for Message Header Fields", BCP 90, 357 RFC 3864, September 2004. 359 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 360 "Uniform Resource Identifier (URI): Generic Syntax", 361 RFC 3986, STD 66, January 2005. 363 Appendix A. Changes from the RFC 2616 Definition 365 Compared to Section 19.5.1 of [RFC2616], the following normative 366 changes reflecting actual implementations have been made: 368 o According to RFC 2616, the disposition type "attachment" only 369 applies to content of type "application/octet-stream". This 370 restriction has been removed, because user agents in practice do 371 not check the content type, and it also discourages properly 372 declaring the media type. 374 o RFC 2616 only allows "quoted-string" for the filename parameter. 375 This would be an exceptional parameter syntax, and also doesn't 376 reflect actual use. 378 o The definition for the disposition type "inline" ([RFC2183], 379 Section 2.1) has been re-added with a suggestion for its 380 processing. 382 o This specification requires support for the extended parameter 383 encoding defined in [RFC5987]. 385 Appendix B. Differences compared to RFC 2183 387 Section 2 of [RFC2183] defines several additional disposition 388 parameters: "creation-date", "modification-date", "quoted-date-time", 389 and "size". These do not appear to be implemented by any user agent, 390 thus have been omitted from this specification. 392 Appendix C. Alternative Approaches to Internationalization 394 By default, HTTP header field parameters cannot carry characters 395 outside the ISO-8859-1 ([ISO-8859-1]) character encoding (see 396 [RFC2616], Section 2.2). For the "filename" parameter, this of 397 course is an unacceptable restriction. 399 Unfortunately, user agent implementers have not managed to come up 400 with an interoperable approach, although the IETF Standards Track 401 specifies exactly one solution ([RFC2231], clarified and profiled for 402 HTTP in [RFC5987]). 404 For completeness, the sections below describe the various approaches 405 that have been tried, and explains how they are inferior to the RFC 406 5987 encoding used in this specification. 408 C.1. RFC 2047 Encoding 410 RFC 2047 defines an encoding mechanism for header fields, but this 411 encoding is not supposed to be used for header field parameters - see 412 Section 5 of [RFC2047]: 414 An 'encoded-word' MUST NOT appear within a 'quoted-string'. 416 ... 418 An 'encoded-word' MUST NOT be used in parameter of a MIME Content- 419 Type or Content-Disposition field, or in any structured field body 420 except within a 'comment' or 'phrase'. 422 In practice, some user agents implement the encoding, some do not 423 (exposing the encoded string to the user), and some get confused by 424 it. 426 C.2. Percent Encoding 428 Some user agents accept percent encoded ([RFC3986], Section 2.1) 429 sequences of characters encoded using the UTF-8 ([RFC3629]) character 430 encoding. 432 In practice, this is hard to use because those user agents that do 433 not support it will display the escaped character sequence to the 434 user. 436 Furthermore, the first user agent to implement this did choose the 437 encoding based on local settings; thus making it very hard to use in 438 multi-lingual environments. 440 C.3. Encoding Sniffing 442 Some user agents inspect the value (which defaults to ISO-8859-1) and 443 switch to UTF-8 when it seems to be more likely to be the correct 444 interpretation. 446 As with the approaches above, this is not interoperable and 447 furthermore risks misinterpreting the actual value. 449 C.4. Implementations 451 Unfortunately, as of August 2010, neither the encoding defined in 452 RFCs 2231 and 5789, nor any of the alternate approaches discussed 453 above was implemented interoperably. Thus, this specification 454 recommends the approach defined in RFC 5987, which at least has the 455 advantage of actually being specified properly. 457 The table below shows the implementation support for the various 458 approaches: [[impls: Discuss: should we mention the implementation 459 status of actual UAs in a RFC? Up to the IESG to decide...]] 460 +---------------+------------+--------+--------------+--------------+ 461 | User Agent | RFC | RFC | Percent | Encoding | 462 | | 2231/5987 | 2047 | Encoding | Sniffing | 463 +---------------+------------+--------+--------------+--------------+ 464 | Chrome | no | yes | yes | yes | 465 | Firefox | yes (*) | yes | no | yes | 466 | Internet | no | no | yes | no | 467 | Explorer | | | | | 468 | Konqueror | yes | no | no | no | 469 | Opera | yes (*) | no | no | no | 470 | Safari | no | no | no | yes | 471 +---------------+------------+--------+--------------+--------------+ 473 (*) Does not implement the fallback behavior to "filename" described 474 in Section 3.3. 476 Appendix D. Change Log (to be removed by RFC Editor before publication) 478 D.1. Since draft-reschke-rfc2183-in-http-00 480 Adjust terminology ("header" -> "header field"). Update rfc2231-in- 481 http reference. 483 D.2. Since draft-reschke-rfc2183-in-http-01 485 Update rfc2231-in-http reference. Actually define the "filename" 486 parameter. Add internationalization considerations. Add examples 487 using the RFC 5987 encoding. Add overview over other approaches, 488 plus a table reporting implementation status. Add and resolve issue 489 "nodep2183". Add issues "asciivsiso", "deplboth", "quoted", and 490 "registry". 492 D.3. Since draft-reschke-rfc2183-in-http-02 494 Add and close issue "docfallback". Close issues "asciivsiso", 495 "deplboth", "quoted", and "registry". 497 D.4. Since draft-reschke-rfc2183-in-http-03 499 Updated to be a Working Draft of the IETF HTTPbis Working Group. 501 Index 503 C 504 Content-Disposition header 4 506 H 507 Headers 508 Content-Disposition 4 510 Author's Address 512 Julian F. Reschke 513 greenbytes GmbH 514 Hafenweg 16 515 Muenster, NW 48155 516 Germany 518 EMail: julian.reschke@greenbytes.de 519 URI: http://greenbytes.de/tech/webdav/