RFC 2183

Title Block 💖

RFC 2183: Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field 🎀

This one is from the Network Working Group and it's a Standards Track doc, so it's the real deal ✨ Dated August 1997. The authors are R. Troost (New Century Systems), S. Dorner (QUALCOMM Incorporated), and K. Moore, Editor (University of Tennessee). It Updates: 1806, which is RFC 1806, so this is basically the glow-up of that earlier spec 🦋

---

Status of this Memo 📜

Okay so this doc is an Internet standards track protocol for the Internet community, and it's basically asking everyone to talk about it and suggest improvements 🫶 For the current standardization state and status, go check the "Internet Official Protocol Standards" (STD 1) 📚 Distribution is unlimited, so share it with everyone 💅

---

Abstract ✨

This memo is giving us a way for messages that follow the MIME specifications [RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049] to carry presentation info 🎀 It defines the "Content-Disposition" header field, which is optional and works for any MIME entity ("message" or "body part") 💖 There are two values in here: one for normal linear display of a body part, and one that makes it easier to use mail to send files 📩 More values are expected later, and there are procedures for extending the set 🌈

This is an extension to MIME, so it assumes you already know the MIME specs and [RFC 822] 🧚 It adds to those docs but doesn't replace them, so keep them handy 🍓

This doc is also a revision of the Experimental protocol from RFC 1806 🦋 Compared to RFC 1806, it has some minor editorial cleanup, adds new parameters for the File Transfer Body Part, and points to a separate spec for handling non-ASCII and/or very long parameter values 💜

---

1. Introduction ✨

Okay so MIME is the standard format for packing a bunch of data pieces into one Internet message 📦 But it doesn't say anything about presentation styles 🙈 It's a framework for swapping message content, and it leaves all the presentation stuff up to the mail user agent (MUA) implementors 💅

There are two popular ways to show multipart messages. One is a main document with a list of separate attachments. The other is one document with all the parts expanded (displayed) inline 🌸 Showing an attachment usually needs the recipient to do something on purpose, while inline components just show up automatically when you open the message 👀 So we need a way for the sender to tell the recipient what kind of presentation they want ✨ That's where the Content-Disposition header comes in: it tags each component of a message with its desired presentation semantics 🎀

Tagging like this will often be enough for basic formatting 💖 But sometimes you'll want something more powerful and flexible 🔥 Defining those fancier approaches is outside the scope of this memo, but they can totally benefit from extra Content-Disposition values and parameters that get defined later 🧚

Beyond presentation, the sender can also suggest a default archival disposition, which is a filename 📁 The optional "filename" parameter handles that 💜 The creation-date, modification-date, and read-date parameters keep those file attributes intact when the file gets sent 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 💅 If it's not there, the MUA can use whatever presentation method it thinks works best ✨

It's nice to keep the set of disposition types small and well defined so nothing gets too messy 🧹 But real-life usage will probably need new disposition types or parameters, so the set is extensible. Check below for more 🦋

The header field is defined in the extended BNF notation of [RFC 822] like this:

    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: Okay this one's important 🚨 A short parameter value (length <= 78 characters) that only has non-tspecials' characters SHOULD be written as a single token'. A short parameter value with only ASCII characters that does include tspecials' characters SHOULD be written as quoted-string'. Parameter values longer than 78 characters, or ones with non-ASCII characters, MUST be encoded as specified in [RFC 2184]. Don't skip this, bestie 😭

Extension-token, parameter, tspecials and value are defined according to [RFC 2045] (which references [RFC 822] for some of these tokens). quoted-string and DIGIT are defined in [RFC 822] 🧚

2.1. The Inline Disposition Type 🌸

A bodypart should be marked inline if it's meant to be displayed automatically when the message is displayed 👀 Inline bodyparts should be presented in the order they show up, following the normal semantics of multipart messages 💖

2.2. The Attachment Disposition Type 📎

Bodyparts can be labeled attachment to show that they're separate from the main body of the mail message 💅 Their display shouldn't happen automatically. It depends on the user doing something else first 🫶 The MUA might show a user on a bitmap terminal an iconic representation of the attachments, or, on character terminals, a list of attachments they can pick from to view or store 🖼️

2.3. The Filename Parameter 📁

The sender might want to suggest a filename for when the entity gets detached and stored in its own file 🎀 If the receiving MUA writes the entity to a file, the suggested filename should be used as the basis for the actual filename, where possible ✨

The receiving MUA should not blindly use the suggested filename 🙅‍♀️ The suggested filename SHOULD be checked (and maybe changed) to make sure it follows local filesystem conventions, doesn't overwrite an existing file, and doesn't cause a security problem (see Security Considerations below) 🔒

The receiving MUA SHOULD NOT respect any directory path info that might seem to be in the filename parameter 🚫 Treat the filename as a terminal component only. Portable directory paths might get handled someday through a separate Content-Disposition parameter, but there's no provision for that in this draft 🧭

Current [RFC 2045] grammar limits parameter values (and so Content-Disposition filenames) to US-ASCII 🔤 We totally get why arbitrary character sets in filenames would be amazing, but defining the mechanisms for that is outside this document's scope 🌍 We expect the basic [RFC 1521] value specification will eventually be amended to allow non-US-ASCII characters, and then the same mechanism should be used in the Content-Disposition filename parameter 💜

Beyond the US-ASCII limit, the sending MUA may want to keep common filesystem limits in mind 💾 Lots of them have harsh length and character set restrictions. Short alphanumeric filenames are the least likely to need changes by the receiving system 🍓

The filename parameter doesn't force an implementation to write the entity to a separate file 🙌 It's totally fine for implementations to leave the entity in the normal mail stream unless the user asks otherwise. So the parameter can be used on any MIME entity, even inline ones 🌈 Those won't normally be written to files, but the parameter could still supply a filename if the receiving user decides to save the part to a file 💖

2.4. The Creation-Date parameter 📅

The creation-date parameter MAY be used to show the date the file was created 💅 If this parameter is included, its value MUST be a quoted-string containing a representation of the file's creation date in [RFC 822] date-time format ✨

UNIX and POSIX implementors, be careful 🚨 The st_ctime file attribute of the stat structure is not the creation time of the file 🙈 So don't use it as a source for the creation-date parameter value 💀

2.5. The Modification-Date parameter ✏️

The modification-date parameter MAY be used to show the date the file was last modified 🫶 If the modification-date parameter is included, its value MUST be a quoted-string containing a representation of the file's last modification date in [RFC 822] date-time format 💜

2.6. The Read-Date parameter 👀

The read-date parameter MAY be used to show the date the file was last read 📖 If the read-date parameter is included, its value MUST be a quoted-string containing a representation of the file's last-read date in [RFC 822] date-time format 🦋

2.7. The Size parameter 📏

The size parameter shows the approximate size of the file in octets 🧁 It can be used to pre-allocate space before trying to store the file, or to figure out whether enough space exists 💖

2.8. Future Extensions and Unrecognized Disposition Types ✨

okay so new parameters or disposition types are probably gonna show up eventually 👀 and when they do, they should be registered with the Internet Assigned Numbers Authority (IANA), following the process in Section 9 of this memo 📝

once new disposition types and parameters exist, implementations are gonna run into ones they don't understand 😭 and since x-tokens are allowed, they might even see totally unregistered disposition types and parameters. the chaos is real 💀

unrecognized parameters should be ignored 🫶 unrecognized disposition types should be treated as `attachment'. the reason is kinda iconic: someone who goes to the trouble of writing a Content-Disposition header with a brand new disposition type is probably aiming for something more elaborate than inline presentation 💅

unless a parameter's definition says otherwise, Content-Disposition parameters are valid for all dispositions 🌈 (this is different from MIME content-type parameters, which are defined per content type). so the `filename' parameter still means the name of the file the part should be written to, 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 to the individual subparts 💜 the subpart dispositions don't need to be checked until the multipart itself is presented. once it's displayed, the dispositions of the subparts should be respected ✨

if the inline' disposition is used, the multipart should be displayed as normal 🌸 but an attachment' subpart should require action from the user before it shows up 🙈

if the `attachment' disposition is used, the multipart should not be presented without explicit user action 🔒 once the user chooses to display it, the individual subpart dispositions should be checked to decide how each subpart gets presented 🦋

2.10. Content-Disposition and the Main Message 💌

it's totally allowed to use Content-Disposition on the main body of an [RFC 822] message 🍓

3. Examples 🎀

here's an example of a body part with a JPEG image that should be shown to the user right away 👀

     Content-Type: image/jpeg
     Content-Disposition: inline
     Content-Description: just a small picture of me

      <jpeg data>

this one has a JPEG that should only be displayed if the user asks for it 🙋‍♀️ if the JPEG gets written to a file, that file should be named "genome.jpg". the recipient's user might also choose to set the last-modified date of the stored file to the 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>

and this is the big one with a multipart body part using the `attachment' disposition 🤯 the user should see text-part-1 immediately, then take some action to view multipart-2. after that, they'll see text-part-2 right away, but they'll need to take action to view jpeg-1. the subparts are indented here just for clarity; in a real message they wouldn't be indented 💖

     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' means the entity should be shown to the user immediately, whereas attachment' means the user has to take extra action to view the entity 🧁

the `filename' parameter can be used to suggest a filename for storing the bodypart, in case the user wants to save it to an external file 💾

5. Security Considerations 🚨

okay this part is seriously important 😤 there are security issues any time users exchange data. we don't want to minimize them, but this memo doesn't change the status quo in that regard, except in one instance 🫣

since this memo gives the sender a way 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 in a way that it will get interpreted or executed without the user explicitly starting that action 🚫

this is NOT an exhaustive list. it's just a small set of examples 🙏 implementors must be alert to the potential hazards on their target systems. stay sharp out there bestie 🔥

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.

[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

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 by Experimental documents approved by the Internet Engineering Steering Group 🧐

new content-disposition parameters may be registered by sending the information in the template below 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 🦋

here's the tea ☕ the following changes have been made since the earlier version of this document, which was published in RFC 1806 as an Experimental protocol:

• Updated references to MIME documents. In some cases this meant swapping in one of the current MIME RFCs for a reference to RFC 1521; in other cases, a reference to RFC 1521 was just 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. 💅