HTTP Download Names: Content-Disposition and filename*
Separate response disposition, international filename encoding, and the recipient's responsibility to treat suggested names safely.
Publication & corrections: infostoa · Editorial standards
Individual author and specialist reviewer information is not provided for this article.
HTTP Content-Disposition communicates how to handle a response and suggests a filename for saving it. Attachment requests download handling; inline leaves the response to default handling. A filename is advice to the recipient, not an absolute storage path chosen by the server. International text and safe storage are separate concerns within this header.
Conceptual illustration, not an observed browser result.
Separate disposition from the suggested name
RFC 6266 describes attachment as prompting saving rather than normal handling for the media type. Inline indicates default processing and can carry additional parameters such as a filename. For a PDF, distinguish the requested handling from the name suggested if it is saved. Supplying a filename alone does not turn an inline response into an attachment.
This discussion concerns HTTP response filenames, not multipart form fields. Response rules should not be transferred to upload fields. Response disposition
Use filename* for an international name
The RFC distinguishes filename from filename*: the latter uses an extended encoding capable of representing more characters. UTF-8 data in that format can represent Korean or Japanese names. This is different from placing percent-encoded text indiscriminately into an ordinary filename parameter.
When both are present, the specification recommends that supporting recipients choose filename* and ignore filename. The values can therefore represent the same file for different recipients. A readable ASCII fallback and an extended original name are a practical pairing. Keep their meaning aligned rather than making the two names look like different documents.
A fallback can describe the same report in another language while retaining its extension.
A syntax illustration is filename="report.txt"; filename*=UTF-8''%EB%B3%B4%EA%B3%A0%EC%84%9C.txt. The language slot between the apostrophes is empty; the escapes represent UTF-8 bytes for 보고서.txt. The extended value is not a quoted-string. RFC 8187 specifies UTF-8 for producers and the extended parameter format. This is an illustrative name, not a downloaded file or a browser test. Extended parameter syntax Filename preference
Expert perspective: encoding and browser behavior
MDN's specialist reference recommends supplying both parameters for compatibility. It also warns that percent escapes in filename are handled inconsistently across browsers. Decide which parameter format is being produced before applying a URL-encoding routine to a whole filename.
Check an ASCII name and names containing spaces and international characters in the actual target browsers. Compare the displayed name with the saved name. MDN notes that browsers may transform names to meet filesystem requirements, including modifying path separators. Exact preservation of the server's string is not a universal expectation. Recipient behavior guidance
Recipients must not trust a name as a path
The RFC emphasizes treating the supplied filename as advisory only. A name containing path separators must not let a recipient write beyond its authorized location. One documented strategy is to discard folder information and retain only the last name segment. The suggestion is not permission to widen the recipient's storage access.
Extensions need review as well. In environments that interpret saved files through their extensions, trusting a server-provided extension could induce unsafe handling. The RFC requires a safe extension, ideally matching the received media type, and recommends stripping or replacing control characters and confusing whitespace. This addresses what happens after saving, not just whether the name is readable. Advisory-name safety
Verify the download contract in order
First decide the disposition, international display name, and fallback name. Then check that the two name representations agree in meaning and inspect the result in the intended recipient environment. If building a receiving application, treat storage-location checks and filename checks as explicit separate steps. This is a practical application of the RFC's recipient responsibilities.
The header does not establish the authenticity of the file or authorization to download it. Correct display of a name is separate from judging its content safe. A useful contract combines the sender's accurate disposition and encoding with the recipient's restrictions on how advisory names are used.
The sender also has a separate boundary when constructing the field. RFC 9110 treats CR, LF and NUL in field values as invalid and dangerous. Concatenating an unchecked original name into a header and using a decoded name as a recipient storage path are different problems. Filename encoding alone does not establish that both boundaries were handled safely. HTTP field values
In an illustrative checklist, keep the original display name, the two generated parameters, the observed display result and the final storage location in separate columns. Success in one column does not prove safety in the next. This exercise makes construction errors and storage restrictions separate questions rather than promising a particular sanitization algorithm.