Skip to main content

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

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

It is essential that recipients treat the specified filename as advisory only, and thus be very careful in extracting the desired information. In particular:

  • 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 "/").

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

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

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

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.

Last updated on