mirror of https://github.com/moparisthebest/xeps
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
431 lines
19 KiB
431 lines
19 KiB
<?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>Draft</status> |
|
<type>Standards Track</type> |
|
<sig>Standards</sig> |
|
<dependencies> |
|
<spec>XMPP Core</spec> |
|
<spec>XEP-0047</spec> |
|
</dependencies> |
|
<supersedes/> |
|
<supersededby/> |
|
<shortname>jingle-ibb</shortname> |
|
<schemaloc> |
|
<url>http://xmpp.org/schemas/jingle-transports-ibb.xsd</url> |
|
</schemaloc> |
|
<discuss>jingle</discuss> |
|
&stpeter; |
|
<revision> |
|
<version>1.0</version> |
|
<date>2011-09-23</date> |
|
<initials>psa</initials> |
|
<remark><p>Per a vote of the XMPP Council, advanced specification from Experimental to Draft.</p></remark> |
|
</revision> |
|
<revision> |
|
<version>0.8</version> |
|
<date>2011-08-31</date> |
|
<initials>psa</initials> |
|
<remark><p>Per feedback from the XMPP Council, modified the security considerations to remove the recommendation to use XTLS (since it is not longer being actively developed).</p></remark> |
|
</revision> |
|
<revision> |
|
<version>0.7</version> |
|
<date>2011-05-16</date> |
|
<initials>psa</initials> |
|
<remark><p>Further clarified order of layers, in particular the reuse of IBB <open/> and <close/> elements.</p></remark> |
|
</revision> |
|
<revision> |
|
<version>0.6</version> |
|
<date>2011-03-07</date> |
|
<initials>psa</initials> |
|
<remark><p>Clarified error flows and handling of multiple IBB sessions within the bytestream.</p></remark> |
|
</revision> |
|
<revision> |
|
<version>0.5</version> |
|
<date>2010-04-14</date> |
|
<initials>psa</initials> |
|
<remark><p>Incremented the protocol version from 0 to 1 because the changes in document version 0.4 are backward-incompatible.</p></remark> |
|
</revision> |
|
<revision> |
|
<version>0.4</version> |
|
<date>2010-04-13</date> |
|
<initials>psa</initials> |
|
<remark><p>Added roundtrip for exchange of IBB <open/> element to provide proper layering between Jingle and IBB; defined how to close a single session within the bytestream; defined how to close the bytestream itself.</p></remark> |
|
</revision> |
|
<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 (e.g., &xep0260;) cannot be negotiated.</p> |
|
<p>The approach taken in this specification is to use the existing IBB mechanisms described in <cite>XEP-0047</cite> 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'> |
|
|
|
<section2 topic='Flow' anchor='protocol-flow'> |
|
<p>The basic flow is as follows.</p> |
|
<code><![CDATA[ |
|
Initiator Responder |
|
| | |
|
| session-initiate | |
|
| (with IBB info) | |
|
|--------------------------->| |
|
| ack | |
|
|<---------------------------| |
|
| session-accept | |
|
|<---------------------------| |
|
| ack | |
|
|--------------------------->| |
|
| IBB <open/> | |
|
|--------------------------->| |
|
| ack | |
|
|<---------------------------| |
|
| IBB "SESSION" | |
|
|<==========================>| |
|
| IBB <close/> | |
|
|--------------------------->| |
|
| ack | |
|
|<---------------------------| |
|
| session-terminate | |
|
|<---------------------------| |
|
| ack | |
|
|--------------------------->| |
|
| | |
|
]]></code> |
|
<p>This flow is illustrated in the following sections (to prevent confusion these use an "example" description instead of a real application type).</p> |
|
</section2> |
|
|
|
<section2 topic='Establishing a Bytestream' anchor='protocol-start'> |
|
<p>First the initiator sends a Jingle session-initiate request.</p> |
|
<example caption="Initiator sends session-initiate"><![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='ex'> |
|
<description xmlns='urn:xmpp:example'/> |
|
<transport xmlns='urn:xmpp:jingle:transports:ibb:1' |
|
block-size='4096' |
|
sid='ch3d9s71'/> |
|
</content> |
|
</jingle> |
|
</iq> |
|
]]></example> |
|
<p>Note: The default value of the 'stanza' attribute is "iq", signifying use of &IQ; stanzas for data exchange; a value of "message" signifies that &MESSAGE; stanzas are to be used for data exchange. See <cite>XEP-0047</cite> for further discussion regarding use of these stanza types for data exchange.</p> |
|
<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' |
|
responder='juliet@capulet.lit/balcony' |
|
sid='a73sjjvkla37jfea'> |
|
<content creator='initiator' name='ex'> |
|
<description xmlns='urn:xmpp:example'/> |
|
<transport xmlns='urn:xmpp:jingle:transports:ibb:1' |
|
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>In essence, the foregoing Jingle negotiation replaces the <open/> element from <cite>XEP-0047</cite>. However, to provide consistent layering of Jingle on top of IBB (thus enabling separation of existing IBB code from new Jingle code), the initiator now MUST also send the <open/> element, with the same 'block-size' and 'sid' values as for the Jingle <transport/> element it negotiated with the recipient (i.e., if the recipient sent a modified <transport/> element element containing a different block size, the initiator MUST use the negotiated values). This adds a roundtrip to the negotiation and could be considered a "no-op", but the extra roundtrip is inconsequential given that the parties will be exchanging base64-encoded data in-band.</p> |
|
<example caption='Initiator sends IBB <open/>'><![CDATA[ |
|
<iq from='romeo@montague.net/orchard' |
|
id='jn3h8g65' |
|
to='juliet@capulet.com/balcony' |
|
type='set'> |
|
<open xmlns='http://jabber.org/protocol/ibb' |
|
block-size='2048' |
|
sid='ch3d9s71' |
|
stanza='iq'/> |
|
</iq> |
|
]]></example> |
|
<p>If no error occurs, the responder returns an IQ-result to the initiator.</p> |
|
<example caption='Responder accepts IBB <open/>'><![CDATA[ |
|
<iq from='juliet@capulet.com/balcony' |
|
id='jn3h8g65' |
|
to='romeo@montague.net/orchard' |
|
type='result'/> |
|
]]></example> |
|
<p>However, one of the errors described in <cite>XEP-0047</cite> might occur; in particular, if the value of the IBB 'block-size' attribute sent by the initiator in the <open/> element does not match the value of the 'block-size' attribute communicated by the responder in the Jingle session-accept message then the responder SHOULD return a &constraint; error as described in <cite>XEP-0047</cite>.</p> |
|
</section2> |
|
|
|
<section2 topic='Exchanging Data' anchor='protocol-data'> |
|
<p>Now the initiator can begin sending IBB packets using an IQ-set for each chunk as described in <cite>XEP-0047</cite>, where the responder will acknowledge each IQ-set in accordance with &xmppcore;.</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> |
|
</section2> |
|
|
|
<section2 topic='Managing Multiple IBB Sessions' anchor='protocol-multi'> |
|
<p>As IBB is defined in <cite>XEP-0047</cite>, there is one session per bytestream (which can be used in both directions). However, because Jingle-IBB provides a management layer on top of IBB, it can be used to run multiple IBB 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 (although this example shows the initiator adding a session, the responder could just as well do so).</p> |
|
<example caption="Initiator adds a session to the bytestream"><![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' |
|
sid='a73sjjvkla37jfea'> |
|
<content creator='initiator' name='ex'> |
|
<transport xmlns='urn:xmpp:jingle:transports:ibb:1' |
|
block-size='2048' |
|
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> |
|
<p>The initiator opens the second session by sending an IBB <open/> element, which the responder acknowledges (not shown).</p> |
|
<example caption='Initiator sends IBB <open/>'><![CDATA[ |
|
<iq from='romeo@montague.net/orchard' |
|
id='yh3vs613' |
|
to='juliet@capulet.com/balcony' |
|
type='set'> |
|
<open xmlns='http://jabber.org/protocol/ibb' |
|
block-size='2048' |
|
sid='bt8a71h6' |
|
stanza='iq'/> |
|
</iq> |
|
]]></example> |
|
<p>The parties can then exchange data over the second session (see <cite>XEP-0047</cite>).</p> |
|
<p>If a party wishes to close one session within a bytestream, it sends an IBB <close/> element as defined in <cite>XEP-0047</cite> specifying the appropriate IBB SessionID.</p> |
|
<example caption='Ending an IBB session'><![CDATA[ |
|
<iq from='romeo@montague.net/orchard' |
|
id='us71g45j' |
|
to='juliet@capulet.com/balcony' |
|
type='set'> |
|
<close xmlns='http://jabber.org/protocol/ibb' |
|
sid='bt8a71h6'/> |
|
</iq> |
|
]]></example> |
|
<p>The receiving party then acknowledges that the IBB session has been closed by returning an IQ-result.</p> |
|
<example caption='Success response'><![CDATA[ |
|
<iq from='juliet@capulet.com/balcony' |
|
id='us71g45j' |
|
to='romeo@montague.net/orchard' |
|
type='result'/> |
|
]]></example> |
|
</section2> |
|
|
|
<section2 topic='Closing the Bytestream' anchor='protocol-close'> |
|
<p>Whenever a party is finished with a particular session within the bytestream, it SHOULD send an IBB <close/> as shown above. This applies to all sessions, including the last one.</p> |
|
<p>To close the bytestream itself (e.g., because the parties have finished using all sessions associated with the bytestream), a party sends a Jingle session-terminate action as defined in <cite>XEP-0166</cite>.</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' |
|
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> |
|
</section2> |
|
</section1> |
|
|
|
<section1 topic='Processing Rules and Usage Guidelines' anchor='rules'> |
|
<p>The same processing rules and usage guidelines defined in <cite>XEP-0047</cite> 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:1" 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='security'> |
|
<section2 topic='Encryption of Media' anchor='security-media'> |
|
<p>This specification, like <cite>XEP-0047</cite> before it, does not directly support end-to-end encryption of the media sent over the transport.</p> |
|
</section2> |
|
<section2 topic='Use of Base64' anchor='security-base64'> |
|
<p>See <cite>XEP-0047</cite> for security considerations related to the use 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>The ®ISTRAR; includes 'urn:xmpp:jingle:transports:ibb:1' in its registry of protocol namespaces 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 includes "jingle-ibb" in its registry of Jingle transport methods at &JINGLETRANSPORTS;. 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:1' |
|
xmlns='urn:xmpp:jingle:transports:ibb:1' |
|
elementFormDefault='qualified'> |
|
|
|
<xs:annotation> |
|
<xs:documentation> |
|
The protocol documented by this schema is defined in |
|
XEP-0261: http://www.xmpp.org/extensions/xep-0261.html |
|
</xs:documentation> |
|
</xs:annotation> |
|
|
|
<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> |
|
|
|
<section1 topic='Acknowledgements' anchor='ack'> |
|
<p>Thanks to Paul Aurich, Fabio Forno, and Marcus Lundblad for their feedback.</p> |
|
</section1> |
|
|
|
</xep>
|
|
|