From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc6266.txt | 787 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 787 insertions(+) create mode 100644 doc/rfc/rfc6266.txt (limited to 'doc/rfc/rfc6266.txt') diff --git a/doc/rfc/rfc6266.txt b/doc/rfc/rfc6266.txt new file mode 100644 index 0000000..7e5a074 --- /dev/null +++ b/doc/rfc/rfc6266.txt @@ -0,0 +1,787 @@ + + + + + + +Internet Engineering Task Force (IETF) J. Reschke +Request for Comments: 6266 greenbytes +Updates: 2616 June 2011 +Category: Standards Track +ISSN: 2070-1721 + + + Use of the Content-Disposition Header Field in the + Hypertext Transfer Protocol (HTTP) + +Abstract + + RFC 2616 defines the Content-Disposition response header field, but + points out that it is not part of the HTTP/1.1 Standard. This + specification takes over the definition and registration of Content- + Disposition, as used in HTTP, and clarifies internationalization + aspects. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6266. + +Copyright Notice + + Copyright (c) 2011 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + +Reschke Standards Track [Page 1] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Notational Conventions ..........................................3 + 3. Conformance and Error Handling ..................................3 + 4. Header Field Definition .........................................3 + 4.1. Grammar ....................................................4 + 4.2. Disposition Type ...........................................5 + 4.3. Disposition Parameter: 'Filename' ..........................5 + 4.4. Disposition Parameter: Extensions ..........................6 + 4.5. Extensibility ..............................................7 + 5. Examples ........................................................7 + 6. Internationalization Considerations .............................8 + 7. Security Considerations .........................................8 + 8. IANA Considerations .............................................8 + 8.1. Registry for Disposition Values and Parameters .............8 + 8.2. Header Field Registration ..................................8 + 9. Acknowledgements ................................................9 + 10. References .....................................................9 + 10.1. Normative References ......................................9 + 10.2. Informative References ....................................9 + Appendix A. Changes from the RFC 2616 Definition ..................11 + Appendix B. Differences Compared to RFC 2183 ......................11 + Appendix C. Alternative Approaches to Internationalization ........11 + C.1. RFC 2047 Encoding ..........................................12 + C.2. Percent Encoding ...........................................12 + C.3. Encoding Sniffing ..........................................12 + Appendix D. Advice on Generating Content-Disposition Header + Fields ................................................13 + +1. Introduction + + RFC 2616 defines the Content-Disposition response header field + (Section 19.5.1 of [RFC2616]) but points out that it is not part of + the HTTP/1.1 Standard (Section 15.5): + + Content-Disposition is not part of the HTTP standard, but since it + is widely implemented, we are documenting its use and risks for + implementers. + + This specification takes over the definition and registration of + Content-Disposition, as used in HTTP. Based on interoperability + testing with existing user agents (UAs), it fully defines a profile + of the features defined in the Multipurpose Internet Mail Extensions + (MIME) variant ([RFC2183]) of the header field, and also clarifies + internationalization aspects. + + + + + +Reschke Standards Track [Page 2] + +RFC 6266 Content-Disposition in HTTP June 2011 + + + Note: This document does not apply to Content-Disposition header + fields appearing in payload bodies transmitted over HTTP, such as + when using the media type "multipart/form-data" ([RFC2388]). + +2. Notational Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + This specification uses the augmented BNF (ABNF) notation defined in + Section 2.1 of [RFC2616], including its rules for implied linear + whitespace (LWS). + +3. Conformance and Error Handling + + This specification defines conformance criteria for both senders + (usually, HTTP origin servers) and recipients (usually, HTTP user + agents) of the Content-Disposition header field. An implementation + is considered conformant if it complies with all of the requirements + associated with its role. + + This specification also defines certain forms of the header field + value to be invalid, using both ABNF and prose requirements + (Section 4), but it does not define special handling of these invalid + field values. + + Senders MUST NOT generate Content-Disposition header fields that are + invalid. + + Recipients MAY take steps to recover a usable field value from an + invalid header field, but SHOULD NOT reject the message outright, + unless this is explicitly desirable behavior (e.g., the + implementation is a validator). As such, the default handling of + invalid fields is to ignore them. + +4. Header Field Definition + + The Content-Disposition response header field is used to convey + additional information about how to process the response payload, and + also can be used to attach additional metadata, such as the filename + to use when saving the response payload locally. + + + + + + + + + +Reschke Standards Track [Page 3] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +4.1. Grammar + + content-disposition = "Content-Disposition" ":" + disposition-type *( ";" disposition-parm ) + + disposition-type = "inline" | "attachment" | disp-ext-type + ; case-insensitive + disp-ext-type = token + + disposition-parm = filename-parm | disp-ext-parm + + filename-parm = "filename" "=" value + | "filename*" "=" ext-value + + disp-ext-parm = token "=" value + | ext-token "=" ext-value + ext-token = + + Defined in [RFC2616]: + + token = + quoted-string = + value = + ; token | quoted-string + + Defined in [RFC5987]: + + ext-value = + + Content-Disposition header field values with multiple instances of + the same parameter name are invalid. + + Note that due to the rules for implied linear whitespace (Section 2.1 + of [RFC2616]), OPTIONAL whitespace can appear between words (token or + quoted-string) and separator characters. + + Furthermore, note that the format used for ext-value allows + specifying a natural language (e.g., "en"); this is of limited use + for filenames and is likely to be ignored by recipients. + + + + + + + + + + + + +Reschke Standards Track [Page 4] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +4.2. Disposition Type + + If the disposition type matches "attachment" (case-insensitively), + this indicates that the recipient should prompt the user to save the + response locally, rather than process it normally (as per its media + type). + + On the other hand, if it matches "inline" (case-insensitively), this + implies default processing. Therefore, the disposition type "inline" + is only useful when it is augmented with additional parameters, such + as the filename (see below). + + Unknown or unhandled disposition types SHOULD be handled by + recipients the same way as "attachment" (see also [RFC2183], + Section 2.8). + +4.3. Disposition Parameter: 'Filename' + + The parameters "filename" and "filename*", to be matched case- + insensitively, provide information on how to construct a filename for + storing the message payload. + + Depending on the disposition type, this information might be used + right away (in the "save as..." interaction caused for the + "attachment" disposition type), or later on (for instance, when the + user decides to save the contents of the current page being + displayed). + + The parameters "filename" and "filename*" differ only in that + "filename*" uses the encoding defined in [RFC5987], allowing the use + of characters not present in the ISO-8859-1 character set + ([ISO-8859-1]). + + Many user agent implementations predating this specification do not + understand the "filename*" parameter. Therefore, when both + "filename" and "filename*" are present in a single header field + value, recipients SHOULD pick "filename*" and ignore "filename". + This way, senders can avoid special-casing specific user agents by + sending both the more expressive "filename*" parameter, and the + "filename" parameter as fallback for legacy recipients (see Section 5 + for an example). + + + + + + + + + + +Reschke Standards Track [Page 5] + +RFC 6266 Content-Disposition in HTTP June 2011 + + + It is essential that recipients treat the specified filename as + advisory only, and thus be very careful in extracting the desired + information. In particular: + + o Recipients MUST NOT be able to write into any location other than + one to which they are specifically entitled. To illustrate the + problem, consider the consequences of being able to overwrite + well-known system locations (such as "/etc/passwd"). One strategy + to achieve this is to never trust folder name information in the + filename parameter, for instance by stripping all but the last + path segment and only considering the actual filename (where 'path + segments' are the components of the field value delimited by the + path separator characters "\" and "/"). + + o Many platforms do not use Internet Media Types ([RFC2046]) to hold + type information in the file system, but rely on filename + extensions instead. Trusting the server-provided file extension + could introduce a privilege escalation when the saved file is + later opened (consider ".exe"). Thus, recipients that make use of + file extensions to determine the media type MUST ensure that a + file extension is used that is safe, optimally matching the media + type of the received payload. + + o Recipients SHOULD strip or replace character sequences that are + known to cause confusion both in user interfaces and in filenames, + such as control characters and leading and trailing whitespace. + + o Other aspects recipients need to be aware of are names that have a + special meaning in the file system or in shell commands, such as + "." and "..", "~", "|", and also device names. Recipients SHOULD + ignore or substitute names like these. + + Note: Many user agents do not properly handle the escape character + "\" when using the quoted-string form. Furthermore, some user + agents erroneously try to perform unescaping of "percent" escapes + (see Appendix C.2), and thus might misinterpret filenames + containing the percent character followed by two hex digits. + +4.4. Disposition Parameter: Extensions + + To enable future extensions, recipients SHOULD ignore unrecognized + parameters (see also [RFC2183], Section 2.8). + + + + + + + + + +Reschke Standards Track [Page 6] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +4.5. Extensibility + + Note that Section 9 of [RFC2183] defines IANA registries both for + disposition types and disposition parameters. This registry is + shared by different protocols using Content-Disposition, such as MIME + and HTTP. Therefore, not all registered values may make sense in the + context of HTTP. + +5. Examples + + Direct the UA to show "save as" dialog, with a filename of + "example.html": + + Content-Disposition: Attachment; filename=example.html + + Direct the UA to behave as if the Content-Disposition header field + wasn't present, but to remember the filename "an example.html" for a + subsequent save operation: + + Content-Disposition: INLINE; FILENAME= "an example.html" + + Note: This uses the quoted-string form so that the space character + can be included. + + Direct the UA to show "save as" dialog, with a filename containing + the Unicode character U+20AC (EURO SIGN): + + Content-Disposition: attachment; + filename*= UTF-8''%e2%82%ac%20rates + + Here, the encoding defined in [RFC5987] is also used to encode the + non-ISO-8859-1 character. + + This example is the same as the one above, but adding the "filename" + parameter for compatibility with user agents not implementing + RFC 5987: + + Content-Disposition: attachment; + filename="EURO rates"; + filename*=utf-8''%e2%82%ac%20rates + + Note: Those user agents that do not support the RFC 5987 encoding + ignore "filename*" when it occurs after "filename". + + + + + + + + +Reschke Standards Track [Page 7] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +6. Internationalization Considerations + + The "filename*" parameter (Section 4.3), using the encoding defined + in [RFC5987], allows the server to transmit characters outside the + ISO-8859-1 character set, and also to optionally specify the language + in use. + + Future parameters might also require internationalization, in which + case the same encoding can be used. + +7. Security Considerations + + Using server-supplied information for constructing local filenames + introduces many risks. These are summarized in Section 4.3. + + Furthermore, implementers ought to be aware of the security + considerations applying to HTTP (see Section 15 of [RFC2616]), and + also the parameter encoding defined in [RFC5987] (see Section 5). + +8. IANA Considerations + +8.1. Registry for Disposition Values and Parameters + + This specification does not introduce any changes to the registration + procedures for disposition values and parameters that are defined in + Section 9 of [RFC2183]. + +8.2. Header Field Registration + + This document updates the definition of the Content-Disposition HTTP + header field in the permanent HTTP header field registry (see + [RFC3864]). + + Header field name: Content-Disposition + + Applicable protocol: http + + Status: standard + + Author/Change controller: IETF + + Specification document: this specification (Section 4) + + Related information: none + + + + + + + +Reschke Standards Track [Page 8] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +9. Acknowledgements + + Thanks to Adam Barth, Rolf Eike Beer, Stewart Bryant, Bjoern + Hoehrmann, Alfred Hoenes, Roar Lauritzsen, Alexey Melnikov, Henrik + Nordstrom, and Mark Nottingham for their valuable feedback. + +10. References + +10.1. Normative References + + [ISO-8859-1] International Organization for Standardization, + "Information technology -- 8-bit single-byte coded + graphic character sets -- Part 1: Latin alphabet + No. 1", ISO/IEC 8859-1:1998, 1998. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [RFC5987] Reschke, J., "Character Set and Language Encoding for + Hypertext Transfer Protocol (HTTP) Header Field + Parameters", RFC 5987, August 2010. + +10.2. Informative References + + [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet + Mail Extensions (MIME) Part Two: Media Types", + RFC 2046, November 1996. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail + Extensions) Part Three: Message Header Extensions for + Non-ASCII Text", RFC 2047, November 1996. + + [RFC2183] Troost, R., Dorner, S., and K. Moore, Ed., + "Communicating Presentation Information in Internet + Messages: The Content-Disposition Header Field", + RFC 2183, August 1997. + + [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and + Encoded Word Extensions: Character Sets, Languages, and + Continuations", RFC 2231, November 1997. + + [RFC2388] Masinter, L., "Returning Values from Forms: multipart/ + form-data", RFC 2388, August 1998. + + + + +Reschke Standards Track [Page 9] + +RFC 6266 Content-Disposition in HTTP June 2011 + + + [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration + Procedures for Message Header Fields", BCP 90, + RFC 3864, September 2004. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, + "Uniform Resource Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [US-ASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Reschke Standards Track [Page 10] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +Appendix A. Changes from the RFC 2616 Definition + + Compared to Section 19.5.1 of [RFC2616], the following normative + changes reflecting actual implementations have been made: + + o According to RFC 2616, the disposition type "attachment" only + applies to content of type "application/octet-stream". This + restriction has been removed, because recipients in practice do + not check the content type, and it also discourages properly + declaring the media type. + + o RFC 2616 only allows "quoted-string" for the filename parameter. + This would be an exceptional parameter syntax, and also doesn't + reflect actual use. + + o The definition for the disposition type "inline" ([RFC2183], + Section 2.1) has been re-added with a suggestion for its + processing. + + o This specification requires support for the extended parameter + encoding defined in [RFC5987]. + +Appendix B. Differences Compared to RFC 2183 + + Section 2 of [RFC2183] defines several additional disposition + parameters: "creation-date", "modification-date", "quoted-date-time", + and "size". The majority of user agents do not implement these; + thus, they have been omitted from this specification. + +Appendix C. Alternative Approaches to Internationalization + + By default, HTTP header field parameters cannot carry characters + outside the ISO-8859-1 ([ISO-8859-1]) character encoding (see + [RFC2616], Section 2.2). For the "filename" parameter, this of + course is an unacceptable restriction. + + Unfortunately, user agent implementers have not managed to come up + with an interoperable approach, although the IETF Standards Track + specifies exactly one solution ([RFC2231], clarified and profiled for + HTTP in [RFC5987]). + + For completeness, the sections below describe the various approaches + that have been tried, and explain how they are inferior to the + RFC 5987 encoding used in this specification. + + + + + + + +Reschke Standards Track [Page 11] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +C.1. RFC 2047 Encoding + + RFC 2047 defines an encoding mechanism for header fields, but this + encoding is not supposed to be used for header field parameters -- + see Section 5 of [RFC2047]: + + An 'encoded-word' MUST NOT appear within a 'quoted-string'. + + ... + + An 'encoded-word' MUST NOT be used in parameter of a MIME Content- + Type or Content-Disposition field, or in any structured field body + except within a 'comment' or 'phrase'. + + In practice, some user agents implement the encoding, some do not + (exposing the encoded string to the user), and some get confused by + it. + +C.2. Percent Encoding + + Some user agents accept percent-encoded ([RFC3986], Section 2.1) + sequences of characters. The character encoding being used for + decoding depends on various factors, including the encoding of the + referring page, the user agent's locale, its configuration, and also + the actual value of the parameter. + + In practice, this is hard to use because those user agents that do + not support it will display the escaped character sequence to the + user. For those user agents that do implement this, it is difficult + to predict what character encoding they actually expect. + +C.3. Encoding Sniffing + + Some user agents inspect the value (which defaults to ISO-8859-1 for + the quoted-string form) and switch to UTF-8 when it seems to be more + likely to be the correct interpretation. + + As with the approaches above, this is not interoperable and, + furthermore, risks misinterpreting the actual value. + + + + + + + + + + + + +Reschke Standards Track [Page 12] + +RFC 6266 Content-Disposition in HTTP June 2011 + + +Appendix D. Advice on Generating Content-Disposition Header Fields + + To successfully interoperate with existing and future user agents, + senders of the Content-Disposition header field are advised to: + + o Include a "filename" parameter when US-ASCII ([US-ASCII]) is + sufficiently expressive. + + o Use the 'token' form of the filename parameter only when it does + not contain disallowed characters (e.g., spaces); in such cases, + the quoted-string form should be used. + + o Avoid including the percent character followed by two hexadecimal + characters (e.g., %A9) in the filename parameter, since some + existing implementations consider it to be an escape character, + while others will pass it through unchanged. + + o Avoid including the "\" character in the quoted-string form of the + filename parameter, as escaping is not implemented by some user + agents, and "\" can be considered an illegal path character. + + o Avoid using non-ASCII characters in the filename parameter. + Although most existing implementations will decode them as + ISO-8859-1, some will apply heuristics to detect UTF-8, and thus + might fail on certain names. + + o Include a "filename*" parameter where the desired filename cannot + be expressed faithfully using the "filename" form. Note that + legacy user agents will not process this, and will fall back to + using the "filename" parameter's content. + + o When a "filename*" parameter is sent, to also generate a + "filename" parameter as a fallback for user agents that do not + support the "filename*" form, if possible. This can be done by + substituting characters with US-ASCII sequences (e.g., Unicode + character point U+00E4 (LATIN SMALL LETTER A WITH DIARESIS) by + "ae"). Note that this may not be possible in some locales. + + o When a "filename" parameter is included as a fallback (as per + above), "filename" should occur first, due to parsing problems in + some existing implementations. + + o Use UTF-8 as the encoding of the "filename*" parameter, when + present, because at least one existing implementation only + implements that encoding. + + + + + + +Reschke Standards Track [Page 13] + +RFC 6266 Content-Disposition in HTTP June 2011 + + + Note that this advice is based upon UA behavior at the time of + writing, and might be superseded. At the time of publication of this + document, + provides an overview of current levels of support in various + implementations. + +Author's Address + + Julian F. Reschke + greenbytes GmbH + Hafenweg 16 + Muenster, NW 48155 + Germany + + EMail: julian.reschke@greenbytes.de + URI: http://greenbytes.de/tech/webdav/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Reschke Standards Track [Page 14] + -- cgit v1.2.3