Merge branch 'hashUsed' of https://github.com/vanitasvitae/xeps into feature/xep-0234,xep-0300

xep-0234.xml

@@ -24,6 +24,12 @@
   <shortname>NOT_YET_ASSIGNED</shortname>
   &stpeter;
   &lance;
+  <revision>
+    <version>0.18.3</version>
+    <date>2017-08-24</date>
+    <initials>ps</initials>
+    <remark><p>Make use of &lt;hash-used/&gt; from XEP-0300.</p></remark>
+  </revision>
   <revision>
     <version>0.18.2</version>
     <date>2017-08-23</date>
@@ -365,7 +371,12 @@
     <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:2' namespace. Multiple hashes MAY be included for hash agility.</td>
-      <td>REQUIRED when offering a file, otherwise OPTIONAL</td>
+      <td>See &lt;hash-used/&gt;</td>
+    </tr>
+    <tr>
+      <td>hash-used</td>
+      <td>Alternatively to a &lt;hash/&gt; element, the initiator can also include a &lt;hash-used/&gt; element. This avoids the need to read the file twice to calculate the hash.</td>
+      <td>Either a &lt;hash/&gt; or a &lt;hash-used/&gt; element MUST be included when offering a file.</td>
     </tr>
     <tr>
       <td>media-type</td>
@@ -796,7 +807,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: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>
+    <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. In such a case however, the session-initiate message MUST contain a &lt;hash-used/&gt; element. 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; or &lt;hash-used/&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'

xep-0300.xml

@@ -24,6 +24,12 @@
   &mwild;
   &ksmith;
   &tobias;
+  <revision>
+    <version>0.5.2</version>
+    <date>2017-08-21</date>
+    <initials>ps</initials>
+    <remark><p>Add hash-used element</p></remark>
+  </revision>
   <revision>
     <version>0.5.1</version>
     <date>2017-03-17</date>
@@ -93,6 +99,8 @@
   <p>An XMPP protocol can include more than one instance of the &lt;hash/&gt; element, as long as each one has a different value for the 'algo' attribute:</p>
   <code><![CDATA[<hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
 <hash xmlns='urn:xmpp:hashes:2' algo='sha-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>]]></code>
+  <p>In certain scenarios it makes sense to communicate the hash algorithm that is used prior to the calculation of the hash value.</p>
+  <code><![CDATA[<hash-used xmlns='urn:xmpp:hashes:2' algo='sha-256'/>]]></code>
   <p>The value of the 'algo' attribute MUST be one of the values from the &ianahashes; maintained by &IANA;, or one of the values
   defined in the following table.</p>
   <table caption='Additional Hash Function Textual Names'>
@@ -393,13 +401,21 @@
     </xs:complexType>
   </xs:element>
 
+  <xs:element name='hash-used'>
+    <xs:complexType>
+      <xs:extension base='empty'>
+        <xs:attribute name='algo' type='xs:NCName' use='required'/>
+      </xs:extension>
+    </xs:complexType>
+  </xs:element>
+
 </xs:schema>
 ]]></code>
 </section1>
 
 <section1 topic='Acknowledgements' anchor='ack'>
   <p>Thanks to Dave Cridland, Waqas Hussain, Glenn Maynard, Remko
-  Tronçon, and Christian Schudt for their input.</p>
+  Tronçon, Paul Schaub and Christian Schudt for their input.</p>
 </section1>
 
 </xep>