-
Notifications
You must be signed in to change notification settings - Fork 0
/
xep-0234.xml
1123 lines (1082 loc) · 58.1 KB
/
xep-0234.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
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?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 File Transfer</title>
<abstract>This specification defines a Jingle application type for transferring a file from one entity to another. The protocol provides a modular framework that enables the exchange of information about the file to be transferred as well as the negotiation of parameters such as the transport to be used.</abstract>
&LEGALNOTICE;
<number>0234</number>
<status>Deferred</status>
<lastcall>2017-12-12</lastcall>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0166</spec>
<spec>XEP-0261</spec>
<spec>XEP-0300</spec>
</dependencies>
<supersedes><spec>XEP-0096</spec></supersedes>
<supersededby/>
<shortname>jingle-ft</shortname>
&stpeter;
&lance;
<revision>
<version>0.19.1</version>
<date>2019-06-19</date>
<initials>ri0n</initials>
<remark>Fix use of hash elements from XEP—0300.</remark>
</revision>
<revision>
<version>0.19.0</version>
<date>2018-11-08</date>
<initials>XEP Editor (jsc)</initials>
<remark>Defer due to lack of activity.</remark>
</revision>
<revision>
<version>0.18.3</version>
<date>2017-08-24</date>
<initials>ps</initials>
<remark><p>Make use of <hash-used/> from XEP-0300.</p></remark>
</revision>
<revision>
<version>0.18.2</version>
<date>2017-08-23</date>
<initials>editor (jwi)</initials>
<remark><ul>
<li>Fix a date missing its timezone in examples. (egp)</li>
<li>Remove the mention of UTC, timestamps are already properly described in XEP-0082. (egp)</li>
<li>Add missing length attribute to XML schema. (ps)</li>
<li>Fix incorrect XML in examples. (ps)</li>
</ul></remark>
</revision>
<revision>
<version>0.18.1</version>
<date>2017-05-20</date>
<initials>egp</initials>
<remark><ul>
<li>Add missing anchor to the <link url='#received'>Received</link> section.</li>
<li>Add missing received and desc elements in schema.</li>
</ul></remark>
</revision>
<revision>
<version>0.18.0</version>
<date>2017-01-30</date>
<initials>ls</initials>
<remark>
<ul>
<li>Update dependency on XEP-0300 to require the 'urn:xmpp:hashes:2' namespace that mandates base64 encoding.</li>
<li>Clarify that a <range/> element with a limit or offset value in a 'session-accept' should be honored by the file sender.</li>
<li>Namespace version bumped to ':5'.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.17.2</version>
<date>2016-07-15</date>
<initials>ph (XEP Editor: ssw)</initials>
<remark><p>Fix references to ICE-TCP.</p></remark>
</revision>
<revision>
<version>0.17.1</version>
<date>2016-03-08</date>
<initials>ls</initials>
<remark><p>Corrected some instances of transport-info to instead be session-info.</p></remark>
</revision>
<revision>
<version>0.17</version>
<date>2015-09-08</date>
<initials>ls/psa</initials>
<remark>
<ul>
<li>Recast the document to match the registration procedure defined by XEP-0166 for new application types.</li>
<li>Explicitly defined the schema of the <file/> element instead of referencing XEP-0096.</li>
<li>Defined the use of a 'length' attribute on <range/> elements. This attribute was always there because the <file/> and <range/> elements had been defined as the same as the parallel elements in XEP-0096, but the 'length' attribute was not explicitly referenced in this document.</li>
<li>Clarified the need for the 'senders' attribute on Jingle <content/> elements to distinguish between File Offers and File Requests.</li>
<li>Added the <file-not-found/> and <file-too-large/> reason types.</li>
<li>Clarified how to abort a file transfer via 'content-remove' or 'session-terminate' actions.</li>
<li>Added <received/> element for indicating that a transfer was successful, particularly when there are multiple transfers.</li>
<li>Added SDP mapping.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.16</version>
<date>2014-08-11</date>
<initials>psa</initials>
<remark>
<ul>
<li>Modified protocol to support sending only one file at a time (multi-file adds unnecessary complexity).</li>
<li>Removed <request/> flow in favor of a dedicated protocol similar to XEP-0137 ("jingle-pub").</li>
<li>Removed <offer/> wrapper since it is no longer necessary (with the removal of the request flow).</li>
<li>Removed the <abort/> element since it was related to the transfer of multiple files.</li>
<li>Changed <candidate-used/> to >remote-candidate/> for consistency with XEP-0176.</li>
<li>Added media-type child to <file/> element.</li>
<li>Added example for communicating empty <hash/> element in the session-initiate message.</li>
<li>Incremented namespace version from 3 to 4.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.15</version>
<date>2012-02-08</date>
<initials>psa</initials>
<remark><p>Updated to track revisions to XEP-0300.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2011-06-29</date>
<initials>psa</initials>
<remark>
<ul>
<li>Defined file description format separate from XEP-0096</li>
<li>Modified the checksum format to reuse the <hashes/> element from XEP-0300</li>
<li>Described the process of aborting a file transfer</li>
<li>Clarified the order of events (Jingle, then transport) when the session is terminated</li>
<li>Added section on determining spport, including service discovery feature for multi-file support</li>
<li>Removed the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace by putting all elements into the 'urn:xmpp:jingle:apps:file-transfer:4' namespace</li>
<li>Incremented namespace version from 2 to 3</li>
</ul>
</remark>
</revision>
<revision>
<version>0.13</version>
<date>2011-06-01</date>
<initials>psa</initials>
<remark><p>Added multi-file use case; updated spec to reflect XEP-0260 and XEP-0261; added algorithm attribute from XEP-0096; increased namespace versions from 1 to 2.</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2011-01-05</date>
<initials>psa</initials>
<remark><p>Clarified usage of Jingle actions as well as several ambiguous points in the text, including use of the range feature from XEP-0096.</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2010-02-19</date>
<initials>psa</initials>
<remark><p>Added session-info message and namespace for communicating the file hash.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2010-02-11</date>
<initials>psa</initials>
<remark><p>Described the file retrieval case; updated referenced namespaces.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2009-02-19</date>
<initials>psa</initials>
<remark>
<ul>
<li>Moved Jingle definitions of S5B and IBB transports to standalone documents.</li>
<li>Because the jingle-s5b and jingle-ibb transport methods are backward-incompatible, incremented protocol version number from 0 to 1 and changed namespace from urn:xmpp:jingle:apps:file-transfer:0 to urn:xmpp:jingle:apps:file-transfer:2.</li>
<li>Moved transport fallback scenario to XEP-0260.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.8</version>
<date>2008-09-30</date>
<initials>psa</initials>
<remark><p>Corrected fallback scenario to use transport-replace and transport-accept.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2008-09-25</date>
<initials>psa</initials>
<remark>
<ul>
<li>Deleted content-replace from session flows.</li>
<li>Modified namespaces to incorporate namespace versioning.</li>
<li>Cleaned up XML schemas.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.6</version>
<date>2008-07-31</date>
<initials>psa</initials>
<remark><p>Harmonized with XEP-0166; modified fallback to use transport-replace and transport-accept.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2008-06-05</date>
<initials>psa</initials>
<remark><p>Modified fallback scenario to use content-replace action during pending state.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2008-06-04</date>
<initials>psa</initials>
<remark><p>Harmonized negotiation flows with other Jingle application types.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2008-05-29</date>
<initials>psa</initials>
<remark><p>Corrected and more clearly explained negotiation flows for consistency with XEP-0166 and other Jingle specifications.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2008-03-20</date>
<initials>psa</initials>
<remark><p>Added transport negotiation scenario.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-02-29</date>
<initials>psa</initials>
<remark><p>Corrected use of content-replace action; specified that the In-Band Bytestreams transport method is mandatory-to-implement but must have the lowest preference order.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-02-28</date>
<initials>psa</initials>
<remark><p>Modified negotiation flow to use new content-replace action.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-01-29</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is file transfer. This document specifies an application format for negotiating Jingle file transfer sessions, where files are exchanged via any available reliable transport.</p>
</section1>
<section1 topic='Requirements'>
<p>&xep0096; was the original XMPP protocol extension for file transfer negotiation. However, that protocol has several drawbacks, most related to the &xep0095; protocol on which it depends:</p>
<ol>
<li><p>It does not enable a true, bidirectional negotiation; instead, the initiator sets the terms for the file transfer and the responder either accepts the terms or cancels the negotiation.</p></li>
<li><p>It is the only technology in the Jabber/XMPP protocol "stack" that uses <cite>XEP-0095: Stream Initiation</cite>. More modern technologies such as voice and video session negotiation use &xep0166;, and it would be helpful if implementors could re-use the same code for all negotiation use cases.</p></li>
</ol>
<p>To overcome these drawbacks, this specification defines a file transfer negotiation method that meets the following requirements:</p>
<ul>
<li><p>Use the session negotiation semantics from <cite>XEP-0166</cite>.</p></li>
<li>
<p>Use any reliable Jingle transport mechanism, including but not limited to:</p>
<ul>
<li>ICE-TCP &rfc6544;</li>
<li>SOCKS5 Bytestreams &xep0260;</li>
<li>In-Band Bytestreams &xep0261;</li>
</ul>
</li>
<li><p>Define a file description format that, unlike <cite>XEP-0096</cite>, enables hash agility (via &xep0300;).</p></li>
<li><p>Define a clear upgrade path from SI File Transfer to Jingle File Transfer.</p></li>
</ul>
<p>Note that Jingle file transfer is only as reliable as the transports on which it depends. In particular, SOCKS5 Bytestreams ("S5B") does not always result in NAT or firewall traversal. To work around that problem, this specification requires all implementations to support as a fallback mechanism In-Band Bytestreams ("IBB"), which usually results in a successful (if slow) file transfer. A more robust and adaptable option is ICE-TCP (RFC 6544); at the time of writing &xep0176; is being updated to include the ability to negotiate ICE-TCP candidates.</p>
</section1>
<section1 topic='Terminology' anchor='terms'>
<dl>
<di>
<dt>File Offer</dt>
<dd>A Jingle File Transfer Content is said to be a File Offer if the content creator is the same as the content sender (see <link url='#content-senders'>Use of Jingle Content Senders</link>).</dd>
</di>
<di>
<dt>File Request</dt>
<dd>A Jingle File Transfer Content is said to be a File Request if the content creator is the opposite of the content sender (see <link url='#content-senders'>Use of Jingle Content Senders</link>).</dd>
</di>
<di>
<dt>File Sender</dt>
<dd>The File Sender is the side of the Jingle session responsible for sending the file data. The File Sender is not necessarily the same entity as the Jingle session initiator, and an entity could be both a File Sender and File Receiver in the context of a single Jingle session with multiple files.</dd>
</di>
<di>
<dt>File Receiver</dt>
<dd>The File Receiver is the side of the Jingle session responsible for receiving the file data. The File Receiver is not necessarily the same entity as the Jingle session responder, and an entity could be both a File Receiver and File Sender in the context of a single Jingle session with multiple files.</dd>
</di>
</dl>
</section1>
<section1 topic='Jingle Conformance'>
<p>In accordance with Section 12 of <cite>XEP-0166</cite>, this document specifies the following information related to the Jingle File Transfer ("Jingle FT") application type:</p>
<ol>
<li><p>The application format negotiation process is defined in the <link url='#negotiation'>Negotiating a Jingle File Transfer Session</link> section of this document.</p></li>
<li><p>The semantics of the &DESCRIPTION; element are defined in the <link url='#format'>Application Format</link> section of this document.</p></li>
<li><p>A mapping of Jingle semantics to the Session Description Protocol is provided in the <link url='#sdp'>Mapping to Session Description Protocol</link> section of this document.</p></li>
<li><p>A Jingle File Transfer session SHOULD use a streaming transport method, not a datagram transport method.</p></li>
<li><p>Transport components are not used in Jingle File Transfer.</p></li>
<li>
<p>Content is to be sent and received as follows:</p>
<p>For streaming transports, outbound content shall be encoded into packets (as defined by the transport mechanism) without any other framing mechanism and sent in succession over the transport. Incoming data received over the transport shall be processed as a stream of packets, where each packet's content payload is entirely composed of the next portion of file data to be processed.</p>
</li>
</ol>
<section2 topic='Use of Jingle Content Senders' anchor='content-senders'>
<p>Jingle File Transfer makes critical use of the 'senders' attribute of Jingle &CONTENT; elements in order to specify which party is responsible for sending the described file. As such, Jingle File Transfer content MUST include a 'senders' attribute, where the allowed values are "initiator" and "responder". The semantics of the values "both" and "none" are undefined in Jingle File Transfer and thus NOT RECOMMENDED for use with Jingle File Transfer content.</p>
<p>In general, a Jingle File Transfer content is said to be a "File Offer" if the 'senders' attribute is the same as the role of the party adding the content to the session, and a "File Request" if the 'senders' value is the opposite role of the party adding the content.</p>
<p>Note: The content 'creator' attribute does <em>not</em> specify who created or is sending the file, it only specifies which party to the session added the Jingle content to the session.</p>
<table caption='Distinguishing File Offers and Requests'>
<tr>
<th>Jingle Session Role</th>
<th>Content Senders</th>
<th>File Transfer Type</th>
</tr>
<tr>
<td>initiator</td>
<td>initiator</td>
<td>File Offer</td>
</tr>
<tr>
<td>initiator</td>
<td>responder</td>
<td>File Request</td>
</tr>
<tr>
<td>responder</td>
<td>initiator</td>
<td>File Request</td>
</tr>
<tr>
<td>responder</td>
<td>responder</td>
<td>File Offer</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='Application Format'>
<p>A Jingle File Transfer session is described by a content type that contains one application format and one transport method. Each &CONTENT; element defines the details of a single file transfer. A Jingle negotiation MAY result in the establishment of multiple file transfers by including multiple &CONTENT; elements.</p>
<p>The application format consists of a file description contained within a &DESCRIPTION; element qualified by the "urn:xmpp:jingle:apps:file-transfer:5" namespace &VNOTE;. The file description is a <file/> element specifying metadata such as the name of the file, media type, etc., as illustrated in the following example.</p>
<code><![CDATA[
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<media-type>text/plain</media-type>
<name>test.txt</name>
<date>2015-07-26T21:46:00+01:00</date>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>]]></code>
<p>The &DESCRIPTION; element is intended to be a child of a Jingle &CONTENT; element as specified in <cite>XEP-0166</cite>.</p>
<p>The child elements of the <file/> element are as follows:</p>
<table caption='File Description Elements'>
<tr>
<th>Element Name</th>
<th>Description</th>
<th>Inclusion</th>
</tr>
<tr>
<td>date</td>
<td>Timestamp specifying the last modified time of the file (which MUST conform to the DateTime profile of &xep0082;).</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>desc</td>
<td>A human readable description of the file. Multiple <desc/> elements MAY be included if different xml:lang values are specified.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>hash</td>
<td>A hash of the file content, using the <hash/> element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:2' namespace. Multiple hashes MAY be included for hash agility.</td>
<td>See <hash-used/></td>
</tr>
<tr>
<td>hash-used</td>
<td>Alternatively to a <hash/> element, the initiator can also include a <hash-used/> element. This avoids the need to read the file twice to calculate the hash.</td>
<td>Either a <hash/> or a <hash-used/> element MUST be included when offering a file.</td>
</tr>
<tr>
<td>media-type</td>
<td>The media type of the file content, which SHOULD be a valid MIME-TYPE as registered with &IANA; (specifically, as listed at <<link url='http://www.iana.org/assignments/media-types'>http://www.iana.org/assignments/media-types</link>>). If not specified, the content is assumed to be "application/octet-stream".</td>
<td>RECOMMENDED when offering a file, otherwise OPTIONAL</td>
</tr>
<tr>
<td>name</td>
<td>The name of the file. The name SHOULD NOT contain characters or character sequences that would be interpreted as a directory structure by the local file system (e.g. "/", "\", "../", etc.). If any such characters or character sequences are present (possibly because the local and remote file systems use different syntax for directory structure), they SHOULD be escaped (e.g., via percent-encoding) before using the name as part of any file system operation. See <link url='#security'>Security Considerations</link>.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>size</td>
<td>The length of the file's content, in bytes.</td>
<td>OPTIONAL, but SHOULD be present when offering a file.</td>
</tr>
<tr>
<td>range</td>
<td>The presence of the <range/> element indicates support of ranged transfers, and can be used to control where a transfer starts.</td>
<td>OPTIONAL</td>
</tr>
</table>
<p>One or more <hash/> elements MUST be present when offering a file, but those elements MAY be empty if the hash has not yet been computed. If there is no computed hash value, the <hash/> element(s) MUST possess an 'algo' attribute specifying which hash algorithm will be used. Once a hash has been calculated by the File Sender, the File Sender SHOULD inform the File Receiver of the hash value as described in <link url='#hash'>Checksum</link>.</p>
<p>Additional elements MAY be included as children of the <file/> element to provide additional metadata about the file, such as &xep0264;.</p>
<p>The optional <range/> element MAY possess two attributes:</p>
<table caption='Range Element Attributes'>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Inclusion</th>
</tr>
<tr>
<td>offset</td>
<td>Specifies the position, in bytes, from which to start transferring file data. This defaults to zero (0) if not specified.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>length</td>
<td>Specifies the number of bytes to retrieve starting at offset. This defaults to the length of the file from offset to the end.</td>
<td>OPTIONAL</td>
</tr>
</table>
<p>Inclusion of a <range/> element in a File Offer indicates support of ranged transfers for future File Requests if the transfer is interrupted and needs to be restarted.</p>
<p>A <range/> element MAY include an 'offset' attribute set to begin the transfer at a point other than the start of the file, and MAY include a 'length' attribute to request a portion of the file smaller than the remaining length of the file. If no 'offset' or 'length' attributes are present then it is the same as if no <range/> element was present, because the default values of the attributes would indicate a requested range of the entire file. In general, the first byte of data to be transferred is at the (zero-indexed) position specified by the 'offset' value, with a total of 'length' bytes sent.</p>
</section1>
<section1 topic='Negotiating a Jingle File Transfer Session'>
<p>In general, the process for negotiating a Jingle File Transfer session is as follows:</p>
<code><![CDATA[
Initiator Responder
| |
| session-initiate |
|---------------------------->|
| ack |
|<----------------------------|
| session-accept |
|<----------------------------|
| ack |
|---------------------------->|
| [optional further |
| negotiation] |
|<--------------------------->|
| File Transfer |
|============================>|
| |]]></code>
<section2 topic='Offering a File' anchor='offering'>
<p>To start a File Offer, the initiator sends a Jingle session-initiation request to a potential responder. The request specifies three things:</p>
<ol>
<li>A content 'senders' attribute with the value of 'initiator' to indicate this is a File Offer.</li>
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:5". In particular, the <description/> element contains a <file/> elements describing the file to be sent.</li>
<li>An appropriate transport method.</li>
</ol>
<p>In this example, the initiator is <romeo@montague.example>, the responder is <juliet@capulet.example>, the application type is a File Offer, and the transport method is jingle-s5b (XEP-0260).</p>
<p>The flow is as follows.</p>
<p>First the initiator sends a Jingle session-initiate.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='nzu25s8'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<media-type>text/plain</media-type>
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
<candidate cid='hutr46fe'
host='24.24.24.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5087'
priority='8258636'
type='direct'/>
</transport>
</content>
</jingle>
</iq>]]></example>
<p>Note: Inclusion of the <range/> child of the <file/> element indicates that the initiator supports ranged transfers as described below under <link url='#range'>Ranged Transfers</link>.</p>
<p>Note: Computing the hash of the file before sending it can slow down the process of file transfer, because the sending application needs to process the file twice. The File Sender might prefer to send the hash after the file transfer has begun, using a session-info message as described under <link url='#hash'>Checksum</link>.</p>
<p>The responder immediately acknowledges receipt of the Jingle session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='nzu25s8'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='result'/>]]></example>
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in <cite>XEP-0260</cite> and <cite>XEP-0065</cite>. In the meantime, the responder returns a Jingle session-accept. In the session-accept message, the <file/> element MAY contain a <range/> element to indicate that the receiver also supports ranged transfers as described below under <link url='#range'>Ranged Transfers</link>. If the responder includes a <range /> element with a limit or offset, the File Sender SHOULD respect the provided range settings.</p>
<example caption="Responder sends session-accept"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jn2vs71g'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-accept'
responder='juliet@capulet.example/yn0cl4bnw0yr3vym'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<media-type>text/plain</media-type>
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='ht567dq'
host='192.169.1.10'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='6539'
priority='8257636'
type='direct'/>
<candidate cid='hr65dqyd'
host='134.102.201.180'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='16453'
priority='7929856'
type='assisted'/>
<candidate cid='grt654q2'
host='2001:638:708:30c9:219:d1ff:fea4:a17d'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='6539'
priority='8257606'
type='direct'/>
</transport>
</content>
</jingle>
</iq>]]></example>
<p>The initiator acknowledges the Jingle session-accept.</p>
<example caption="Initiator acknowledges session-accept"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='jn2vs71g'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='result'/>]]></example>
</section2>
<section2 topic='Requesting a File' anchor='requesting'>
<p>If the File Sender has advertised the existence of a file that it hosts, such as by &xep0358;, or if a previous file transfer attempt has failed and the File Receiver would like to initiate another attempt, the File Receiver can "pull" the file from the File Sender. This is done by sending a Jingle session-initiate to the File Sender which includes a <content/> with the 'senders' attribute set to the opposite Jingle session role of the party requesting the file (see <link url='#content-senders'>Use of Jingle Content Senders</link>) and a <description/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace and which includes a <file/> element with enough information included to form a "file selector" (see Section 5 of &rfc5547;) to identify the requested file.</p>
<example caption="File Receiver requests hosted file"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='wsn361c3'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='juliet@capulet.example/yn0cl4bnw0yr3vym'
sid='uj3b2'>
<content creator='initiator' name='a-file-request' senders='responder'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='xig361fj'>
<candidate cid='ht567dq'
host='192.169.1.10'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='6539'
priority='8257636'
type='direct'/>
<candidate cid='hr65dqyd'
host='134.102.201.180'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='16453'
priority='7929856'
type='assisted'/>
<candidate cid='grt654q2'
host='2001:638:708:30c9:219:d1ff:fea4:a17d'
jid='juliet@capulet.example/yn0cl4bnw0yr3vym'
port='6539'
priority='8257606'
type='direct'/>
</transport>
</content>
</jingle>
</iq>]]></example>
<p>See <link url='#file-not-available'>File not Available</link> for how to respond if the requester does not have permission to request the file, or if the file cannot be found.</p>
</section2>
<section2 topic='Offering or Requesting Additional Files'>
<p>While the Jingle File Transfer session is active, either party MAY choose to add additional files (both offers and requests) to the transfer session. To do so, a Jingle content-add action is used, as shown in the following examples.</p>
<example caption="File Sender offers additional file"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='wsn361c9'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-add'
sid='uj3b2'>
<content creator='initiator' name='additional' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<name>second-file.txt</name>
<media-type>text/plain</media-type>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
<candidate cid='hutr46fe'
host='24.24.24.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5087'
priority='8258636'
type='direct'/>
</transport>
</content>
</jingle>
</iq>]]></example>
<p>The other party then acks the content-add request.</p>
<example caption="File Receiver acks content-add request"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
to='romeo@montague.example/dr4hcr0st3lup4c'
id='wsn361c9'
type='result' />]]></example>
<p>At this point, the content-add request needs to be either accepted or rejected using Jingle content-accept or content-reject actions.</p>
</section2>
<section2 topic='Ranged Transfers' anchor='range'>
<p>As in <cite>XEP-0096</cite>, a transfer can include only part of a file (e.g., to restart delivery of a truncated transfer session at a point other than the start of the file). This is done using the <range/> element. The usage is illustrated in the following examples.</p>
<p>Let us imagine that the parties negotiate a file transfer session using, say, In-Band Bytestreams. During the transfer, the recipient goes offline unexpectedly and IBB stanzas from the File Sender to the File Receiver begin to bounce. When the recipient comes back online, the File Sender could initiate a new Jingle session and specify that it wants to send all chunks after byte 270336 (which might be the 66th chunk of size 4096).</p>
<example caption="File Sender requests session to send file, with range"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='wsn361c3'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='uj3b2'>
<content creator='initiator' name='restart' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<range offset='270336'/>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
<candidate cid='hutr46fe'
host='24.24.24.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5087'
priority='8258636'
type='direct'/>
</transport>
</content>
</jingle>
</iq>]]></example>
</section2>
<section2 topic='Aborting a Transfer'>
<p>At any point, either party MAY choose to abort the transfer of a single file, or end the session entirely to abort all active transfers.</p>
<p>When there is only a single Jingle content or if a party wishes to abort the transfer of all files in the session, a session-terminate including a Jingle reason of <cancel /> is sent.</p>
<example caption='File Receiver aborts all active file transfers'><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jp2ba614'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
sid='a73sjjvkla37jfea'>
<reason>
<cancel />
</reason>
</jingle>
</iq>]]></example>
<p>If a party chooses to abort the transfer of a single file out of several active transfers, a Jingle content-remove action is used, which MAY include a Jingle reason of <cancel/>, as shown in the following example.</p>
<example caption='File Receiver aborts the transfer'><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jp2ba614'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-remove'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='a-file-offer' />
<reason>
<cancel />
</reason>
</jingle>
</iq>]]></example>
<p>The other party then acks the content-remove request.</p>
<example caption='File Sender acks abort request'><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='jp2ba614'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='result' />]]></example>
<p>If after removing the content there are no other Jingle contents the session MUST be terminated as described in the next section.</p>
</section2>
<section2 topic='Ending the Session'>
<p>Once all file content in the session has been transfered, either party MAY acknowledge receipt of the received files (see <link url='#received'>Received</link>) or, if there are no other active file transfers, terminate the Jingle session with a Jingle session of <success/>. Preferably, sending the session-terminate is done by the last entity to finish receiving a file to ensure that all offered or requested files by either party have been completely received (up to the advertised sizes).</p>
<example caption='File Receiver ends the session after successfully receiving all files'><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jp2ba614'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
sid='a73sjjvkla37jfea'>
<reason>
<success />
</reason>
</jingle>
</iq>]]></example>
</section2>
</section1>
<section1 topic='Mapping to Session Description Protocol' anchor='sdp'>
<p>&rfc5547; defines the general process for including file transfer information in SDP.</p>
<p>The SDP media type for Jingle File Transfer can be "message" (e.g. when used with &rfc4975;) or "application"; however, this media value is not reflected in the Jingle File Transfer application format.</p>
<p>Any combination of <name/>, <size/>, <media-type/>and <hash/> values MAY be used to form a "file selector" (see Section 5 of &rfc5547;), which would be mapped to SDP as follows:</p>
<code><![CDATA[
a=file-selector [name:"<name>"] [size:<size>] [type:<media-type>] [hash:<hash algo>:<hash value>]]]></code>
<p>(The hash value MUST be encoded as hexadecimal with each byte separated by a colon.)</p>
<p>The <date/> value is the last modified time of the file, and thus is mapped as follows:</p>
<code><![CDATA[
a=file-date:modification:"<date>"]]></code>
<p>Note: the format used here for <date> is the date-time format defined in &rfc5322;.</p>
<p>If a range is specified, the SDP mapping requires both a start and stop offset. If no length was specified for the range, the stop offset is "*". If a length was specified, the stop offset is the <range/> offset value plus the length.</p>
<code><![CDATA[
a=file-range:<offset>-<(offset + length) | *>]]></code>
<p>As a full example, given the following Jingle File Transfer content description:</p>
<code><![CDATA[
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<media-type>text/plain</media-type>
<name>test.txt</name>
<date>2015-07-26T21:46:00+01:00</date>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
<range offset='1024' />
</file>
</description>]]></code>
<p>The equivalent SDP would be:</p>
<code><![CDATA[
a=file-selector: name:"test.txt" size:6144 type:text/plain hash:sha-1:55:2D:A7:49:93:08:52:C6:9A:E5:D2:14:1D:37:66:B1
a=file-date:modification:"26 Jul 2015 21:46:00"
a=file-range:1024-*]]></code>
</section1>
<section1 topic='Informational Messages'>
<section2 topic='Received' anchor='received'>
<p>Once a file has been successfully received, the recipient MAY send a Jingle session-info message indicating receipt of the complete file, which consists of a <received/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. The <received/> element SHOULD contain 'creator' and 'name' attributes sufficient to identify the content that was received.</p>
<example caption='File Receiver sends ack in session-info'><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jp2ba614'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
sid='a73sjjvkla37jfea'>
<received xmlns='urn:xmpp:jingle:apps:file-transfer:5'
creator='initiator'
name='a-file-offer' />
</jingle>
</iq>]]></example>
</section2>
<section2 topic='Checksum' anchor='hash'>
<p>At any time during the lifetime of the file transfer session, the File Sender can communicate the checksum of the file to the File Receiver.</p>
<p>This can be done in the session-initiate message if the File Sender already knows the checksum, as shown above in Example 3.</p>
<p>After the session-initiate message, this can also be done by sending a session-info message containing a <checksum/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. In such a case however, the session-initiate message MUST contain a <hash-used/> element. The <checksum/> element SHOULD contain 'creator' and 'name' attributes sufficient to identitfy the content the checksum belongs to. Additionally, the <checksum/> element MUST contain a <file/> element which MUST contain at least one <hash/> or <hash-used/> element qualified by the 'urn:xmpp:hashes:2' namespace. Each <hash/> element contains a checksum of the file data produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;.</p>
<example caption="Initiator sends checksum in session-info"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='kqh401b5'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
sid='a73sjjvkla37jfea'>
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5'
creator='initiator'
name='a-file-offer'>
<file>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</checksum>
</jingle>
</iq>]]></example>
<p>If a ranged transfer was requested, the <file/> element inside the <checksum/> element MAY include a <range/> element specifying the offset and length of the requested range, which in turn includes <hash/> element(s) with hashes of the data that was transferred for that range.</p>
<example caption="Initiator sends checksum in session-info for a specific range"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='kqh401b5'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
sid='a73sjjvkla37jfea'>
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5'
creator='initiator'
name='a-file-offer'>
<file>
<range offset='2048' length='1024'>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>kHp5RSzW/h7Gm1etSf90Mr5PC/k=</hash>
</range>
</file>
</checksum>
</jingle>
</iq>]]></example>
<p>If the initiator wishes to communicate only the hashing algorithm at the beginning of the session (e.g., because it has not yet calculated the checksum), it can send <hash-used/> element in the session-initiate message; this enables the recipient to check the file during the transfer session (which can be helpful in the case of transfers that are truncated or fail mid-stream).</p>
<example caption="Initiator communicates hashing algorithm in session-initiate"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='nzu25s8'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<media-type>text/plain</media-type>
<name>test.txt</name>
<range/>
<size>6144</size>
<hash-used xmlns='urn:xmpp:hashes:2' algo='sha-1'/>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
mode='tcp'
sid='vj3hs98y'>
<candidate cid='hft54dqy'
host='192.168.4.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5086'
priority='8257636'
type='direct'/>
<candidate cid='hutr46fe'
host='24.24.24.1'
jid='romeo@montague.example/dr4hcr0st3lup4c'
port='5087'
priority='8258636'
type='direct'/>
</transport>
</content>
</jingle>
</iq>]]></example>
</section2>
</section1>
<section1 topic='Errors' anchor='errors'>
<section2 topic='File not Available' anchor='file-not-available'>
<p>If a requested file cannot be found (or the requester does not have permission to request or know about the existence of the file in question), then the File Sender SHOULD send either a session-terminate or content-reject action in response to the session-initiate or content-add request, and SHOULD include a Jingle reason of <failed-application/> and MAY include an application specific reason of a <file-not-available/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:errors:0' namespace.</p>
<example caption="File Sender rejects file request because the file could not be found"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='wsn361c9'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-reject'
sid='uj3b2'>
<content creator='initiator' name='requesting-file' senders='initiator'/>
<reason>
<failed-application />
<file-not-available xmlns='urn:xmpp:jingle:apps:file-transfer:errors:0' />
</reason>
</jingle>
</iq>]]></example>
</section2>
<section2 topic='File too Large' anchor='file-too-large'>
<p>There are several situations where a File Receiver might wish to abort a transfer due to an excess of file data, for example:</p>
<ul>
<li>The File Receiver has reached a file system storage quota or other hard limit that prevents continuing to receive file data.</li>
<li>The File Sender has continued sending data past the initially specified size of the file.</li>
</ul>
<p>In such cases, the File Receiver MAY abort the transfer by sending a Jingle session-terminate (or content-remove as appropriate) which includes a Jingle reason of <media-error/> and MAY include an application specific reason of a <file-too-large/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:errors:0' namespace.</p>
<example caption="File Receiver rejects file offer because the file is too large"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='wsn361c9'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-remove'
sid='uj3b2'>
<content creator='initiator' name='big-file' senders='initiator'/>
<reason>
<media-error />
<file-too-large xmlns='urn:xmpp:jingle:apps:file-transfer:errors:0' />
</reason>
</jingle>
</iq>]]></example>
<p>To prevent denial of service and other attacks, the File Receiver is fully within its rights to drop received data or not send a session-terminate message.</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Mandatory to Implement Technologies' anchor='impl-mti'>
<p>All implementations MUST support the Jingle In-Band Bytestreams Transport Method (<cite>XEP-0261</cite>) as a reliable method of last resort. An implementation SHOULD support other transport methods as well, especially ICE-TCP (RFC 6544) and the Jingle SOCKS5 Bytestreams Transport Method (<cite>XEP-0260</cite>).</p>
</section2>
<section2 topic='Preference Order of Transport Methods' anchor='impl-pref'>
<p>An application MAY present transport methods in any order, except that the Jingle In-Band Bytestreams Transport Method MUST be the lowest preference.</p>
</section2>
<section2 topic='Migration from XEP-0096' anchor='impl-migration'>
<p>Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:jingle:apps:file-transfer:5' namespace &VNOTE;, via either service discovery (<cite>XEP-0030</cite>) or entity capabilities (<cite>XEP-0115</cite>). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using Jingle rather than Stream Initiation.</p>
</section2>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>To advertise its support for the Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:apps:file-transfer:5" for this version &VNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='uw72g176'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption="Service discovery information response"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='uw72g176'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:1'/>
<feature var='urn:xmpp:jingle:apps:file-transfer:5'/>
<feature var='urn:xmpp:jingle:transports:s5b: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'>
<p>Caution needs to be exercised when using the <name/> of a file offer or request to control any interaction with a file system. For example, a malicious user could request a file with <name>/etc/passwd</name> or include file system specific control patterns such as <name>../../private.txt</name> to try and access a sensitive file outside of the set of files intended to be shared. Or a malicious user could offer a file named "/etc/passwd" to try and trick the receiver into overwriting that or other sensitive files. Therefore, implementations SHOULD escape any file system path separators in the <name/> before using that value in any file system calls.</p>
<p>It is RECOMMENDED for implementations to use the strongest hashing algorithm available to both parties. See <cite>XEP-0300</cite> for further discussion.</p>
<p>In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method being used. For example, end-to-end encryption can be negotiated over either SOCKS5 Bytestreams or In-Band Bytestreams as described in <cite>XEP-0260</cite> and <cite>XEP-0261</cite>.</p>
<p>Refer to <cite>XEP-0047</cite>, <cite>XEP-0065</cite>, <cite>XEP-0096</cite>, <cite>XEP-0176</cite>, <cite>XEP-0260</cite>, <cite>XEP-0261</cite>, and <cite>RFC 6544</cite> for related security considerations.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>No interaction with &IANA; is required as a result of this document.</p>
<p>The XML character data of the <media-type/> element SHOULD be a value registered with the IANA in the &ianamedia;.</p>
</section1>