doc/src/rfc2183.txt

   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 \f
  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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f