-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathxep-0261.xml
431 lines (411 loc) · 19.3 KB
/
xep-0261.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
<?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>