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.
This extension is designed to meet the following criteria:
This document defines a new XML element that can be used in any XMPP protocol extension. An example follows.
<hash xmlns='urn:xmpp:hashes:2' algo='sha-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
An XMPP protocol can include more than one instance of the <hash/> element, as long as each one has a different value for the 'algo' attribute:
<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>
In certain scenarios it makes sense to communicate the hash algorithm that is used prior to the calculation of the hash value.
<hash-used xmlns='urn:xmpp:hashes:2' algo='sha-256'/>
The value of the 'algo' attribute MUST be one of the values from the IANA Hash Function Textual Names Registry [1] maintained by the Internet Assigned Numbers Authority (IANA) [2], or one of the values defined in the following table.
| Hash Function Name | Reference |
|---|---|
| "sha3-256" | FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [3] |
| "sha3-512" | FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [3] |
| "blake2b-256" | RFC 7693 [4] |
| "blake2b-512" | RFC 7693 [4] |
The digest produced by the used hash algorithm is included as the XML character data of the <hash/> element after being encoded using Base64 as specified in Section 4 of RFC 4648 [5]. Thus the character data MUST conform to the base64Binary datatype [6] as defined in XML Schema Part 2 [7]. The Base64 output MUST NOT include whitespace and MUST set padding bits to zero.
Previously, this document made recommendations for specific hash functions. Those documentations have been removed in version 0.6.0 and are now found in Cryptographic Hash Function Recommendations for XMPP (XEP-0414) [8].
If an entity supports the protocol defined herein, it MUST report that by including a Service Discovery (XEP-0030) [9] feature of "urn:xmpp:hashes:2" in response to disco#info requests, along with one service discovery feature for each algorithm it supports:
<iq from='romeo@montague.lit/orchard'
id='uw72g176'
to='juliet@capulet.lit/balcony'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<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>
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 Entity Capabilities (XEP-0115) [10]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.
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).
Specifications should take the considerations in Cryptographic Hash Function Recommendations for XMPP (XEP-0414) [8] into account.
This entire document discusses security.
This document requires no interaction with the IANA. However, it reuses entries from the relevant IANA registry.
This specification defines the following XML namespace:
The XMPP Registrar [11] shall include the foregoing namespace in its registry at <https://xmpp.org/registrar/namespaces.html>, as governed by XMPP Registrar Function (XEP-0053) [12].
If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.
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.
<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>
<?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>
Thanks to Dave Cridland, Waqas Hussain, Glenn Maynard, Remko Tronçon, Paul Schaub, Christian Schudt, and Florian Schmaus for their input.
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2018 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. IANA registry of Hash Function Textual Names <http://www.iana.org/assignments/hash-function-text-names>.
2. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
3. FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions <http://dx.doi.org/10.6028/NIST.FIPS.202>.
4. RFC 7693: The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC) <http://tools.ietf.org/html/rfc7693>.
5. RFC 4648: The Base16, Base32, and Base64 Data Encodings <http://tools.ietf.org/html/rfc4648>.
6. See <http://www.w3.org/TR/xmlschema-2/#base64Binary>.
7. XML Schema Part 2: Datatypes <http://www.w3.org/TR/xmlschema11-2/>.
8. XEP-0414: Cryptographic Hash Function Recommendations for XMPP <https://xmpp.org/extensions/xep-0414.html>.
9. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.
10. XEP-0115: Entity Capabilities <https://xmpp.org/extensions/xep-0115.html>.
11. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.
12. XEP-0053: XMPP Registrar Function <https://xmpp.org/extensions/xep-0053.html>.
Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/
Remove hash function recommendations to be able to advance this without tying down the recommendations. Recommendations are now in XEP-0414.
Clarify textual content of the <hash/> element.
Add hash-used element
Use xs:base64Binary instead of xs:string in the schema
Explicitly specify encoding format. Namespace version bump to urn:xmpp:hashes:2.
Updating to current knowledge on security of algorithms. Adding SHA-3 and BLAKE families of hashes.
Modified XML structure to remove wrapper element; added recommendations for new XMPP extensions; softened recommendations for existing extensions.
Updated to reflect initial analysis of existing XMPP protocol extensions.
Initial published version.
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.
Rough draft based on list discussion.
END