-
Notifications
You must be signed in to change notification settings - Fork 121
/
xep-0052.xml
401 lines (372 loc) · 17.5 KB
/
xep-0052.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
<?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>File Transfer</title>
<abstract>A protocol for transferring a file between two Jabber IDs.</abstract>
&LEGALNOTICE;
<number>0052</number>
<status>Retracted</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>XEP-0004</spec>
<spec>XEP-0020</spec>
<spec>XEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby>
<spec>XEP-0095</spec>
<spec>XEP-0096</spec>
</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Thomas</firstname>
<surname>Muldowney</surname>
<email>temas@box5.net</email>
<jid>temas@jabber.org</jid>
</author>
<author>
<firstname>Matthew</firstname>
<surname>Miller</surname>
<email>linuxwolf@outer-planes.net</email>
<jid>linuxwolf@outer-planes.net</jid>
</author>
<author>
<firstname>Justin</firstname>
<surname>Karneges</surname>
<email>justin@affinix.com</email>
<jid>justin@andbit.net</jid>
</author>
<revision>
<version>0.2.1</version>
<date>2018-11-03</date>
<initials>pep</initials>
<remark>Fix a bunch of typos, batch-style.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the authors, the status of this document has been changed to Retracted since it has been superseded by XEP-0095 and XEP-0096.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-03</date>
<initials>tjm</initials>
<remark>Initial version, based on original XEP-0052 revision 0.1.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>
This document describes the http://www.jabber.org/protocol/filexfer
namespace, which is used for offering and transferring files from one Jabber
ID to another. It tries to expand the basic method (iq:oob) that currently
exists to allow for numerous stream methods, and more detailed file
information before accepting an offer. This document only describes the
negotiation method and suggests how streams could link back to the
negotiated information.
</p>
</section1>
<section1 topic='Use Cases'>
<p>
This document covers one use case of sending a file to another user. Future specifications
may enhance this to include searching and offering.
</p>
<section2 topic='Send File Use Case'>
<p>Primary Flow:</p>
<ol>
<li>Determine if the receiver supports FT through disco/browse. [E1]</li>
<li>Sender sends metadata and available methods to receiver</li>
<li>Receiver sends the accepted method to Sender and any range/offset
information. [E2],[E3]</li>
<li>Sender and Receiver establish the negotiated method[E4]</li>
<li>Sender sends data as described by method</li>
<li>After the stream closes the Receiver notifies the Sender of
completion. [E5]</li>
<li>END</li>
</ol>
<p>Errors Conditions:</p>
<ol>
<li>User does not support filetransfer. END</li>
<li>Receiver rejects send. END</li>
<li>Receiver does not have any methods shared with the sender. END</li>
<li>The stream is unable to be started. END</li>
<li>The Receiver notifies sender of an error transferring. END</li>
</ol>
</section2>
</section1>
<section1 topic='Basic Usage'>
<p>
In order to send a file, the sender must first tell the receiver a little
bit about the file to make sure they will accept it. At the same time they
list the stream methods they support in the order they wish to use them.
This is done by sending the information in the http://www.jabber.org/protocol/filexfer namespace.
</p>
<example caption='Generic Offer'>
<iq type='set' id='ft_1' to='recvr@jabber.org/Home'>
<file xmlns='http://www.jabber.org/protocol/filexfer'
action='offer'
id='a0'
name='myfile.txt'
size='1024'
mime-type='text/plain'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data'>
<field var='file-transfer-method' type='list-single'>
<option><value>jabber:iq:oob</value></option>
</field>
</x>
</feature>
</file>
</iq>
</example>
<p>
That is the basic request, a more complete requeset with range support is
shown below.
</p>
<example caption='Complete File Offer'>
<iq type='set' id='ft_1' to='recvr@jabber.org/Home'>
<file xmlns='http://www.jabber.org/protocol/filexfer'
action='offer'
id='a0'
name='myfile.txt'
size='1024'
mime-type='text/plain'
date='20020412T00:00:00'
hash='23e4ad6b63343b33a333c334'>
<desc>A cool file</desc>
<range/>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data'>
<field var='file-transfer-method' type='list-single'>
<option><value>jobs</value></option>
<option><value>dtcp</value></option>
<option><value>jabber:iq:oob</value></option>
<option><value>ibb</value></option>
</field>
</x>
</feature>
</file>
</iq>
</example>
<p>If a receiver decides to accept an offered file they request it from the sending with an <iq/> type result. The receiver sends back the id of the file being sent, the method they wish to use, and the range they wish to download (if the sender announced support). When range support is being used the receiver MUST specify the length and MAY specify a beginning offset with the acceptance.</p>
<example caption='Request the Offered File'>
<iq type='result' id='ft_req_1' to='sender@jabber.org/res'>
<file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data'>
<field var='file-transfer-method'>
<option><value>jabber:iq:oob</value></option>
</field'>
</x>
</feature>
</file>
</iq>
</example>
<example caption='Accept the Offered File with a Range and Offset'>
<iq type='result' id='ft_req_q' to='sender@jabber.org/res'>
<file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'>
<range offset='100' length='500' />
<x xmlns='jabber:x:data'>
<field var='file-transfer-method'>
<option><value>jobs</value></option>
</field>
</x>
</feature>
</file>
</iq>
</example>
<p>
If the receiver decides to not accept the file they SHOULD send back an
error 403 to the sender.
</p>
<example caption='Declining the Offered File'>
<iq type='error' id='ft_1' to='sender@jabber.org/res'>
<error code='403'>Offer Declined</error>
</iq>
</example>
<p>
If the receiver does not support any of the offered stream methods they
SHOULD send back an error 406 to the sender.
</p>
<example caption='No Acceptable Methods'>
<iq type='error' id='ft_1' to='sender@jabber.org/res'>
<error code='406'>No Acceptable Methods</error>
</iq>
</example>
<p>
At this point the sender will setup the stream method and begin to transfer
data. The stream itself can use the file transfer namespace to tie the
metadata to the actual data sent, this is illustrated below using iq:oob.
</p>
<example caption='Starting an iq:oob transfer'>
<iq type='set' id='ft_oob_1' to='recvr@jabber.org/Home'>
<file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='start'/>
<query xmlns='jabber:iq:oob'>
<url>http://www.jabber.org/file.txt</url>
<desc>Here is the file</desc>
</query>
</iq>
</example>
<p>
If the receiver is unable to start the negotiated stream for any reason they
should send an <error/> with a 502 code to the sender.
</p>
<example caption='Unable to Start Stream'>
<iq type='error' id='ft_oob_e_1' to='sender@jabber.org/res'>
<file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/>
<error code='502'>Unable to Start Stream</error>
</iq>
</example>
<p>
Once the data has been transferred the receiver SHOULD send the sender a
notification that the transfer completed. This is done by sending an
<iq/> type set with the file id and a completed action.
</p>
<example caption='Completed Transfer Notification'>
<iq type='set' id='ft_c_1' to='sender@jabber.org/res'>
<file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='complete' />
</iq>
</example>
<p>
If the transfer does not complete, for any reason after the metadata
negotiation, the party that has the error SHOULD send an error 500 and
the file id to the other party.
</p>
<example caption='Failed Transfer Error'>
<iq type='error' id='ft_1' to='sender@jabber.org/res'>
<error code='500'>File Transfer Failed</error>
<file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/>
</iq>
</example>
</section1>
<section1 topic='Stream Relation'>
<p>By staying in just the realm of negotiating the metadata to a file, we allow for multiple transport layers, or streams, to be used. Some streams will need to tie the metadata to the actual data transfer, to help accomodate this the stream may use the <file/> with an action of start and the correct id. The <file/> could be transported in the stream negotiations, or along side it. Although this spec does not mandate any specific methods to new stream authors, it does provide the syntax for the currently existing "iq:oob" system.</p>
<section2 topic='"iq:oob" Relation'>
<p>For an "iq:oob" transfer to be related to its metadata, a <file/> is transported along side the <query/>. The id used on the <file/> is the id for the metadata of the actual data that is being sent. The action on the <file/> is "start". An example of this can be found in the Basic Usage section.</p>
</section2>
</section1>
<section1 topic='Formal Description'>
<section2 topic='DTD'>
<code><![CDATA[
<!ELEMENT file ( ( desc )? | ( range )? | ( PCDATA )* ) >
<!ELEMENT desc ( #PCDATA )* >
<!ELEMENT range EMPTY >
<!ATTLIST file
id CDATA #REQUIRED
action "offer" | "get" | "complete" | "start" | "error" #IMPLIED "offer"
name CDATA #OPTIONAL
size CDATA #OPTIONAL >
mime-type CDATA #OPTIONAL
date CDATA #OPTIONAL
hash CDATA #OPTIONAL
<!ATTLIST range
length CDATA #OPTIONAL
offset CDATA #OPTIONAL >
]]></code>
</section2>
<section2 topic='<file/> Element'>
<p>The <file/> element is the "workhorse" element. This element is used to convey metadata and report file transfer actions. This elemnt contains attributes for file metadata and actions, and MAY contain a <desc/>, a <range/>, and zero or more <feature xmlns='jabber:iq:negotiate'/> (&xep0020;) elements.</p>
<p>The "id" attribute specifies the identifier for this particular file transfer. This attribute MUST be present at all times. There are no value requirements other than it MUST be unique between the sender and receiver.</p>
<p>The "action" attribute specifies the action to undertake with the given file. This attribute SHOULD be present in most cases. If not present, the value "offer" is implied. The value of "action" MUST be one of the following:</p>
<table caption='Possible "action" values'>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>complete</td>
<td>The file transfer is complete.</td>
</tr>
<tr>
<td>get</td>
<td>The file transfer should start.</td>
</tr>
<tr>
<td>offer</td>
<td>The file transfer is offered (metadata MUST be present)</td>
</tr>
<tr>
<td>start</td>
<td>The file transfer is starting.</td>
</tr>
<tr>
<td>error</td>
<td>The file transfer has failed. The outlying error tag has more
information.
</td>
</tr>
</table>
<p>The "name" attribute specifies the file name. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
<p>The "size" attribute specifies the file size, in bytes. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
<p>The "mime-type" attribute specifies the MIME-type for the file. This attribute SHOULD be present if the action is "offer", otherwise it SHOULD NOT be present. The value of this attribute MUST follow the specification for MIME-types from RFC-2046<note>RFC 2046: "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" -- <link url='http://www.ietf.org/rfc/rfc2046.txt'>http://www.ietf.org/rfc/rfc2046.txt</link></note>.</p>
<p>The "date" attribute specifies the file date. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST follow the specification for ISO 8601 date/time formats<note>ISO 8601: "[Summary of the] International Standard Date and Time Notation" -- <link url='http://www.cl.cam.ac.uk/~mgk25/iso-time.html'>http://www.cl.cam.ac.uk/~mgk25/iso-time.html</link></note>.</p>
<p>The "hash" attribute specifies the hash of the file contents. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST be an SHA1 hash of the file contents.</p>
</section2>
<section2 topic='<desc/> Element'>
<p>The <desc/> element contains a human-readable description of the file. This element has no attributes, and contains character data content.</p>
</section2>
<section2 topic='<range/> Element'>
<p>The <range/> element describes range information for a partial transfer. This element has attributes to define the range length and range offset. This element contains no content.</p>
<p>The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. The value of this attribute MUST be an integer value and MUST be less than or equal to the (size + offset) of the file.</p>
<p>The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. If this attribute is not present, a value of 0 is implied. The value of this attribute MUST be an integer, MUST NOT be less than 0, and MUST be less than (size - length).</p>
</section2>
<section2 topic='Error Descriptions'>
<p>There are three main error conditions in file transfer. Following are the
conditions, error codes and descriptions:</p>
<ul>
<li>
<em>Declining Transfer (403)</em>: During the metadata negotiation
the receiver may decline the transfer by sending the 403 error. The
<error/> CDATA MAY contain a descriptive reason why, but is not
necessary.
</li>
<li>
<em>No Available Methods (406)</em>: When the sender presents the
available stream methods, and the receiver can not use any of them,
they send a 406 error. The <error/> CDATA is not important.
</li>
<li>
<em>Transfer Failed (500)</em>: If the file transfer fails for any
reason after negotiation, the error generator SHOULD send a 500 error
to the other party. This is the only error message that both the
sender and reciever may send. The <error/> CDATA MAY contain
information about the failure.
</li>
<li>
<em>Unable to Start Stream (502)</em>: When the receiver is unable to
start the negotiated stream method they send a 502 error to the
sender. The <error/> CDATA is not important.
</li>
</ul>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>
Data integrity can be checked with the sha1 of the file that is sent. This
could be attacked via a man in the middle attack, but much more embarrasing
things could result from that than a bad file. The wire integrity is left
to the stream method.
</p>
</section1>
<section1 topic='IANA Considerations'>
<p>
The mime-type attribute on <file/> is a valid MIME type as controlled
by the IANA.
</p>
</section1>
<section1 topic='JANA Considerations'>
<p>
The "http://jabber.org/protocol/filexfer" is the only namespace that needs
to be registered with the JANA.
</p>
</section1>
</xep>