Internet Draft Claus Andre Faerber draft-faerber-http-content-disp-00 1998-09-25 Intends to Update: RFC 2068/draft-ietf-http-v11-rev Expires: 1999-04-25 Use of the Content-Disposition header with HTTP. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). This memo is an individual submission and not a product of an IETF Working Group. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract [RFC2183] introduces a Content-Disposition header field for Internet Mail Messages to transmit presentation information as well as a suggested file name for saving the content to disk and the file's date information. All of this information is missing from HTTP entities [RFC2068]. However, there is nothing that would prevent the use of the Content- Disposition header with this HTTP. Without being standard, the Content-Disposition header has already been introduced by some software products. [HTTP1.1-REV] documents this practice, based on [RFC1806]. This memo also extends the specification to cover [RFC2183] and corrects the common abuse of the Content-Type header to cover presentation information. Table of Contents Status of this Memo Copyright Notice Abstract Table of Contents Definitions 1 Format of the Content-Disposition Header 2 Interpretation of the Disposition Types and Parameters 2.1 The Inline Disposition type 2.2 The Attachment Disposition Type 2.3 The Filename Parameter 2.4 The Creation-Date, Modification-Date, Read-Date and Size parameters 2.4.1 Relation of Modification-Date to Last-Modified 2.4.2 Relation of Size and Content-Length/Content-Range 3 Use within HTTP Messages 3.1 Use within HTTP multipart messages. 3.1.1 Use on individual parts of the multipart messages 3.1.2 Use on the top level multipart message 4 Security Considerations Appendix A Examples B Acknowledgements References Author Full Copyright Statement Definitions This memo uses the Augmented BNF defined in [RFC2234] as well as some definitions from [RFC822]. 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]. The reader should be familiar with [RFC2068] and [RFC2183]. 1 Format of the Content-Disposition Header [RFC2183] defines the Content-Disposition header as follows (modified for HTTP and to align with [ABNF]): disposition = "Content-Disposition" *WSP ":" LWSP disposition-type LWSP *( LWSP ";" LWSP disposition-parm LWSP ) disposition-type = "inline" / "attachment" / extension-token ; values are not case-sensitive disposition-parm = filename-parm / creation-date-parm / modification-date-parm / read-date-parm / size-parm / parameter See [RFC2183] for more details on definitions of the parameters defined. Please note that while in mail messages there MAY be CFWS within the header field, this is not true for HTTP headers, which only allows linear white space and line folding but no comments. 2 Interpretation of the Disposition Types and Parameters As HTTP differs from email, there are also small semantic differences for the meaning of the disposition-types. Future documents defining other disposition-types may also define whether and how they are to be interpreted within HTTP. Registration of new disposition-types SHOULD use the procedures described in [RFC2183, section 9]. HTTP disposition-types share the registry with MIME. Unknown types should be handled as "attachment". See [RFC2183, section 2.8] for details. 2.1 The Inline Disposition type An HTTP entity should be marked "inline" if it is intended to be displayed automatically upon receipt of the HTTP message, e.g. in the web browser's window. This is the default. (However, the fall back mechanism described below MAY be implemented in a way that it is only used if the entity is not marked explicitly as "inline".) User agents MAY fall back to "attachment" (see section 2.2) if they feel unable to display the entity received (e.g. because they can't handle the Content-Type). They MIGHT also use a generic viewer, such as a hex viewer. 2.2 The Attachment Disposition Type Entities can be designated "attachment" to indicate that their display should not be automatic, but contingent upon some further action of the user. The HTTP user agent might instead present the user a request to save the entity as a file to disk ("download"). 2.3 The Filename Parameter The sender of an entity-body may want to suggest a filename to be used if the entity is stored in a separate file. If the receiving HTTP User Agent writes the entity to a file, the suggested filename should be used as a basis for the actual filename, where possible. NOTE: This is particularly useful if an entity is transmitted by something like a CGI programme, as the request URL might not contain the actual or an appropriate filename in this case. It is important that the receiving HTTP user agent not blindly use the suggested filename. The suggested filename SHOULD be checked (and possibly changed) to see that it conforms to local filesystem conventions, does not overwrite an existing file, and does not present a security problem (see Security Considerations below). On systems that determine file types as part of the file name (e.g. an "extension"), the filename SHOULD be modified according to the Content-Type header, so that the system will correctly determine the file type. For a more complete discussion of the filename parameter, see [RFC2183, section 2.3]. 2.4 The Creation-Date, Modification-Date, Read-Date and Size parameters These headers have the same semantics as described in [RFC2182, sections 2.4 to 2.7]. For the relation to some "similar" HTTP headers, see the sections 2.4.1 and 2.4.2 in this memo. 2.4.1 Relation of Modification-Date to Last-Modified The Modification-Date parameter has similar semantics to the Last- Modified HTTP message header. As a general rule, Last-Modified is a generic HTTP modification date, possibly used for cache validation, while the Modification-date parameter is exclusively used to specify the modification date for a file created when the HTTP entity is saved to disk. As a consequence, the date given in the Modification-Date parameter MAY be different from that in the Last-Modified header, e.g. if a file is presented for download, the Last-Modified header MAY contain the date at which the file was made available under this URL ("upload"), while the Modification-Date parameter MAY contain the date at which the file was originally created. 2.4.2 Relation of Size and Content-Length/Content-Range Unlike the Content-Length and Content-Range header, which refer to the size of the encoded entity-body (or message-body), the Size parameter specifies the length in octets of the unencoded/decoded (if a Content-Encoding is used) entity transmitted, as a hint for the User Agent when saving the entity to a file. For the difference of message-body and entity-body, see [RFC2068, section 4.3]. As a result, the Size parameter MAY always be used, even if the Content-Length header MUST NOT. 3 Use within HTTP Messages The Content-Disposition header MAY be used with any HTTP response or request that contains or references to entities as defined in [RFC2068, section 7]. The Content-Disposition header is an extension to the entity header list defined in section [RFC2068, section 7.1]. For POST and PUT requests, only the disposition-type "attachment" SHOULD be used. 3.1 Use within HTTP multipart messages. 3.1.1 Use on individual parts of the multipart messages If the Content-Disposition header is used on individual parts of a HTTP multipart/* response, the semantics of [RFC2183] should be used if the entity is displayed as a whole. However, the semantics described in this memo apply if the definition of the multipart type suggest individual display of the individual parts as separate top-level entities (e.g. "server-push" [FIXME: reference]). The Content-Type header SHOULD NOT be used for multipart/byte-range messages. 3.1.2 Use on the top level multipart message The Content-Disposition header can also be used on top level multipart entities. In this case, the header applies to the multipart message as a whole. 4 Security Considerations See [RFC2183, section 5] for a complete discussions for the security impacts of the Content-Disposition header. Appendix A Examples In this sections, lines starting with C: are sent by the client, while those starting with S: are sent by the server. Only relevant headers are shown. A.1 Downloading a file through a CGI URL. C: GET /cgi-bin/download.cgi?product=foo;ver=1.2;lang=de;pack=tgz HTT P/1.1 C: Host: www.example.com C: S: 200 HTTP/1.1 OK S: Content-Type: application/tar S: Content-Encoding: gzip S: Content-Length: 123456 S: Content-Disposition: attachment; filename="foo-1.2.tar"; S: modification-date="Sat, 01 Aug 1998 00:00:00 +0000"; size=234567 S: Last-Modified: Mon, 03 Aug 1998 08:23:23 +0200 S: S: ...data B Acknowledgements Many parts of these document are taken more or less literally from [RFC2183] by R. Troost, S. Dorner, and K. Moore. This document has also been inspired by the discussion in the IETF HTTP-WG. References [HTTP1.1-REV] Fielding, R., Gettys, J., Mogul, J. C., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., "Hypertext Transfer Protocol -- HTTP/1.1", September 1998 (Expires March 1999), Internet Draft <draft-ietf-http-v11-spec-rev-05>, WORK IN PROGRESS (Will Update RFC 2068). [RFC822] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", August 1982, STD 11, RFC 822. [RFC1806] Troost, R., Dorner, S. "Communicating Presentation Information in Internet Messages: The Content-Disposition Header", June 1995. RFC 1806 (Updated by RFC 2183). [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Berners-Lee, T., "Hypertext Transfer Protocol -- HTTP/1.1", January 1997, RFC 2068. [RFC2183] Troost, R., Dorner, S., Moore, K., "Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field", August 1997. RFC 2183. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", March 1997, RFC 2119. [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax Specifications: ABNF", November 1997, RFC 2234. Author Claus Andre Faerber Mitterfeldstrasse 20 83043 Bad Aibling Germany Fax: +49-8061-3361 E-Mail: cfaerber@muc.de Note: Please write the author's name with the correct diacritic marks where possible, i.e. Claus André Färber in HTML. Full Copyright Statement Copyright (C) The Internet Society (1998). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organisations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Internet Draft Expires 1999-03-25 Claus