mirror of https://github.com/moparisthebest/xeps
0.14rc1, awaiting hashes XEP
This commit is contained in:
stpeter
parent
c42eadd8dd
commit
38096f09fd
180
xep-0234.xml
180
xep-0234.xml
|
|
@ -24,6 +24,12 @@
|
|||
<supersededby/>
|
||||
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||
&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 <hashes/> 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>
|
||||
<version>0.13</version>
|
||||
<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>
|
||||
<ul>
|
||||
<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>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>
|
||||
</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>
|
||||
|
|
@ -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>
|
||||
<ul>
|
||||
<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:ibb:1 as defined in <cite>XEP-0261</cite></li>
|
||||
</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>
|
||||
<ol>
|
||||
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:2". In particular, the <description/> element contains an <offer/> element or a <request/> element that in turn contains one or more <file/> 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 <description/> element contains an <offer/> element or a <request/> element that in turn contains one or more <file/> 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>
|
||||
</ol>
|
||||
<p>Note: All attributes of the <file/> element are defined in <cite>XEP-0096</cite>, not in this specification.</p>
|
||||
|
|
@ -200,15 +206,17 @@ Initiator Responder
|
|||
initiator='romeo@montague.lit/orchard'
|
||||
sid='851ba2'>
|
||||
<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>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
date='1969-07-21T02:56:15Z'
|
||||
hash='552da749930852c69ae5d2141d3766b1'
|
||||
name='test.txt'
|
||||
size='1022'>
|
||||
<file>
|
||||
<date>1969-07-21T02:56:15Z</date>
|
||||
<desc>This is a test. If this were a real file...</desc>
|
||||
<name>test.txt</name>
|
||||
<range/>
|
||||
<size>1022</size>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
|
||||
</hashes>
|
||||
</file>
|
||||
</offer>
|
||||
</description>
|
||||
|
|
@ -232,7 +240,7 @@ Initiator Responder
|
|||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: Inclusion of the <range/> child of the <file/> 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 <range/> child of the <file/> 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>The responder immediately acknowledges receipt of the Jingle session-initiate.</p>
|
||||
<example caption="Responder acknowledges session-initiate"><![CDATA[
|
||||
|
|
@ -252,15 +260,17 @@ Initiator Responder
|
|||
initiator='romeo@montague.lit/orchard'
|
||||
sid='851ba2'>
|
||||
<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>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
name='test.txt'
|
||||
size='1022'
|
||||
hash='552da749930852c69ae5d2141d3766b1'
|
||||
date='1969-07-21T02:56:15Z'>
|
||||
<file>
|
||||
<date>1969-07-21T02:56:15Z</date>
|
||||
<desc>This is a test. If this were a real file...</desc>
|
||||
<name>test.txt</name>
|
||||
<range/>
|
||||
<size>1022</size>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
|
||||
</hashes>
|
||||
</file>
|
||||
</offer>
|
||||
</description>
|
||||
|
|
@ -344,7 +354,7 @@ Initiator Responder
|
|||
</section1>
|
||||
|
||||
<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 <hash/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace. The XML character data of this <hash/> element has the same meaning as the 'hash' attribute of the <file/> 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 <checksum/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:3' namespace, which in turn contains a <file/> element that MUST at least contain a child element of <hashes/> 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. <name/> and <date/>). Each <hash/> child of the <hashes/> 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[
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='kqh401b5'
|
||||
|
|
@ -354,16 +364,20 @@ Initiator Responder
|
|||
action='session-info'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<hash xmlns='urn:xmpp:jingle:apps:file-transfer:info:2'>
|
||||
552da749930852c69ae5d2141d3766b1
|
||||
</hash>
|
||||
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
|
||||
<file>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
|
||||
</hashes>
|
||||
</file>
|
||||
</checksum>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
</section1>
|
||||
|
||||
<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 <request/> 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 <request/> element that defines the requested file.</p>
|
||||
<example caption="Receiver requests hosted file"><![CDATA[
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='wsn361c3'
|
||||
|
|
@ -374,10 +388,13 @@ Initiator Responder
|
|||
initiator='romeo@montague.lit/orchard'
|
||||
sid='uj3b2'>
|
||||
<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>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
hash='552da749930852c69ae5d2141d3766b1'/>
|
||||
<file>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
|
||||
</hashes>
|
||||
</file>
|
||||
</request>
|
||||
</description>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
|
||||
|
|
@ -423,11 +440,13 @@ Initiator Responder
|
|||
initiator='romeo@montague.lit/orchard'
|
||||
sid='uj3b2'>
|
||||
<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>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
hash='552da749930852c69ae5d2141d3766b1'>
|
||||
<file>
|
||||
<range offset='270336'/>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
|
||||
</hashes>
|
||||
</file>
|
||||
</request>
|
||||
</description>
|
||||
|
|
@ -472,23 +491,32 @@ Initiator Responder
|
|||
initiator='romeo@montague.lit/orchard'
|
||||
sid='h2va419i'>
|
||||
<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>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
date='2011-06-01T15:58:15Z'
|
||||
hash='a749930852c69ae5d2141d3766b1552d'
|
||||
name='somefile.txt'
|
||||
size='1234'/>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
date='2011-06-01T15:58:15Z'
|
||||
hash='930852c69ae5d2141d3766b1552da749'
|
||||
name='anotherfile.txt'
|
||||
size='2345'/>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
date='2011-06-01T15:58:15Z'
|
||||
hash='52c69ae5d2141d3766b1552da7499308'
|
||||
name='yetanotherfile.txt'
|
||||
size='3456'/>
|
||||
<file>
|
||||
<date>2011-06-01T15:58:15Z</date>
|
||||
<name>somefile.txt</name>
|
||||
<size>1234</size>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha1'>a749930852c69ae5d2141d3766b1552d
|
||||
</hashes>
|
||||
</file>
|
||||
<file>
|
||||
<date>2011-06-01T15:58:15Z</date>
|
||||
<name>anotherfile.txt</name>
|
||||
<size>2345</size>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha1'>930852c69ae5d2141d3766b1552da749</hash>
|
||||
</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>
|
||||
</description>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
|
||||
|
|
@ -522,9 +550,11 @@ Initiator Responder
|
|||
action='session-info'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<received xmlns='urn:xmpp:jingle:apps:file-transfer:info:2'>
|
||||
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
hash='a749930852c69ae5d2141d3766b1552d'/>
|
||||
<received xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
|
||||
<file>
|
||||
<hashes xmlns='urn:xmpp:hashes:0'>
|
||||
<hash algo='sha-1'>a749930852c69ae5d2141d3766b1552d</hash>
|
||||
</hashes>
|
||||
</received>
|
||||
</jingle>
|
||||
</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>
|
||||
</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: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>
|
||||
</section1>
|
||||
|
||||
|
|
@ -630,7 +660,7 @@ Initiator Responder
|
|||
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
|
||||
<p>This specification defines the following XML namespace:</p>
|
||||
<ul>
|
||||
<li>urn:xmpp:jingle:apps:file-transfer:2</li>
|
||||
<li>urn:xmpp:jingle:apps:file-transfer:3</li>
|
||||
</ul>
|
||||
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
|
||||
</section2>
|
||||
|
|
@ -651,19 +681,16 @@ Initiator Responder
|
|||
</section1>
|
||||
|
||||
<section1 topic='XML Schema' anchor='schema'>
|
||||
<section2 topic='File Transfer' anchor='schema-ft'>
|
||||
<code><![CDATA[
|
||||
<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:2'
|
||||
xmlns='urn:xmpp:jingle:apps:file-transfer:2'
|
||||
targetNamespace='urn:xmpp:jingle:apps:file-transfer:3'
|
||||
xmlns='urn:xmpp:jingle:apps:file-transfer:3'
|
||||
elementFormDefault='qualified'>
|
||||
|
||||
<xs:import
|
||||
namespace='http://jabber.org/protocol/si/profile/file-transfer'
|
||||
schemaLocation='http://www.xmpp.org/schemas/file-transfer.xsd'/>
|
||||
<xs:import namespace='urn:xmpp:hashes:0'/>
|
||||
|
||||
<xs:element name='description'>
|
||||
<xs:complexType>
|
||||
|
|
@ -674,42 +701,33 @@ Initiator Responder
|
|||
</xs:complexType>
|
||||
</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='checksum' type='fileTransferElementType'/>
|
||||
|
||||
<xs:complexType name='fileTransferElementType'>
|
||||
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
|
||||
<xs:element ref='ft:file'/>
|
||||
<xs:sequence>
|
||||
<xs:element name='file'/>
|
||||
</xs:sequence>
|
||||
</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>
|
||||
]]></code>
|
||||
</section2>
|
||||
]]></code>
|
||||
</section1>
|
||||
|
||||
<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>
|
||||
|
||||
</xep>
|
||||
|
|
|
|||
Loading…
Reference in New Issue