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