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 19.5.1 of [RFC2616]) but points out that it is not part of the HTTP/1.1 Standard (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.

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           = <the characters in token, followed by "*">

Defined in [RFC2616]:

  token         = <token, defined in [RFC2616], Section 2.2>
  quoted-string = <quoted-string, defined in [RFC2616], Section 2.2>
  value         = <value, defined in [RFC2616], Section 3.6>
                ; token | quoted-string

Defined in [RFC5987]:

  ext-value   = <ext-value, defined in [RFC5987], Section 3.2>

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

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 Key words for use in RFCs to Indicate Requirement Levels”, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types”, RFC 2046, November 1996.

[RFC2047]

Moore, K., “Returning Values from Forms: multipart/form-data”, RFC 2388, August 1998.

[RFC3864]

Klyne, G., Nottingham, M., and J. Mogul, “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.

Appendix A. Changes from the RFC 2616 Definition

Compared to 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 http://greenbytes.de/tech/webdav/