mirror of https://github.com/moparisthebest/xeps
292 lines
12 KiB
XML
292 lines
12 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE jep SYSTEM '../jep.dtd' [
|
|
<!ENTITY % ents SYSTEM '../jep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
|
|
<jep>
|
|
<header>
|
|
<title>In-Band Bytestreams (IBB)</title>
|
|
<abstract>This JEP defines a protocol 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>JEP-0079</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<schemaloc>
|
|
<url>http://jabber.org/protocol/ibb/ibb.xsd</url>
|
|
</schemaloc>
|
|
<shortname>ibb</shortname>
|
|
&infiniti;
|
|
<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 JEP-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 &jep0065; 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 message stanzas. Either participant in the bytestream may send such packets. The data to be sent, prior to any encoding or wrapping in the message stanza, must be no larger than the 'block-size' determined in the stream negotiation. All packets 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. Note that &jep0079; SHOULD be used to ensure that the data packet is not spooled or sent to the wrong resource.</p>
|
|
<example caption='Sending data'><![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>
|
|
|
|
<p>The data to send is included as XML character data of the <data/> element after being encoded as Base64 as specified in Section 3 of &rfc3548;. The 'seq' attribute is a 16-bit 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>It is possible that the message may fail to be delivered:</p>
|
|
|
|
<example caption='Failed delivery'><![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>
|
|
|
|
<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>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 JEP requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Jabber Registrar Considerations'>
|
|
<section2 topic='Protocol Namespaces'>
|
|
<p>The ®ISTRAR; shall register the 'http://jabber.org/protocol/ibb' namespace as a result of this JEP.</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
|
|
JEP-0047: http://www.jabber.org/jeps/jep-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>
|
|
|
|
</jep>
|