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-0052.xml 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394
  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>File Transfer</title>
  10. <abstract>A protocol for transferring a file between two Jabber IDs.</abstract>
  11. &LEGALNOTICE;
  12. <number>0052</number>
  13. <status>Retracted</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies>
  17. <spec>XMPP Core</spec>
  18. <spec>XMPP IM</spec>
  19. <spec>XEP-0004</spec>
  20. <spec>XEP-0020</spec>
  21. <spec>XEP-0030</spec>
  22. </dependencies>
  23. <supersedes/>
  24. <supersededby>
  25. <spec>XEP-0095</spec>
  26. <spec>XEP-0096</spec>
  27. </supersededby>
  28. <shortname>N/A</shortname>
  29. <author>
  30. <firstname>Thomas</firstname>
  31. <surname>Muldowney</surname>
  32. <email>temas@box5.net</email>
  33. <jid>temas@jabber.org</jid>
  34. </author>
  35. <author>
  36. <firstname>Matthew</firstname>
  37. <surname>Miller</surname>
  38. <email>linuxwolf@outer-planes.net</email>
  39. <jid>linuxwolf@outer-planes.net</jid>
  40. </author>
  41. <author>
  42. <firstname>Justin</firstname>
  43. <surname>Karneges</surname>
  44. <email>justin@affinix.com</email>
  45. <jid>justin@andbit.net</jid>
  46. </author>
  47. <revision>
  48. <version>0.2</version>
  49. <date>2003-09-30</date>
  50. <initials>psa</initials>
  51. <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>
  52. </revision>
  53. <revision>
  54. <version>0.1</version>
  55. <date>2002-12-03</date>
  56. <initials>tjm</initials>
  57. <remark>Initial version, based on original XEP-0052 revision 0.1.</remark>
  58. </revision>
  59. </header>
  60. <section1 topic='Introduction'>
  61. <p>
  62. This document describes the http://www.jabber.org/protocol/filexfer
  63. namespace, which is used for offering and transferring files from one Jabber
  64. ID to another. It tries to expand the basic method (iq:oob) that currently
  65. exists to allow for numerous stream methods, and more detailed file
  66. information before accepting an offer. This document only describes the
  67. negotiation method and suggests how streams could link back to the
  68. negotiated information.
  69. </p>
  70. </section1>
  71. <section1 topic='Use Cases'>
  72. <p>
  73. This document covers one use case of sending a file to another user. Future specifications
  74. may enhance this to include searching and offering.
  75. </p>
  76. <section2 topic='Send File Use Case'>
  77. <p>Primary Flow:</p>
  78. <ol>
  79. <li>Determine if the receiver supports FT through disco/browse. [E1]</li>
  80. <li>Sender sends meta-data and available methods to receiver</li>
  81. <li>Receiver sends the accepted method to Sender and any range/offset
  82. information. [E2],[E3]</li>
  83. <li>Sender and Receiver establish the negotiated method[E4]</li>
  84. <li>Sender sends data as described by method</li>
  85. <li>After the stream closes the Receiver notifies the Sender of
  86. completion. [E5]</li>
  87. <li>END</li>
  88. </ol>
  89. <p>Errors Conditions:</p>
  90. <ol>
  91. <li>User does not support filetransfer. END</li>
  92. <li>Receiver rejects send. END</li>
  93. <li>Receiver does not have any methods shared with the sender. END</li>
  94. <li>The stream is unable to be started. END</li>
  95. <li>The Receiver notifies sender of an error transferring. END</li>
  96. </ol>
  97. </section2>
  98. </section1>
  99. <section1 topic='Basic Usage'>
  100. <p>
  101. In order to send a file, the sender must first tell the receiver a little
  102. bit about the file to make sure they will accept it. At the same time they
  103. list the stream methods they support in the order they wish to use them.
  104. This is done by sending the information in the http://www.jabber.org/protocol/filexfer namespace.
  105. </p>
  106. <example caption='Generic Offer'>
  107. &lt;iq type='set' id='ft_1' to='recvr@jabber.org/Home'&gt;
  108. &lt;file xmlns='http://www.jabber.org/protocol/filexfer'
  109. action='offer'
  110. id='a0'
  111. name='myfile.txt'
  112. size='1024'
  113. mime-type='text/plain'&gt;
  114. &lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
  115. &lt;x xmlns='jabber:x:data'&gt;
  116. &lt;field var='file-transfer-method' type='list-single'&gt;
  117. &lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
  118. &lt;/field&gt;
  119. &lt;/x&gt;
  120. &lt;/feature&gt;
  121. &lt;/file&gt;
  122. &lt;/iq&gt;
  123. </example>
  124. <p>
  125. That is the basic request, a more complete requeset with range support is
  126. shown below.
  127. </p>
  128. <example caption='Complete File Offer'>
  129. &lt;iq type='set' id='ft_1' to='recvr@jabber.org/Home'&gt;
  130. &lt;file xmlns='http://www.jabber.org/protocol/filexfer'
  131. action='offer'
  132. id='a0'
  133. name='myfile.txt'
  134. size='1024'
  135. mime-type='text/plain'
  136. date='20020412T00:00:00'
  137. hash='23e4ad6b63343b33a333c334'&gt;
  138. &lt;desc&gt;A cool file&lt;/desc&gt;
  139. &lt;range/&gt;
  140. &lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
  141. &lt;x xmlns='jabber:x:data'&gt;
  142. &lt;field var='file-transfer-method' type='list-single'&gt;
  143. &lt;option&gt;&lt;value&gt;jobs&lt;/value&gt;&lt;/option&gt;
  144. &lt;option&gt;&lt;value&gt;dtcp&lt;/value&gt;&lt;/option&gt;
  145. &lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
  146. &lt;option&gt;&lt;value&gt;ibb&lt;/value&gt;&lt;/option&gt;
  147. &lt;/field&gt;
  148. &lt;/x&gt;
  149. &lt;/feature&gt;
  150. &lt;/file&gt;
  151. &lt;/iq&gt;
  152. </example>
  153. <p>If a receiver decides to accept an offered file they request it from the sending with an &lt;iq/&gt; 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>
  154. <example caption='Request the Offered File'>
  155. &lt;iq type='result' id='ft_req_1' to='sender@jabber.org/res'&gt;
  156. &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'&gt;
  157. &lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
  158. &lt;x xmlns='jabber:x:data'&gt;
  159. &lt;field var='file-transfer-method'&gt;
  160. &lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
  161. &lt;/field'&gt;
  162. &lt;/x&gt;
  163. &lt;/feature&gt;
  164. &lt;/file&gt;
  165. &lt;/iq&gt;
  166. </example>
  167. <example caption='Accept the Offered File with a Range and Offset'>
  168. &lt;iq type='result' id='ft_req_q' to='sender@jabber.org/res'&gt;
  169. &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'&gt;
  170. &lt;range offset='100' length='500' /&gt;
  171. &lt;x xmlns='jabber:x:data'&gt;
  172. &lt;field var='file-transfer-method'&gt;
  173. &lt;option&gt;&lt;value&gt;jobs&lt;/value&gt;&lt;/option&gt;
  174. &lt;/field&gt;
  175. &lt;/x&gt;
  176. &lt;/feature&gt;
  177. &lt;/file&gt;
  178. &lt;/iq&gt;
  179. </example>
  180. <p>
  181. If the receiver decides to not accept the file they SHOULD send back an
  182. error 403 to the sender.
  183. </p>
  184. <example caption='Declining the Offered File'>
  185. &lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
  186. &lt;error code='403'&gt;Offer Declined&lt;/error&gt;
  187. &lt;/iq&gt;
  188. </example>
  189. <p>
  190. If the receiver does not support any of the offered stream methods they
  191. SHOULD send back an error 406 to the sender.
  192. </p>
  193. <example caption='No Acceptable Methods'>
  194. &lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
  195. &lt;error code='406'&gt;No Acceptable Methods&lt;/error&gt;
  196. &lt;/iq&gt;
  197. </example>
  198. <p>
  199. At this point the sender will setup the stream method and begin to transfer
  200. data. The stream itself can use the file transfer namespace to tie the
  201. meta-data to the actual data sent, this is illustrated below using iq:oob.
  202. </p>
  203. <example caption='Starting an iq:oob transfer'>
  204. &lt;iq type='set' id='ft_oob_1' to='recvr@jabber.org/Home'&gt;
  205. &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='start'/&gt;
  206. &lt;query xmlns='jabber:iq:oob'&gt;
  207. &lt;url&gt;http://www.jabber.org/file.txt&lt;/url&gt;
  208. &lt;desc&gt;Here is the file&lt;/desc&gt;
  209. &lt;/query&gt;
  210. &lt;/iq&gt;
  211. </example>
  212. <p>
  213. If the receiver is unable to start the negotiated stream for any reason they
  214. should send an &lt;error/&gt; with a 502 code to the sender.
  215. </p>
  216. <example caption='Unable to Start Stream'>
  217. &lt;iq type='error' id='ft_oob_e_1' to='sender@jabber.org/res'&gt;
  218. &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/&gt;
  219. &lt;error code='502'&gt;Unable to Start Stream&lt;/error&gt;
  220. &lt;/iq&gt;
  221. </example>
  222. <p>
  223. Once the data has been transferred the receiver SHOULD send the sender a
  224. notification that the transfer completed. This is done by sending an
  225. &lt;iq/&gt; type set with the file id and a completed action.
  226. </p>
  227. <example caption='Completed Transfer Notification'>
  228. &lt;iq type='set' id='ft_c_1' to='sender@jabber.org/res'&gt;
  229. &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='complete' /&gt;
  230. &lt;/iq&gt;
  231. </example>
  232. <p>
  233. If the transfer does not complete, for any reason after the meta-data
  234. negotiation, the party that has the error SHOULD send an error 500 and
  235. the file id to the other party.
  236. </p>
  237. <example caption='Failed Transfer Error'>
  238. &lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
  239. &lt;error code='500'&gt;File Transfer Failed&lt;/error&gt;
  240. &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/&gt;
  241. &lt;/iq&gt;
  242. </example>
  243. </section1>
  244. <section1 topic='Stream Relation'>
  245. <p>By staying in just the realm of negotiating the meta-data to a file, we allow for multiple transport layers, or streams, to be used. Some streams will need to tie the meta-data to the actual data transfer, to help accomodate this the stream may use the &lt;file/&gt; with an action of start and the correct id. The &lt;file/&gt; 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>
  246. <section2 topic='"iq:oob" Relation'>
  247. <p>For an "iq:oob" transfer to be related to it's meta-data, a &lt;file/&gt; is transported along side the &lt;query/&gt;. The id used on the &lt;file/&gt; is the id for the meta-data of the actual data that is being sent. The action on the &lt;file/&gt; is "start". An example of this can be found in the Basic Usage section.</p>
  248. </section2>
  249. </section1>
  250. <section1 topic='Formal Description'>
  251. <section2 topic='DTD'>
  252. <code><![CDATA[
  253. <!ELEMENT file ( ( desc )? | ( range )? | ( PCDATA )* ) >
  254. <!ELEMENT desc ( #PCDATA )* >
  255. <!ELEMENT range EMPTY >
  256. <!ATTLIST file
  257. id CDATA #REQUIRED
  258. action "offer" | "get" | "complete" | "start" | "error" #IMPLIED "offer"
  259. name CDATA #OPTIONAL
  260. size CDATA #OPTIONAL >
  261. mime-type CDATA #OPTIONAL
  262. date CDATA #OPTIONAL
  263. hash CDATA #OPTIONAL
  264. <!ATTLIST range
  265. length CDATA #OPTIONAL
  266. offset CDATA #OPTIONAL >
  267. ]]></code>
  268. </section2>
  269. <section2 topic='&lt;file/&gt; Element'>
  270. <p>The &lt;file/&gt; element is the "workhorse" element. This element is used to convey meta-data and report file transfer actions. This elemnt contains attributes for file meta-data and actions, and MAY contain a &lt;desc/&gt;, a &lt;range/&gt;, and zero or more &lt;feature xmlns='jabber:iq:negotiate'/&gt; (&xep0020;) elements.</p>
  271. <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>
  272. <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>
  273. <table caption='Possible "action" values'>
  274. <tr>
  275. <th>Value</th>
  276. <th>Description</th>
  277. </tr>
  278. <tr>
  279. <td>complete</td>
  280. <td>The file transfer is complete.</td>
  281. </tr>
  282. <tr>
  283. <td>get</td>
  284. <td>The file transfer should start.</td>
  285. </tr>
  286. <tr>
  287. <td>offer</td>
  288. <td>The file transfer is offered (meta-data MUST be present)</td>
  289. </tr>
  290. <tr>
  291. <td>start</td>
  292. <td>The file transfer is starting.</td>
  293. </tr>
  294. <tr>
  295. <td>error</td>
  296. <td>The file transfer has failed. The outlying error tag has more
  297. information.
  298. </td>
  299. </tr>
  300. </table>
  301. <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>
  302. <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>
  303. <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>
  304. <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>
  305. <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>
  306. </section2>
  307. <section2 topic='&lt;desc/&gt; Element'>
  308. <p>The &lt;desc/&gt; element contains a human-readable description of the file. This element has no attributes, and contains character data content.</p>
  309. </section2>
  310. <section2 topic='&lt;range/&gt; Element'>
  311. <p>The &lt;range/&gt; 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>
  312. <p>The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing &lt;file/&gt; 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>
  313. <p>The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing &lt;file/&gt; 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>
  314. </section2>
  315. <section2 topic='Error Descriptions'>
  316. <p>There are three main error conditions in file transfer. Following are the
  317. conditions, error codes and descriptions:</p>
  318. <ul>
  319. <li>
  320. <em>Declining Transfer (403)</em>: During the meta-data negotiation
  321. the receiver may decline the transfer by sending the 403 error. The
  322. &lt;error/&gt; CDATA MAY contain a descriptive reason why, but is not
  323. necessary.
  324. </li>
  325. <li>
  326. <em>No Available Methods (406)</em>: When the sender presents the
  327. available stream methods, and the receiver can not use any of them,
  328. they send a 406 error. The &lt;error/&gt; CDATA is not important.
  329. </li>
  330. <li>
  331. <em>Transfer Failed (500)</em>: If the file transfer fails for any
  332. reason after negotiation, the error generator SHOULD send a 500 error
  333. to the other party. This is the only error message that both the
  334. sender and reciever may send. The &lt;error/&gt; CDATA MAY contain
  335. information about the failure.
  336. </li>
  337. <li>
  338. <em>Unable to Start Stream (502)</em>: When the receiver is unable to
  339. start the negotiated stream method they send a 502 error to the
  340. sender. The &lt;error/&gt; CDATA is not important.
  341. </li>
  342. </ul>
  343. </section2>
  344. </section1>
  345. <section1 topic='Security Considerations'>
  346. <p>
  347. Data integrity can be checked with the sha1 of the file that is sent. This
  348. could be attacked via a man in the middle attack, but much more embarrasing
  349. things could result from that than a bad file. The wire integrity is left
  350. to the stream method.
  351. </p>
  352. </section1>
  353. <section1 topic='IANA Considerations'>
  354. <p>
  355. The mime-type attribute on &lt;file/&gt; is a valid MIME type as controlled
  356. by the IANA.
  357. </p>
  358. </section1>
  359. <section1 topic='JANA Considerations'>
  360. <p>
  361. The "http://jabber.org/protocol/filexfer" is the only namespace that needs
  362. to be registered with the JANA.
  363. </p>
  364. </section1>
  365. </xep>