Internet DRAFT - draft-faerber-http-content-disp
draft-faerber-http-content-disp
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
