RFC 7578

RFC 7578: Returning Values from Forms: multipart/form-data 🎀

Okay bestie, this one is RFC 7578 💖. It's called Returning Values from Forms: multipart/form-data, and it was written by L. Masinter from Adobe ✨. It came out in July 2015 under the IETF (Internet Engineering Task Force), and it's on the Standards Track 🔥, so it's a real Internet standard and not just vibes. It obsoletes RFC 2388 💅, which means it replaces that older spec. It doesn't list any updates. It's identified as ISSN 2070-1721 🦋.

Abstract 🌸

So this spec defines the multipart/form-data media type 💜. It's super versatile: lots of different apps can use it, and lots of different protocols can carry it, as a way to send back a set of values after someone fills out a form ✨. This document obsoletes RFC 2388 💅.

Status of This Memo 🦋

This is an Internet Standards Track document 🔥.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community 🫶. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG) 👑. If you want more info on Internet Standards, check out Section 2 of RFC 5741 📚.

Info about the current status of this document, any errata, and how to give feedback on it lives at:

http://www.rfc-editor.org/info/rfc7578

Copyright Notice 🌈

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved 💅.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they're in effect on the date this document was published 📜. Please actually read these, bestie, because they spell out your rights and restrictions for this document 🙈. Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License ⚠️.

Table of Contents 📚

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Percent-Encoding Option . . . . . . . . . . . . . . . . . . .   3
3.  Advice for Forms and Form Processing  . . . . . . . . . . . .   3
4.  Definition of multipart/form-data . . . . . . . . . . . . . .   4
  4.1.  "Boundary" Parameter of multipart/form-data . . . . . . .   4
  4.2.  Content-Disposition Header Field for Each Part  . . . . .   4
  4.3.  Multiple Files for One Form Field . . . . . . . . . . . .   5
  4.4.  Content-Type Header Field for Each Part . . . . . . . . .   5
  4.5.  The Charset Parameter for "text/plain" Form Data  . . . .   5
  4.6.  The _charset_ Field for Default Charset . . . . . . . . .   6
  4.7.  Content-Transfer-Encoding Deprecated  . . . . . . . . . .   6
  4.8.  Other "Content-" Header Fields  . . . . . . . . . . . . .   7
5.  Operability Considerations  . . . . . . . . . . . . . . . . .   7
  5.1.  Non-ASCII Field Names and Values  . . . . . . . . . . . .   7
    5.1.1.  Avoid Non-ASCII Field Names . . . . . . . . . . . . .   7
    5.1.2.  Interpreting Forms and Creating multipart/form-data
            Data  . . . . . . . . . . . . . . . . . . . . . . . .   7
    5.1.3.  Parsing and Interpreting Form Data  . . . . . . . . .   8
  5.2.  Ordered Fields and Duplicated Field Names . . . . . . . .   8
  5.3.  Interoperability with Web Applications  . . . . . . . . .   8
  5.4.  Correlating Form Data with the Original Form  . . . . . .   9
6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
7.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
8.  Media Type Registration for multipart/form-data . . . . . . .  10
9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
  9.1.  Normative References  . . . . . . . . . . . . . . . . . .  11
  9.2.  Informative References  . . . . . . . . . . . . . . . . .  12
Appendix A.  Changes from RFC 2388  . . . . . . . . . . . . . . .  14
Appendix B.  Alternatives . . . . . . . . . . . . . . . . . . . .  14
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  15
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  15

1. Introduction 🫶

Okay, so picture this: lots of apps show a user a form 📝. The user fills it out, typing stuff in, generating stuff with input, or grabbing files they've picked ✨. Once the form is filled out, the form's data gets sent from the user to the app that's receiving it 💌.

multipart/form-data came out of one of those apps, first set out in [RFC1867] and then folded into HTML 3.2 [W3C.REC-html32-19970114] 💖. In that world, the forms are written in HTML and the form data goes over HTTP or email. This representation is widely implemented across tons of web browsers and web servers 🌐.

But here's the twist: multipart/form-data also shows up for forms written in other formats (spreadsheets, PDF, and so on) and goes over transports that aren't email or HTTP 🧚. It even shows up in distributed apps that don't have forms at all, or that don't have a user filling anything out 😭. So this document defines a general syntax and semantics that don't depend on any one app, with the specific web app rules called out where they matter 🦋.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119 [RFC2119] 💅.

2. Percent-Encoding Option 🌸

Within this spec, "percent-encoding" (as defined in [RFC3986]) is offered as one possible way to encode characters in file names that would otherwise be disallowed 🎀. Those include non-ASCII characters, spaces, control characters, and so forth 🙈. Here's how it works: each non-ASCII or disallowed character gets swapped out for a sequence. Each byte of that character's UTF-8 encoding becomes a percent sign (%) followed by that byte's hexadecimal value, and the hex is case-insensitive 🔥.

3. Advice for Forms and Form Processing 📋

The way forms are represented and interpreted, and what form processing actually looks like, is not specified by this document 🤷‍♀️. That said, for forms and form processing that end up generating multipart/form-data, we include some suggestions ✨.

A form usually has a sequence of fields, and each field is expected to get a value, like from a user filling it out 💜. Each field has a name 🏷️. Once the form's been filled out and the data is "submitted", the form processing produces a set of values for each field, and that's the "form data" 🎀.

For forms that use multipart/form-data, field names could technically be any Unicode strings 🌈. But restricting them to ASCII helps dodge some interoperability issues (see Section 5.1) 💅.

It's also helpful to make sure field names are unique within a given form 🫶. Some fields come with default values or presupplied values right in the form itself 🍓. Fields with presupplied values might be hidden or invisible, and that lets generic processing handle form data from all kinds of different forms ✨.

4. Definition of multipart/form-data 💖

The media type multipart/form-data follows the model of multipart MIME data streams as specified in Section 5.1 of [RFC2046], with changes noted in this document 📜.

A multipart/form-data body is a series of parts, separated by a boundary 🧁.

4.1. "Boundary" Parameter of multipart/form-data 🦋

Like other multipart types, the parts get delimited with a boundary delimiter. That delimiter is built from CRLF, "--", and the value of the "boundary" parameter 🔥. The boundary is supplied as a "boundary" parameter to the multipart/form-data type. As noted in Section 5.1 of [RFC2046], the boundary delimiter MUST NOT appear inside any of the encapsulated parts 🚫. Also, it's often necessary to put the "boundary" parameter values in quotes in the Content-Type header field 💅.

4.2. Content-Disposition Header Field for Each Part 🎀

Each part MUST contain a Content-Disposition header field [RFC2183], and its disposition type has to be form-data 💖. The Content-Disposition header field MUST also include a "name" parameter. The value of "name" is the original field name from the form (possibly encoded, see Section 5.1) 🏷️. For example, a part might contain a header field like this one, with the part's body holding the form data for the "user" field:

        Content-Disposition: form-data; name="user"

For form data that represents the contents of a file, you SHOULD also supply a file name, using a "filename" parameter on the Content-Disposition header field 📁. Hmm, let me be clear on this: the file name isn't mandatory when it isn't available, or when it's meaningless or private 🙈. That can happen, for example, with selection or drag-and-drop, or when the form data is streamed straight from a device 📱.

If a "filename" parameter is supplied, the requirements in Section 2.3 of [RFC2183] for the "receiving MUA" (that's the receiving Mail User Agent) apply to receivers of multipart/form-data too 📬. So: don't use the file name blindly 🚫. Check it, and maybe change it to match local file system conventions if that applies 🗂️. And don't use any directory path information that might be in there 🙅‍♀️.

Most multipart types restrict the MIME header fields in each part to US-ASCII 🔤. For compatibility with those systems, file names that normally show up to users MAY be percent-encoded using the method in Section 2, following how a "file:" URI [URI-SCHEME] might be encoded 🦋.

NOTE: The encoding method described in [RFC5987], which would add a "filename*" parameter to the Content-Disposition header field, MUST NOT be used. Absolutely not, bestie 💀.

Some commonly deployed systems use multipart/form-data with file names that are directly encoded and include octets outside the US-ASCII range 🌍. The encoding for those file names is typically UTF-8 ✨, although HTML forms use the charset associated with the form 🌸.

4.3. Multiple Files for One Form Field 📂

A form field's form data might include multiple files 🗃️.

[RFC2388] suggested sending multiple files for a single form field using a nested "multipart/mixed" part. That usage is deprecated, so we're moving on 🙅‍♀️.

To match widely deployed implementations, multiple files MUST be sent by putting each file in a separate part, but all of those parts use the same "name" parameter 💜.

Receiving applications meant for wide applicability (like multipart/form-data parsing libraries) SHOULD also support the older method of sending multiple files 🫶.

4.4. Content-Type Header Field for Each Part 🧚

Each part MAY have an (optional) Content-Type header field 💅. If you don't include one, it defaults to "text/plain" 📝. If the contents of a file are being sent, the file data SHOULD be labeled with an appropriate media type, if it's known, or with "application/octet-stream" 🎀.

4.5. The Charset Parameter for "text/plain" Form Data ✨

Okay, so when the form data is text, the charset parameter for the "text/plain" Content-Type MAY be used to say which character encoding is used in that part. 🌸 Picture a form where someone typed "Joe owes €100" (with the Euro sign 💶). The form data might come back looking like this:

    --AaB03x
    content-disposition: form-data; name="field1"
    content-type: text/plain;charset=UTF-8
    content-transfer-encoding: quoted-printable

    Joe owes =E2=82=AC100.
    --AaB03x

Here's the tea 🫖: lots of widely deployed implementations don't put a charset parameter in each part. Instead, they lean on a "default charset" for the whole multipart/form-data instance. 💅 We'll get to how that default gets set in the next bits.

4.6. The _charset_ Field for Default Charset

Some form-processing apps (HTML is one of them) have this convention where a form entry named _charset_ with type "hidden" gets filled in automatically when the form opens. 🦋 That value then becomes the default charset for text field values (check form-charset in Section 5.1.2). So any "text/plain" part that doesn't have its own charset parameter just uses that supplied value. Iconic, right? ✨ Example time:

    --AaB03x
    content-disposition: form-data; name="_charset_"

    iso-8859-1
    --AaB03x--
    content-disposition: form-data; name="field1"

    ...text encoded in iso-8859-1 ...
    AaB03x--

4.7. Content-Transfer-Encoding Deprecated 🙈

Okay, flashback moment 🕰️: it used to be recommended that senders use a Content-Transfer-Encoding (like "quoted-printable") on every non-ASCII part of a multipart/form-data body. The reason was so it could travel over transports that only handle "7bit" encoding. But this is now deprecated for contexts that handle binary data fine, like HTTP. Senders SHOULD NOT generate any parts with a Content-Transfer-Encoding header field. 🙅‍♀️

Fun fact (well, a sad one 😭): no deployed implementations that send bodies like this have been found.

4.8. Other "Content-" Header Fields

Main character rule 👑: multipart/form-data only supports the Content-Type and Content-Disposition header fields in its parts, plus Content-Transfer-Encoding in a few limited situations. Any other header fields MUST NOT be included, and they MUST be ignored. 🚫

5. Operability Considerations 🔧

5.1. Non-ASCII Field Names and Values

Normally, MIME header fields in multipart bodies have to be 7-bit data in the US-ASCII character set. 🔤 [RFC2388] suggested that non-ASCII field names get encoded with the method from [RFC2047], but nobody really did that, so it didn't catch on. 😬

This spec gives three sets of recommendations for three different stages of the workflow. Let's go! 🚀

5.1.1. Avoid Non-ASCII Field Names

For the broadest interoperability with software that's already out there, people making forms SHOULD avoid non-ASCII field names. 🌈 This shouldn't be a big deal, since field names usually aren't visible to users anyway. The field names in the underlying form don't have to match what the user sees on screen. 💖

If non-ASCII field names are unavoidable, form or application creators SHOULD use UTF-8 uniformly. That keeps interoperability problems to a minimum. 🫶

5.1.2. Interpreting Forms and Creating multipart/form-data Data

Some apps that use this spec will supply a character encoding to read the multipart/form-data body with. HTML 5 [W3C.REC-html5-20141028] is a good example, and it looks at these things, in order:

• the content of a _charset_ field, if there is one;
• the value of an accept-charset attribute of the <form> element, if there is one;
• the character encoding of the document containing the form, if it is US-ASCII compatible;
• otherwise, UTF-8.

We call that result the form-charset. Any text outside the ASCII range (whether it's a field name, a field value, or "text/plain" form data) MAY be sent directly encoded in the form-charset. ✨

5.1.3. Parsing and Interpreting Form Data 🕵️‍♀️

Okay, so this spec gives guidance on making multipart/form-data, but parsers and interpreters should know that implementations are all over the place 🗺️. File systems disagree on whether and how they normalise Unicode names, for example. Matching form elements to form-data parts might need a fuzzier match. 🌀

Some multipart/form-data generators followed the older advice from [RFC2388] and used the "encoded-word" method for non-ASCII values, as described in [RFC2047]:

    encoded-word = "=?" charset "?" encoding "?" encoded-text "?="

Others follow [RFC2231], send unencoded UTF-8, or even send strings encoded in the form-charset. 🤯

So, even conforming generators can produce bodies that need you to know the charset used for the form encoding, especially when the _charset_ field value or a charset parameter on a "text/plain" Content-Type header field isn't supplied. It's giving chaos, but we handle it 💅.

5.2. Ordered Fields and Duplicated Field Names 📋

Form processors that get forms with a well-defined ordering SHOULD send the results back in order. (Some forms don't have a natural order, though, so don't panic if yours doesn't. 🙃) Intermediaries MUST NOT reorder the results. And form parts with identical field names MUST NOT be coalesced. Don't merge them, bestie! 🚫🫂

5.3. Interoperability with Web Applications 🌐

A lot of web apps use the "application/x-www-form-urlencoded" method to send form data back. It's super compact, like this:

   name=Xavier+Xantico&verdict=Yes&colour=Blue&happy=sad&Utf%F6r=Send

The catch is there's no way to label the enclosed data with a content type, apply a charset, or use other encoding mechanisms. 😔

Lots of form-interpreting programs (mainly web browsers) now implement and generate multipart/form-data. But a receiving app might still need to support "application/x-www-form-urlencoded" too. 🫠

5.4. Correlating Form Data with the Original Form 🔗

This spec doesn't give any specific mechanism for linking multipart/form-data back to the form that sent it. That's on purpose! 🙌 Lots of different forms might be used to send the same data. In practice, apps can give each different form its own form processing resource (in HTML, that's the ACTION attribute on a FORM tag). Or, data about the form can go in a "hidden field": a field that's part of the form but has a fixed value that gets sent back to the form-data processor. 🧚

6. IANA Considerations 📚

The media type registration for multipart/form-data now points to this document, using the template in Section 8. 🎀 Also, the "name" parameter and the "form-data" value in the "Content Disposition Values and Parameters" registry have both been updated to point here. ✅

7. Security Considerations 🔐

⚠️ Okay bestie, this section is seriously important, so read every word!

All form-processing software should handle user-supplied form-data with care, because it often has confidential or personally identifying info in it. 🥺 Web browsers have form "auto-fill" features everywhere, and those could be used to trick users into unknowingly sending confidential info while they're doing something that seems totally harmless. multipart/form-data doesn't provide any features for checking integrity, ensuring confidentiality, avoiding user confusion, or other security features. 😱 Those concerns have to be handled by the form-filling and form-data-interpreting apps.

Apps that receive and process forms must be really careful not to send back data to the requesting form-processing site that wasn't meant to be sent. 🚨

When you interpret the filename in the Content-Disposition header field, it's important not to accidentally overwrite files in the recipient's file space. 📁💀

User apps that ask users to fill in forms must be careful not to get a user to send information to the requestor or a third party without meaning to. 🙅‍♀️ For example, a form might ask for spam info to go to some unintended third party, or private info to go to someone the user doesn't actually intend. This is mostly about how forms themselves are represented and interpreted (not the data representation of the form data). Still, moving private info around has to be done in a way that doesn't expose it to unwanted prying. 👀

Now, form-data can realistically send back the contents of files from a user's file space. So it's possible a user gets sent an automated script that fills out a form and then sends one of the user's local files to another address. 😨 That means extra caution is needed whenever you run automated scripting where form-data might include a user's files. Not me, not running that without checking!! 🙅‍♀️

Files sent via multipart/form-data may contain arbitrary executable content, so precautions against malicious content are necessary. 🦠

The considerations in Sections 2.3 and 5 of [RFC2183], about the "filename" parameter of the Content-Disposition header field, also apply to how it's used here. 📎

8. Media Type Registration for multipart/form-data 🧾

This section is the media type registration, made using the template from [RFC6838]. Here's the template, copied as it appears in the spec:

   Type name:  multipart

   Subtype name:  form-data

   Required parameters:  boundary

   Optional parameters:  none

   Encoding considerations:  Common use is BINARY.
      In limited use (or transports that restrict the encoding to 7bit
      or 8bit), each part is encoded separately using Content-Transfer-
      Encoding; see Section 4.7.

   Security considerations:  See Section 7 of this document.

   Interoperability considerations:  This document makes several
      recommendations for interoperability with deployed
      implementations, including Section 4.7.

   Published specification:  This document.

   Applications that use this media type:  Numerous web browsers,
      servers, and web applications.

   Fragment identifier considerations:  None; fragment identifiers are
      not defined for this type.

   Additional information:

   Additional information:

         Deprecated alias names for this type: N/A
         Magic number(s): N/A
         File extension(s): N/A
         Macintosh file type code(s): N/A

   Person & email address to contact for further information:  Author of
      this document.

   Intended usage:  COMMON

   Restrictions on usage:  none

   Author:  Author of this document.

   Change controller:  IETF

   Provisional registration:  N/A

9. References 📖

9.1. Normative References

Okay, bestie, here's the must-read list 📚✨ These are the RFCs and specs the whole thing leans on, so you need them to get the full picture 🧚

[RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
           Extensions (MIME) Part Two: Media Types", RFC 2046,
           DOI 10.17487/RFC2046, November 1996,
           <http://www.rfc-editor.org/info/rfc2046>.

[RFC2047]  Moore, K., "MIME (Multipurpose Internet Mail Extensions)
           Part Three: Message Header Extensions for Non-ASCII Text",
           RFC 2047, DOI 10.17487/RFC2047, November 1996,
           <http://www.rfc-editor.org/info/rfc2047>.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC2183]  Troost, R., Dorner, S., and K. Moore, Ed., "Communicating
           Presentation Information in Internet Messages: The
           Content-Disposition Header Field", RFC 2183,
           DOI 10.17487/RFC2183, August 1997,
           <http://www.rfc-editor.org/info/rfc2183>.

[RFC2231]  Freed, N. and K. Moore, "MIME Parameter Value and Encoded
           Word Extensions: Character Sets, Languages, and
           Continuations", RFC 2231, DOI 10.17487/RFC2231, November
           1997, <http://www.rfc-editor.org/info/rfc2231>.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <http://www.rfc-editor.org/info/rfc3986>.

9.2. Informative References

These ones are the background reading 🦋 Not required to get the core ideas, but SO good for the history and the extra context 💅

[RFC1867]  Nebel, E. and L. Masinter, "Form-based File Upload in
           HTML", RFC 1867, DOI 10.17487/RFC1867, November 1995,
           <http://www.rfc-editor.org/info/rfc1867>.

[RFC2388]  Masinter, L., "Returning Values from Forms: multipart/
           form-data", RFC 2388, DOI 10.17487/RFC2388, August 1998,
           <http://www.rfc-editor.org/info/rfc2388>.

[RFC5987]  Reschke, J., "Character Set and Language Encoding for
           Hypertext Transfer Protocol (HTTP) Header Field
           Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010,
           <http://www.rfc-editor.org/info/rfc5987>.

[RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
           Specifications and Registration Procedures", BCP 13,
           RFC 6838, DOI 10.17487/RFC6838, January 2013,
           <http://www.rfc-editor.org/info/rfc6838>.

[URI-SCHEME]
           Kerwin, M., "The file URI Scheme", Work in Progress,
           draft-ietf-appsawg-file-scheme-02, May 2015.

[W3C.REC-html32-19970114]
           Raggett, D., "HTML 3.2 Reference Specification", W3C
           Recommendation REC-html32-19970114, January 1997,
           <http://www.w3.org/TR/REC-html32-19970114>.

[W3C.REC-html5-20141028]
           Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
           Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", W3C
           Recommendation REC-html5-20141028, October 2014,
           <http://www.w3.org/TR/2014/REC-html5-20141028>.

---

Appendix A. Changes from RFC 2388 🔄

Okay, so this is the tea on what changed since RFC 2388 ☕ The non-ASCII field name stuff got a glow-up 💖 RFC 2047 is no longer the recommended move. Now it's suggested that senders just send UTF-8 field names straight up, and that file names get sent directly in the form-charset 🌸

Next, when a single form field gives you multiple files (think HTML's <input type=file multiple>), each file now gets its own top-level part with the same name parameter 📁 The nested "multipart/mixed" trick from RFC 2388 is no longer recommended for creators, and receivers aren't required to handle it either, since there are no known implementations of senders doing it 🙈

The _charset_ convention and an explicit "form-data" charset are now documented 🎀 And "boundary" is now a required parameter in Content-Type 🔥

Also, the relationship between field ordering in a form and the ordering of returned values in multipart/form-data wasn't defined before. Same goes for forms with multiple fields sharing a name. Both are sorted out now 💅

Last but not least, there were a bunch of editorial cleanups 🧹 The obsolete alternatives discussion got removed from the appendix, the references got updated, and the outline of form processing moved up into the introduction ✨

Appendix B. Alternatives 🧚

There are loads of ways to encode form data, and many are listed in Section 5.2 of [RFC2388] 🍓 Honestly, multipart/form-data is verbose, especially when you've got lots of fields with short values. But in most use cases, that extra overhead isn't a big deal 💜

The real drama is with non-ASCII field names 😭 Some implementers chose not to follow [RFC2388] here, probably because "may" should have been "MUST". So now there are more ways a field name can show up, and parsers have to get more complex to match all the possible outputs of different encoding methods 🙈

Acknowledgements 🫶

Big thanks to everyone who reviewed this document: Alexey Melnikov, Salvatore Loreto, Chris Lonvick, Kathleen Moriarty, Barry Leiba, Julian Reschke, Tom Petch, Ned Freed, and Cedric Brancourt, plus everyone else, including Ian Hickson, who asked for it to be written in the first place 🌈 You're all iconic 👑

Author's Address 📮

Larry Masinter
Adobe

Email: masinter@adobe.com
URI:   http://larry.masinter.net