xeps/xep-0261.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>Jingle In-Band Bytestreams Transport Method</title>
  <abstract>This specification defines a Jingle transport method that results in sending data via the In-Band Bytestreams (IBB) protocol defined in XEP-0047. Essentially this transport method reuses XEP-0047 semantics for sending the data and defines native Jingle methods for starting and ending an IBB session.</abstract>
  &LEGALNOTICE;
  <number>0261</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0047</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>jingle-ibb</shortname>
  <discuss>jingle</discuss>
  &stpeter;
  <revision>
    <version>0.3</version>
    <date>2010-02-16</date>
    <initials>psa</initials>
    <remark><p>Added negotiation flow for block size; corrected some slight errors.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2009-03-09</date>
    <initials>psa</initials>
    <remark><p>Minor changes to track modifications to XEP-0166; updated security considerations for consistency with other transport methods; added section on service discovery.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2009-02-19</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2009-02-11</date>
    <initials>psa</initials>
    <remark>Defined ability to add more session IDs to a bytestream using Jingle transport-info.</remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2009-02-10</date>
    <initials>psa</initials>
    <remark>Rough draft.</remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing In-Band Bytestreams (IBB) protocol specified in &xep0047;. This "jingle-ibb" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer); however, because the "jingle-ibb" transport method sends data over the XMPP channel itself (albeit not the Jingle signalling channel), it is intended as a transport of last resort when other streaming transports cannot be negotiated.</p>
  <p>The approach taken in this specification is to use the existing IBB mechanisms described in XEP-0047 for transporting the data, and to define Jingle-specific methods only to start and end the in-band bytestream.</p>
</section1>

<section1 topic='Protocol' anchor='protocol'>
  <para>The basic flow is as follows.</para>
  <code><![CDATA[
Initiator                   Responder
  |                            |
  |  session-initiate          |
  |  (with IBB info)           |
  |--------------------------->|
  |  ack                       |
  |<---------------------------|
  |  session-accept            |
  |<---------------------------|
  |  ack                       |
  |--------------------------->|
  |  IBB "SESSION"             |
  |<==========================>|
  |  session-terminate         |
  |<---------------------------|
  |  ack                       |
  |--------------------------->|
  |                            |
  ]]></code>
  <p>This flow is illustrated in the following examples (to prevent confusion these use a "stub" description instead of a real application type).</p>
  <p>First the initiator sends a Jingle session-initiate request.</p>
  <example caption="Initiator sends session-initiate (stub)"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='xn28s7gk'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'>
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:ibb:0'
                 block-size='4096'
                 sid='ch3d9s71'/>
    </content>
  </jingle>
</iq>
  ]]></example>
  <p>The responder immediately acknowledges receipt (but does not yet accept the session).</p>
  <example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
    id='xn28s7gk'
    to='romeo@montague.lit/orchard'
    type='result'/>
  ]]></example>
  <p>If the offer is acceptable, the responder returns a Jingle session-accept. If the responder wishes to use a smaller block-size, the responder can specify that in the session-accept by returning a different value for the 'block-size' attribute.</p>
  <example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
    id='bsa91h56'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          initiator='romeo@montague.lit/orchard'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:ibb:0'
                 block-size='2048'
                 sid='ch3d9s71'/>
    </content>
  </jingle>
</iq>
  ]]></example>
  <p>The initiator then acknowledges the session-accept.</p>
  <example caption="Initiator acknowledges session-accept"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='bsa91h56'
    to='juliet@capulet.lit/balcony'
    type='result'/>
  ]]></example>
  <p>The foregoing Jingle negotiation replaces the &lt;open/&gt; element from <cite>XEP-0047</cite>. Therefore the initiator can now immediately begin sending IBB packets using an IQ-set for each chunk as described in XEP-0047, where the responder will acknowledge each IQ-set in accordance with &rfc3920;.</p>
  <example caption='An IBB packet'><![CDATA[
<iq from='romeo@montague.net/orchard' 
    id='ls72b58f'
    to='juliet@capulet.com/balcony' 
    type='set'>
  <data xmlns='http://jabber.org/protocol/ibb' seq='0' sid='ch3d9s71'>
    qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
    WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
    IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
    AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
    kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
  </data>
</iq>
  ]]></example>
  <example caption='An IBB ack'><![CDATA[
<iq from='juliet@capulet.com/balcony' 
    id='ls72b58f'
    to='romeo@montague.net/orchard' 
    type='result'/>
  ]]></example>
  <p>Once the parties have finished using the bytestream (e.g., because a complete file has been sent), either party can send a Jingle session-terminate action.</p>
  <example caption="Initiator terminates the session"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='hz81vf48'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <reason><success/></reason>
  </jingle>
</iq>
  ]]></example>
  <p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
  <example caption="Responder acknowledges session-terminate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
    id='hz81vf48'
    to='romeo@montague.lit/orchard'
    type='result'/>
  ]]></example>
</section1>

<section1 topic='Adding a Session to a Bytestream' anchor='session'>
  <p>As IBB is defined in XEP-0047, there is one session per bytestream (which can be used in both directions). To extend this idea, it might be useful to run multiple sessions over a single bytestream. This can be done by sending a transport-info message that authorizes an additional session, as shown in the following example.</p>
  <example caption="Initiator adds a session"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='znb376s4'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'>
          action='transport-info'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='stub'>
      <transport xmlns='urn:xmpp:jingle:transports:ibb:0'
                 block-size='4096'
                 sid='bt8a71h6'/>
    </content>
  </jingle>
</iq>
  ]]></example>
  <p>Here the Jingle Session ID is the same ("a73sjjvkla37jfea") but the new IBB Session ID ("bt8a71h6") is different from the old IBB Session ID that is already in use ("ch3d9s71").</p>
</section1>

<section1 topic='Processing Rules and Usage Guidelines' anchor='rules'>
  <p>The same processing rules and usage guidelines defined in XEP-0047 apply to the Jingle IBB Transport Method.</p>
</section1>

<section1 topic='Determining Support' anchor='support'>
  <p>To advertise its support for the Jingle In-Band Bytestreams Transport Method, when replying to &xep0030; information requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:transports:ibb:0" for this version &VNOTE;.</p>
  <example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='uw72g176'
    to='juliet@capulet.lit/balcony'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  ]]></example>
  <example caption="Service discovery information response"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
    id='uw72g176'
    to='romeo@montague.lit/orchard'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:jingle:1'/>
    <feature var='urn:xmpp:jingle:transports:ibb:1'/>
  </query>
</iq>
  ]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>

<section1 topic='Security Considerations' anchor='sec'>
  <section2 topic='Encryption of Media' anchor='security-media'>
    <p>A Jingle implementation SHOULD support security preconditions that are enforced before application media is allowed to flow over the bytestream, such as those described in &xtls;.</p>
  </section2>
  <section2 topic='Use of Base64' anchor='security-base64'>
    <p>See <cite>XEP-0047</cite> for security considerations related to the user of Base64.</p>
  </section2>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:jingle:transports:ibb:0</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
  <section2 topic='Jingle Transport Methods' anchor='registrar-transports'>
    <p>The XMPP Registrar shall add to its registry of Jingle transport methods a definition for the "jingle-ibb" transport method. The registry submission is as follows:</p>
    <code><![CDATA[
<transport>
  <name>ibb</name>
  <desc>A method for data exchange over In-Band Bytestreams.</desc>
  <type>streaming</type>
  <doc>XEP-0261</doc>
</transport>
    ]]></code>
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:jingle:transports:ibb:0'
    xmlns='urn:xmpp:jingle:transports:ibb:0'
    elementFormDefault='qualified'>

   <xs:element name='transport'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='block-size' type='xs:short' use='required'/>
          <xs:attribute name='sid' type='xs:string' use='required'/>
          <xs:attribute name='stanza' use='optional' default='iq'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='iq'/>
                <xs:enumeration value='message'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:extension>
      </xs:simpleContent>
     </xs:complexType>
   </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
  ]]></code>
</section1>

</xep>