Network Working Group L. Masinter Internet-Draft Adobe Obsoletes: 2388 (if approved) December 2, 2014 Intended status: Standards Track Expires: June 5, 2015 Returning Values from Forms: multipart/form-data draft-ietf-appsawg-multipart-form-data-07 Abstract This specification (re)defines the multipart/form-data Internet Media Type, which can be used by a wide variety of applications and transported by a wide variety of protocols as a way of returning a set of values as the result of a user filling out a form. It replaces RFC 2388. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on June 5, 2015. Copyright Notice Copyright (c) 2014 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of Masinter Expires June 5, 2015 [Page 1] Internet-Draft multipart/form-data December 2014 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. NOTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 3. URL encoding non-ASCII values . . . . . . . . . . . . . . . . 3 4. Advice for Forms and Form Processing . . . . . . . . . . . . 3 5. Definition of multipart/form-data . . . . . . . . . . . . . . 4 5.1. Boundary parameter of multipart/form-data . . . . . . . . 4 5.2. Content-Disposition header for each part . . . . . . . . 4 5.3. filename attribute of content-distribution part header . 5 5.4. Multiple files for one form field . . . . . . . . . . . . 5 5.5. Content-Type header for each part . . . . . . . . . . . . 5 5.6. The charset parameter for text/plain form data . . . . . 6 5.7. The _charset_ field for default charset . . . . . . . . . 6 5.8. Content-Transfer-Encoding deprecated . . . . . . . . . . 6 5.9. Other Content- headers . . . . . . . . . . . . . . . . . 7 6. Operability considerations . . . . . . . . . . . . . . . . . 7 6.1. Non-ASCII field names and values . . . . . . . . . . . . 7 6.1.1. Avoid non-ASCII field names . . . . . . . . . . . . . 7 6.1.2. Interpreting forms and creating form-data . . . . . . 7 6.1.3. Parsing and interpreting form data . . . . . . . . . 8 6.2. Ordered fields and duplicated field names . . . . . . . . 8 6.3. Interoperability with web applications . . . . . . . . . 8 6.4. Correlating form data with the original form . . . . . . 9 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 9. Media type registration for multipart/form-data . . . . . . . 10 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 10.1. Normative References . . . . . . . . . . . . . . . . . . 10 10.2. Informative References . . . . . . . . . . . . . . . . . 11 Appendix A. Changes from RFC 2388 . . . . . . . . . . . . . . . 11 Appendix B. Alternatives . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 1. NOTE There is a GitHub repository for this draft at https://github.com/masinter/multipart-form-data along with an issue tracker. This specification is a work item of the APPSAWG Applications Area working group, apps-discuss@ietf.org. Please raise issues in the tracker, and/or send to the apps-discuss list. Masinter Expires June 5, 2015 [Page 2] Internet-Draft multipart/form-data December 2014 2. Introduction In many applications, it is possible for a user to be presented with a form. The user will fill out the form, including information that is typed, generated by user input, or included from files that the user has selected. When the form is filled out, the data from the form is sent from the user to the receiving application. The definition of "multipart/form-data" is derived from one of those applications, originally set out in [RFC1867] and subsequently incorporated into HTML 3.2 [W3C.REC-html32-19970114], where forms are expressed in HTML, and in which the form data is sent via HTTP or electronic mail. This representation is widely implemented in numerous web browsers and web servers. However, "multipart/form-data" is also used for forms that are presented using representations other than HTML (spreadsheets, PDF, etc.), and for transport using means other than electronic mail or HTTP; it is used in distributed applications which do not involve forms at all, or do not have users filling out the form. For this reason, this document defines a general syntax and semantics independent of the application for which it is used, with specific rules for web applications noted in context. 3. URL encoding non-ASCII values Within this specification, "URL-encoding" is offered as a possible way of encoding non-ASCII characters in file names. The encoding is created replacing each non-ASCII or disallowed character with a sequence, where each byte of the UTF-8 encoding of the character is represented by a percent-sign (%) followed by the (lower case) hexadecimal of that byte. 4. Advice for Forms and Form Processing The representation and interpretation of forms and the nature of form processing is not specified by this document. However, for forms and form-processing that result in generation of multipart/form-data, some suggestions are included. In a form, there is generally a sequence of fields, where each field is expected to be supplied with a value, e.g. by a user who fills out the form. Each field has a name. After a form has been filled out, and the form's data is "submitted": the form processing results in a set of values for each field-- the "form data". Masinter Expires June 5, 2015 [Page 3] Internet-Draft multipart/form-data December 2014 In forms that work with multipart/form-data, field names could be arbitrary Unicode strings; however, restricting field names to ASCII will help avoid some interoperability issues (see Section 6.1). Within a given form, insuring field names are unique is also helpful. Some fields may have default values or presupplied values in the form itself. Fields with presupplied values might be hidden or invisible; this allows using generic processing for form data from a variety of actual forms. 5. Definition of multipart/form-data The media-type "multipart/form-data" follows the model of multipart MIME data streams as specified in [RFC2046] Section 5.1; changes are noted in this document. A "multipart/form-data" body contains a series of parts, separated by a boundary. 5.1. Boundary parameter of multipart/form-data As with other multipart types, the parts are delimited with a boundary delimiter, constructed using CRLF, "--", the value of the boundary parameter. Each field's form data of the form is sent, in the order defined by the sending application and form, as a part of the multipart stream. The boundary is supplied as a "boundary" parameter to the "multipart/form-data type". As noted in [RFC2046] Section 5.1, the boundary delimiter MUST NOT appear inside any of the encapsulated parts, and it is often necessary to enclose the boundary parameter values in quotes on the Content-type line. 5.2. Content-Disposition header for each part Each part MUST contain a "content-disposition" header [RFC2183] and where the disposition type is "form-data". The "content-disposition" header MUST also contain an additional parameter of "name"; the value of the "name" parameter is the original field name from the form (possibly encoded; see Section 6.1). For example, a part might contain a header: Content-Disposition: form-data; name="user" with the body of the part corresponding to the form data of the "user" field. Masinter Expires June 5, 2015 [Page 4] Internet-Draft multipart/form-data December 2014 5.3. filename attribute of content-distribution part header For form data that represents the content of a file, a name for the file SHOULD be supplied as well, by using a "filename" parameter of the "content-disposition" header. A file name isn't mandatory; file uploads might result from selection or drag-and-drop even in systems where the file name is meaningless or private, where the form data content is streamed directly from a device, or where the file name is not user visible and would be unrecognized.) In most multipart types, the MIME headers in each part are restricted to US-ASCII; for compatibility with those systems, file names normally visible to users MAY be encoded (using the URL-encoding method in Section 3, such as how a "file:" URI might be encoded. NOTE: the method in [RFC5987] for using a "filename*" paramter of the "Content-Disposition" header SHOULD NOT be used. Some commonly deployed systems use multipart/form-data with file names directly encoded including octets outside the US-ASCII range. The encoding used for the file names is typically UTF-8, although HTML forms will use the charset associated with the form. 5.4. Multiple files for one form field The form data for a form field might include multiple files. [RFC2388] suggested that multiple files for a single form field be transmitted using a nested multipart/mixed part. To match widely deployed implementations, multiple files SHOULD be sent by supplying each file in a separate part, but all with the same "name" parameter. Receiving applications intended for wide applicability (e.g. multipart/form-data parsing libraries) SHOULD also support the older method of supplying multiple files. 5.5. Content-Type header for each part Each part MAY have an (optional) "content-type", which defaults to "text/plain". If the contents of a file are to be sent, the file data SHOULD be labeled with an appropriate media type, if known, or "application/octet-stream". Masinter Expires June 5, 2015 [Page 5] Internet-Draft multipart/form-data December 2014 5.6. The charset parameter for text/plain form data In the case where the form data is text, the charset parameter for the "text/plain" Content-Type MAY be used to indicate the character encoding used in that part. For example, a form with a text field in which a user typed "Joe owes 100" where is the Euro symbol might have form data returned as: --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 In practice, many widely deployed implementations do not supply a charset parameter in each part, but, rather, they rely on the notion of a "default charset" for a multipart/form-data instance. Subsequent sections will explain how the default charset is established. 5.7. The _charset_ field for default charset Some form processing applications (including HTML) have the convention that the value of a form entry with entry name "_charset_" and type "hidden" is automatically set when the form is opened; the value is used as the default charset of text field values (see form- charset in Section 6.1.2). In such cases, the value of the default charset for each text/plain part without a charset parameter is the supplied value. For example: --AaB03x content-disposition: form-data; name="_charset_" iso8859-1 --AaB03x-- content-disposition: form-data; name="field1" ...text encoded in iso-8859-1 ... AaB03x-- 5.8. Content-Transfer-Encoding deprecated Previously, it was recommended that senders use a "Content-Transfer- Encoding" encoding (such as "quoted-printable") for each non-ASCII part of a multipart/form-data body, because that would allow use in transports that only support a "7BIT" encoding. This use is Masinter Expires June 5, 2015 [Page 6] Internet-Draft multipart/form-data December 2014 deprecated for use in contexts that support binary data such as HTTP. Senders SHOULD NOT generate any parts with a "Content-Transfer- Encoding" header. Currently, no deployed implementations that send such bodies have been discovered. 5.9. Other Content- headers The "multipart/form-data" media type does not support any MIME headers in the parts other than Content-Type, Content-Disposition, and (in limited circumstances) Content-Transfer-Encoding. Other headers MUST NOT be included and MUST be ignored. 6. Operability considerations 6.1. Non-ASCII field names and values Normally, MIME headers in multipart bodies are required to consist only of 7-bit data in the US-ASCII character set. While [RFC2388] suggested that non-ASCII field names should be encoded according to the method in [RFC2047] if they contain characters outside of US- ASCII, this practice doesn't seem to have been followed widely. This specification makes three sets of recommendations for three different states of workflow. 6.1.1. Avoid non-ASCII field names For broadest interoperability with existing deployed software, those creating forms SHOULD avoid non-ASCII field names. This should not be a burden, because in general the field names are not visible to users. If non-ASCII field names are unavoidable, form or application creators SHOULD use UTF-8 uniformly. This will minimize interoperability problems. 6.1.2. Interpreting forms and creating form-data Some applications of this specification will supply a character encoding to be used for interpretation of the multipart/form-data body. In particular, HTML 5 [W3C.REC-html5-20141028] uses: o The content of a '_charset_' field, if there is one. o the value of an accept-charset attribute of the
element, if there is one, Masinter Expires June 5, 2015 [Page 7] Internet-Draft multipart/form-data December 2014 o the character encoding of the document containing the form, if it is US-ASCII compatible, o otherwise UTF-8. Call this value the form-charset. Any text, whether field name, field value, or (text/plain) form data which is uses characters outside the ASCII range MAY be represented directly encoded in the form-charset. 6.1.3. Parsing and interpreting form data While this specification provides guidance for creation of multipart/ form-data, parsers and interpreters should be aware of the variety of implementations. File systems differ as to whether and how they normalize Unicode names, for example. The matching of form elements to form-data parts may rely on a fuzzier match. In particular, some multipart/form-data generators might have followed the previous advice of [RFC2388] and used the [RFC2047] "encoded-word" method of encoding non-ASCII values: encoded-word = "=?" charset "?" encoding "?" encoded-text "?=" Others have been known to follow [RFC2231], to send unencoded UTF-8, or even strings encoded in the form-charset. For this reason, interpreting "multipart/form-data" (even from conforming generators) may require knowing the charset used in form encoding, in cases where the _charset_ field value or a charset parameter of a text/plain Content-Type header is not supplied. 6.2. Ordered fields and duplicated field names Form processors given forms with a well-defined ordering SHOULD send back results in the order received and preserve duplicate field names, in order. Intermediaries MUST NOT reorder the results. (Note that there are some forms which do not define a natural order of appearance.) 6.3. Interoperability with web applications Many web applications use the "application/x-url-encoded" method for returning data from forms. This format is quite compact, e.g.: name=Xavier+Xantico&verdict=Yes&colour=Blue&happy=sad&Utf%F6r=Send However, there is no opportunity to label the enclosed data with content type, apply a charset, or use other encoding mechanisms. Masinter Expires June 5, 2015 [Page 8] Internet-Draft multipart/form-data December 2014 Many form-interpreting programs (primarily web browsers) now implement and generate multipart/form-data, but an existing application might need to optionally support both the application/x- url-encoded format as well. 6.4. Correlating form data with the original form This specification provides no specific mechanism by which multipart/ form-data can be associated with the form that caused it to be transmitted. This separation is intentional; many different forms might be used for transmitting the same data. In practice, applications may supply a specific form processing resource (in HTML, the ACTION attribute in a FORM tag) for each different form. Alternatively, data about the form might be encoded in a "hidden field" (a field which is part of the form but which has a fixed value to be transmitted back to the form-data processor.) 7. IANA Considerations Please update the Internet Media Type registration of multipart/form- data to point to this document. In addition, please update the registration of the "name" parameter in the "Content Disposition Paramters" registry to point to this document. 8. Security Considerations Applications which receive forms and process them must be careful not to supply data back to the requesting form processing site that was not intended to be sent. It is important when interpreting the filename of the Content- Disposition header to not overwrite files in the recipient's file space inadvertently. User applications that request form information from users must be careful not to cause a user to send information to the requestor or a third party unwillingly or unwittingly. For example, a form might request 'spam' information to be sent to an unintended third party, or private information to be sent to someone that the user might not actually intend. While this is primarily an issue for the representation and interpretation of forms themselves (rather than the data representation of the form data), the transportation of private information must be done in a way that does not expose it to unwanted prying. With the introduction of form-data that can reasonably send back the content of files from a user's file space, the possibility arises that a user might be sent an automated script that fills out a form Masinter Expires June 5, 2015 [Page 9] Internet-Draft multipart/form-data December 2014 and then sends one of the user's local files to another address. Thus, additional caution is required when executing automated scripting where form-data might include a user's files. Files sent via multipart/form-data may contain arbitrary executable content, and precautions against malicious content are necessary. All form processing software should treat user supplied form-data with sensitivity, as it often contains confidential or personally identifying information. Multipart/form-data does not supply any features for checking integrity, ensuring confidentiality or other security features; those concerns must be addressed by the form- filling and form-data-interpreting applications. 9. Media type registration for multipart/form-data Media Type name: multipart Media 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 Section 5.8. Security considerations: See Section 8 of this document. Interoperability considerations: This document makes several recommendations for interoperability with deployed implementations, including Section 5.8. 10. References 10.1. Normative References [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996. [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text", RFC 2047, November 1996. Masinter Expires June 5, 2015 [Page 10] Internet-Draft multipart/form-data December 2014 [RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field", RFC 2183, August 1997. [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations", RFC 2231, November 1997. 10.2. Informative References [RFC1867] Nebel, E. and L. Masinter, "Form-based File Upload in HTML", RFC 1867, November 1995. [RFC2388] Masinter, L., "Returning Values from Forms: multipart/ form-data", RFC 2388, August 1998. [RFC5987] Reschke, J., "Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters", RFC 5987, August 2010. [W3C.REC-html32-19970114] Raggett, D., "HTML 3.2 Reference Specification", World Wide Web Consortium Recommendation REC-html32-19970114, January 1997, . [W3C.REC-html5-20141028] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World Wide Web Consortium Recommendation REC- html5-20141028, October 2014, . Appendix A. Changes from RFC 2388 The handling of non-ASCII field names changed-- no longer recommending the RFC 2047 method, instead suggesting senders send UTF-8 field names directly, and file names directly in the form- charset. The handling of multiple files submitted as the result of a single form field (e.g. HTML's element) results in each file having its own top level part with the same name parameter; the method of using a nested "multipart/mixed" from [RFC2388] is no longer recommended for creators, and not required for receivers as there are no known implementations of senders. Masinter Expires June 5, 2015 [Page 11] Internet-Draft multipart/form-data December 2014 The _charset_ convention and use of an explicit form-data charset is documented. 'boundary' is a required parameter in Content-Type. The relationship of the ordering of fields within a form and the ordering of returned values within multipart/form-data was not defined before, nor was the handling of the case where a form has multiple fields with the same name. Editorial: Removed obsolete discussion of alternatives in appendix. Update references. Move outline of form processing into Introduction. Appendix B. Alternatives There are numerous alternative ways in which form data can be encoded; many are listed in [RFC2388] section 5.2. The multipart/ form-data encoding is verbose, especially if there are many fields with short values. In most use cases, this overhead isn't significant. More problematic is the ambiguity introduced because implementations did not follow [RFC2388] because it used "may" instead of "MUST" when specifying encoding of field names, and for other unknown reasons, so now, parsers need to be more complex for fuzzy matching against the possible outputs of various encoding methods. Author's Address Larry Masinter Adobe Email: masinter@adobe.com URI: http://larry.masinter.net Masinter Expires June 5, 2015 [Page 12]