Removed simple-gettext.c, as it is not being used at all.
[claws.git] / 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