[Search] [txt|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
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&eacute; F&auml;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