1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675
|
Network Working Group R. Troost
Request for Comments: 2183 New Century Systems
Updates: 1806 S. Dorner
Category: Standards Track QUALCOMM Incorporated
K. Moore, Editor
University of Tennessee
August 1997
Communicating Presentation Information in
Internet Messages:
The Content-Disposition Header Field
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Abstract
This memo provides a mechanism whereby messages conforming to the
MIME specifications [RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC
2049] can convey presentational information. It specifies the
"Content-Disposition" header field, which is optional and valid for
any MIME entity ("message" or "body part"). Two values for this
header field are described in this memo; one for the ordinary linear
presentation of the body part, and another to facilitate the use of
mail to transfer files. It is expected that more values will be
defined in the future, and procedures are defined for extending this
set of values.
This document is intended as an extension to MIME. As such, the
reader is assumed to be familiar with the MIME specifications, and
[RFC 822]. The information presented herein supplements but does not
replace that found in those documents.
This document is a revision to the Experimental protocol defined in
RFC 1806. As compared to RFC 1806, this document contains minor
editorial updates, adds new parameters needed to support the File
Transfer Body Part, and references a separate specification for the
handling of non-ASCII and/or very long parameter values.
Troost, et. al. Standards Track [Page 1]
RFC 2183 Content-Disposition August 1997
1. Introduction
MIME specifies a standard format for encapsulating multiple pieces of
data into a single Internet message. That document does not address
the issue of presentation styles; it provides a framework for the
interchange of message content, but leaves presentation issues solely
in the hands of mail user agent (MUA) implementors.
Two common ways of presenting multipart electronic messages are as a
main document with a list of separate attachments, and as a single
document with the various parts expanded (displayed) inline. The
display of an attachment is generally construed to require positive
action on the part of the recipient, while inline message components
are displayed automatically when the message is viewed. A mechanism
is needed to allow the sender to transmit this sort of presentational
information to the recipient; the Content-Disposition header provides
this mechanism, allowing each component of a message to be tagged
with an indication of its desired presentation semantics.
Tagging messages in this manner will often be sufficient for basic
message formatting. However, in many cases a more powerful and
flexible approach will be necessary. The definition of such
approaches is beyond the scope of this memo; however, such approaches
can benefit from additional Content-Disposition values and
parameters, to be defined at a later date.
In addition to allowing the sender to specify the presentational
disposition of a message component, it is desirable to allow her to
indicate a default archival disposition; a filename. The optional
"filename" parameter provides for this. Further, the creation-date,
modification-date, and read-date parameters allow preservation of
those file attributes when the file is transmitted over MIME email.
NB: The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD,
SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this
document, are to be interpreted as described in [RFC 2119].
2. The Content-Disposition Header Field
Content-Disposition is an optional header field. In its absence, the
MUA may use whatever presentation method it deems suitable.
It is desirable to keep the set of possible disposition types small
and well defined, to avoid needless complexity. Even so, evolving
usage will likely require the definition of additional disposition
types or parameters, so the set of disposition values is extensible;
see below.
Troost, et. al. Standards Track [Page 2]
RFC 2183 Content-Disposition August 1997
In the extended BNF notation of [RFC 822], the Content-Disposition
header field is defined as follows:
disposition := "Content-Disposition" ":"
disposition-type
*(";" disposition-parm)
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
filename-parm := "filename" "=" value
creation-date-parm := "creation-date" "=" quoted-date-time
modification-date-parm := "modification-date" "=" quoted-date-time
read-date-parm := "read-date" "=" quoted-date-time
size-parm := "size" "=" 1*DIGIT
quoted-date-time := quoted-string
; contents MUST be an RFC 822 `date-time'
; numeric timezones (+HHMM or -HHMM) MUST be used
NOTE ON PARAMETER VALUE LENGHTS: A short (length <= 78 characters)
parameter value containing only non-`tspecials' characters SHOULD be
represented as a single `token'. A short parameter value containing
only ASCII characters, but including `tspecials' characters, SHOULD
be represented as `quoted-string'. Parameter values longer than 78
characters, or which contain non-ASCII characters, MUST be encoded as
specified in [RFC 2184].
`Extension-token', `parameter', `tspecials' and `value' are defined
according to [RFC 2045] (which references [RFC 822] in the definition
of some of these tokens). `quoted-string' and `DIGIT' are defined in
[RFC 822].
Troost, et. al. Standards Track [Page 3]
RFC 2183 Content-Disposition August 1997
2.1 The Inline Disposition Type
A bodypart should be marked `inline' if it is intended to be
displayed automatically upon display of the message. Inline
bodyparts should be presented in the order in which they occur,
subject to the normal semantics of multipart messages.
2.2 The Attachment Disposition Type
Bodyparts can be designated `attachment' to indicate that they are
separate from the main body of the mail message, and that their
display should not be automatic, but contingent upon some further
action of the user. The MUA might instead present the user of a
bitmap terminal with an iconic representation of the attachments, or,
on character terminals, with a list of attachments from which the
user could select for viewing or storage.
2.3 The Filename Parameter
The sender may want to suggest a filename to be used if the entity is
detached and stored in a separate file. If the receiving MUA writes
the entity to a file, the suggested filename should be used as a
basis for the actual filename, where possible.
It is important that the receiving MUA 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).
The receiving MUA SHOULD NOT respect any directory path information
that may seem to be present in the filename parameter. The filename
should be treated as a terminal component only. Portable
specification of directory paths might possibly be done in the future
via a separate Content-Disposition parameter, but no provision is
made for it in this draft.
Current [RFC 2045] grammar restricts parameter values (and hence
Content-Disposition filenames) to US-ASCII. We recognize the great
desirability of allowing arbitrary character sets in filenames, but
it is beyond the scope of this document to define the necessary
mechanisms. We expect that the basic [RFC 1521] `value'
specification will someday be amended to allow use of non-US-ASCII
characters, at which time the same mechanism should be used in the
Content-Disposition filename parameter.
Troost, et. al. Standards Track [Page 4]
RFC 2183 Content-Disposition August 1997
Beyond the limitation to US-ASCII, the sending MUA may wish to bear
in mind the limitations of common filesystems. Many have severe
length and character set restrictions. Short alphanumeric filenames
are least likely to require modification by the receiving system.
The presence of the filename parameter does not force an
implementation to write the entity to a separate file. It is
perfectly acceptable for implementations to leave the entity as part
of the normal mail stream unless the user requests otherwise. As a
consequence, the parameter may be used on any MIME entity, even
`inline' ones. These will not normally be written to files, but the
parameter could be used to provide a filename if the receiving user
should choose to write the part to a file.
2.4 The Creation-Date parameter
The creation-date parameter MAY be used to indicate the date at which
the file was created. If this parameter is included, the paramter
value MUST be a quoted-string which contains a representation of the
creation date of the file in [RFC 822] `date-time' format.
UNIX and POSIX implementors are cautioned that the `st_ctime' file
attribute of the `stat' structure is not the creation time of the
file; it is thus not appropriate as a source for the creation-date
parameter value.
2.5 The Modification-Date parameter
The modification-date parameter MAY be used to indicate the date at
which the file was last modified. If the modification-date parameter
is included, the paramter value MUST be a quoted-string which
contains a representation of the last modification date of the file
in [RFC 822] `date-time' format.
2.6 The Read-Date parameter
The read-date parameter MAY be used to indicate the date at which the
file was last read. If the read-date parameter is included, the
parameter value MUST be a quoted-string which contains a
representation of the last-read date of the file in [RFC 822] `date-
time' format.
2.7 The Size parameter
The size parameter indicates an approximate size of the file in
octets. It can be used, for example, to pre-allocate space before
attempting to store the file, or to determine whether enough space
exists.
Troost, et. al. Standards Track [Page 5]
RFC 2183 Content-Disposition August 1997
2.8 Future Extensions and Unrecognized Disposition Types
In the likely event that new parameters or disposition types are
needed, they should be registered with the Internet Assigned Numbers
Authority (IANA), in the manner specified in Section 9 of this memo.
Once new disposition types and parameters are defined, there is of
course the likelihood that implementations will see disposition types
and parameters they do not understand. Furthermore, since x-tokens
are allowed, implementations may also see entirely unregistered
disposition types and parameters.
Unrecognized parameters should be ignored. Unrecognized disposition
types should be treated as `attachment'. The choice of `attachment'
for unrecognized types is made because a sender who goes to the
trouble of producing a Content-Disposition header with a new
disposition type is more likely aiming for something more elaborate
than inline presentation.
Unless noted otherwise in the definition of a parameter, Content-
Disposition parameters are valid for all dispositions. (In contrast
to MIME content-type parameters, which are defined on a per-content-
type basis.) Thus, for example, the `filename' parameter still means
the name of the file to which the part should be written, even if the
disposition itself is unrecognized.
2.9 Content-Disposition and Multipart
If a Content-Disposition header is used on a multipart body part, it
applies to the multipart as a whole, not the individual subparts.
The disposition types of the subparts do not need to be consulted
until the multipart itself is presented. When the multipart is
displayed, then the dispositions of the subparts should be respected.
If the `inline' disposition is used, the multipart should be
displayed as normal; however, an `attachment' subpart should require
action from the user to display.
If the `attachment' disposition is used, presentation of the
multipart should not proceed without explicit user action. Once the
user has chosen to display the multipart, the individual subpart
dispositions should be consulted to determine how to present the
subparts.
Troost, et. al. Standards Track [Page 6]
RFC 2183 Content-Disposition August 1997
2.10 Content-Disposition and the Main Message
It is permissible to use Content-Disposition on the main body of an
[RFC 822] message.
3. Examples
Here is a an example of a body part containing a JPEG image that is
intended to be viewed by the user immediately:
Content-Type: image/jpeg
Content-Disposition: inline
Content-Description: just a small picture of me
<jpeg data>
The following body part contains a JPEG image that should be
displayed to the user only if the user requests it. If the JPEG is
written to a file, the file should be named "genome.jpg". The
recipient's user might also choose to set the last-modified date of
the stored file to date in the modification-date parameter:
Content-Type: image/jpeg
Content-Disposition: attachment; filename=genome.jpeg;
modification-date="Wed, 12 Feb 1997 16:29:51 -0500";
Content-Description: a complete map of the human genome
<jpeg data>
The following is an example of the use of the `attachment'
disposition with a multipart body part. The user should see text-
part-1 immediately, then take some action to view multipart-2. After
taking action to view multipart-2, the user will see text-part-2
right away, and be required to take action to view jpeg-1. Subparts
are indented for clarity; they would not be so indented in a real
message.
Troost, et. al. Standards Track [Page 7]
RFC 2183 Content-Disposition August 1997
Content-Type: multipart/mixed; boundary=outer
Content-Description: multipart-1
--outer
Content-Type: text/plain
Content-Disposition: inline
Content-Description: text-part-1
Some text goes here
--outer
Content-Type: multipart/mixed; boundary=inner
Content-Disposition: attachment
Content-Description: multipart-2
--inner
Content-Type: text/plain
Content-Disposition: inline
Content-Description: text-part-2
Some more text here.
--inner
Content-Type: image/jpeg
Content-Disposition: attachment
Content-Description: jpeg-1
<jpeg data>
--inner--
--outer--
4. Summary
Content-Disposition takes one of two values, `inline' and
`attachment'. `Inline' indicates that the entity should be
immediately displayed to the user, whereas `attachment' means that
the user should take additional action to view the entity.
The `filename' parameter can be used to suggest a filename for
storing the bodypart, if the user wishes to store it in an external
file.
Troost, et. al. Standards Track [Page 8]
RFC 2183 Content-Disposition August 1997
5. Security Considerations
There are security issues involved any time users exchange data.
While these are not to be minimized, neither does this memo change
the status quo in that regard, except in one instance.
Since this memo provides a way for the sender to suggest a filename,
a receiving MUA must take care that the sender's suggested filename
does not represent a hazard. Using UNIX as an example, some hazards
would be:
+ Creating startup files (e.g., ".login").
+ Creating or overwriting system files (e.g., "/etc/passwd").
+ Overwriting any existing file.
+ Placing executable files into any command search path
(e.g., "~/bin/more").
+ Sending the file to a pipe (e.g., "| sh").
In general, the receiving MUA should not name or place the file such
that it will get interpreted or executed without the user explicitly
initiating the action.
It is very important to note that this is not an exhaustive list; it
is intended as a small set of examples only. Implementors must be
alert to the potential hazards on their target systems.
6. References
[RFC 2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997.
[RFC 2184]
Freed, N. and K. Moore, "MIME Parameter value and Encoded Words:
Character Sets, Lanaguage, and Continuations", RFC 2184, August
1997.
[RFC 2045]
Freed, N. and N. Borenstein, "MIME (Multipurpose Internet Mail
Extensions) Part One: Format of Internet Message Bodies", RFC
2045, December 1996.
Troost, et. al. Standards Track [Page 9]
RFC 2183 Content-Disposition August 1997
[RFC 2046]
Freed, N. and N. Borenstein, "MIME (Multipurpose Internet Mail
Extensions) Part Two: Media Types", RFC 2046, December 1996.
[RFC 2047]
Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
Three: Message Header Extensions for non-ASCII Text", RFC 2047,
December 1996.
[RFC 2048]
Freed, N., Klensin, J. and J. Postel, "MIME (Multipurpose
Internet Mail Extensions) Part Four: Registration Procedures",
RFC 2048, December 1996.
[RFC 2049]
Freed, N. and N. Borenstein, "MIME (Multipurpose Internet Mail
Extensions) Part Five: Conformance Criteria and Examples", RFC
2049, December 1996.
[RFC 822]
Crocker, D., "Standard for the Format of ARPA Internet Text
Messages", STD 11, RFC 822, UDEL, August 1982.
7. Acknowledgements
We gratefully acknowledge the help these people provided during the
preparation of this draft:
Nathaniel Borenstein
Ned Freed
Keith Moore
Dave Crocker
Dan Pritchett
Troost, et. al. Standards Track [Page 10]
RFC 2183 Content-Disposition August 1997
8. Authors' Addresses
You should blame the editor of this version of the document for any
changes since RFC 1806:
Keith Moore
Department of Computer Science
University of Tennessee, Knoxville
107 Ayres Hall
Knoxville TN 37996-1301
USA
Phone: +1 (423) 974-5067
Fax: +1 (423) 974-8296
Email: moore@cs.utk.edu
The authors of RFC 1806 are:
Rens Troost
New Century Systems
324 East 41st Street #804
New York, NY, 10017 USA
Phone: +1 (212) 557-2050
Fax: +1 (212) 557-2049
EMail: rens@century.com
Steve Dorner
QUALCOMM Incorporated
6455 Lusk Boulevard
San Diego, CA 92121
USA
EMail: sdorner@qualcomm.com
9. Registration of New Content-Disposition Values and Parameters
New Content-Disposition values (besides "inline" and "attachment")
may be defined only by Internet standards-track documents, or in
Experimental documents approved by the Internet Engineering Steering
Group.
Troost, et. al. Standards Track [Page 11]
RFC 2183 Content-Disposition August 1997
New content-disposition parameters may be registered by supplying the
information in the following template and sending it via electronic
mail to IANA@IANA.ORG:
To: IANA@IANA.ORG
Subject: Registration of new Content-Disposition parameter
Content-Disposition parameter name:
Allowable values for this parameter:
(If the parameter can only assume a small number of values,
list each of those values. Otherwise, describe the values
that the parameter can assume.)
Description:
(What is the purpose of this parameter and how is it used?)
10. Changes since RFC 1806
The following changes have been made since the earlier version of
this document, published in RFC 1806 as an Experimental protocol:
+ Updated references to MIME documents. In some cases this
involved substituting a reference to one of the current MIME
RFCs for a reference to RFC 1521; in other cases, a reference to
RFC 1521 was simply replaced with the word "MIME".
+ Added a section on registration procedures, since none of the
procedures in RFC 2048 seemed to be appropriate.
+ Added new parameter types: creation-date, modification-date,
read-date, and size.
+ Incorporated a reference to draft-freed-pvcsc-* for encoding
long or non-ASCII parameter values.
+ Added reference to RFC 2119 to define MUST, SHOULD, etc.
keywords.
Troost, et. al. Standards Track [Page 12]
|