XEP-0234 Update to new version of XEP-0300

This commit is contained in:
Lance Stout 2017-01-30 11:06:57 -08:00 committed by Sam Whited
parent 3849f03db4
commit ac1582ecc6
1 changed files with 60 additions and 48 deletions

View File

@ -24,6 +24,18 @@
<shortname>NOT_YET_ASSIGNED</shortname>
&stpeter;
&lance;
<revision>
<version>0.18.0</version>
<date>2017-01-30</date>
<initials>ls</initials>
<remark>
<ul>
<li>Update dependency on XEP-0300 to require the 'urn:xmpp:hashes:2' namespace that mandates base64 encoding.</li>
<li>Clarify that a &lt;range/&gt; element with a limit or offset value in a 'session-accept' should be honored by the file sender.</li>
<li>Namespace version bumped to ':5'.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.17.2</version>
<date>2016-07-15</date>
@ -300,16 +312,16 @@
<section1 topic='Application Format'>
<p>A Jingle File Transfer session is described by a content type that contains one application format and one transport method. Each &CONTENT; element defines the details of a single file transfer. A Jingle negotiation MAY result in the establishment of multiple file transfers by including multiple &CONTENT; elements.</p>
<p>The application format consists of a file description contained within a &DESCRIPTION; element qualified by the "urn:xmpp:jingle:apps:file-transfer:4" namespace &VNOTE;. The file description is a &lt;file/&gt; element specifying metadata such as the name of the file, media type, etc., as illustrated in the following example.</p>
<p>The application format consists of a file description contained within a &DESCRIPTION; element qualified by the "urn:xmpp:jingle:apps:file-transfer:5" namespace &VNOTE;. The file description is a &lt;file/&gt; element specifying metadata such as the name of the file, media type, etc., as illustrated in the following example.</p>
<code><![CDATA[
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<media-type>text/plain</media-type>
<name>test.txt</name>
<date>2015-07-26T21:46:00</date>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>]]></code>
<p>The &DESCRIPTION; element is intended to be a child of a Jingle &CONTENT; element as specified in <cite>XEP-0166</cite>.</p>
@ -332,7 +344,7 @@
</tr>
<tr>
<td>hash</td>
<td>A hash of the file content, using the &lt;hash/&gt; element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:1' namespace. Multiple hashes MAY be included for hash agility.</td>
<td>A hash of the file content, using the &lt;hash/&gt; element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:2' namespace. Multiple hashes MAY be included for hash agility.</td>
<td>REQUIRED when offering a file, otherwise OPTIONAL</td>
</tr>
<tr>
@ -404,7 +416,7 @@ Initiator Responder
<p>To start a File Offer, the initiator sends a Jingle session-initiation request to a potential responder. The request specifies three things:</p>
<ol>
<li>A content 'senders' attribute with the value of 'initiator' to indicate this is a File Offer.</li>
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:4". In particular, the &lt;description/&gt; element contains a &lt;file/&gt; elements describing the file to be sent.</li>
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:5". In particular, the &lt;description/&gt; element contains a &lt;file/&gt; elements describing the file to be sent.</li>
<li>An appropriate transport method.</li>
</ol>
<p>In this example, the initiator is &lt;romeo@montague.example&gt;, the responder is &lt;juliet@capulet.example&gt;, the application type is a File Offer, and the transport method is jingle-s5b (XEP-0260).</p>
@ -420,7 +432,7 @@ Initiator Responder
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
@ -428,8 +440,8 @@ Initiator Responder
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -459,7 +471,7 @@ Initiator Responder
id='nzu25s8'
to='romeo@montague.example/dr4hcr0st3lup4c'
type='result'/>]]></example>
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in <cite>XEP-0260</cite> and <cite>XEP-0065</cite>. In the meantime, the responder returns a Jingle session-accept. In the session-accept message, the &lt;file/&gt; element MAY contain a &lt;range/&gt; element to indicate that the receiver also supports ranged transfers as described below under <link url='#range'>Ranged Transfers</link>.</p>
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in <cite>XEP-0260</cite> and <cite>XEP-0065</cite>. In the meantime, the responder returns a Jingle session-accept. In the session-accept message, the &lt;file/&gt; element MAY contain a &lt;range/&gt; element to indicate that the receiver also supports ranged transfers as described below under <link url='#range'>Ranged Transfers</link>. If the responder includes a &lt;range /&gt; element with a limit or offset, the File Sender SHOULD respect the provided range settings.</p>
<example caption="Responder sends session-accept"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jn2vs71g'
@ -470,7 +482,7 @@ Initiator Responder
responder='juliet@capulet.example/yn0cl4bnw0yr3vym'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
@ -478,8 +490,8 @@ Initiator Responder
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -516,7 +528,7 @@ Initiator Responder
</section2>
<section2 topic='Requesting a File' anchor='requesting'>
<p>If the File Sender has advertised the existence of a file that it hosts, such as by &xep0358;, or if a previous file transfer attempt has failed and the File Receiver would like to initiate another attempt, the File Receiver can "pull" the file from the File Sender. This is done by sending a Jingle session-initiate to the File Sender which includes a &lt;content/&gt; with the 'senders' attribute set to the opposite Jingle session role of the party requesting the file (see <link url='#content-senders'>Use of Jingle Content Senders</link>) and a &lt;description/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:4' namespace and which includes a &lt;file/&gt; element with enough information included to form a "file selector" (see Section 5 of &rfc5547;) to identify the requested file.</p>
<p>If the File Sender has advertised the existence of a file that it hosts, such as by &xep0358;, or if a previous file transfer attempt has failed and the File Receiver would like to initiate another attempt, the File Receiver can "pull" the file from the File Sender. This is done by sending a Jingle session-initiate to the File Sender which includes a &lt;content/&gt; with the 'senders' attribute set to the opposite Jingle session role of the party requesting the file (see <link url='#content-senders'>Use of Jingle Content Senders</link>) and a &lt;description/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace and which includes a &lt;file/&gt; element with enough information included to form a "file selector" (see Section 5 of &rfc5547;) to identify the requested file.</p>
<example caption="File Receiver requests hosted file"><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='wsn361c3'
@ -527,10 +539,10 @@ Initiator Responder
initiator='juliet@capulet.example/yn0cl4bnw0yr3vym'
sid='uj3b2'>
<content creator='initiator' name='a-file-request' senders='responder'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -572,13 +584,13 @@ Initiator Responder
action='content-add'
sid='uj3b2'>
<content creator='initiator' name='additional' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<name>second-file.txt</name>
<media-type>text/plain</media-type>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -622,11 +634,11 @@ Initiator Responder
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='uj3b2'>
<content creator='initiator' name='restart' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<range offset='270336'/>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -725,14 +737,14 @@ a=file-date:modification:"<date>"]]></code>
a=file-range:<offset>-<(offset + length) | *>]]></code>
<p>As a full example, given the following Jingle File Transfer content description:</p>
<code><![CDATA[
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<media-type>text/plain</media-type>
<name>test.txt</name>
<date>2015-07-26T21:46:00</date>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
<range offset='1024' />
</file>
</description>]]></code>
@ -745,7 +757,7 @@ a=file-range:1024-*]]></code>
<section1 topic='Informational Messages'>
<section2 topic='Received'>
<p>Once a file has been successfully received, the recipient MAY send a Jingle session-info message indicating receipt of the complete file, which consists of a &lt;received/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:4' namespace. The &lt;received/&gt; element SHOULD contain 'creator' and 'name' attributes sufficient to identify the content that was received.</p>
<p>Once a file has been successfully received, the recipient MAY send a Jingle session-info message indicating receipt of the complete file, which consists of a &lt;received/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. The &lt;received/&gt; element SHOULD contain 'creator' and 'name' attributes sufficient to identify the content that was received.</p>
<example caption='File Receiver sends ack in session-info'><![CDATA[
<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
id='jp2ba614'
@ -754,7 +766,7 @@ a=file-range:1024-*]]></code>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
sid='a73sjjvkla37jfea'>
<received xmlns='urn:xmpp:jingle:apps:file-transfer:4'
<received xmlns='urn:xmpp:jingle:apps:file-transfer:5'
creator='initiator'
name='a-file-offer' />
</jingle>
@ -764,7 +776,7 @@ a=file-range:1024-*]]></code>
<section2 topic='Checksum' anchor='hash'>
<p>At any time during the lifetime of the file transfer session, the File Sender can communicate the checksum of the file to the File Receiver.</p>
<p>This can be done in the session-initiate message if the File Sender already knows the checksum, as shown above in Example 3.</p>
<p>After the session-initiate message, this can also be done by sending a session-info message containing a &lt;checksum/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:4' namespace. The &lt;checksum/&gt; element SHOULD contain 'creator' and 'name' attributes sufficient to identitfy the content the checksum belongs to. Additionally, the &lt;checksum/&gt; element MUST contain a &lt;file/&gt; element which MUST contain at least one &lt;hash/&gt; element qualified by the 'urn:xmpp:hashes:1' namespace. Each &lt;hash/&gt; element contains a checksum of the file data produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;.</p>
<p>After the session-initiate message, this can also be done by sending a session-info message containing a &lt;checksum/&gt; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. The &lt;checksum/&gt; element SHOULD contain 'creator' and 'name' attributes sufficient to identitfy the content the checksum belongs to. Additionally, the &lt;checksum/&gt; element MUST contain a &lt;file/&gt; element which MUST contain at least one &lt;hash/&gt; element qualified by the 'urn:xmpp:hashes:2' namespace. Each &lt;hash/&gt; element contains a checksum of the file data 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="Initiator sends checksum in session-info"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='kqh401b5'
@ -773,12 +785,12 @@ a=file-range:1024-*]]></code>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
sid='a73sjjvkla37jfea'>
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:4'
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5'
creator='initiator'
name='a-file-offer'>
<file>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>
</checksum>
</jingle>
@ -792,13 +804,13 @@ a=file-range:1024-*]]></code>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
sid='a73sjjvkla37jfea'>
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:4'
<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5'
creator='initiator'
name='a-file-offer'>
<file>
<range offset='2048' length='1024'>
<hash xmlns='urn:xmpp:hashes:1'
algo='sha-1'>4df403604e746f15062ffdbc29367886</hash>
<hash xmlns='urn:xmpp:hashes:2'
algo='sha-1'>kHp5RSzW/h7Gm1etSf90Mr5PC/k=</hash>
</range>
</file>
</checksum>
@ -815,7 +827,7 @@ a=file-range:1024-*]]></code>
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
@ -823,7 +835,7 @@ a=file-range:1024-*]]></code>
<name>test.txt</name>
<range/>
<size>6144</size>
<hash xmlns='urn:xmpp:hashes:1' algo='sha-1'/>
<hash xmlns='urn:xmpp:hashes:2' algo='sha-1'/>
</file>
</description>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1'
@ -903,12 +915,12 @@ a=file-range:1024-*]]></code>
<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:4' 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:5' 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>
<section1 topic='Determining Support' anchor='support'>
<p>To advertise its support for the Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:apps:file-transfer:4" for this version &VNOTE;.</p>
<p>To advertise its support for the Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:apps:file-transfer:5" for this version &VNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='uw72g176'
@ -923,7 +935,7 @@ a=file-range:1024-*]]></code>
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:1'/>
<feature var='urn:xmpp:jingle:apps:file-transfer:4'/>
<feature var='urn:xmpp:jingle:apps:file-transfer:5'/>
<feature var='urn:xmpp:jingle:transports:s5b:1'/>
<feature var='urn:xmpp:jingle:transports:ibb:1'/>
</query>
@ -947,7 +959,7 @@ a=file-range:1024-*]]></code>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:jingle:apps:file-transfer:4</li>
<li>urn:xmpp:jingle:apps:file-transfer:5</li>
</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>
</section2>
@ -968,17 +980,17 @@ a=file-range:1024-*]]></code>
<section1 topic='XML Schema' anchor='schema'>
<section2 topic='urn:xmpp:jingle:apps:file-transfer:4' anchor='schemas-file-transfer'>
<section2 topic='urn:xmpp:jingle:apps:file-transfer:5' anchor='schemas-file-transfer'>
<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:4'
xmlns='urn:xmpp:jingle:apps:file-transfer:4'
targetNamespace='urn:xmpp:jingle:apps:file-transfer:5'
xmlns='urn:xmpp:jingle:apps:file-transfer:5'
elementFormDefault='qualified'>
<xs:import namespace='urn:xmpp:hashes:1'/>
<xs:import namespace='urn:xmpp:hashes:2'/>
<xs:element name='description'>
<xs:complexType>
@ -1006,7 +1018,7 @@ a=file-range:1024-*]]></code>
</xs:element>
<xs:complexType name='fileTransferElementType'>
<xs:all xmlns:h='urn:xmpp:hashes:1' minOccurs='0'>
<xs:all xmlns:h='urn:xmpp:hashes:2' minOccurs='0'>
<xs:element name='date' type='xs:date'/>
<xs:element name='media-type' type='xs:string'/>
<xs:element name='name' type='xs:string'/>
@ -1018,7 +1030,7 @@ a=file-range:1024-*]]></code>
<xs:complexType name='fileTransferRangeType'>
<xs:attribute name='offset' type='xs:nonNegativeInteger' use='optional' default='0' />
<xs:all xmlns:h='urn:xmpp:hashes:1' minOccurs='0'>
<xs:all xmlns:h='urn:xmpp:hashes:2' minOccurs='0'>
<xs:element ref='h:hash' minOccurs='0' maxOccurs='unbounded' />
</xs:all>
</xs:complexType>
@ -1032,7 +1044,7 @@ a=file-range:1024-*]]></code>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:apps:file-transfer:4'
targetNamespace='urn:xmpp:jingle:apps:file-transfer:5'
xmlns='urn:xmpp:jingle:apps:file-transfer:errors:0'
elementFormDefault='qualified'>