This JEP documents a protocol for authentication with Jabber servers and services using the jabber:iq:auth namespace.
NOTICE: The protocol defined herein is a Draft Standard of the Jabber Software Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.
Status: Draft
Type: Standards Track
Number: 0078
Version: 1.8
Last Updated: 2004-10-18
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, RFC 3174
Supersedes: None
Superseded By: None
Short Name: iq-auth
Schema: <http://jabber.org/protocol/iq-auth/iq-auth.xsd>
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
Given that this JEP normatively references IETF technologies, discussion on the JSF-IETF list may also be appropriate (see <http://mail.jabber.org/mailman/listinfo/jsf-ietf> for details).
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Jabber technologies have long included a wire protocol that enables a client to authenticate with a server. [1] This method makes use of the 'jabber:iq:auth' namespace and has been documented variously in Internet-Drafts and elsewhere. Because the XMPP specifications required upgraded authentication methods using SASL in order to progress through the Internet Standards Process, documentation of the 'jabber:iq:auth' namespace was removed from the XMPP specifications (XMPP Core [3] and XMPP IM [4]).
Unfortunately, SASL libraries are not available (and are unlikely to be available soon, if ever) for all platforms on which Jabber clients may be written (this is especially true of platforms with small footprints, such as J2ME, Symbian, and the like). Furthermore, it will take some time for existing server implementations and deployments to be upgraded to use of SASL as specified in XMPP Core. Therefore, while use of old-style authentication is discouraged and will eventually be deprecated, there is value in allowing its use on the Jabber network as a fallback method for authentication between client and server if SASL is not supported by one party.
Note well that this JEP defines a standard component of the Basic IM Protocol Suite [5]. Thus, despite its perceived limitations, the 'jabber:iq:auth' namespace is not informational. If more secure authentication is required or desired, implementations SHOULD use the SASL authentication protocol defined in XMPP Core.
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:
Note: This JEP does not include the so-called "zero-knowledge" method; that method did not provide stronger security than digest authentication and thus is unnecessary. As noted, those desiring stronger security SHOULD use SASL authentication as defined in XMPP Core.
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.
Example 1. Client Opens Stream to Server
<stream:stream to='shakespeare.lit'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
Example 2. Server Opens Streams to Client
<stream:stream from='shakespeare.lit'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
id='3EE948B0'>
Example 3. Client Requests Authentication Fields from Server
<iq type='get' to='shakespeare.lit' id='auth1'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
</query>
</iq>
Example 4. Server Returns Authentication Fields to Client
<iq type='result' id='auth1'>
<query xmlns='jabber:iq:auth'>
<username/>
<password/>
<digest/>
<resource/>
</query>
</iq>
If 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 XMPP Core), it MUST return a <service-unavailable/> error. If the client previously attempted SASL authentication but that attempt failed, the server MUST return a <policy-violation/> stream error (see XMPP Core regarding stream error syntax).
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 XMPP Core (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.
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).
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.
Example 5. Client Provides Required Information (Plaintext)
<iq type='set' id='auth2'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
<password>Calli0pe</password>
<resource>globe</resource>
</query>
</iq>
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 XMPP Core, i.e., UTF-8 as defined in RFC 3269 [7]).
The value of the <digest/> element MUST be computed according to the following algorithm:
Example 6. Client Provides Required Information (Digest)
<iq type='set' id='auth2'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
<digest>48fc78be9ec8f86d8ce1c39c320c97c21d62334d</digest>
<resource>globe</resource>
</query>
</iq>
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'.
If the credentials provided match those known by the server, the client will be successfully authenticated.
Example 7. Server Informs Client of Successful Authentication
<iq type='result' id='auth2'/>
Alternatively, authentication may fail. Possible causes of failure include:
Although XMPP Core 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.
Example 8. Server Informs Client of Failed Authentication (Incorrect Credentials)
<iq type='error' id='auth2'>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Example 9. Server Informs Client of Failed Authentication (Resource Conflict)
<iq type='error' id='auth2'>
<error code='409' type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Example 10. Server Informs Client of Failed Authentication (Required Information Not Provided)
<iq type='error' id='auth2'>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
XMPP Core defines methods for advertising feature support during stream negotiation. It may be desirable for a server to advertise support for non-SASL authentication as a stream feature. The namespace for reporting support within <stream:features/> is "http://jabber.org/features/iq-auth". Upon receiving a stream header qualified by the 'jabber:client' namespace, a server that returns stream features SHOULD also announce support for non-SASL authentication by including the relevant stream feature. Exactly when a server advertises the iq-auth stream feature is up to the implementation or deployment (e.g., a server MAY advertise this feature only after successful TLS negotiation or if the channel is encrypted via the older SSL method). Obviously, this does not apply to servers that do not support stream features (e.g., older servers that do not comply with XMPP 1.0).
Example 11. Advertising non-SASL authentication as a stream feature
<?xml version='1.0' encoding='utf-8'?>
<stream:stream xmlns:stream='http://etherx.jabber.org/streams/'
xmlns='jabber:client'
from='somedomain'
version='1.0'>
<stream:features>
...
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<mechanism>DIGEST-MD5</mechanism>
<mechanism>PLAIN</mechanism>
</mechanisms>
<auth xmlns='http://jabber.org/features/iq-auth'/>
...
</stream:features>
A server SHOULD NOT advertise non-SASL authentication to another server (i.e., if the initial stream header was qualified by the 'jabber:server' namespace).
As defined herein, the 'jabber:iq:auth' namespace supports both the old (HTTP-style) error codes and the extensible error classes and conditions specified in XMPP Core. A compliant server or service implementation MUST support both old-style and new-style error handling. A compliant client implementation SHOULD support both.
In accordance with Section 8 of Jabber Enhancement Proposals [9], this JEP shall expire six months from the date of its advancement to a status of Final. The Jabber Council shall review this JEP before its expiration date, and at that time shall determine whether to change its status to Deprecated or to extend the expiration date for an additional six months. This process will continue until the JEP is deprecated.
Use of the 'jabber:iq:auth' namespace for client-server authentication is not as secure as SASL authentication (defined in XMPP Core). If both client and server implement SASL, they SHOULD use SASL. If a client attempts to authenticate using the 'jabber:iq:auth' namespace after an attempt at SASL authentication fails, the server MUST refuse the 'jabber:iq:auth' attempt by returning a <policy-violation/> stream error to the client.
Client implementations MUST NOT make plaintext the default mechanism, and SHOULD warn the user that the plaintext mechanism is insecure. The plaintext mechanism SHOULD NOT be used unless the underlying stream is encrypted (using SSL or TLS) and the client has verified that the server certificate is signed by a trusted certificate authority. A given domain MAY choose to disable plaintext logins if the stream is not properly encrypted, or disable them entirely. If a client implements the plaintext mechanism and a server allows both the digest mechanism and the plaintext mechanism, an upgrade attack is possible, in which a man-in-the-middle tricks the client into revealing the user's plaintext password.
Authentication using the 'jabber:iq:auth' namespace is known to be less secure than SASL authentication, and this JEP shall be fully deprecated as soon as SASL authentication is implemented widely enough.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [10].
The Jabber Registrar [11] includes the 'jabber:iq:auth' namespace in its registry of protocol namespaces.
The Jabber Registrar includes the 'http://jabber.org/features/iq-auth' namespace in its registry of stream feature namespaces.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:auth'
xmlns='jabber:iq:auth'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0078: http://www.jabber.org/jeps/jep-0078.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:sequence minOccurs='0'>
<xs:element name='username' type='xs:string' minOccurs='0'/>
<xs:choice>
<xs:element name='password' type='xs:string' minOccurs='0'/>
<xs:element name='digest' type='xs:string' minOccurs='0'/>
</xs:choice>
<xs:element name='resource' type='xs:string' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/features/iq-auth'
xmlns='http://jabber.org/features/iq-auth'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0078: http://www.jabber.org/jeps/jep-0078.html
</xs:documentation>
</xs:annotation>
<xs:element name='auth' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
1. Component authentication is out of scope for this JEP, and is specified separately in Jabber Component Protocol [2].
2. JEP-0114: Jabber Component Protocol <http://www.jabber.org/jeps/jep-0114.html>.
3. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
4. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
5. JEP-0073: Basic IM Protocol Suite <http://www.jabber.org/jeps/jep-0073.html>.
6. RFC 3174: US Secure Hash Algorithm 1 (SHA1) <http://www.ietf.org/rfc/rfc3174.txt>.
7. RFC 3269: UTF-8, a transformation format of ISO 10646 <http://www.ietf.org/rfc/rfc3269.txt>.
8. 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.
9. JEP-0001: Jabber Enhancement Proposals <http://www.jabber.org/jeps/jep-0001.html>.
10. 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/>.
11. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END