Skip to main content

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:

  • 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.

  • RFC 2616 only allows "quoted-string" for the filename parameter. This would be an exceptional parameter syntax, and also doesn't reflect actual use.

  • The definition for the disposition type "inline" ([RFC2183], Section 2.1) has been re-added with a suggestion for its processing.

  • 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.

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.

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:

  • Include a "filename" parameter when US-ASCII ([US-ASCII]) is sufficiently expressive.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • When a "filename" parameter is included as a fallback (as per above), "filename" should occur first, due to parsing problems in some existing implementations.

  • Use UTF-8 as the encoding of the "filename*" parameter, when present, because at least one existing implementation only implements that encoding.

Note: This advice is based upon UA behavior at the time of writing, and might be superseded. At the time of publication of this document, http://purl.org/NET/http/content-disposition-tests provides an overview of current levels of support in various implementations.

Last updated on