moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-22 07:38:52 -05:00
Code Issues Releases Wiki Activity

0.14rc1, awaiting hashes XEP

Browse Source
This commit is contained in:
stpeter 2011-06-23 12:55:42 -06:00
parent c42eadd8dd
commit 38096f09fd
1 changed files with 99 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
xep-0234.xml
View File

@ -24,6 +24,12 @@
<supersededby/> <supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname> <shortname>NOT_YET_ASSIGNED</shortname>
&stpeter; &stpeter;
<revision>
<version>0.14rc1</version>
<date>2011-06-23</date>
<initials>psa</initials>
<remark><p>Defined file description format separate from XEP-0096; modified the checksum format to reuse the &lt;hashes/&gt; element from XEP-0300; removed the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace by putting all elements into the 'urn:xmpp:jingle:apps:file-transfer:3' namespace; incremented namespace version from 2 to 3.</p></remark>
</revision>
<revision> <revision>
<version>0.13</version> <version>0.13</version>
<date>2011-06-01</date> <date>2011-06-01</date>
@ -143,8 +149,8 @@
<p>To overcome these drawbacks, this specification defines a file transfer negotiation method that meets the following requirements:</p> <p>To overcome these drawbacks, this specification defines a file transfer negotiation method that meets the following requirements:</p>
<ul> <ul>
<li>Use the session negotiation semantics from <cite>XEP-0166</cite>.</li> <li>Use the session negotiation semantics from <cite>XEP-0166</cite>.</li>
<li>Use the file description format from <cite>XEP-0096</cite>.</li>
<li>Use &xep0260; and &xep0261;.</li> <li>Use &xep0260; and &xep0261;.</li>
<li>Define a file description format that enables hash agility (unlike <cite>XEP-0096</cite>).</li>
<li>Define a clear upgrade path from SI File Transfer to Jingle File Transfer.</li> <li>Define a clear upgrade path from SI File Transfer to Jingle File Transfer.</li>
</ul> </ul>
<p>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.</p> <p>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.</p>
@ -156,13 +162,13 @@
<p>First, the party that wishes to initiate the file transfer determines the responder's capabilities (via &xep0030; or &xep0115;). Here we assume that the responder supports the following service discovery features:</p> <p>First, the party that wishes to initiate the file transfer determines the responder's capabilities (via &xep0030; or &xep0115;). Here we assume that the responder supports the following service discovery features:</p>
<ul> <ul>
<li>urn:xmpp:jingle:1 as described in <cite>XEP-0166</cite></li> <li>urn:xmpp:jingle:1 as described in <cite>XEP-0166</cite></li>
<li>urn:xmpp:jingle:apps:file-transfer:2 as defined in this document &NSVER;</li> <li>urn:xmpp:jingle:apps:file-transfer:3 as defined in this document &NSVER;</li>
<li>urn:xmpp:jingle:transports:s5b:1 as defined in <cite>XEP-0260</cite></li> <li>urn:xmpp:jingle:transports:s5b:1 as defined in <cite>XEP-0260</cite></li>
<li>urn:xmpp:jingle:transports:ibb:1 as defined in <cite>XEP-0261</cite></li> <li>urn:xmpp:jingle:transports:ibb:1 as defined in <cite>XEP-0261</cite></li>
</ul> </ul>
<p>The initiator then sends a Jingle session-initiation request to a potential responder. The content-type of the request specifies two things:</p> <p>The initiator then sends a Jingle session-initiation request to a potential responder. The content-type of the request specifies two things:</p>
<ol> <ol>
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:2". In particular, the &lt;description/&gt; element contains an &lt;offer/&gt; element or a &lt;request/&gt; element that in turn contains one or more &lt;file/&gt; elements qualified by the existing 'http://jabber.org/protocol/si/profile/file-transfer' namespace from <cite>XEP-0096</cite>.</li> <li>An application type of "urn:xmpp:jingle:apps:file-transfer:3". In particular, the &lt;description/&gt; element contains an &lt;offer/&gt; element or a &lt;request/&gt; element that in turn contains one or more &lt;file/&gt; elements defining a file to be sent.</li>
<li>An appropriate transport method. So far the suggested methods are jingle-s5b (<cite>XEP-0260</cite>) and, as a fallback, jingle-ibb (<cite>XEP-0261</cite>).</li> <li>An appropriate transport method. So far the suggested methods are jingle-s5b (<cite>XEP-0260</cite>) and, as a fallback, jingle-ibb (<cite>XEP-0261</cite>).</li>
</ol> </ol>
<p>Note: All attributes of the &lt;file/&gt; element are defined in <cite>XEP-0096</cite>, not in this specification.</p> <p>Note: All attributes of the &lt;file/&gt; element are defined in <cite>XEP-0096</cite>, not in this specification.</p>
@ -200,15 +206,17 @@ Initiator Responder
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='851ba2'> sid='851ba2'>
<content creator='initiator' name='a-file-offer'> <content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:2'> <description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<offer> <offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <file>
date='1969-07-21T02:56:15Z' <date>1969-07-21T02:56:15Z</date>
hash='552da749930852c69ae5d2141d3766b1'
name='test.txt'
size='1022'>
<desc>This is a test. If this were a real file...</desc> <desc>This is a test. If this were a real file...</desc>
<name>test.txt</name>
<range/> <range/>
<size>1022</size>
<hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
</hashes>
</file> </file>
</offer> </offer>
</description> </description>
@ -232,7 +240,7 @@ Initiator Responder
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
<p>Note: Inclusion of the &lt;range/&gt; child of the &lt;file/&gt; element indicates that the initiatior supports ranged transfers as described below under <link url='#range'>Ranged Transfers</link>.</p> <p>Note: As in <cite>XEP-0096</cite>, inclusion of the &lt;range/&gt; child of the &lt;file/&gt; element indicates that the initiatior 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, since the sending application needs to process the file twice. The sender might prefer to send the hash after the file transfer has begun, using a transport-info message as described under <link url='#hash'>Communicating the Hash</link>.</p> <p>Note: Computing the hash of the file before sending it can slow down the process of file transfer, since the sending application needs to process the file twice. The sender might prefer to send the hash after the file transfer has begun, using a transport-info message as described under <link url='#hash'>Communicating the Hash</link>.</p>
<p>The responder immediately acknowledges receipt of the Jingle session-initiate.</p> <p>The responder immediately acknowledges receipt of the Jingle session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[ <example caption="Responder acknowledges session-initiate"><![CDATA[
@ -252,15 +260,17 @@ Initiator Responder
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='851ba2'> sid='851ba2'>
<content creator='initiator' name='a-file-offer'> <content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:2'> <description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<offer> <offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <file>
name='test.txt' <date>1969-07-21T02:56:15Z</date>
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc> <desc>This is a test. If this were a real file...</desc>
<name>test.txt</name>
<range/> <range/>
<size>1022</size>
<hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
</hashes>
</file> </file>
</offer> </offer>
</description> </description>
@ -344,7 +354,7 @@ Initiator Responder
</section1> </section1>
<section1 topic='Communicating the Hash' anchor='hash'> <section1 topic='Communicating the Hash' anchor='hash'>
<p>At any time during the lifetime of the file transfer session, the hosting entity (i.e., the entity where the file resides) can communicate the hash of the file to the receiving entity. This is done by sending a session-info message containing a &lt;hash/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace. The XML character data of this &lt;hash/&gt; element has the same meaning as the 'hash' attribute of the &lt;file/&gt; element qualified by the 'http://jabber.org/protocol/si/profile/file-transfer' namespace from <cite>XEP-0096</cite>; that is, it is a checksum of the file contents produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;. For historical reasons and for backward-compatibility with <cite>XEP-0096</cite>, the 'algo' attribute defaults to a value of "md5".</p> <p>At any time during the lifetime of the file transfer session, the hosting entity (i.e., the entity where the file resides) can communicate the checksum of the file to the receiving entity. This is done by sending a session-info message containing a &lt;checksum/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:3' namespace, which in turn contains a &lt;file/&gt; element that MUST at least contain a child element of &lt;hashes/&gt; qualified by the 'urn:xmpp:hashes:0' namespace and MAY contain other elements qualified by the 'urn:xmpp:jingle:apps:file-transfer:3' namespace (e.g. &lt;name/&gt; and &lt;date/&gt;). Each &lt;hash/&gt; child of the &lt;hashes/&gt; element contains a checksum of the file contents 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="Hosting entity sends hash in session-info"><![CDATA[ <example caption="Hosting entity sends hash in session-info"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='romeo@montague.lit/orchard'
id='kqh401b5' id='kqh401b5'
@ -354,16 +364,20 @@ Initiator Responder
action='session-info' action='session-info'
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<hash xmlns='urn:xmpp:jingle:apps:file-transfer:info:2'> <checksum xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
552da749930852c69ae5d2141d3766b1 <file>
</hash> <hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
</hashes>
</file>
</checksum>
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
</section1> </section1>
<section1 topic='Requesting a File' anchor='request'> <section1 topic='Requesting a File' anchor='request'>
<p>If the entity that hosts a file has advertised its existence (or if a previous file transfer attempt has failed and the receiver would like to initiate another attempt), the entity that wishes to receive the file can "pull" the file from the hosting entity. This is done by sending a Jingle session-initiate to the hosting entity, including a &DESCRIPTION; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:2' namespace and containing a &lt;request/&gt; element that defines the requested file.</p> <p>If the entity that hosts a file has advertised its existence (or if a previous file transfer attempt has failed and the receiver would like to initiate another attempt), the entity that wishes to receive the file can "pull" the file from the hosting entity. This is done by sending a Jingle session-initiate to the hosting entity, including a &DESCRIPTION; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:3' namespace and containing a &lt;request/&gt; element that defines the requested file.</p>
<example caption="Receiver requests hosted file"><![CDATA[ <example caption="Receiver requests hosted file"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='wsn361c3' id='wsn361c3'
@ -374,10 +388,13 @@ Initiator Responder
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='uj3b2'> sid='uj3b2'>
<content creator='initiator' name='a-file-request'> <content creator='initiator' name='a-file-request'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:2'> <description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<request> <request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <file>
hash='552da749930852c69ae5d2141d3766b1'/> <hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
</hashes>
</file>
</request> </request>
</description> </description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1' <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -423,11 +440,13 @@ Initiator Responder
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='uj3b2'> sid='uj3b2'>
<content creator='initiator' name='a-file-request'> <content creator='initiator' name='a-file-request'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:2'> <description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<request> <request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <file>
hash='552da749930852c69ae5d2141d3766b1'>
<range offset='270336'/> <range offset='270336'/>
<hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
</hashes>
</file> </file>
</request> </request>
</description> </description>
@ -472,23 +491,32 @@ Initiator Responder
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='h2va419i'> sid='h2va419i'>
<content creator='initiator' name='a-file-offer'> <content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:2'> <description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<offer> <offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <file>
date='2011-06-01T15:58:15Z' <date>2011-06-01T15:58:15Z</date>
hash='a749930852c69ae5d2141d3766b1552d' <name>somefile.txt</name>
name='somefile.txt' <size>1234</size>
size='1234'/> <hashes xmlns='urn:xmpp:hashes:0'>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <hash algo='sha1'>a749930852c69ae5d2141d3766b1552d
date='2011-06-01T15:58:15Z' </hashes>
hash='930852c69ae5d2141d3766b1552da749' </file>
name='anotherfile.txt' <file>
size='2345'/> <date>2011-06-01T15:58:15Z</date>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <name>anotherfile.txt</name>
date='2011-06-01T15:58:15Z' <size>2345</size>
hash='52c69ae5d2141d3766b1552da7499308' <hashes xmlns='urn:xmpp:hashes:0'>
name='yetanotherfile.txt' <hash algo='sha1'>930852c69ae5d2141d3766b1552da749</hash>
size='3456'/> </hashes>
</file>
<file>
<date>2011-06-01T15:58:15Z</date>
<name>yetanotherfile.txt</name>
<size>3456</size>
<hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha1'>52c69ae5d2141d3766b1552da7499308</hash>
</hashes>
</file>
</offer> </offer>
</description> </description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1' <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -522,9 +550,11 @@ Initiator Responder
action='session-info' action='session-info'
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<received xmlns='urn:xmpp:jingle:apps:file-transfer:info:2'> <received xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <file>
hash='a749930852c69ae5d2141d3766b1552d'/> <hashes xmlns='urn:xmpp:hashes:0'>
<hash algo='sha-1'>a749930852c69ae5d2141d3766b1552d</hash>
</hashes>
</received> </received>
</jingle> </jingle>
</iq> </iq>
@ -612,7 +642,7 @@ Initiator Responder
<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> <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>
<section2 topic='Migration from XEP-0096' anchor='impl-migration'> <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:2' 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> <p>Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:jingle:apps:file-transfer:3' 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> </section2>
</section1> </section1>
@ -630,7 +660,7 @@ Initiator Responder
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p> <p>This specification defines the following XML namespace:</p>
<ul> <ul>
<li>urn:xmpp:jingle:apps:file-transfer:2</li> <li>urn:xmpp:jingle:apps:file-transfer:3</li>
</ul> </ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p> <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2> </section2>
@ -651,19 +681,16 @@ Initiator Responder
</section1> </section1>
<section1 topic='XML Schema' anchor='schema'> <section1 topic='XML Schema' anchor='schema'>
<section2 topic='File Transfer' anchor='schema-ft'>
<code><![CDATA[ <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>
<xs:schema <xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:apps:file-transfer:2' targetNamespace='urn:xmpp:jingle:apps:file-transfer:3'
xmlns='urn:xmpp:jingle:apps:file-transfer:2' xmlns='urn:xmpp:jingle:apps:file-transfer:3'
elementFormDefault='qualified'> elementFormDefault='qualified'>
<xs:import <xs:import namespace='urn:xmpp:hashes:0'/>
namespace='http://jabber.org/protocol/si/profile/file-transfer'
schemaLocation='http://www.xmpp.org/schemas/file-transfer.xsd'/>
<xs:element name='description'> <xs:element name='description'>
<xs:complexType> <xs:complexType>
@ -674,42 +701,33 @@ Initiator Responder
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:complexType name='fileTransferElementType'>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:schema>
]]></code>
</section2>
<section2 topic='File Transfer Info' anchor='schema-info'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:apps:file-transfer:info:2'
xmlns='urn:xmpp:jingle:apps:file-transfer:info:2'
elementFormDefault='qualified'>
<xs:element name='hash' type='xs:string'/>
<xs:element name='received' type='fileTransferElementType'/> <xs:element name='received' type='fileTransferElementType'/>
<xs:element name='checksum' type='fileTransferElementType'/>
<xs:complexType name='fileTransferElementType'> <xs:complexType name='fileTransferElementType'>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'> <xs:sequence>
<xs:element ref='ft:file'/> <xs:element name='file'/>
</xs:sequence> </xs:sequence>
</xs:complexType> </xs:complexType>
<xs:element name='file'>
<xs:complexType>
<xs:sequence xmlns:h='urn:xmpp:hashes:0'>
<xs:element name='date' type='xs:date'/>
<xs:element name='name' type='xs:string'/>
<xs:element name='size' type='xs:positiveInteger'/>
<xs:element ref='h:hashes'/>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section2>
</section1> </section1>
<section1 topic='Acknowledgements' anchor='ack'> <section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Diana Cionoiu, Olivier Crête, Justin Karneges, Steffen Larsen, Yann Leboulanger, Marcus Lundblad, Joe Maissel, Robert McQueen, Ali Sabil, Sjoerd Simons, Will Thompson, Matthew Wild, and Jiří Zárevúcky for their feedback.</p> <p>Thanks to Diana Cionoiu, Olivier Crête, Waqas Hussain, Justin Karneges, Steffen Larsen, Yann Leboulanger, Marcus Lundblad, Robert McQueen, Joe Maissel, Glenn Maynard, Ali Sabil, Sjoerd Simons, Will Thompson, Matthew Wild, and Jiří Zárevúcky for their feedback.</p>
</section1> </section1>
</xep> </xep>