xeps/xep-0300.xml

<?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>Use of Cryptographic Hash Functions in XMPP</title>
  <abstract>This document provides a common wire format for the transport of cryptographic hash function references and hash function values in XMPP protocol extensions.</abstract>
  &LEGALNOTICE;
  <number>0300</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>hashes</shortname>
  &stpeter;
  &mwild;
  &ksmith;
  &tobias;
  <revision>
    <version>1.0.0</version>
    <date>2019-11-13</date>
    <initials>mb</initials>
    <remark><p>Advance to Draft as per 2019-09-19 Council vote</p></remark>
  </revision>
  <revision>
    <version>0.6.0</version>
    <date>2019-04-28</date>
    <initials>jsc</initials>
    <remark><p>Remove hash function recommendations to be able to advance this without tying down the recommendations. Recommendations are now in XEP-0414.</p></remark>
  </revision>
  <revision>
    <version>0.5.3</version>
    <date>2018-02-14</date>
    <initials>fs</initials>
    <remark><p>Clarify textual content of the &lt;hash/&gt; element.</p></remark>
  </revision>
  <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>
    <initials>fs</initials>
    <remark><p>Use xs:base64Binary instead of xs:string in the schema</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2017-01-24</date>
    <initials>tobias</initials>
    <remark><p>Explicitly specify encoding format. Namespace version bump to urn:xmpp:hashes:2.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2016-05-16</date>
    <initials>tobias</initials>
    <remark><p>Updating to current knowledge on security of algorithms. Adding SHA-3 and BLAKE families of hashes.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2012-02-08</date>
    <initials>psa</initials>
    <remark><p>Modified XML structure to remove wrapper element; added recommendations for new XMPP extensions; softened recommendations for existing extensions.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2011-12-05</date>
    <initials>psa</initials>
    <remark><p>Updated to reflect initial analysis of existing XMPP protocol extensions.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2011-06-29</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2011-06-22</date>
    <initials>mw/ks/psa</initials>
    <remark><p>Adjusted format to include multiple hashes in one element; modified namespace versioning rules to align with common practice; added service discovery features for various algorithms.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2011-06-16</date>
    <initials>psa</initials>
    <remark><p>Rough draft based on list discussion.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>Various XMPP extensions make use of cryptographic hash functions, but they do so in different ways (e.g., some define XML elements and some define XML attributes) and often mandate support for different algorithms. The lack of a consistent approach to the use of cryptographic hash functions in XMPP extensions can lead to interoperability problems and security vulnerabilities. Therefore, this document recommends a common approach and XML element that can be re-used in any XMPP protocol extension.</p>
</section1>

<section1 topic='Requirements' anchor='reqs'>
  <p>This extension is designed to meet the following criteria:</p>
  <dl>
    <di><dt>Agility</dt><dd>It is absolutely necessary to support more secure cryptographic hash functions as they become available, and to stop supporting less secure functions as they are deprecated. The wire format should make it easy to use multiple hash functions at the same time.</dd></di>
    <di><dt>Reusability</dt><dd>The extension needs to be reusable in any XMPP protocol.</dd></di>
  </dl>
</section1>

<section1 topic='XML Format' anchor='format'>
  <p>This document defines a new XML element that can be used in any XMPP protocol extension. An example follows.</p>
  <code><![CDATA[<hash xmlns='urn:xmpp:hashes:2' algo='sha-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>]]></code>
  <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'>
    <tr>
      <th>Hash Function Name</th>
      <th>Reference</th>
    </tr>
    <tr>
      <td>"sha3-256"</td>
      <td><span class='ref'><link url='http://dx.doi.org/10.6028/NIST.FIPS.202'>FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions</link></span> <note>FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions &lt;<link url='http://dx.doi.org/10.6028/NIST.FIPS.202'>http://dx.doi.org/10.6028/NIST.FIPS.202</link>&gt;.</note></td>
    </tr>
    <tr>
      <td>"sha3-512"</td>
      <td><span class='ref'><link url='http://dx.doi.org/10.6028/NIST.FIPS.202'>FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions</link></span> <note>FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions &lt;<link url='http://dx.doi.org/10.6028/NIST.FIPS.202'>http://dx.doi.org/10.6028/NIST.FIPS.202</link>&gt;.</note></td>
    </tr>
    <tr>
      <td>"blake2b-256"</td>
      <td>&rfc7693;</td>
    </tr>
    <tr>
      <td>"blake2b-512"</td>
      <td>&rfc7693;</td>
    </tr>
  </table>
  <p>The digest produced by the used hash algorithm is included as the XML character data of the &lt;hash/&gt; element after being encoded using Base64 as specified in Section 4 of &rfc4648;. Thus the character data MUST conform to the base64Binary datatype <note>See &lt;<link url='http://www.w3.org/TR/xmlschema-2/#base64Binary'>http://www.w3.org/TR/xmlschema-2/#base64Binary</link>&gt;.</note> as defined in &w3xmlschema2;. The Base64 output MUST NOT include whitespace and MUST set padding bits to zero.</p>
</section1>

<section1 topic='Hash Functions and Recommendations' anchor='recommendations'>
  <p>Previously, this document made recommendations for specific hash functions.
  Those documentations have been removed in version 0.6.0 and are now found
  in &xep0414;.</p>
</section1>

<section1 topic='Determining Support' anchor='disco'>
  <p>If an entity supports the protocol defined herein, it MUST report that by including a &xep0030; feature of "urn:xmpp:hashes:2" in response to disco#info requests, along with one service discovery feature for each algorithm it supports:</p>
  <example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='uw72g176'
    to='juliet@capulet.lit/balcony'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption="Service discovery information response"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
    id='uw72g176'
    to='romeo@montague.lit/orchard'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:hashes:2'/>
    <feature var='urn:xmpp:hash-function-text-names:sha-256'/>
    <feature var='urn:xmpp:hash-function-text-names:sha3-256'/>
  </query>
</iq>
]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>

<section1 topic='Recommendations for New XMPP Extensions' anchor='new'>
  <p>The XSF is strongly encouraged to incorporate hash agility into new XMPP extensions that it develops by mandating re-use of the protocol defined in this specification (instead of hash elements or attributes specific to each extension).</p>
  <p>Specifications should take the considerations in &xep0414; into
    account.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>This entire document discusses security.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with the IANA. However, it reuses entries from the relevant IANA registry.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:hashes:2</li>
    </ul>
    <p>The &REGISTRAR; shall include the foregoing namespace in its registry at &NAMESPACES;, as governed by &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
  <section2 topic='Service Discovery Features' anchor='registrar-features'>
    <p>An entity SHOULD provide one service discovery feature for each algorithm it supports. Ideally these features would be of the form "urn:iana:hash-function-text-names:foo" (where "foo" is the name of an algorithm registered with the IANA); however there is no urn:iana namespace at present. Until there is, we use features of the form "urn:xmpp:hash-function-text-names:foo" instead. Therefore the registry submission is as follows.</p>
    <code caption='Registry Submission'><![CDATA[
<var>
  <name>urn:xmpp:hash-function-text-names:md5</name>
  <desc>Support for the MD5 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>

<var>
  <name>urn:xmpp:hash-function-text-names:sha-1</name>
  <desc>Support for the SHA-1 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>

<var>
  <name>urn:xmpp:hash-function-text-names:sha-224</name>
  <desc>Support for the SHA-224 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:sha-256</name>
  <desc>Support for the SHA-256 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:sha-384</name>
  <desc>Support for the SHA-384 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:sha-512</name>
  <desc>Support for the SHA-512 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>

<var>
  <name>urn:xmpp:hash-function-text-names:sha3-224</name>
  <desc>Support for the SHA3-224 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:sha3-256</name>
  <desc>Support for the SHA3-256 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:sha3-384</name>
  <desc>Support for the SHA3-384 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:sha3-512</name>
  <desc>Support for the SHA3-512 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>

<var>
  <name>urn:xmpp:hash-function-text-names:id-blake2b160</name>
  <desc>Support for the BLAKE2b-160 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:id-blake2b256</name>
  <desc>Support for the BLAKE2b-256 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:id-blake2b384</name>
  <desc>Support for the BLAKE2b-384 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
<var>
  <name>urn:xmpp:hash-function-text-names:id-blake2b512</name>
  <desc>Support for the BLAKE2b-512 hashing algorithm</desc>
  <doc>XEP-0300</doc>
</var>
]]></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:hashes:2'
    xmlns='urn:xmpp:hashes:2'
    elementFormDefault='qualified'>

  <xs:element name='hash'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:base64Binary'>
          <xs:attribute name='algo' type='xs:NCName' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </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, Paul Schaub, Christian Schudt, and Florian Schmaus for their input.</p>
</section1>

</xep>