<abstract>This document specifies a protocol for authentication with Jabber servers and services using the jabber:iq:auth namespace. Note Well: The protocol specified herein has been deprecated in favor of SASL authentication as specified in RFC 3920.</abstract>
<remark><p>Per a vote of the Jabber Council, advanced status to Final.</p></remark>
</revision>
<revision>
<version>1.8</version>
<date>2004-10-18</date>
<initials>psa</initials>
<remark><p>Specified advertising iq-auth stream feature is implementation-specific; clarified several small matters in the text.</p></remark>
</revision>
<revision>
<version>1.7</version>
<date>2004-07-27</date>
<initials>psa</initials>
<remark><p>Added reference to character escaping in digest authentication; required inclusion of stream feature when server supports stream features and it is safe to advertise non-SASL authentication.</p></remark>
</revision>
<revision>
<version>1.6</version>
<date>2004-07-21</date>
<initials>psa</initials>
<remark><p>Removed reference to UTF-16, which is disallowed by XMPP Core; removed reference to character escaping in digest authentication pending list discussion.</p></remark>
<p>Jabber technologies have long included a wire protocol that enables a client to authenticate with a server. <note>Component authentication is out of scope for this document, and is specified separately in &xep0114;.</note> The method originally used in the Jabber community makes use of the 'jabber:iq:auth' namespace and has been documented variously in Internet-Drafts and elsewhere. When the core Jabber protocols were formalized by the IETF, the 'jabber:iq:auth' protocol was replaced by the Simple Authentication and Security Layer (SASL) as specified in &rfc4422;. SASL was incorporated into XMPP because it provides a more flexible approach to authentication by enabling XMPP entities to use a wide variety of authentication methods (e.g., PLAIN, DIGEST-MD5, EXTERNAL, and ANONYMOUS), some of which are more secure than the 'jabber:iq:auth' protocol.</p>
<p>The 'jabber:iq:auth' protocol specified herein has been deprecated. However, because it will take some time for existing implementations and deployments to be upgraded to SASL, client and server software implementations still need to include support for 'jabber:iq:auth' in order to interoperate, and this document provides canonical documentation of the 'jabber:iq:auth' protocol. Nevertheless, implementation and deployment of SASL authentication is strongly recommended, since the 'jabber:iq:auth' protocol will eventually be obsoleted entirely.</p>
<p>The 'jabber:iq:auth' namespace must make it possible for a Jabber client to authenticate with a server. In particular, the client must provide a username and appropriate credentials for the specific authentication method used. The methods defined herein are:</p>
<ol>
<li>plaintext</li>
<li>digest (using the SHA1 algorithm specified in &rfc3174;)</li>
<p>Note: This document does not include the so-called "zero-knowledge" method; that method did not provide stronger security than digest authentication and thus is unnecessary.</p>
<section2topic='User Authenticates with Server'anchor='usecases-auth'>
<p>In order to determine which fields are required for authentication with a server, a client SHOULD first send an IQ get to the server. A client SHOULD NOT attempt to guess at the required fields, since the nature of the required data is subject to service provisioning.</p>
<examplecaption='Client Opens Stream to Server'><![CDATA[
<stream:streamto='shakespeare.lit'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
]]></example>
<examplecaption='Server Opens Streams to Client'><![CDATA[
<stream:streamfrom='shakespeare.lit'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
id='3EE948B0'>
]]></example>
<examplecaption='Client Requests Authentication Fields from Server'><![CDATA[
<iqtype='get'to='shakespeare.lit'id='auth1'>
<queryxmlns='jabber:iq:auth'/>
</iq>
]]></example>
<examplecaption='Server Returns Authentication Fields to Client'><![CDATA[
<iqtype='result'id='auth1'>
<queryxmlns='jabber:iq:auth'>
<username/>
<password/>
<digest/>
<resource/>
</query>
</iq>
]]></example>
<p>If the client included a username with the IQ-get but there is no such username, the server SHOULD NOT return an error, but instead SHOULD return the normal authentication fields (this helps to prevent unknown users from discovering which usernames are in use). If the server does not support non-SASL authentication (e.g., because it supports only SASL authentication as defined in <cite>RFC 3920</cite>), it MUST return a &unavailable; error. If the client previously attempted SASL authentication but that attempt failed, the server MUST return a <policy-violation/> stream error (see <cite>RFC 3920</cite> regarding stream error syntax).</p>
<p>Both the username and the resource are REQUIRED for client authentication using the 'jabber:iq:auth' namespace; if more flexible authentication and resource provisioning are desired, a server SHOULD implement SASL authentication and resource binding as defined in <cite>RFC 3920</cite> (e.g., to enable the server to provide the resource). The <username/> and <resource/> elements MUST be included in the IQ result returned by the server in response to the initial IQ get, and also MUST be included in the IQ set sent by the client when providing authentication credentials.</p>
<p>The foregoing stanza shows that the server supports both plaintext authentication (via the <password/> element) and digest authentication with SHA1-encrypted passwords (via the <digest/> element).</p>
<p>Therefore, in order to successfully authenticate with the server in this example, a client MUST provide a username, a resource, and one of password or digest.</p>
<examplecaption='Client Provides Required Information (Plaintext)'><![CDATA[
<iqtype='set'id='auth2'>
<queryxmlns='jabber:iq:auth'>
<username>bill</username>
<password>Calli0pe</password>
<resource>globe</resource>
</query>
</iq>
]]></example>
<p>Plaintext passwords are straightforward (obviously, characters that map to predefined XML entities MUST be escaped according to the rules defined in section 4.6 of the XML specification, and any non-US-ASCII characters MUST be encoded according to the encoding of XML streams as specified in <cite>RFC 3920</cite>, i.e., UTF-8 as defined in &rfc3269;).</p>
<p>The value of the <digest/> element MUST be computed according to the following algorithm:</p>
<ol>
<li>Concatenate the Stream ID received from the server with the password. <note>In Digest authentication, password characters that map to predefined XML entities SHOULD NOT be escaped as they are for plaintext passwords, but non-US-ASCII characters MUST be encoded as UTF-8 since the SHA-1 hashing algorithm operates on byte arrays.</note></li>
<li>Hash the concatenated string according to the SHA1 algorithm, i.e., SHA1(concat(sid, password)).</li>
<li>Ensure that the hash output is in hexidecimal format, not binary or base64.</li>
<li>Convert the hash output to all lowercase characters.</li>
</ol>
<examplecaption='Client Provides Required Information (Digest)'><![CDATA[
<p>The character data shown in the <digest/> element is the output produced as a result of following the algorithm defined above when the stream ID is '3EE948B0' and the password is 'Calli0pe'.</p>
<p>If the credentials provided match those known by the server, the client will be successfully authenticated.</p>
<examplecaption='Server Informs Client of Successful Authentication'><![CDATA[
<iqtype='result'id='auth2'/>
]]></example>
<p>Alternatively, authentication may fail. Possible causes of failure include:</p>
<ol>
<li>The user provided incorrect credentials.</li>
<li>There is a resource conflict (i.e., there is already an active session with that resource identifier associated with the same username). The RECOMMENDED behavior is for the server to terminate the existing session and create the new one; however, the server MAY provide the opposite behavior if desired, leading to a conflict error for the newly requested login.</li>
<li>The user did not provide all of the required information (e.g., did not provide a username or resource).</li>
</ol>
<p>Although <cite>RFC 3920</cite> specifies that error stanzas SHOULD include the original XML sent, error stanzas qualified by the 'jabber:iq:auth' namespace SHOULD NOT do so given the sensitive nature of the information being exchanged.</p>
<examplecaption='Server Informs Client of Failed Authentication (Incorrect Credentials)'><