moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-10 03:15:00 -05:00
Code Issues Releases Wiki Activity
d96c74981c
xeps/xep-0234.xml
Peter Saint-Andre 2e28fa6c36 0.2 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1765 4b5297f7-1745-476d-ba37-a9c6900126ab
2008-04-18 16:20:38 +00:00

485 lines
20 KiB
XML
Raw Blame History

<?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 files between two entities. 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>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0096</spec>
<spec>XEP-0166</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
&stpeter;
<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>Modified negotiation flow to use new content-replace action.</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-01-29</date>
<initials>psa</initials>
<remark>First draft.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0096; defines the current XMPP protocol extension for file transfer. However, that protocol has several drawbacks, most related to the &xep0095; protocol on which it depends:</p>
<ol>
<li>It does not enable a true, bidirectional negotiation; instead, the initiator sets the terms for the file transfer and the receiver either accepts the terms or cancels the negotiation.</li>
<li>It is the only technology in the Jabber/XMPP protocol "stack" that uses <cite>XEP-095: Stream Initiation</cite>. More modern technologies such as voice and video session negotiation use &xep0166;, and it would be helpful if implementors could use the same code for all negotiation use cases.</li>
</ol>
<p>To overcome these drawbacks, this specification defines a file transfer negotiation method that meets the following requirements:</p>
<ul>
<li>Reuse the session negotiation semantics from <cite>XEP-0166</cite>.</li>
<li>Reuse the file description format from <cite>XEP-0096</cite>.</li>
<li>Define a clear upgrade path from <cite>XEP-0096</cite> to this specification.</li>
</ul>
</section1>
<section1 topic='How It Works' anchor='protocol'>
<p>This section provides a friendly introduction to Jingle file transfer.</p>
<p>First, the party that wishes to initiate the file transfer determines the receiver's capabilities (via &xep0030; or &xep0115;). In this example, we assume that the receiver supports the following service discovery features (note: these features may not reflect final namespace assignments):</p>
<ul>
<li>urn:xmpp:tmp:jingle</li>
<li>urn:xmpp:tmp:jingle:apps:file-transfer</li>
<li>urn:xmpp:tmp:jingle:transports:bytestreams</li>
<li>urn:xmpp:tmp:jingle:transports:ibb</li>
</ul>
<p>The initiator then sends a Jingle session-initiation request to a potential receiver. The content-type of the request specifies two things:</p>
<ol>
<li>An application type of "urn:xmpp:tmp:jingle:apps:file-transfer" &NSNOTE;. In particular, the &lt;description/&gt; element contains an &lt;offer/&gt; or &lt;request/&gt; element that in turn contains a &lt;file/&gt; element qualified by the existing 'http://jabber.org/protocol/si/profile/file-transfer' namespace from <cite>XEP-0096</cite>.</li>
<li>An appropriate transport method. Because the existing transport methods used in <cite>XEP-0096</cite> (i.e., &xep0065; and &xep0047;) are not yet defined as Jingle transport methods, this specification registers those definitions.</li>
</ol>
<p>In this example, the initiation request specifies a file offer and a transport method of bytestreams (i.e., XEP-065).</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The parties would then attempt to negotiate use of the SOCKS5 Bytestreams transport method, as described in <cite>XEP-0065</cite>.</p>
<p>More detailed scenarios follow.</p>
</section1>
<section1 topic='Scenarios' anchor='scenarios'>
<section2 topic='Fallback' anchor='fallback'>
<p>Currently, <cite>XEP-0096</cite> does not enable the parties to fall back to a second method (e.g., In-Band Bytestreams) if the first method tried (e.g., SOCKS5 Bytestreams) does not work. This problem is addressed by Jingle. Consider the following protocol flow.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The receiver would then sends a session-accept.</p>
<example caption="Receiver sends session-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges the session-accept action.</p>
<example caption="Responder acknowledges session-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>Now the parties attempt to negotiate use of SOCKS5 Bytestreams as defined in <cite>XEP-0065</cite>.</p>
<p>However, let us imagine that the SOCKS5 Bytestreams negotiation fails. The initiator or responder can then suggest the use of In-Band Bytestreams by sending a content-replace action. Here we assume that the responder sends a content-replace action including a request for the file originally offered and a transport of IBB.</p>
<example caption="Responder requests content-replace"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='replace1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='content-replace'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='a-file-request'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
hash='552da749930852c69ae5d2141d3766b1'
name='test.txt'/>
</file>
</request>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator then acknowledges the content-replace action.</p>
<example caption="Initiator acknowledges content-replace"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='replace1'
to='laertes@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>If the content definition is acceptable, the initiator then sends a content-accept action to the responder.</p>
<example caption="Initiator sends content-accept"><![CDATA[
<iq to='kingclaudius@shakespeare.lit/castle'
id='accept2'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='content-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='a-file-request'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
hash='552da749930852c69ae5d2141d3766b1'
name='test.txt'/>
</file>
</request>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder then acknowledges the content-accept action.</p>
<example caption="Responder acknowledges content-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept2'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The parties then attempt to use In-Band Bytestreams.</p>
</section2>
<section2 topic='Transport Selection' anchor='select'>
<p><cite>XEP-0096</cite> enable the initiator to offer more than one transport and for the receiving party to choose its desired transport. This flow can be emulated in Jingle negotiation as follows.</p>
<example caption="Initiator sends session-initiate with multiple transports"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='first-transport'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
<content creator='initiator' name='second-transport'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The receiver then sends a content-remove in order to choose the desired transport, which in this case is IBB.</p>
<example caption="Receiver sends content-remove"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='remove1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='content-remove'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='first-transport'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges the content-remove action.</p>
<example caption="Responder acknowledges content-remove"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='remove1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The receiver then sends a session-accept.</p>
<example caption="Receiver sends session-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges the session-accept action.</p>
<example caption="Responder acknowledges session-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>Now the initiator sends the file using In-Band Bytestreams as defined in <cite>XEP-0047</cite>.</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Mandatory to Implement Technologies' anchor='impl-mti'>
<p>All implementations MUST support the In-Band Bytestreams transport method.</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 In-Band Bytestreams 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:tmp:jingle:apps:file-transfer' namespace &NSNOTE;, via either service discovery or entity capabilities. If the initiator knows that the receiver supports Jingle file transfer, it SHOULD attempt negotiation using XEP-0166 rather than XEP-0095.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method being used. For details, refer to the specifications for those transport methods.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>No interaction with &IANA; is required as a result of this document.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>Until this specification advances to a status of Draft, its associated namespaces shall be:</p>
<ul>
<li>urn:xmpp:tmp:jingle:apps:file-transfer</li>
</ul>
<p>Upon advancement of this specification, the &REGISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
<p>The following namespaces are requested, and are thought to be unique per the XMPP Registrar's requirements:</p>
<ul>
<li>urn:xmpp:jingle:apps:file-transfer</li>
</ul>
</section2>
<section2 topic='Jingle Application Formats' anchor='registrar-content'>
<p>The XMPP Registrar shall include "file-transfer" in its registry of Jingle application formats. The registry submission is as follows:</p>
<code><![CDATA[
<application>
<name>file-transfer</name>
<desc>Jingle sessions for the transfer of a file</desc>
<transport>reliable</transport>
<doc>XEP-xxxx</doc>
</application>
]]></code>
</section2>
<section2 topic='Jingle Transport Methods' anchor='registrar-transports'>
<p>The XMPP Registrar shall add to its registry of Jingle transport methods definitions for the reliable transport methods defined in <cite>XEP-0047</cite> and <cite>XEP-0065</cite>. The registry submissions are as follows:</p>
<code><![CDATA[
<transport>
<name>bytestreams</name>
<desc>A method for exchanging data over SOCKS5 Bytestreams.</desc>
<type>reliable</type>
<doc>XEP-0065</doc>
</transport>
<transport>
<name>ibb</name>
<desc>A method for exchanging data over In-Band Bytestreams.</desc>
<type>reliable</type>
<doc>XEP-0047</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:tmp:jingle:apps:file-transfer'
xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'
elementFormDefault='qualified'>
<xs:import
namespace='http://jabber.org/protocol/si/profile/file-transfer'
schemaLocation='http://www.xmpp.org/schemas/file-transfer.xsd'/>
<xs:element name='description'>
<xs:complexType>
<xs:choice>
<xs:element ref='offer'/>
<xs:element ref='request'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='offer'>
<xs:complexType>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='request'>
<xs:complexType>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>
Reference in New Issue View Git Blame Copy Permalink