xeps/xep-0047.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>In-Band Bytestreams (IBB)</title>
  <abstract>This document defines an XMPP protocol extension for bytestreaming data in band between any two entities over Jabber/XMPP.</abstract>
  &LEGALNOTICE;
  <number>0047</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <jig>Standards JIG</jig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0079</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <schemaloc>
    <url>http://www.xmpp.org/schemas/ibb.xsd</url>
  </schemaloc>
  <shortname>ibb</shortname>
  &infiniti;
  <revision>
    <version>1.1</version>
    <date>2006-11-21</date>
    <initials>jk</initials>
    <remark>Allow IQ for delivery.</remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2003-12-10</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
  </revision>
  <revision>
    <version>0.8</version>
    <date>2003-12-04</date>
    <initials>jk</initials>
    <remark>Add 'block-size' attribute and usage guidelines</remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2003-05-23</date>
    <initials>jk</initials>
    <remark>Use IQ for shutdown, remove XEP-0022 dependency, loop the counter</remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2003-05-14</date>
    <initials>jk</initials>
    <remark>Use message for delivery</remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2003-04-06</date>
    <initials>jk</initials>
    <remark>Changed newseq to prevseq, added acks, changed seq size to 32-bit</remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2003-03-22</date>
    <initials>jk</initials>
    <remark>Changed protocol, added sequence id</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2002-12-10</date>
    <initials>jk</initials>
    <remark>Removed the 'comment' block, changed namespace</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2002-10-10</date>
    <initials>jk</initials>
    <remark>Revised the text</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2002-09-29</date>
    <initials>jk</initials>
    <remark>Initial version.</remark>
  </revision>
</header>

<section1 topic='Introduction'>
<p>This document describes In-Band Bytestreams (or IBB), a reliable bytestream protocol between two Jabber entities over a Jabber XML stream.  The basic idea is that binary data is encoded as Base64 and transferred over the Jabber network.</p>
</section1>

<section1 topic='Uses'>
<p>IBB is a generic bytestream, and so its usage is left open-ended.  It is likely to be useful for sending small payloads, such as files that would otherwise be too cumbersome to send as an instant message (such as a text file) or impossible to send (such as a small binary image file).  It could also be useful for any kind of low-bandwidth activity, such as a chess game or a shell session.  And, while it is mostly intended as a fallback in situations where a &xep0065; is unavailable, IBB could be more desirable for many of the simple bytestream use-cases that do not have high bandwidth requirements.</p>
</section1>

<section1 topic='Implementation'>
  <section2 topic='Creating a bytestream'>

<example caption='Initiation of Interaction'><![CDATA[
<iq type='set' 
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='inband_1'>
  <open sid='mySID' 
        block-size='4096'
        xmlns='http://jabber.org/protocol/ibb'/>
</iq>
]]></example>

<p>This asks Juliet if she would like to form an In-Band Bytestreams connection, using the session ID 'mySID' (generated by the initiator here) to uniquely reference the bytestream.  The 'block-size' attribute specifies the maximum amount of data (in bytes) that an IBB packet may contain.</p>

<example caption='Success Response'><![CDATA[
<iq type='result' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_1'/>
]]></example>

<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is active.</p>

<example caption='Error'><![CDATA[
<iq type='error' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_1'/>
  <error code='501' type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>

<p>This is an error response from juliet@capulet.com/balcony saying that an In-Band Bytestreams is not possible.</p>

  </section2>
  <section2 topic='Sending data'>

<p>Data is sent using either &lt;message&gt; or &lt;iq&gt; stanzas.  Either participant in the bytestream may send such packets.  The data to be sent, prior to any encoding or wrapping in the stanza, must be no larger than the 'block-size' determined in the stream negotiation.  All stanzas are to be addressed to the FULL JID of the bytestream peer.  In order to keep track of stanzas sent and any errors received, the sender SHOULD include the 'id' attribute on stanzas sent to the recipient.  When using &lt;message&gt; stanzas, &xep0079; SHOULD be used to ensure that the data packet is not spooled or sent to the wrong resource.</p>
<example caption='Sending data using message'><![CDATA[
<message from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='msg1'>
  <data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
    qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
    WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
    IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
    AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
    kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
  </data>
  <amp xmlns='http://jabber.org/protocol/amp'>
    <rule condition='deliver-at' value='stored' action='error'/>
    <rule condition='match-resource' value='exact' action='error'/>
  </amp>
</message>
]]></example>

<example caption='Sending data using iq'><![CDATA[
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' type='set' id='ibb1'>
  <data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
    qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
    WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
    IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
    AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
    kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
  </data>
</iq>
]]></example>

<p>The data to send is included as XML character data of the &lt;data/&gt; element after being encoded as Base64 as specified in Section 3 of &rfc3548;.  The 'seq' attribute is a 16-bit unsigned integer counter starting at 0, and MUST be incremented for each packet sent.  Thus, the next packet sent should have a 'seq' of 1, the one after that with a 'seq' of 2, and so on.  The counter loops at maximum, so after value 65535, 'seq' MUST start again at 0.</p>

<p>Note that in the case of iq stanzas, the recipient must reply with an iq of type 'result'.</p>
<example caption='Acknowledging data using iq'><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='result' id='ibb1'/>
]]></example>

<p>The sender need not wait for these acknowledgements before sending further stanzas.  However, it is RECOMMENDED that the sender does wait in order to minimize possible rate-limiting penalties.</p>

<p>It is possible that the stanza may fail to be delivered:</p>

<example caption='Failed delivery with message'><![CDATA[
<message from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='msg1' type='error'>
  ...
  <error code='504' type='cancel'>
    <remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</message>
]]></example>

<example caption='Failed delivery with iq'><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='ibb1' type='error'>
  ...
  <error code='504' type='cancel'>
    <remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>

<p>Upon delivery failure, the sender MUST consider the bytestream to be closed and invalid.</p>

  </section2>
  <section2 topic='Closing the bytestream'>

<p>To close the bytestream, send the following:</p>

<example caption='Closing the bytestream'><![CDATA[
<iq type='set' 
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='inband_2'>
  <close xmlns='http://jabber.org/protocol/ibb' sid='mySID'/>
</iq>
]]></example>

<example caption='Success response'><![CDATA[
<iq type='result' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_2'/>
]]></example>

<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is now closed.</p>

<example caption='Possible error'><![CDATA[
<iq type='error' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_2'>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>

<p>Upon error, the bytestream MUST be considered closed and invalid.</p>

  </section2>
  <section2 topic='Receiving packets'>
<p>Data packets MUST be processed in the order they are received.  If an out-of-sequence packet is received for a particular bytestream (determined by checking the 'seq' attribute), then this indicates that a packet has been lost.  The recipient MUST NOT process the data of such an out-of-sequence packet, nor any that follow it within the same bytestream, and at this point MUST consider the bytestream closed and invalid.</p>
  </section2>

</section1>

<section1 topic='Usage Guidelines'>
  <ul>
    <li>Generally, IBB should be used as a last resort. <strong>SOCKS5 Bytestreams</strong> will almost always be preferable.</li>
    <li>A server MAY rate limit a connection, depending on the size and frequency of data packets.</li>
    <li>A server MAY disconnect a connection that sends overly large packets as defined by server policy.</li>
    <li>&lt;message&gt; delivery SHOULD be used when &xep0079; or other stanza flow-control facilities are available.  However, if they are not available, then &lt;iq&gt; SHOULD be used.</li>
    <li>It is RECOMMENDED to use a 'block-size' of 4096.</li>
    <li>For proper tracking of message delivery errors, the use of the stanza 'id' attribute is RECOMMENDED.</li>
  </ul>
</section1>

<section1 topic='Security Considerations'>
  <p>In-Band Bytestreams is as secure as the underlying Jabber transport.  The bytestream application could have its own security layer, but this is outside of the scope of IBB.</p>
  <p>An entity MUST verify any Base64 data received.  An implementation MUST reject (not ignore) any characters that are not explicitly allowed by the Base64 alphabet; this helps to guard against creation of a covert channel that could be used to "leak" information.  An implementation MUST NOT break on invalid input and MUST reject any sequence of Base64 characters containing the pad ('=') character if that character is included as something other than the last character of the data (e.g.  "=AAA" or "BBBB=CCC"); this helps to guard against buffer overflow attacks and other attacks on the implementation.  Base encoding visually hides otherwise easily recognized information, such as passwords, but does not provide any computational confidentiality.  Base64 encoding MUST follow the definition in Section 3 of RFC 3548.</p>
</section1>

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

<section1 topic='XMPP Registrar Considerations'>
  <section2 topic='Protocol Namespaces'>
    <p>The &REGISTRAR; shall register the 'http://jabber.org/protocol/ibb' namespace as a result of this document.</p> 
  </section2>
</section1>

<section1 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/ibb'
    xmlns='http://jabber.org/protocol/ibb'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0047: http://www.xmpp.org/extensions/xep-0047.html
    </xs:documentation>
  </xs:annotation>

   <xs:element name='open'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='sid' type='xs:string' use='required'/>
          <xs:attribute name='block-size' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
     </xs:complexType>
   </xs:element>

   <xs:element name='close'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='sid' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
     </xs:complexType>
   </xs:element>

   <xs:element name='data'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='sid' type='xs:string' use='required'/>
          <xs:attribute name='seq' type='xs:string' use='required'/>
        </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>