No Description
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.

xep-0261.xml 19KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Jingle In-Band Bytestreams Transport Method</title>
  10. <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>
  11. &LEGALNOTICE;
  12. <number>0261</number>
  13. <status>Draft</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies>
  17. <spec>XMPP Core</spec>
  18. <spec>XEP-0047</spec>
  19. </dependencies>
  20. <supersedes/>
  21. <supersededby/>
  22. <shortname>jingle-ibb</shortname>
  23. <schemaloc>
  24. <url>http://xmpp.org/schemas/jingle-transports-ibb.xsd</url>
  25. </schemaloc>
  26. <discuss>jingle</discuss>
  27. &stpeter;
  28. <revision>
  29. <version>1.0</version>
  30. <date>2011-09-23</date>
  31. <initials>psa</initials>
  32. <remark><p>Per a vote of the XMPP Council, advanced specification from Experimental to Draft.</p></remark>
  33. </revision>
  34. <revision>
  35. <version>0.8</version>
  36. <date>2011-08-31</date>
  37. <initials>psa</initials>
  38. <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>
  39. </revision>
  40. <revision>
  41. <version>0.7</version>
  42. <date>2011-05-16</date>
  43. <initials>psa</initials>
  44. <remark><p>Further clarified order of layers, in particular the reuse of IBB &lt;open/&gt; and &lt;close/&gt; elements.</p></remark>
  45. </revision>
  46. <revision>
  47. <version>0.6</version>
  48. <date>2011-03-07</date>
  49. <initials>psa</initials>
  50. <remark><p>Clarified error flows and handling of multiple IBB sessions within the bytestream.</p></remark>
  51. </revision>
  52. <revision>
  53. <version>0.5</version>
  54. <date>2010-04-14</date>
  55. <initials>psa</initials>
  56. <remark><p>Incremented the protocol version from 0 to 1 because the changes in document version 0.4 are backward-incompatible.</p></remark>
  57. </revision>
  58. <revision>
  59. <version>0.4</version>
  60. <date>2010-04-13</date>
  61. <initials>psa</initials>
  62. <remark><p>Added roundtrip for exchange of IBB &lt;open/&gt; 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>
  63. </revision>
  64. <revision>
  65. <version>0.3</version>
  66. <date>2010-02-16</date>
  67. <initials>psa</initials>
  68. <remark><p>Added negotiation flow for block size; corrected some slight errors.</p></remark>
  69. </revision>
  70. <revision>
  71. <version>0.2</version>
  72. <date>2009-03-09</date>
  73. <initials>psa</initials>
  74. <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>
  75. </revision>
  76. <revision>
  77. <version>0.1</version>
  78. <date>2009-02-19</date>
  79. <initials>psa</initials>
  80. <remark><p>Initial published version.</p></remark>
  81. </revision>
  82. <revision>
  83. <version>0.0.2</version>
  84. <date>2009-02-11</date>
  85. <initials>psa</initials>
  86. <remark>Defined ability to add more session IDs to a bytestream using Jingle transport-info.</remark>
  87. </revision>
  88. <revision>
  89. <version>0.0.1</version>
  90. <date>2009-02-10</date>
  91. <initials>psa</initials>
  92. <remark>Rough draft.</remark>
  93. </revision>
  94. </header>
  95. <section1 topic='Introduction' anchor='intro'>
  96. <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>
  97. <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>
  98. </section1>
  99. <section1 topic='Protocol' anchor='protocol'>
  100. <section2 topic='Flow' anchor='protocol-flow'>
  101. <p>The basic flow is as follows.</p>
  102. <code><![CDATA[
  103. Initiator Responder
  104. | |
  105. | session-initiate |
  106. | (with IBB info) |
  107. |--------------------------->|
  108. | ack |
  109. |<---------------------------|
  110. | session-accept |
  111. |<---------------------------|
  112. | ack |
  113. |--------------------------->|
  114. | IBB <open/> |
  115. |--------------------------->|
  116. | ack |
  117. |<---------------------------|
  118. | IBB "SESSION" |
  119. |<==========================>|
  120. | IBB <close/> |
  121. |--------------------------->|
  122. | ack |
  123. |<---------------------------|
  124. | session-terminate |
  125. |<---------------------------|
  126. | ack |
  127. |--------------------------->|
  128. | |
  129. ]]></code>
  130. <p>This flow is illustrated in the following sections (to prevent confusion these use an "example" description instead of a real application type).</p>
  131. </section2>
  132. <section2 topic='Establishing a Bytestream' anchor='protocol-start'>
  133. <p>First the initiator sends a Jingle session-initiate request.</p>
  134. <example caption="Initiator sends session-initiate"><![CDATA[
  135. <iq from='romeo@montague.lit/orchard'
  136. id='xn28s7gk'
  137. to='juliet@capulet.lit/balcony'
  138. type='set'>
  139. <jingle xmlns='urn:xmpp:jingle:1'
  140. action='session-initiate'
  141. initiator='romeo@montague.lit/orchard'
  142. sid='a73sjjvkla37jfea'>
  143. <content creator='initiator' name='ex'>
  144. <description xmlns='urn:xmpp:example'/>
  145. <transport xmlns='urn:xmpp:jingle:transports:ibb:1'
  146. block-size='4096'
  147. sid='ch3d9s71'/>
  148. </content>
  149. </jingle>
  150. </iq>
  151. ]]></example>
  152. <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>
  153. <p>The responder immediately acknowledges receipt (but does not yet accept the session).</p>
  154. <example caption="Responder acknowledges session-initiate"><![CDATA[
  155. <iq from='juliet@capulet.lit/balcony'
  156. id='xn28s7gk'
  157. to='romeo@montague.lit/orchard'
  158. type='result'/>
  159. ]]></example>
  160. <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>
  161. <example caption="Responder definitively accepts the session"><![CDATA[
  162. <iq from='juliet@capulet.lit/balcony'
  163. id='bsa91h56'
  164. to='romeo@montague.lit/orchard'
  165. type='set'>
  166. <jingle xmlns='urn:xmpp:jingle:1'
  167. action='session-accept'
  168. responder='juliet@capulet.lit/balcony'
  169. sid='a73sjjvkla37jfea'>
  170. <content creator='initiator' name='ex'>
  171. <description xmlns='urn:xmpp:example'/>
  172. <transport xmlns='urn:xmpp:jingle:transports:ibb:1'
  173. block-size='2048'
  174. sid='ch3d9s71'/>
  175. </content>
  176. </jingle>
  177. </iq>
  178. ]]></example>
  179. <p>The initiator then acknowledges the session-accept.</p>
  180. <example caption="Initiator acknowledges session-accept"><![CDATA[
  181. <iq from='romeo@montague.lit/orchard'
  182. id='bsa91h56'
  183. to='juliet@capulet.lit/balcony'
  184. type='result'/>
  185. ]]></example>
  186. <p>In essence, the foregoing Jingle negotiation replaces the &lt;open/&gt; 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 &lt;open/&gt; element, with the same 'block-size' and 'sid' values as for the Jingle &lt;transport/&gt; element it negotiated with the recipient (i.e., if the recipient sent a modified &lt;transport/&gt; 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>
  187. <example caption='Initiator sends IBB &lt;open/&gt;'><![CDATA[
  188. <iq from='romeo@montague.net/orchard'
  189. id='jn3h8g65'
  190. to='juliet@capulet.com/balcony'
  191. type='set'>
  192. <open xmlns='http://jabber.org/protocol/ibb'
  193. block-size='2048'
  194. sid='ch3d9s71'
  195. stanza='iq'/>
  196. </iq>
  197. ]]></example>
  198. <p>If no error occurs, the responder returns an IQ-result to the initiator.</p>
  199. <example caption='Responder accepts IBB &lt;open/&gt;'><![CDATA[
  200. <iq from='juliet@capulet.com/balcony'
  201. id='jn3h8g65'
  202. to='romeo@montague.net/orchard'
  203. type='result'/>
  204. ]]></example>
  205. <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 &lt;open/&gt; 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>
  206. </section2>
  207. <section2 topic='Exchanging Data' anchor='protocol-data'>
  208. <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>
  209. <example caption='An IBB packet'><![CDATA[
  210. <iq from='romeo@montague.net/orchard'
  211. id='ls72b58f'
  212. to='juliet@capulet.com/balcony'
  213. type='set'>
  214. <data xmlns='http://jabber.org/protocol/ibb' seq='0' sid='ch3d9s71'>
  215. qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
  216. WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
  217. IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
  218. AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
  219. kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
  220. </data>
  221. </iq>
  222. ]]></example>
  223. <example caption='An IBB ack'><![CDATA[
  224. <iq from='juliet@capulet.com/balcony'
  225. id='ls72b58f'
  226. to='romeo@montague.net/orchard'
  227. type='result'/>
  228. ]]></example>
  229. </section2>
  230. <section2 topic='Managing Multiple IBB Sessions' anchor='protocol-multi'>
  231. <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>
  232. <example caption="Initiator adds a session to the bytestream"><![CDATA[
  233. <iq from='romeo@montague.lit/orchard'
  234. id='znb376s4'
  235. to='juliet@capulet.lit/balcony'
  236. type='set'>
  237. <jingle xmlns='urn:xmpp:jingle:1'
  238. action='transport-info'
  239. sid='a73sjjvkla37jfea'>
  240. <content creator='initiator' name='ex'>
  241. <transport xmlns='urn:xmpp:jingle:transports:ibb:1'
  242. block-size='2048'
  243. sid='bt8a71h6'/>
  244. </content>
  245. </jingle>
  246. </iq>
  247. ]]></example>
  248. <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>
  249. <p>The initiator opens the second session by sending an IBB &lt;open/&gt; element, which the responder acknowledges (not shown).</p>
  250. <example caption='Initiator sends IBB &lt;open/&gt;'><![CDATA[
  251. <iq from='romeo@montague.net/orchard'
  252. id='yh3vs613'
  253. to='juliet@capulet.com/balcony'
  254. type='set'>
  255. <open xmlns='http://jabber.org/protocol/ibb'
  256. block-size='2048'
  257. sid='pd51xa96'
  258. stanza='iq'/>
  259. </iq>
  260. ]]></example>
  261. <p>The parties can then exchange data over the second session (see <cite>XEP-0047</cite>).</p>
  262. <p>If a party wishes to close one session within a bytestream, it sends an IBB &lt;close/&gt; element as defined in <cite>XEP-0047</cite> specifying the appropriate IBB SessionID.</p>
  263. <example caption='Ending an IBB session'><![CDATA[
  264. <iq from='romeo@montague.net/orchard'
  265. id='us71g45j'
  266. to='juliet@capulet.com/balcony'
  267. type='set'>
  268. <close xmlns='http://jabber.org/protocol/ibb'
  269. sid='bt8a71h6'/>
  270. </iq>
  271. ]]></example>
  272. <p>The receiving party then acknowledges that the IBB session has been closed by returning an IQ-result.</p>
  273. <example caption='Success response'><![CDATA[
  274. <iq from='juliet@capulet.com/balcony'
  275. id='us71g45j'
  276. to='romeo@montague.net/orchard'
  277. type='result'/>
  278. ]]></example>
  279. </section2>
  280. <section2 topic='Closing the Bytestream' anchor='protocol-close'>
  281. <p>Whenever a party is finished with a particular session within the bytestream, it SHOULD send an IBB &lt;close/&gt; as shown above. This applies to all sessions, including the last one.</p>
  282. <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>
  283. <example caption="Initiator terminates the session"><![CDATA[
  284. <iq from='romeo@montague.lit/orchard'
  285. id='hz81vf48'
  286. to='juliet@capulet.lit/balcony'
  287. type='set'>
  288. <jingle xmlns='urn:xmpp:jingle:1'
  289. action='session-terminate'
  290. sid='a73sjjvkla37jfea'>
  291. <reason><success/></reason>
  292. </jingle>
  293. </iq>
  294. ]]></example>
  295. <p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
  296. <example caption="Responder acknowledges session-terminate"><![CDATA[
  297. <iq from='juliet@capulet.lit/balcony'
  298. id='hz81vf48'
  299. to='romeo@montague.lit/orchard'
  300. type='result'/>
  301. ]]></example>
  302. </section2>
  303. </section1>
  304. <section1 topic='Processing Rules and Usage Guidelines' anchor='rules'>
  305. <p>The same processing rules and usage guidelines defined in <cite>XEP-0047</cite> apply to the Jingle IBB Transport Method.</p>
  306. </section1>
  307. <section1 topic='Determining Support' anchor='support'>
  308. <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>
  309. <example caption="Service discovery information request"><![CDATA[
  310. <iq from='romeo@montague.lit/orchard'
  311. id='uw72g176'
  312. to='juliet@capulet.lit/balcony'
  313. type='get'>
  314. <query xmlns='http://jabber.org/protocol/disco#info'/>
  315. </iq>
  316. ]]></example>
  317. <example caption="Service discovery information response"><![CDATA[
  318. <iq from='juliet@capulet.lit/balcony'
  319. id='uw72g176'
  320. to='romeo@montague.lit/orchard'
  321. type='result'>
  322. <query xmlns='http://jabber.org/protocol/disco#info'>
  323. <feature var='urn:xmpp:jingle:1'/>
  324. <feature var='urn:xmpp:jingle:transports:ibb:1'/>
  325. </query>
  326. </iq>
  327. ]]></example>
  328. <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>
  329. </section1>
  330. <section1 topic='Security Considerations' anchor='security'>
  331. <section2 topic='Encryption of Media' anchor='security-media'>
  332. <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>
  333. </section2>
  334. <section2 topic='Use of Base64' anchor='security-base64'>
  335. <p>See <cite>XEP-0047</cite> for security considerations related to the use of Base64.</p>
  336. </section2>
  337. </section1>
  338. <section1 topic='IANA Considerations' anchor='iana'>
  339. <p>This document requires no interaction with &IANA;.</p>
  340. </section1>
  341. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  342. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  343. <p>The &REGISTRAR; includes 'urn:xmpp:jingle:transports:ibb:1' in its registry of protocol namespaces at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  344. </section2>
  345. <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
  346. &NSVER;
  347. </section2>
  348. <section2 topic='Jingle Transport Methods' anchor='registrar-transports'>
  349. <p>The XMPP Registrar includes "jingle-ibb" in its registry of Jingle transport methods at &JINGLETRANSPORTS;. The registry submission is as follows.</p>
  350. <code><![CDATA[
  351. <transport>
  352. <name>ibb</name>
  353. <desc>
  354. A method for data exchange over In-Band Bytestreams.
  355. </desc>
  356. <type>streaming</type>
  357. <doc>XEP-0261</doc>
  358. </transport>
  359. ]]></code>
  360. </section2>
  361. </section1>
  362. <section1 topic='XML Schema' anchor='schema'>
  363. <code><![CDATA[
  364. <?xml version='1.0' encoding='UTF-8'?>
  365. <xs:schema
  366. xmlns:xs='http://www.w3.org/2001/XMLSchema'
  367. targetNamespace='urn:xmpp:jingle:transports:ibb:1'
  368. xmlns='urn:xmpp:jingle:transports:ibb:1'
  369. elementFormDefault='qualified'>
  370. <xs:annotation>
  371. <xs:documentation>
  372. The protocol documented by this schema is defined in
  373. XEP-0261: http://www.xmpp.org/extensions/xep-0261.html
  374. </xs:documentation>
  375. </xs:annotation>
  376. <xs:element name='transport'>
  377. <xs:complexType>
  378. <xs:simpleContent>
  379. <xs:extension base='empty'>
  380. <xs:attribute name='block-size'
  381. type='xs:short'
  382. use='required'/>
  383. <xs:attribute name='sid'
  384. type='xs:string'
  385. use='required'/>
  386. <xs:attribute name='stanza'
  387. use='optional'
  388. default='iq'>
  389. <xs:simpleType>
  390. <xs:restriction base='xs:NCName'>
  391. <xs:enumeration value='iq'/>
  392. <xs:enumeration value='message'/>
  393. </xs:restriction>
  394. </xs:simpleType>
  395. </xs:attribute>
  396. </xs:extension>
  397. </xs:simpleContent>
  398. </xs:complexType>
  399. </xs:element>
  400. <xs:simpleType name='empty'>
  401. <xs:restriction base='xs:string'>
  402. <xs:enumeration value=''/>
  403. </xs:restriction>
  404. </xs:simpleType>
  405. </xs:schema>
  406. ]]></code>
  407. </section1>
  408. <section1 topic='Acknowledgements' anchor='ack'>
  409. <p>Thanks to Paul Aurich, Fabio Forno, and Marcus Lundblad for their feedback.</p>
  410. </section1>
  411. </xep>