xeps/xep-0104.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM "xep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>HTTP Scheme for URL Data</title>
  <abstract>This document provides a schema description for detailed information about HTTP URLs.</abstract>
  &LEGALNOTICE;
  <number>0104</number>
  <status>Deferred</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>RFC 3986</spec>
    <spec>RFC 2616</spec>
    <spec>RFC 2617</spec>
    <spec>XEP-0103</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>N/A</shortname>
  <author>
    <firstname>Matthew</firstname>
    <surname>Miller</surname>
    <email>linuxwolf@outer-planes.net</email>
    <jid>linuxwolf@outer-planes.net</jid>
  </author>
  <revision>
    <version>0.3</version>
    <date>2004-01-20</date>
    <initials>lw</initials>
    <remark>Reorganized for Editorial preferences; Removed (outdated) references to XEP-0070</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-09-19</date>
    <initials>lw</initials>
    <remark>Added more information about cookies; Added more information about headers</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-06-30</date>
    <initials>lw</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction'>
  <p>The most common URL scheme distributed over the Internet is HTTP and HTTPS. This document defines a structure that extends &xep0103; to enable more advanced access to such URLs within Jabber.</p>
</section1>
<section1 topic='Requirements'>
  <p>This document supplements XEP-0103 to provide more detailed information about HTTP and HTTPS URLs. The requirements this document fulfills are:</p>
  <ul>
    <li>Provide authentication information.</li>
    <li>Provide cookie data.</li>
    <li>Provide necessary headers.</li>
  </ul>
  <p>The intent of this information is to provide an HTTP client with enough information in order to construct the HTTP request and entity headers necessary, as defined in &rfc2616;.</p>
  <p>The use of this document in conjunction with XEP-0103 is OPTIONAL. The entity sending the URL is not required to provide any of this information, and receiving entities MAY ignore it.</p>
</section1>
<section1 topic='Basic Usage'>
  <p>The two most typical types of information that can be necessary for accessing an HTTP URL are authentication details and cookies. In some cases, custom headers MAY also be necessary for successful use. Authentication information is provided in a scheme-independent format. Cookie data provided includes what would be necessary for a client to properly persist the value.</p>
  <section2 topic='Providing Authentication'>
    <p>At a minimum, this document allows for an entity to indicate what authentication scheme is in use:</p>
    <example caption='Indicating auth scheme'><![CDATA[
<message to='client@domain.com'>
  <url-data xmlns='http://jabber.org/protocol/url-data'
      xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
      target='http://www.jabber.org/members/index.php'>
    <http:auth scheme='basic'/>
  </url-data>
</message>
]]></example>
    <p>To provide additional parameters (such as a realm and username/password), the &lt;auth-param/&gt; element is used:</p>
    <code><![CDATA[
<message to='client@domain.com'>
  <url-data xmlns='http://jabber.org/protocol/url-data'
      xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
      target='http://www.jabber.org/members/index.php'>
    <http:auth scheme='basic'>
      <http:auth-param name='realm' value='www.jabber.org'/>
      <auth-param name='username' value='defaultuser'/>
      <auth-param name='password' value='defaultpwd'/>
    </http:auth>
  </url-data>
</message>
]]></code>
  </section2>
  <section2 topic='Providing Cookies'>
    <p>Cookie information is provided by the &lt;cookie/&gt; element. This element can provide all of the information of the "Set-Cookie" response header<note>"Set-Cookie" is a message header for the HTTP response, and the &lt;header/&gt; element represents only message headers for HTTP requests. Therefore, cookies are handled differently.</note>. The simplest usage is:</p>
    <code><![CDATA[
<message to='client@domain.com'>
  <url-data xmlns='http://jabber.org/protocol/url-data'
      xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
      target='http://www.jabber.org/members/index.php'>
    <http:cookie name='jsessionid' value='1243asd234190sa32ds'/>
  </url-data>
</message>
]]></code>
    <p>The above cookie is considered "transient", and will terminate when the HTTP session ends. Additional information about the cookie can be provided:</p>
    <code><![CDATA[
<message to='client@domain.com'>
  <url-data xmlns='http://jabber.org/protocol/url-data'
      xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
      target='http://www.jabber.org/members/index.php'>
    <http:cookie name='jsessionid'
        domain='jabber.org'
        max-age='1234000'
        path='/members'
        comment='Web Session Identifier'
        version='1.0'
        secure='false'
        value='1243asd234190sa32ds'/>
  </url-data>
</message>
]]></code>
    <p>As demonstrated, the &lt;cookie/&gt; provides all the attributes provided by the "Set-Cookie" header. The only attributes required are "name" and "value".</p>
  </section2>
  <section2 topic='Providing Headers'>
    <p>In some cases, arbitrary headers are necessary. They are provided using the &lt;header/&gt; element:</p>
    <code><![CDATA[
<message to='client@domain.com'>
  <url-data xmlns='http://jabber.org/protocol/url-data'
      xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
      target='http://www.jabber.org/members/index.php'>
    <http:header name='Custom-Data' value='some custom data'/>
  </url-data>
</message>
]]></code>
  </section2>
</section1>
<section1 topic='Implementation Notes'>
  <section2 topic='Cookies'>
    <p>Entities receiving cookie information SHOULD following the state management guidelines from &rfc2109;. In particular, the interpretation of the "persistence details" attribute values from &lt;cookie/&gt; is that defined in section 4.2.2 of RFC 1209.</p>
    <p>The attributes provided by &lt;cookie/&gt; MUST NOT be "pre-escaped" for HTTP message headers. it is the responsibility of the receiving entity to properly encode cookie information into the "cookie" message header, including any character escaping.</p>
  </section2>
  <section2 topic='Headers'>
    <p>The &lt;header/&gt; element only provides those message headers used for an HTTP request. There is currently no mechanism to convey HTTP response headers.</p>
    <p>The name and value attributes from &lt;header/&gt; MUST NOT be "pre-escaped" for HTTP message headers. It is the responsibility of the receiving entity to properly encode message headers, including any character escaping.</p>
  </section2>
</section1>
<section1 topic='Formal Description'>
  <section2 topic='Overview'>
    <p>The namespace for this structure is "http://jabber.org/protocol/url-data/scheme/http". Because this namespace is intended to supplement the &lt;url-data/&gt; element, this namespace SHOULD be declared within the &lt;url-data/&gt; element using the "http" namespace prefix (as demonstrated in the examples above). This namespace MUST only be applied when the "target" attribute in &lt;url-data/&gt; uses the scheme "http" or "https".</p>
  </section2>
  <section2 topic='&lt;auth/&gt; Element'>
    <p>The &lt;auth/&gt; element provides authentication information, including scheme. The contents of this element detail any additional parameters for authentication.</p>
    <p>The "scheme" attribute describes the HTTP authentication scheme to use. This attribute MUST be present, and MUST be the name of an HTTP authentication scheme (such as "basic").</p>
  </section2>
  <section2 topic='&lt;auth-param/&gt; Element'>
    <p>The &lt;auth-param/&gt; element provides authentication parameters. This element has attributes for the parameter name and value.</p>
    <p>The "name" attribute specifies the (logical) name of the authentication parameter. This attribute MUST be present, and MUST be applicable to the given scheme, although "realm" is always a valid parameter.</p>
    <p>The "value" attribute specifies the value for this authentication parameter. This attribute MUST be present, but MAY be empty if a value is not required.</p>
  </section2>
  <section2 topic='&lt;cookie/&gt; Element'>
    <p>The &lt;cookie/&gt; element provides client cookie data. This element has attributes for the cookie name and value, as well as the persistence details.</p>
    <p>The "name" attribute specifies the name of the cookie. This attribute MUST be present, and MUST NOT be empty. It corresponds to the "name" in the "name=value" syntax.</p>
    <p>The "value" attribute specifies the value for the cookie. This attribute MUST be present, but MAY be empty if a value is not required. It corresponds to the "value" in the "name=value" syntax.</p>
    <p>The "comment" attribute provides the description of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL.</p>
    <p>The "domain" attribute provides the applicable domain of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL.</p>
    <p>The "path" attribute provides the applicable HTTP path of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL.</p>
    <p>The "max-age" attribute provides the maximum age for the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL, and MUST be a non-negative integer. If not specified, the default value is "0".</p>
    <p>The "secure" attribute indicates if this cookie is only offered in secure environments, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL, and MUST be a boolean value of "true" or "false". The default value is "false".</p>
    <p>The "version" attribute provides the version of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL, and SHOULD be "1.0" unless otherwise needed. If not specified, the default value is "1.0".</p>
  </section2>
  <section2 topic='&lt;header/&gt; Element'>
    <p>The &lt;header/&gt; element provides generic request and entity header information, to be included in the connection attempt. This element is ONLY for message headers included in the HTTP request; it SHOULD NOT be used for message headers included in the HTTP response. The attributes for this element are the name and value of the header.</p>
    <p>The "name" attribute specifies the name of the header. This attribute MUST be present, and MUST conform to the "field-name" pattern for RFC 2616. It corresponds to the "name" in the (simplified) "name: value" header syntax.</p>
    <p>The "value" attribute specifies the value of the header. This attribute MUST be present, and MUST conform to the "field-value" pattern for RFC 2616. It MAY empty if a value is not required. It corresponds to the "value" in the (simplified) "name: value" header syntax.</p>
  </section2>
  <section2 topic='XML Schema'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/url-data/scheme/http'
    xmlns='http://jabber.org/protocol/url-data/scheme/http'
    elementFormDefault='qualified'>

  <xs:element name='auth'>
    <xs:complexType>
      <xs:attribute name='scheme' use='required' type='xs:string'/>
      <xs:element name='auth-param' minOccurs='0' maxOccurs='unbounded'>
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base='xs:string'>
              <xs:attribute name='name' use='required' type='xs:string'/>
              <xs:attribute name='value' use='required' type='xs:string'/>
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:complexType>
  </xs:element>

  <xs:element name='cookie'>
    <xs:complexType>
      <xs:attribute name='name' use='required' type='xs:string'/>
      <xs:attribute name='value' use='required' type='xs:string'/>
      <xs:attribute name='comment' use='optional' type='xs:string'/>
      <xs:attribute name='domain' use='optional' type='xs:string'/>
      <xs:attribute name='max-age' use='optional' type='xs:integer'/>
      <xs:attribute name='path' use='optional' type='xs:string'/>
      <xs:attribute name='secure' use='optional' type='xs:boolean'/>
      <xs:attribute name='version' use='optional' type='xs:string'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='header'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='name' use='required' type='xs:string'/>
          <xs:attribute name='value' use='required' type='xs:string'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
]]></code>
  </section2>
</section1>
<section1 topic='Security Considerations'>
  <section2 topic='Authentication Information'>
    <p>This document allows complete authentication information to be passed. This information is only as secure as the connection-path between the provider and acceptor.</p>
  </section2>
</section1>
<section1 topic='IANA Considerations'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations'>
  <p>The &REGISTRAR; shall register the "http://jabber.org/protocol/url-data/scheme/http" namespace.</p>
</section1>
</xep>