One document matched: draft-reschke-rfc2231-in-http-01.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
    This XML document is the output of clean-for-DTD.xslt; a tool that strips
    extensions to RFC2629(bis) from documents for processing with xml2rfc.
-->
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc subcompact="no"?>
<!DOCTYPE rfc
  PUBLIC "" "rfc2629.dtd">
<rfc ipr="trust200811" docName="draft-reschke-rfc2231-in-http-01" category="std">
	<front>
  <title abbrev="RFC2231 Encoding in HTTP">Application of RFC 2231
  Encoding to Hypertext Transfer Protocol (HTTP) Headers</title>

  <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke">
    <organization abbrev="greenbytes">greenbytes GmbH</organization>
    <address>
      <postal>
        <street>Hafenweg 16</street>
        <city>Muenster</city><region>NW</region><code>48155</code>
        <country>Germany</country>
      </postal>
      <email>julian.reschke@greenbytes.de</email>	
      <uri>http://greenbytes.de/tech/webdav/</uri>	
    </address>
  </author>

  <date month="December" year="2008" day="30"/>
  
  <abstract>
    <t>
      By default, message header parameters in Hypertext Transfer Protocol (HTTP) messages
      can not carry characters outside the ISO-8859-1 character set. RFC 2231
      defines an escaping mechanism for use in Multipurpose Internet Mail Extensions
      (MIME) headers. This document specifies a profile of that encoding
      suitable for use in HTTP.
    </t>
  </abstract>
  
  <note title="Editorial Note (To be removed by RFC Editor before publication)">
    <t>
      There are multiple HTTP headers that already use RFC 2231 encoding
      in practice (Content-Disposition) or might use it in the future
      (Link). The purpose of this document is to provide a single place where
      the generic aspects of RFC 2231 encoding in HTTP headers are defined.
    </t>
    <t>
      Distribution of this document is unlimited. Although this is not a work
      item of the HTTPbis Working Group, comments should be sent to the 
      Hypertext Transfer Protocol (HTTP) mailing list at <eref target="mailto:ietf-http-wg@w3.org">ietf-http-wg@w3.org</eref>,
      which may be joined by sending a message with subject 
      "subscribe" to <eref target="mailto:ietf-http-wg-request@w3.org?subject=subscribe">ietf-http-wg-request@w3.org</eref>.
    </t>
    <t>
      Discussions of the HTTPbis Working Group are archived at
      <eref target="http://lists.w3.org/Archives/Public/ietf-http-wg/"/>.               
    </t> 
    <t>
      XML versions, latest edits and the issues list for this document
      are available from <eref target="http://greenbytes.de/tech/webdav/#draft-reschke-rfc2231-in-http"/>.
      A collection of test cases is available at <eref target="http://greenbytes.de/tech/tc2231/"/>.
    </t>
  </note>
  </front>

  <middle>

<section title="Introduction" anchor="introduction">
<t>
  By default, message header parameters in HTTP (<xref target="RFC2616"/>) messages
  can not carry characters outside the ISO-8859-1 character set (<xref target="ISO-8859-1"/>). RFC 2231
  (<xref target="RFC2231"/>) defines an escaping mechanism for use in MIME headers.
  This document specifies a profile of that encoding for use in HTTP.
</t>
</section>  

<section title="Notational Conventions">
<t>
  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 <xref target="RFC2119"/>.
</t>
<t>
  This specification uses the ABNF (Augmented Backus-Naur Form) notation defined in
  <xref target="RFC5234"/>. The following core rules are included by
  reference, as defined in <xref target="RFC5234"/>, Appendix B.1:
  ALPHA (letters), DIGIT (decimal 0-9), HEXDIG (hexadecimal 0-9/A-F/a-f) and
  LWSP (linear white space).
</t>
<t>
  Non-ASCII characters used in prose for examples are encoded using
  the format "Backslash-U with Delimiters", defined in
  Section 5.1 of <xref target="RFC5137"/>.
</t>
<t>
  Note that this specification uses the term "character set" for consistency
  with other IETF specifications such as RFC 2277 (see <xref target="RFC2277"/>, Section 3). A more accurate term would be "character
  encoding" (a mapping of code points to octet sequences).
</t>
</section>  

<section title="A Profile of RFC 2231 for Use in HTTP">
<t>
  RFC 2231 defines several extensions to MIME. The sections below discuss
  if and how they apply to HTTP.
</t>
<t>
  In short:
  <list style="symbols">
    <t>Parameter Continuations aren't needed (<xref target="parameter.continuations"/>),</t>
    <t>Character Set and Language Information are useful, therefore a simple subset
    is specified (<xref target="character.set.and.language.information"/>), and</t>
    <t>Language Specifications in Encoded Words aren't needed (<xref target="language.specification.in.encoded.words"/>).</t>
  </list>
</t>

<section title="Parameter Continuations" anchor="parameter.continuations">
<t>
  Section 3 of <xref target="RFC2231"/> defines a mechanism that
  deals with the length limitations that apply to MIME headers. These
  limitations do not apply to HTTP (<xref target="RFC2616"/>, Section 19.4.7). 
</t>
<t>
  Thus in HTTP, senders MUST NOT use parameter continuations, and 
  therefore recipients do not need to support them.
</t>
</section>

<section title="Parameter Value Character Set and Language Information" anchor="character.set.and.language.information">
<t>
  Section 4 of <xref target="RFC2231"/> specifies how to embed
  language information into parameter values, and also how to encode
  non-ASCII characters, dealing with restrictions both in MIME and HTTP
  header parameters.
</t>
<t>
  However, RFC 2231 does not specify a mandatory-to-implement character encoding,
  making it hard for senders to decide which character set to use.
  Thus, recipients implementing this specification MUST support the
  character sets "ISO-8859-1" <xref target="ISO-8859-1"/> and "UTF-8"
  <xref target="RFC3629"/>.
</t>
<t>
  Furthermore, RFC 2231 allows leaving out the character encoding information.
  The profile defined by this specification does not allow that.
</t>
<t>
  The syntax for parameters is defined in Section 3.6 of <xref target="RFC2616"/>
  (with RFC 2616 implied LWS translated to RFC 5234 LWSP):
</t>
<figure><artwork type="inline"><![CDATA[
  parameter     = attribute LWSP "=" LWSP value
]]></artwork></figure>
<figure><artwork type="abnf"><![CDATA[
  attribute     = token
  value         = token / quoted-string

  quoted-string = <quoted-string, defined in [RFC2616], Section 2.2>
  token         = <token, defined in [RFC2616], Section 2.2>
]]></artwork></figure>
<t anchor="bnf">
  
  This specification extends the grammar to:
</t>
<figure><artwork type="abnf"><![CDATA[
  parameter     = reg-parameter / ext-parameter
   
  reg-parameter = attribute LWSP "=" LWSP value

  ext-parameter = attribute "*" LWSP "=" LWSP ext-value

  ext-value     = charset  "'" [ language ] "'" value-chars
                ; extended-initial-value,
                ; defined in [RFC2231], Section 7

  charset       = %x55.54.46.2D.38 ; "UTF-8"
                / %x49.53.4F.2D.38.38.35.39.2D.31 ; "ISO-8859-1" 
                / ext-charset

  ext-charset   = token ; see IANA charset registry
                ; (<http://www.iana.org/assignments/character-sets>)
  
  language      = <Language-Tag, defined in [RFC4646], Section 2.1>
  
  value-chars   = *( pct-encoded / attr-char )

  pct-encoded   = "%" HEXDIG HEXDIG
                ; see [RFC3986], Section 2.1

  attr-char     = ALPHA / DIGIT
                / "-" / "." / "_" / "~" / ":"
                / "!" / "$" / "&" / "+"
]]></artwork></figure>
<t>
  Thus, a parameter is either regular parameter (reg-parameter), as previously
  defined in Section 3.6 of <xref target="RFC2616"/>, or an extended
  parameter (ext-parameter).
</t>
<t>
  Extended parameters are those where the left hand side of the assignment
  ends with an asterisk character.
</t>
<t>
  The value part of an extended parameter (ext-value) is a token that consists
  of three parts: the REQUIRED character set name (charset), the OPTIONAL
  language information (language), and a a character sequence representing the
  actual value (value-chars), separated by single quote
  characters.
</t>
<t>
  Inside the value part, characters not contained in attr-char are
  encoded into an octet sequence using the specified character set. That octet
  sequence then is percent-encoded as specified in Section 2.1 of <xref target="RFC3986"/>.
</t>
<t>
  Producers MUST NOT use character sets other than "UTF-8" (<xref target="RFC3629"/>)
  or ISO-8859-1 (<xref target="ISO-8859-1"/>). 
  Extension character sets (ext-charset) are reserved for future use.
</t>

<section title="Examples">
<figure>
<preamble>
  Non-extended notation, using "token":
</preamble>
<artwork type="example"><![CDATA[
  foo: bar; title=Economy
]]></artwork></figure>

<figure>
<preamble>
  Non-extended notation, using "quoted-string":
</preamble>
<artwork type="example"><![CDATA[
  foo: bar; title="US-$ rates"
]]></artwork></figure>

<figure>
<preamble>
  Extended notation, using the unicode character \u'00A3' (POUND SIGN):
</preamble>
<artwork type="example"><![CDATA[
  foo: bar; title*=iso-8859-1'en'%A3%20rates
]]></artwork>
<postamble>
  Note: the Unicode pound sign character \u'00A3' was encoded using
  ISO-8859-1 into the single octet A3, then percent-encoded. Also note
  that the space character was encoded as %20, as it is not contained in
  attr-char.
</postamble>
</figure>

<figure>
<preamble>
  Extended notation, using the unicode characters \u'00A3' (POUND SIGN)
  and \u'20AC' (EURO SIGN):
</preamble>
<artwork type="example"><![CDATA[
  foo: bar; title*=UTF-8''%c2%a3%20and%20%e2%82%ac%20rates
]]></artwork>
<postamble>
  Note: the unicode pound sign character \u'00A3' was encoded using
  UTF-8 into the octet sequence C2 A3, then percent-encoded. Likewise,
  the unicode euro sign character \u'20AC' was encoded into the octet
  sequence E2 82 AC, then percent-encoded. Also note that HEXDIG allows
  both lower-case and upper-case character, so recipients must understand
  both, and that the language information is optional, while the character
  set is not.
</postamble>
</figure>
</section>

</section>

<section title="Language specification in Encoded Words" anchor="language.specification.in.encoded.words">
<t>
  Section 5 of <xref target="RFC2231"/> extends the encoding
  defined in <xref target="RFC2047"/> to also support language specification
  in encoded words.
  Although the HTTP/1.1 specification does refer to RFC 2047
  (<xref target="RFC2616"/>, Section 2.2),
  it's not clear to which header field exactly it applies, and whether it is
  implemented in practice (see <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/111"/>
  for details).
</t>
<t>
  Thus, the RFC 2231 profile defined by this specification does not include
  this feature.
</t>
</section>

</section>

<section title="Guidelines for Usage in HTTP Header Definitions">
<t>
  Specifications of HTTP headers that use the extensions defined
  in <xref target="character.set.and.language.information"/> should clearly
  state that. A simple way to achieve this is to normatively reference
  this specification, and to include the <xref target="bnf" format="none">ext-value</xref>
  production into the ABNF for that header.
</t>
<figure><preamble>For instance:</preamble>
<artwork type="example"><![CDATA[
  foo-header  = "foo" LWSP ":" LWSP token ";" LWSP title-param
  title-param = "title" LWSP "=" LWSP value
              / "title*" LWSP "=" LWSP ext-value
  ext-value   = <see RFCxxxx, Section 3.2>
]]></artwork></figure>
<t>
  <cref anchor="rfcno">Note to RFC Editor: in the figure above, please replace "xxxx" by the
  RFC number assigned to this specification.</cref>
</t>

<section title="When to Use the Extension">
<t>
  Section 4.2 of <xref target="RFC2277"/> requires that protocol
  elements containing text can carry language information. Thus, the <xref target="bnf" format="none">ext-value</xref>
  production should always be used when the parameter value is of textual
  nature.
</t>
<t>
  Furthermore, the extension should also be used whenever the parameter value
  needs to carry characters not present in the US-ASCII (<xref target="USASCII"/>)
  character set (note that it would be unacceptable to define a new parameter that
  would be restricted to a subset of the Unicode character set).
</t>
</section>

<section title="Error Handling">
<t>
  Header specifications that include parameters should also specify whether
  same-named parameters can occur multiple times. If repetitions are not
  allowed (and this is believed to be the common case), the specification
  should state whether regular or the extended syntax takes precedence.
  In the latter case, this could be used by producers to use both formats
  without breaking recipients that do not understand the syntax.
  <cref>Does not work as expected, see <http://greenbytes.de/tech/tc2231/#attfnboth>
  and <http://greenbytes.de/tech/tc2231/#attfnboth2>.</cref>
</t>
<figure><preamble>Example:</preamble>
<artwork type="example"><![CDATA[
  foo: bar; title="EURO exchange rates";
            title*=utf-8''%e2%82%ac%20exchange%20rates
]]></artwork>
<postamble>In this case, the sender provides an ASCII version of the title
for legacy recipients, but also includes an internationalized version for
recipients understanding this specification -- the latter obviously 
should prefer the new syntax over the old one.</postamble>
</figure>

</section>

</section>


<section title="Security Considerations" anchor="security.considerations">
<t>
  This document does not discuss security issues and is not believed to raise
  any security issues not already endemic in HTTP.
</t>
</section>  

<section title="IANA Considerations" anchor="iana.considerations">
<t>
  There are no IANA Considerations related to this specification.
</t>
</section>  

<section title="Acknowledgements">
<t>
  Thanks to Frank Ellermann for help figuring out ABNF details.
</t>
</section>  
  </middle>
  <back>
  
<references title="Normative References">
  
  <reference anchor="RFC2119">
    <front>
      <title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title>
      <author initials="S." surname="Bradner" fullname="Scott Bradner">
        <organization>Harvard University</organization>
        <address><email>sob@harvard.edu</email></address>
      </author>
      <date month="March" year="1997"/>
      <area>General</area>
      <keyword>keyword</keyword>
    </front>
    <seriesInfo name="BCP" value="14"/>
    <seriesInfo name="RFC" value="2119"/>
  </reference>

  <reference anchor="RFC2616">
    <front>
      <title>Hypertext Transfer Protocol -- HTTP/1.1</title>
      <author initials="R." surname="Fielding" fullname="R. Fielding">
        <organization>University of California, Irvine</organization>
        <address><email>fielding@ics.uci.edu</email></address>
      </author>
      <author initials="J." surname="Gettys" fullname="J. Gettys">
        <organization>W3C</organization>
        <address><email>jg@w3.org</email></address>
      </author>
      <author initials="J." surname="Mogul" fullname="J. Mogul">
        <organization>Compaq Computer Corporation</organization>
        <address><email>mogul@wrl.dec.com</email></address>
      </author>
      <author initials="H." surname="Frystyk" fullname="H. Frystyk">
        <organization>MIT Laboratory for Computer Science</organization>
        <address><email>frystyk@w3.org</email></address>
      </author>
      <author initials="L." surname="Masinter" fullname="L. Masinter">
        <organization>Xerox Corporation</organization>
        <address><email>masinter@parc.xerox.com</email></address>
      </author>
      <author initials="P." surname="Leach" fullname="P. Leach">
        <organization>Microsoft Corporation</organization>
        <address><email>paulle@microsoft.com</email></address>
      </author>
      <author initials="T." surname="Berners-Lee" fullname="T. Berners-Lee">
        <organization>W3C</organization>
        <address><email>timbl@w3.org</email></address>
      </author>
      <date month="June" year="1999"/>
    </front>
    <seriesInfo name="RFC" value="2616"/>
  </reference>

  <reference anchor="RFC3629">
    <front>
      <title>UTF-8, a transformation format of ISO 10646</title>
      <author initials="F." surname="Yergeau" fullname="F. Yergeau">
        <organization>Alis Technologies</organization>
        <address><email>fyergeau@alis.com</email></address>
      </author>
      <date month="November" year="2003"/>
    </front>
    <seriesInfo name="RFC" value="3629"/>
    <seriesInfo name="STD" value="63"/>
  </reference>

  <reference anchor="RFC4646">
    <front>
      <title>Tags for Identifying Languages</title>
      <author initials="A." surname="Phillips" fullname="A. Phillips">
        <organization>Yahoo! Inc.</organization>
        <address><email>addison@inter-locale.com</email></address>
      </author>
      <author initials="M." surname="Davis" fullname="M. Davis">
        <organization>Google</organization>
        <address><email>mark.davis@macchiato.com</email></address>
      </author>
      <date year="2006" month="September"/>
    </front>
    <seriesInfo name="BCP" value="47"/>
    <seriesInfo name="RFC" value="4646"/>
  </reference>

  <reference anchor="RFC5234">
    <front>
      <title abbrev="ABNF for Syntax Specifications">Augmented BNF for Syntax Specifications: ABNF</title>
      <author initials="D." surname="Crocker" fullname="Dave Crocker" role="editor">
        <organization>Brandenburg InternetWorking</organization>
        <address>
          <phone>+1.408.246.8253</phone>
          <email>dcrocker@bbiw.net</email>
        </address>  
      </author>
      <author initials="P." surname="Overell" fullname="Paul Overell">
        <organization>THUS plc.</organization>
        <address>
          <email>paul.overell@thus.net</email>
        </address>
      </author>
      <date month="January" year="2008"/>
    </front>
    <seriesInfo name="STD" value="68"/>
    <seriesInfo name="RFC" value="5234"/>
  </reference>

  <reference anchor="ISO-8859-1">
    <front>
      <title>Information technology -- 8-bit single-byte coded graphic character sets -- Part 1: Latin alphabet No. 1</title>
      <author>
        <organization>International Organization for Standardization</organization>
      </author>
      <date year="1998"/>
    </front>
    <seriesInfo name="ISO/IEC" value="8859-1:1998"/>
  </reference>

</references>
  
<references title="Informative References">

  <reference anchor="RFC2047">
    <front>
      <title abbrev="Message Header Extensions">MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text</title>
      <author initials="K." surname="Moore" fullname="Keith Moore">
        <organization>University of Tennessee</organization>
        <address><email>moore@cs.utk.edu</email></address>
      </author>
      <date month="November" year="1996"/>
    </front>
    <seriesInfo name="RFC" value="2047"/>
  </reference>

  <reference anchor="RFC2231">
    <front>
      <title abbrev="MIME Value and Encoded Word Extensions">MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations</title>
      <author initials="N." surname="Freed" fullname="Ned Freed">
        <organization abbrev="Innosoft">Innosoft International, Inc.</organization>
        <address><email>ned.freed@innosoft.com</email></address>
      </author>
      <author initials="K." surname="Moore" fullname="Keith Moore">
        <organization>University of Tennessee</organization>
        <address><email>moore@cs.utk.edu</email></address>
      </author>
      <date year="1997" month="November"/>
    </front>
    <seriesInfo name="RFC" value="2231"/>
  </reference>

  <reference anchor="RFC2277">
    <front>
      <title abbrev="Charset Policy">IETF Policy on Character Sets and Languages</title>
      <author initials="H.T." surname="Alvestrand" fullname="Harald Tveit Alvestrand">
        <organization>UNINETT</organization>
        <address><email>Harald.T.Alvestrand@uninett.no</email></address>
      </author>
      <date year="1998" month="January"/>
    </front>
    <seriesInfo name="BCP" value="18"/>
    <seriesInfo name="RFC" value="2277"/>
  </reference>

  <reference anchor="RFC3986">
   <front>
    <title abbrev="URI Generic Syntax">Uniform Resource Identifier (URI): Generic Syntax</title>
    <author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
      <organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
      <address>
         <email>timbl@w3.org</email>
         <uri>http://www.w3.org/People/Berners-Lee/</uri>
      </address>
    </author>
    <author initials="R." surname="Fielding" fullname="Roy T. Fielding">
      <organization abbrev="Day Software">Day Software</organization>
      <address>
        <email>fielding@gbiv.com</email>
        <uri>http://roy.gbiv.com/</uri>
      </address>
    </author>
    <author initials="L." surname="Masinter" fullname="Larry Masinter">
      <organization abbrev="Adobe Systems">Adobe Systems Incorporated</organization>
      <address>
        <email>LMM@acm.org</email>
        <uri>http://larry.masinter.net/</uri>
      </address>
    </author>
    <date month="January" year="2005"/>
   </front>
   <seriesInfo name="RFC" value="3986"/>
   <seriesInfo name="STD" value="66"/>
  </reference>

  <reference anchor="RFC5137">
    <front>
      <title>ASCII Escaping of Unicode Characters</title>
      <author initials="J." surname="Klensin" fullname="J. Klensin">
        <organization/>
        <address><email>john-ietf@jck.com</email></address>
      </author>
      <date year="2008" month="February"/>
    </front>
    <seriesInfo name="BCP" value="137"/>
    <seriesInfo name="RFC" value="5137"/>
  </reference>
  
  <reference anchor="USASCII">
    <front>
      <title>Coded Character Set -- 7-bit American Standard Code for Information Interchange</title>
      <author>
        <organization>American National Standards Institute</organization>
      </author>
      <date year="1986"/>
    </front>
    <seriesInfo name="ANSI" value="X3.4"/>
  </reference>

</references>

<section title="Change Log (to be removed by RFC Editor before publication)" anchor="change.log">

<section title="Since draft-reschke-rfc2231-in-http-00">
<t>
  Use RFC5234-style ABNF, closer to the one used in RFC 2231.
</t>
<t>
  Make RFC 2231 dependency informative, so this specification can evolve
  independantly.
</t>
<t>
  Explain the ABNF in prose.
</t>
</section>

</section>


  </back>

</rfc>