RFC 6120
Extensible Messaging and Presence Protocol (XMPP): Core
Pages: 211
Proposed Standard
→ Errata
Obsoletes: 3920
Updated by: 7590 8553
Proposed Standard
→ Errata
Obsoletes: 3920
Updated by: 7590 8553
Part 4 of 9 – Pages 69 to 99
5. STARTTLS Negotiation
5.1. Fundamentals
XMPP includes a method for securing the stream from tampering and eavesdropping. This channel encryption method makes use of the Transport Layer Security [TLS] protocol, specifically a "STARTTLS" extension that is modeled after similar extensions for the [IMAP],
[POP3], and [ACAP] protocols as described in [USINGTLS]. The XML namespace name for the STARTTLS extension is 'urn:ietf:params:xml:ns:xmpp-tls'.5.2. Support
Support for STARTTLS is REQUIRED in XMPP client and server implementations. An administrator of a given deployment MAY specify that TLS is mandatory-to-negotiate for client-to-server communication, server-to-server communication, or both. An initiating entity SHOULD use TLS to secure its stream with the receiving entity before proceeding with SASL authentication.5.3. Stream Negotiation Rules
5.3.1. Mandatory-to-Negotiate
If the receiving entity advertises only the STARTTLS feature or if the receiving entity includes the <required/> child element as explained under Section 5.4.1, the parties MUST consider TLS as mandatory-to-negotiate. If TLS is mandatory-to-negotiate, the receiving entity SHOULD NOT advertise support for any stream feature except STARTTLS during the initial stage of the stream negotiation process, because further stream features might depend on prior negotiation of TLS given the order of layers in XMPP (e.g., the particular SASL mechanisms offered by the receiving entity will likely depend on whether TLS has been negotiated).5.3.2. Restart
After TLS negotiation, the parties MUST restart the stream.5.3.3. Data Formatting
During STARTTLS negotiation, the entities MUST NOT send any whitespace as separators between XML elements (i.e., from the last character of the first-level <starttls/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls' namespace as sent by the initiating entity, until the last character of the first-level <proceed/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls' namespace as sent by the receiving entity). This prohibition helps to ensure proper security layer byte precision. Any such whitespace shown in the STARTTLS examples provided in this document is included only for the sake of readability.
5.3.4. Order of TLS and SASL Negotiations
If the initiating entity chooses to use TLS, STARTTLS negotiation MUST be completed before proceeding to SASL negotiation (Section 6); this order of negotiation is necessary to help safeguard authentication information sent during SASL negotiation, as well as to make it possible to base the use of the SASL EXTERNAL mechanism on a certificate (or other credentials) provided during prior TLS negotiation.5.3.5. TLS Renegotiation
The TLS protocol allows either party in a TLS-protected channel to initiate a new handshake that establishes new cryptographic parameters (see [TLS-NEG]). The cases most commonly mentioned are: 1. Refreshing encryption keys. 2. Wrapping the TLS sequence number as explained in Section 6.1 of [TLS]. 3. Protecting client credentials by completing server authentication first and then completing client authentication over the protected channel. Because it is relatively inexpensive to establish streams in XMPP, for the first two cases it is preferable to use an XMPP stream reset (as described under Section 4.9.3.16) instead of performing TLS renegotiation. The third case has improved security characteristics when the TLS client (which might be an XMPP server) presents credentials to the TLS server. If communicating such credentials to an unauthenticated TLS server might leak private information, it can be appropriate to complete TLS negotiation for the purpose of authenticating the TLS server to the TLS client and then attempt TLS renegotiation for the purpose of authenticating the TLS client to the TLS server. However, this case is extremely rare because the credentials presented by an XMPP server or XMPP client acting as a TLS client are almost always public (i.e., a PKIX certificate), and therefore providing those credentials before authenticating the XMPP server acting as a TLS server would not in general leak private information. As a result, implementers are encouraged to carefully weigh the costs and benefits of TLS renegotiation before supporting it in their software, and XMPP entities that act as TLS clients are discouraged
from attempting TLS renegotiation unless the certificate (or other credential information) sent during TLS negotiation is known to be private. Support for TLS renegotiation is strictly OPTIONAL. However, implementations that support TLS renegotiation MUST implement and use the TLS Renegotiation Extension [TLS-NEG]. If an entity that does not support TLS renegotiation detects a renegotiation attempt, then it MUST immediately close the underlying TCP connection without returning a stream error (since the violation has occurred at the TLS layer, not the XMPP layer, as described under Section 13.3). If an entity that supports TLS renegotiation detects a TLS renegotiation attempt that does not use the TLS Renegotiation Extension [TLS-NEG], then it MUST immediately close the underlying TCP connection without returning a stream error (since the violation has occurred at the TLS layer, not the XMPP layer as described under Section 13.3).5.3.6. TLS Extensions
Either party to a stream MAY include any TLS extension during the TLS negotiation itself. This is a matter for the TLS layer, not the XMPP layer.5.4. Process
5.4.1. Exchange of Stream Headers and Stream Features
The initiating entity resolves the FQDN of the receiving entity as specified under Section 3, opens a TCP connection to the advertised port at the resolved IP address, and sends an initial stream header to the receiving entity. I: <stream:stream from='juliet@im.example.com' to='im.example.com' version='1.0' xml:lang='en' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'> The receiving entity MUST send a response stream header to the initiating entity over the TCP connection opened by the initiating entity.
R: <stream:stream
from='im.example.com'
id='t7AMCin9zjMNwQKDnplntZPIDEI='
to='juliet@im.example.com'
version='1.0'
xml:lang='en'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
The receiving entity then MUST send stream features to the initiating
entity. If the receiving entity supports TLS, the stream features
MUST include an advertisement for support of STARTTLS negotiation,
i.e., a <starttls/> element qualified by the
'urn:ietf:params:xml:ns:xmpp-tls' namespace.
If the receiving entity considers STARTTLS negotiation to be
mandatory-to-negotiate, the <starttls/> element MUST contain an empty
<required/> child element.
R: <stream:features>
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'>
<required/>
</starttls>
</stream:features>
5.4.2. Initiation of STARTTLS Negotiation
5.4.2.1. STARTTLS Command
In order to begin the STARTTLS negotiation, the initiating entity
issues the STARTTLS command (i.e., a <starttls/> element qualified by
the 'urn:ietf:params:xml:ns:xmpp-tls' namespace) to instruct the
receiving entity that it wishes to begin a STARTTLS negotiation to
secure the stream.
I: <starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
The receiving entity MUST reply with either a <proceed/> element
(proceed case) or a <failure/> element (failure case) qualified by
the 'urn:ietf:params:xml:ns:xmpp-tls' namespace.
5.4.2.2. Failure Case
If the failure case occurs, the receiving entity MUST return a
<failure/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls'
namespace, close the XML stream, and terminate the underlying TCP
connection.
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
R: </stream:stream>
Causes for the failure case include but are not limited to:
1. The initiating entity has sent a malformed STARTTLS command.
2. The receiving entity did not offer the STARTTLS feature in its
stream features.
3. The receiving entity cannot complete STARTTLS negotiation because
of an internal error.
Informational Note: STARTTLS failure is not triggered by TLS
errors such as bad_certificate or handshake_failure, which are
generated and handled during the TLS negotiation itself as
described in [TLS].
If the failure case occurs, the initiating entity MAY attempt to
reconnect as explained under Section 3.3.
5.4.2.3. Proceed Case
If the proceed case occurs, the receiving entity MUST return a
<proceed/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls'
namespace.
R: <proceed xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
The receiving entity MUST consider the TLS negotiation to have begun
immediately after sending the closing '>' character of the <proceed/>
element to the initiating entity. The initiating entity MUST
consider the TLS negotiation to have begun immediately after
receiving the closing '>' character of the <proceed/> element from
the receiving entity.
The entities now proceed to TLS negotiation as explained in the next
section.
5.4.3. TLS Negotiation
5.4.3.1. Rules
In order to complete TLS negotiation over the TCP connection, the
entities MUST follow the process defined in [TLS].
The following rules apply:
1. The entities MUST NOT send any further XML data until the TLS
negotiation is complete.
2. When using any of the mandatory-to-implement (MTI) ciphersuites
specified under Section 13.8, the receiving entity MUST present a
certificate.
3. So that mutual certificate authentication will be possible, the
receiving entity SHOULD send a certificate request to the
initiating entity, and the initiating entity SHOULD send a
certificate to the receiving entity (but for privacy reasons
might opt not to send a certificate until after the receiving
entity has authenticated to the initiating entity).
4. The receiving entity SHOULD choose which certificate to present
based on the domainpart contained in the 'to' attribute of the
initial stream header (in essence, this domainpart is
functionally equivalent to the Server Name Indication defined for
TLS in [TLS-EXT]).
5. To determine if the TLS negotiation will succeed, the initiating
entity MUST attempt to validate the receiving entity's
certificate in accordance with the certificate validation
procedures specified under Section 13.7.2.
6. If the initiating entity presents a certificate, the receiving
entity too MUST attempt to validate the initiating entity's
certificate in accordance with the certificate validation
procedures specified under Section 13.7.2.
7. Following successful TLS negotiation, all further data
transmitted by either party MUST be protected with the negotiated
algorithms, keys, and secrets (i.e., encrypted, integrity-
protected, or both depending on the ciphersuite used).
Security Warning: See Section 13.8 regarding ciphersuites that
MUST be supported for TLS; naturally, other ciphersuites MAY be
supported as well.
5.4.3.2. TLS Failure
If the TLS negotiation results in failure, the receiving entity MUST
terminate the TCP connection.
The receiving entity MUST NOT send a closing </stream> tag before terminating the TCP connection (since the failure has occurred at the TLS layer, not the XMPP layer as described under Section 13.3). The initiating entity MAY attempt to reconnect as explained under Section 3.3, with or without attempting TLS negotiation (in accordance with local service policy, user-configured preferences, etc.).5.4.3.3. TLS Success
If the TLS negotiation is successful, then the entities MUST proceed as follows. 1. The initiating entity MUST discard any information transmitted in layers above TCP that it obtained from the receiving entity in an insecure manner before TLS took effect (e.g., the receiving entity's 'from' address or the stream ID and stream features received from the receiving entity). 2. The receiving entity MUST discard any information transmitted in layers above TCP that it obtained from the initiating entity in an insecure manner before TLS took effect (e.g., the initiating entity's 'from' address). 3. The initiating entity MUST send a new initial stream header to the receiving entity over the encrypted connection (as specified under Section 4.3.3, the initiating entity MUST NOT send a closing </stream> tag before sending the new initial stream header, since the receiving entity and initiating entity MUST consider the original stream to be replaced upon success of the TLS negotiation). I: <stream:stream from='juliet@im.example.com' to='im.example.com' version='1.0' xml:lang='en' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'> 4. The receiving entity MUST respond with a new response stream header over the encrypted connection (for which it MUST generate a new stream ID instead of reusing the old stream ID).
R: <stream:stream
from='im.example.com'
id='vgKi/bkYME8OAj4rlXMkpucAqe4='
to='juliet@im.example.com'
version='1.0'
xml:lang='en'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
5. The receiving entity also MUST send stream features to the
initiating entity, which MUST NOT include the STARTTLS feature
but which SHOULD include the SASL stream feature as described
under Section 6 (see especially Section 6.4.1 regarding the few
reasons why the SASL stream feature would not be offered here).
R: <stream:features>
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<mechanism>EXTERNAL</mechanism>
<mechanism>SCRAM-SHA-1-PLUS</mechanism>
<mechanism>SCRAM-SHA-1</mechanism>
<mechanism>PLAIN</mechanism>
</mechanisms>
</stream:features>
6. SASL Negotiation
6.1. Fundamentals
XMPP includes a method for authenticating a stream by means of an
XMPP-specific profile of the Simple Authentication and Security Layer
protocol (see [SASL]). SASL provides a generalized method for adding
authentication support to connection-based protocols, and XMPP uses
an XML namespace profile of SASL that conforms to the profiling
requirements of [SASL]. The XML namespace name for the SASL
extension is 'urn:ietf:params:xml:ns:xmpp-sasl'.
6.2. Support
Support for SASL negotiation is REQUIRED in XMPP client and server
implementations.
6.3. Stream Negotiation Rules
6.3.1. Mandatory-to-Negotiate
The parties to a stream MUST consider SASL as mandatory-to-negotiate.
6.3.2. Restart
After SASL negotiation, the parties MUST restart the stream.6.3.3. Mechanism Preferences
Any entity that will act as a SASL client or a SASL server MUST maintain an ordered list of its preferred SASL mechanisms according to the client or server, where the list is ordered according to local policy or user configuration (which SHOULD be in order of perceived strength to enable the strongest authentication possible). The initiating entity MUST maintain its own preference order independent of the preference order of the receiving entity. A client MUST try SASL mechanisms in its preference order. For example, if the server offers the ordered list "PLAIN SCRAM-SHA-1 GSSAPI" or "SCRAM-SHA-1 GSSAPI PLAIN" but the client's ordered list is "GSSAPI SCRAM-SHA-1", the client MUST try GSSAPI first and then SCRAM-SHA-1 but MUST NOT try PLAIN (since PLAIN is not on its list).6.3.4. Mechanism Offers
If the receiving entity considers TLS negotiation (Section 5) to be mandatory-to-negotiate before it will accept authentication with a particular SASL mechanism, it MUST NOT advertise that mechanism in its list of available SASL mechanisms before TLS negotiation has been completed. The receiving entity SHOULD offer the SASL EXTERNAL mechanism if both of the following conditions hold: 1. During TLS negotiation the initiating entity presented a certificate that is acceptable to the receiving entity for purposes of strong identity verification in accordance with local service policies (e.g., because said certificate is unexpired, is unrevoked, and is anchored to a root trusted by the receiving entity). 2. The receiving entity expects that the initiating entity will be able to authenticate and authorize as the identity provided in the certificate; in the case of a server-to-server stream, the receiving entity might have such an expectation because a DNS domain name presented in the initiating entity's certificate matches the domain referenced in the 'from' attribute of the initial stream header, where the matching rules of [TLS-CERTS] apply; in the case of a client-to-server stream, the receiving entity might have such an expectation because the bare JID presented in the initiating entity's certificate matches a user account that is registered with the server or because other
information contained in the initiating entity's certificate
matches that of an entity that has permission to use the server
for access to an XMPP network.
However, the receiving entity MAY offer the SASL EXTERNAL mechanism
under other circumstances, as well.
When the receiving entity offers the SASL EXTERNAL mechanism, the
receiving entity SHOULD list the EXTERNAL mechanism first among its
offered SASL mechanisms and the initiating entity SHOULD attempt SASL
negotiation using the EXTERNAL mechanism first (this preference will
tend to increase the likelihood that the parties can negotiate mutual
certificate authentication).
Section 13.8 specifies SASL mechanisms that MUST be supported;
naturally, other SASL mechanisms MAY be supported as well.
Informational Note: Best practices for the use of SASL in the
context of XMPP are described in [XEP-0175] for the ANONYMOUS
mechanism and in [XEP-0178] for the EXTERNAL mechanism.
6.3.5. Data Formatting
The following data formatting rules apply to the SASL negotiation:
1. During SASL negotiation, the entities MUST NOT send any
whitespace as separators between XML elements (i.e., from the
last character of the first-level <auth/> element qualified by
the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace as sent by the
initiating entity, until the last character of the first-level
<success/> element qualified by the
'urn:ietf:params:xml:ns:xmpp-sasl' namespace as sent by the
receiving entity). This prohibition helps to ensure proper
security layer byte precision. Any such whitespace shown in the
SASL examples provided in this document is included only for the
sake of readability.
2. Any XML character data contained within the XML elements MUST be
encoded using base 64, where the encoding adheres to the
definition in Section 4 of [BASE64] and where the padding bits
are set to zero.
3. As formally specified in the XML schema for the
'urn:ietf:params:xml:ns:xmpp-sasl' namespace under Appendix A.4,
the receiving entity MAY include one or more application-specific
child elements inside the <mechanisms/> element to provide
information that might be needed by the initiating entity in
order to complete successful SASL negotiation using one or more
of the offered mechanisms; however, the syntax and semantics of
all such elements are out of scope for this specification (see
[XEP-0233] for one example).
6.3.6. Security Layers
Upon successful SASL negotiation that involves negotiation of a
security layer, both the initiating entity and the receiving entity
MUST discard any application-layer state (i.e, state from the XMPP
layer, excluding state from the TLS negotiation or SASL negotiation).
6.3.7. Simple User Name
Some SASL mechanisms (e.g., CRAM-MD5, DIGEST-MD5, and SCRAM) specify
that the authentication identity used in the context of such
mechanisms is a "simple user name" (see Section 2 of [SASL] as well
as [SASLPREP]). The exact form of the simple user name in any
particular mechanism or deployment thereof is a local matter, and a
simple user name does not necessarily map to an application
identifier such as a JID or JID component (e.g., a localpart).
However, in the absence of local information provided by the server,
an XMPP client SHOULD assume that the authentication identity for
such a SASL mechanism is a simple user name equal to the localpart of
the user's JID.
6.3.8. Authorization Identity
An authorization identity is an OPTIONAL identity included by the
initiating entity to specify an identity to act as (see Section 2 of
[SASL]). In client-to-server streams, it would most likely be used
by an administrator to perform some management task on behalf of
another user, whereas in server-to-server streams it would most
likely be used to specify a particular add-on service at an XMPP
service (e.g., a multi-user chat server at conference.example.com
that is hosted by the example.com XMPP service). If the initiating
entity wishes to act on behalf of another entity and the selected
SASL mechanism supports transmission of an authorization identity,
the initiating entity MUST provide an authorization identity during
SASL negotiation. If the initiating entity does not wish to act on
behalf of another entity, it MUST NOT provide an authorization
identity.
In the case of client-to-server communication, the value of an
authorization identity MUST be a bare JID (<localpart@domainpart>)
rather than a full JID (<localpart@domainpart/resourcepart>).
In the case of server-to-server communication, the value of an
authorization identity MUST be a domainpart only (<domainpart>).
If the initiating entity provides an authorization identity during SASL negotiation, the receiving entity is responsible for verifying that the initiating entity is in fact allowed to assume the specified authorization identity; if not, the receiving entity MUST return an <invalid-authzid/> SASL error as described under Section 6.5.6.6.3.9. Realms
The receiving entity MAY include a realm when negotiating certain SASL mechanisms (e.g., both the GSSAPI and DIGEST-MD5 mechanisms allow the authentication exchange to include a realm, though in different ways, whereas the EXTERNAL, SCRAM, and PLAIN mechanisms do not). If the receiving entity does not communicate a realm, the initiating entity MUST NOT assume that any realm exists. The realm MUST be used only for the purpose of authentication; in particular, an initiating entity MUST NOT attempt to derive an XMPP domainpart from the realm information provided by the receiving entity.6.3.10. Round Trips
[SASL] specifies that a using protocol such as XMPP can define two methods by which the protocol can save round trips where allowed for the SASL mechanism: 1. When the SASL client (the XMPP "initiating entity") requests an authentication exchange, it can include "initial response" data with its request if appropriate for the SASL mechanism in use. In XMPP, this is done by including the initial response as the XML character data of the <auth/> element. 2. At the end of the authentication exchange, the SASL server (the XMPP "receiving entity") can include "additional data with success" if appropriate for the SASL mechanism in use. In XMPP, this is done by including the additional data as the XML character data of the <success/> element. For the sake of protocol efficiency, it is REQUIRED for clients and servers to support these methods and RECOMMENDED to use them; however, clients and servers MUST support the less efficient modes as well.
6.4. Process
The process for SASL negotiation is as follows.6.4.1. Exchange of Stream Headers and Stream Features
If SASL negotiation follows successful STARTTLS negotiation (Section 5), then the SASL negotiation occurs over the protected stream that has already been negotiated. If not, the initiating entity resolves the FQDN of the receiving entity as specified under Section 3, opens a TCP connection to the advertised port at the resolved IP address, and sends an initial stream header to the receiving entity. In either case, the receiving entity will receive an initial stream from the initiating entity. I: <stream:stream from='juliet@im.example.com' to='im.example.com' version='1.0' xml:lang='en' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'> When the receiving entity processes an initial stream header from the initiating entity, it MUST send a response stream header to the initiating entity (for which it MUST generate a unique stream ID. If TLS negotiation has already succeeded, then this stream ID MUST be different from the stream ID sent before TLS negotiation succeeded). R: <stream:stream from='im.example.com' id='vgKi/bkYME8OAj4rlXMkpucAqe4=' to='juliet@im.example.com' version='1.0' xml:lang='en' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'> The receiving entity also MUST send stream features to the initiating entity. The stream features SHOULD include an advertisement for support of SASL negotiation, i.e., a <mechanisms/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace. Typically there are only three cases in which support for SASL negotiation would not be advertised here:
o TLS negotiation needs to happen before SASL can be offered (i.e.,
TLS is required and the receiving entity is responding to the very
first initial stream header it has received for this connection
attempt).
o SASL negotiation is impossible for a server-to-server connection
(i.e., the initiating server has not provided a certificate that
would enable strong authentication and therefore the receiving
server is falling back to weak identity verification using the
Server Dialback protocol [XEP-0220]).
o SASL has already been negotiated (i.e., the receiving entity is
responding to an initial stream header sent as a stream restart
after successful SASL negotiation).
The <mechanisms/> element MUST contain one <mechanism/> child element
for each authentication mechanism the receiving entity offers to the
initiating entity. As noted, the order of <mechanism/> elements in
the XML indicates the preference order of the SASL mechanisms
according to the receiving entity (which is not necessarily the
preference order according to the initiating entity).
R: <stream:features>
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<mechanism>EXTERNAL</mechanism>
<mechanism>SCRAM-SHA-1-PLUS</mechanism>
<mechanism>SCRAM-SHA-1</mechanism>
<mechanism>PLAIN</mechanism>
</mechanisms>
</stream:features>
6.4.2. Initiation
In order to begin the SASL negotiation, the initiating entity sends
an <auth/> element qualified by the
'urn:ietf:params:xml:ns:xmpp-sasl' namespace and includes an
appropriate value for the 'mechanism' attribute, thus starting the
handshake for that particular authentication mechanism. This element
MAY contain XML character data (in SASL terminology, the "initial
response") if the mechanism supports or requires it. If the
initiating entity needs to send a zero-length initial response, it
MUST transmit the response as a single equals sign character ("="),
which indicates that the response is present but contains no data.
I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl'
mechanism='PLAIN'>AGp1bGlldAByMG0zMG15cjBtMzA=</auth>
If the initiating entity subsequently sends another <auth/> element and the ongoing authentication handshake has not yet completed, the receiving entity MUST discard the ongoing handshake and MUST process a new handshake for the subsequently requested SASL mechanism.6.4.3. Challenge-Response Sequence
If necessary, the receiving entity challenges the initiating entity by sending a <challenge/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace; this element MAY contain XML character data (which MUST be generated in accordance with the definition of the SASL mechanism chosen by the initiating entity). The initiating entity responds to the challenge by sending a <response/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace; this element MAY contain XML character data (which MUST be generated in accordance with the definition of the SASL mechanism chosen by the initiating entity). If necessary, the receiving entity sends more challenges and the initiating entity sends more responses. This series of challenge/response pairs continues until one of three things happens: o The initiating entity aborts the handshake for this authentication mechanism. o The receiving entity reports failure of the handshake. o The receiving entity reports success of the handshake. These scenarios are described in the following sections.6.4.4. Abort
The initiating entity aborts the handshake for this authentication mechanism by sending an <abort/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace. I: <abort xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/> Upon receiving an <abort/> element, the receiving entity MUST return a <failure/> element qualified by the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace and containing an <aborted/> child element.
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<aborted/>
</failure>
6.4.5. SASL Failure
The receiving entity reports failure of the handshake for this
authentication mechanism by sending a <failure/> element qualified by
the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace (the particular
cause of failure MUST be communicated in an appropriate child element
of the <failure/> element as defined under Section 6.5).
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<not-authorized/>
</failure>
Where appropriate for the chosen SASL mechanism, the receiving entity
SHOULD allow a configurable but reasonable number of retries (at
least 2 and no more than 5); this enables the initiating entity
(e.g., an end-user client) to tolerate incorrectly provided
credentials (e.g., a mistyped password) without being forced to
reconnect (which it would if the receiving entity immediately
returned a SASL failure and closed the stream).
If the initiating entity attempts a reasonable number of retries with
the same SASL mechanism and all attempts fail, it MAY fall back to
the next mechanism in its ordered list by sending a new <auth/>
request to the receiving entity, thus starting a new handshake for
that authentication mechanism. If all handshakes fail and there are
no remaining mechanisms in the initiating entity's list of supported
and acceptable mechanisms, the initiating entity SHOULD simply close
the stream as described under Section 4.4 (instead of waiting for the
stream to time out).
If the initiating entity exceeds the number of retries, the receiving
entity MUST close the stream with a stream error, which SHOULD be
<policy-violation/> (Section 4.9.3.14), although some existing
implementations send <not-authorized/> (Section 4.9.3.12) instead.
Implementation Note: For server-to-server streams, if the
receiving entity cannot offer the SASL EXTERNAL mechanism or any
other SASL mechanism based on the security context established
during TLS negotiation, the receiving entity MAY attempt to
complete weak identity verification using the Server Dialback
protocol [XEP-0220]; however, if according to local service
policies weak identity verification is insufficient then the
receiving entity SHOULD instead close the stream with a <policy-
violation/> stream error (Section 4.9.3.14) instead of waiting for
the stream to time out.
6.4.6. SASL Success
Before considering the SASL handshake to be a success, if the
initiating entity provided a 'from' attribute on an initial stream
header whose confidentiality and integrity were protected via TLS or
an equivalent security layer (such as the SASL GSSAPI mechanism) then
the receiving entity SHOULD correlate the authentication identity
resulting from the SASL negotiation with that 'from' address; if the
two identities do not match then the receiving entity SHOULD
terminate the connection attempt (however, the receiving entity might
have legitimate reasons not to terminate the connection attempt, for
example, because it has overridden a connecting client's address to
correct the JID format or assign a JID based on information presented
in an end-user certificate).
The receiving entity reports success of the handshake by sending a
<success/> element qualified by the
'urn:ietf:params:xml:ns:xmpp-sasl' namespace; this element MAY
contain XML character data (in SASL terminology, "additional data
with success") if the chosen SASL mechanism supports or requires it.
If the receiving entity needs to send additional data of zero length,
it MUST transmit the data as a single equals sign character ("=").
R: <success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
Informational Note: For client-to-server streams, the
authorization identity communicated during SASL negotiation is
used to determine the canonical address for the initiating client
according to the receiving server, as described under
Section 4.3.6.
Upon receiving the <success/> element, the initiating entity MUST
initiate a new stream over the existing TCP connection by sending a
new initial stream header to the receiving entity (as specified under
Section 4.3.3, the initiating entity MUST NOT send a closing
</stream> tag before sending the new initial stream header, since the
receiving entity and initiating entity MUST consider the original
stream to be replaced upon success of the SASL negotiation).
I: <stream:stream
from='juliet@im.example.com'
to='im.example.com'
version='1.0'
xml:lang='en'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
Upon receiving the new initial stream header from the initiating
entity, the receiving entity MUST respond by sending a new response
stream header to the initiating entity (for which it MUST generate a
new stream ID instead of reusing the old stream ID).
R: <stream:stream
from='im.example.com'
id='gPybzaOzBmaADgxKXu9UClbprp0='
to='juliet@im.example.com'
version='1.0'
xml:lang='en'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
The receiving entity MUST also send stream features, containing any
further available features or containing no features (via an empty
<features/> element).
R: <stream:features>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'/>
</stream:features>
6.5. SASL Errors
The syntax of SASL errors is as follows, where the XML data shown
within the square brackets '[' and ']' is OPTIONAL.
<failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<defined-condition/>
[<text xml:lang='langcode'>
OPTIONAL descriptive text
</text>]
</failure>
The "defined-condition" MUST be one of the SASL-related error
conditions defined in the following sections. However, because
additional error conditions might be defined in the future, if an
entity receives a SASL error condition that it does not understand
then it MUST treat the unknown condition as a generic authentication
failure, i.e., as equivalent to <not-authorized/> (Section 6.5.10).
Inclusion of the <text/> element is OPTIONAL, and can be used to provide application-specific information about the error condition, which information MAY be displayed to a human but only as a supplement to the defined condition. Because XMPP itself defines an application profile of SASL and there is no expectation that more specialized XMPP applications will be built on top of SASL, the SASL error format does not provide extensibility for application-specific error conditions as is done for XML streams (Section 4.9.4) and XML stanzas (Section 8.3.4).6.5.1. aborted
The receiving entity acknowledges that the authentication handshake has been aborted by the initiating entity; sent in reply to the <abort/> element. I: <abort xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <aborted/> </failure>6.5.2. account-disabled
The account of the initiating entity has been temporarily disabled; sent in reply to an <auth/> element (with or without initial response data) or a <response/> element. I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='PLAIN'>AGp1bGlldAByMG0zMG15cjBtMzA=</auth> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <account-disabled/> <text xml:lang='en'>Call 212-555-1212 for assistance.</text> </failure>6.5.3. credentials-expired
The authentication failed because the initiating entity provided credentials that have expired; sent in reply to a <response/> element or an <auth/> element with initial response data. I: <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> [ ... ] </response>
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<credentials-expired/>
</failure>
6.5.4. encryption-required
The mechanism requested by the initiating entity cannot be used
unless the confidentiality and integrity of the underlying stream are
protected (typically via TLS); sent in reply to an <auth/> element
(with or without initial response data).
I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl'
mechanism='PLAIN'>AGp1bGlldAByMG0zMG15cjBtMzA=</auth>
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<encryption-required/>
</failure>
6.5.5. incorrect-encoding
The data provided by the initiating entity could not be processed
because the base 64 encoding is incorrect (e.g., because the encoding
does not adhere to the definition in Section 4 of [BASE64]); sent in
reply to a <response/> element or an <auth/> element with initial
response data.
I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl'
mechanism='DIGEST-MD5'>[ ... ]</auth>
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<incorrect-encoding/>
</failure>
6.5.6. invalid-authzid
The authzid provided by the initiating entity is invalid, either
because it is incorrectly formatted or because the initiating entity
does not have permissions to authorize that ID; sent in reply to a
<response/> element or an <auth/> element with initial response data.
I: <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
[ ... ]
</response>
R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<invalid-authzid/>
</failure>
6.5.7. invalid-mechanism
The initiating entity did not specify a mechanism, or requested a mechanism that is not supported by the receiving entity; sent in reply to an <auth/> element. I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='CRAM-MD5'/> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <invalid-mechanism/> </failure>6.5.8. malformed-request
The request is malformed (e.g., the <auth/> element includes initial response data but the mechanism does not allow that, or the data sent violates the syntax for the specified SASL mechanism); sent in reply to an <abort/>, <auth/>, <challenge/>, or <response/> element. (In the following example, the XML character data of the <auth/> element contains more than 255 UTF-8-encoded Unicode characters and therefore violates the "token" production for the SASL ANONYMOUS mechanism as specified in [ANONYMOUS].) I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='ANONYMOUS'>[ ... some-long-token ... ]</auth> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <malformed-request/> </failure>6.5.9. mechanism-too-weak
The mechanism requested by the initiating entity is weaker than server policy permits for that initiating entity; sent in reply to an <auth/> element (with or without initial response data). I: <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='PLAIN'>AGp1bGlldAByMG0zMG15cjBtMzA=</auth> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <mechanism-too-weak/> </failure>
6.5.10. not-authorized
The authentication failed because the initiating entity did not provide proper credentials, or because some generic authentication failure has occurred but the receiving entity does not wish to disclose specific information about the cause of the failure; sent in reply to a <response/> element or an <auth/> element with initial response data. I: <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> [ ... ] </response> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <not-authorized/> </failure> Security Warning: This error condition includes but is not limited to the case of incorrect credentials or a nonexistent username. In order to discourage directory harvest attacks, no differentiation is made between incorrect credentials and a nonexistent username.6.5.11. temporary-auth-failure
The authentication failed because of a temporary error condition within the receiving entity, and it is advisable for the initiating entity to try again later; sent in reply to an <auth/> element or a <response/> element. I: <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> [ ... ] </response> R: <failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'> <temporary-auth-failure/> </failure>6.6. SASL Definition
The profiling requirements of [SASL] require that the following information be supplied by the definition of a using protocol. service name: "xmpp" initiation sequence: After the initiating entity provides an opening XML stream header and the receiving entity replies in kind, the receiving entity provides a list of acceptable authentication
methods. The initiating entity chooses one method from the list
and sends it to the receiving entity as the value of the
'mechanism' attribute possessed by an <auth/> element, optionally
including an initial response to avoid a round trip.
exchange sequence: Challenges and responses are carried through the
exchange of <challenge/> elements from receiving entity to
initiating entity and <response/> elements from initiating entity
to receiving entity. The receiving entity reports failure by
sending a <failure/> element and success by sending a <success/>
element; the initiating entity aborts the exchange by sending an
<abort/> element. Upon successful negotiation, both sides
consider the original XML stream to be closed and new stream
headers are sent by both entities.
security layer negotiation: The security layer takes effect
immediately after sending the closing '>' character of the
<success/> element for the receiving entity, and immediately after
receiving the closing '>' character of the <success/> element for
the initiating entity. The order of layers is first [TCP], then
[TLS], then [SASL], then XMPP.
use of the authorization identity: The authorization identity can be
used in XMPP to denote the non-default <localpart@domainpart> of a
client; an empty string is equivalent to an absent authorization
identity.
7. Resource Binding
7.1. Fundamentals
After a client authenticates with a server, it MUST bind a specific
resource to the stream so that the server can properly address the
client. That is, there MUST be an XMPP resource associated with the
bare JID (<localpart@domainpart>) of the client, so that the address
for use over that stream is a full JID of the form
<localpart@domainpart/resource> (including the resourcepart). This
ensures that the server can deliver XML stanzas to and receive XML
stanzas from the client in relation to entities other than the server
itself or the client's account, as explained under Section 10.
Informational Note: The client could exchange stanzas with the
server itself or the client's account before binding a resource
since the full JID is needed only for addressing outside the
context of the stream negotiated between the client and the
server, but this is not commonly done.
After a client has bound a resource to the stream, it is referred to
as a "connected resource". A server SHOULD allow an entity to
maintain multiple connected resources simultaneously, where each
connected resource is associated with a distinct XML stream and is
differentiated from the other connected resources by a distinct
resourcepart.
Security Warning: A server SHOULD enable the administrator of an
XMPP service to limit the number of connected resources in order
to prevent certain denial-of-service attacks as described under
Section 13.12.
If, before completing the resource binding step, the client attempts
to send an XML stanza to an entity other than the server itself or
the client's account, the server MUST NOT process the stanza and MUST
close the stream with a <not-authorized/> stream error
(Section 4.9.3.12).
The XML namespace name for the resource binding extension is
'urn:ietf:params:xml:ns:xmpp-bind'.
7.2. Support
Support for resource binding is REQUIRED in XMPP client and server
implementations.
7.3. Stream Negotiation Rules
7.3.1. Mandatory-to-Negotiate
The parties to a stream MUST consider resource binding as mandatory-
to-negotiate.
7.3.2. Restart
After resource binding, the parties MUST NOT restart the stream.
7.4. Advertising Support
Upon sending a new response stream header to the client after
successful SASL negotiation, the server MUST include a <bind/>
element qualified by the 'urn:ietf:params:xml:ns:xmpp-bind' namespace
in the stream features it presents to the client.
The server MUST NOT include the resource binding stream feature until
after the client has authenticated, typically by means of successful
SASL negotiation.
S: <stream:stream
from='im.example.com'
id='gPybzaOzBmaADgxKXu9UClbprp0='
to='juliet@im.example.com'
version='1.0'
xml:lang='en'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
S: <stream:features>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'/>
</stream:features>
Upon being informed that resource binding is mandatory-to-negotiate,
the client MUST bind a resource to the stream as described in the
following sections.
7.5. Generation of Resource Identifiers
A resourcepart MUST at a minimum be unique among the connected
resources for that <localpart@domainpart>. Enforcement of this
policy is the responsibility of the server.
Security Warning: A resourcepart can be security-critical. For
example, if a malicious entity can guess a client's resourcepart
then it might be able to determine if the client (and therefore
the controlling principal) is online or offline, thus resulting in
a presence leak as described under Section 13.10.2. To prevent
that possibility, a client can either (1) generate a random
resourcepart on its own or (2) ask the server to generate a
resourcepart on its behalf. One method for ensuring that the
resourcepart is random is to generate a Universally Unique
Identifier (UUID) as specified in [UUID].
7.6. Server-Generated Resource Identifier
A server MUST be able to generate an XMPP resourcepart on behalf of a
client. The resourcepart generated by the server MUST be random (see
[RANDOM]).
7.6.1. Success Case
A client requests a server-generated resourcepart by sending an IQ
stanza of type "set" (see Section 8.2.3) containing an empty <bind/>
element qualified by the 'urn:ietf:params:xml:ns:xmpp-bind'
namespace.
C: <iq id='tn281v37' type='set'>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'/>
</iq>
Once the server has generated an XMPP resourcepart for the client, it
MUST return an IQ stanza of type "result" to the client, which MUST
include a <jid/> child element that specifies the full JID for the
connected resource as determined by the server.
S: <iq id='tn281v37' type='result'>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
<jid>
juliet@im.example.com/4db06f06-1ea4-11dc-aca3-000bcd821bfb
</jid>
</bind>
</iq>
7.6.2. Error Cases
When a client asks the server to generate a resourcepart during
resource binding, the following stanza error conditions are defined:
o The account has reached a limit on the number of simultaneous
connected resources allowed.
o The client is otherwise not allowed to bind a resource to the
stream.
Naturally, it is possible that error conditions not specified here
might occur, as described under Section 8.3.
7.6.2.1. Resource Constraint
If the account has reached a limit on the number of simultaneous
connected resources allowed, the server MUST return a <resource-
constraint/> stanza error (Section 8.3.3.18).
S: <iq id='tn281v37' type='error'>
<error type='wait'>
<resource-constraint
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
7.6.2.2. Not Allowed
If the client is otherwise not allowed to bind a resource to the stream, the server MUST return a <not-allowed/> stanza error (Section 8.3.3.10). S: <iq id='tn281v37' type='error'> <error type='cancel'> <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error> </iq>7.7. Client-Submitted Resource Identifier
Instead of asking the server to generate a resourcepart on its behalf, a client MAY attempt to submit a resourcepart that it has generated or that the controlling user has provided.7.7.1. Success Case
A client asks its server to accept a client-submitted resourcepart by sending an IQ stanza of type "set" containing a <bind/> element with a child <resource/> element containing non-zero-length XML character data. C: <iq id='wy2xa82b4' type='set'> <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'> <resource>balcony</resource> </bind> </iq> The server SHOULD accept the client-submitted resourcepart. It does so by returning an IQ stanza of type "result" to the client, including a <jid/> child element that specifies the full JID for the connected resource and contains without modification the client- submitted text. S: <iq id='wy2xa82b4' type='result'> <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'> <jid>juliet@im.example.com/balcony</jid> </bind> </iq> Alternatively, in accordance with local service policies the server MAY refuse the client-submitted resourcepart and override it with a resourcepart that the server generates.
S: <iq id='wy2xa82b4' type='result'>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
<jid>
juliet@im.example.com/balcony 4db06f06-1ea4-11dc-aca3-000bcd821bfb
</jid>
</bind>
</iq>
7.7.2. Error Cases
When a client attempts to submit its own XMPP resourcepart during
resource binding, the following stanza error conditions are defined
in addition to those described under Section 7.6.2:
o The provided resourcepart cannot be processed by the server.
o The provided resourcepart is already in use.
Naturally, it is possible that error conditions not specified here
might occur, as described under Section 8.3.
7.7.2.1. Bad Request
If the provided resourcepart cannot be processed by the server (e.g.,
because it is of zero length or because it otherwise violates the
rules for resourceparts specified in [XMPP-ADDR]), the server can
return a <bad-request/> stanza error (Section 8.3.3.1) but SHOULD
instead process the resourcepart so that it is in conformance.
S: <iq id='wy2xa82b4' type='error'>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
7.7.2.2. Conflict
If there is a currently connected client whose session has the
resourcepart being requested by the newly connecting client, the
server MUST do one of the following (which of these the server does
is a matter for implementation or local service policy, although
suggestions are provided below).
1. Override the resourcepart provided by the newly connecting client
with a server-generated resourcepart. This behavior is
encouraged, because it simplifies the resource binding process
for client implementations.
2. Disallow the resource binding attempt of the newly connecting
client and maintain the session of the currently connected
client. This behavior is neither encouraged nor discouraged,
despite the fact that it was implicitly encouraged in RFC 3920;
however, note that handling of the <conflict/> error is unevenly
supported among existing client implementations, which often
treat it as an authentication error and have been observed to
discard cached credentials when receiving it.
3. Terminate the session of the currently connected client and allow
the resource binding attempt of the newly connecting client.
Although this was the traditional behavior of early XMPP server
implementations, it is now discouraged because it can lead to a
never-ending cycle of two clients effectively disconnecting each
other; however, note that this behavior can be appropriate in
some deployment scenarios or if the server knows that the
currently connected client has a dead connection or broken stream
as described under Section 4.6.
If the server follows behavior #1, it returns an <iq/> stanza of type
"result" to the newly connecting client, where the <jid/> child of
the <bind/> element contains XML character data that indicates the
full JID of the client, including the resourcepart that was generated
by the server.
S: <iq id='wy2xa82b4' type='result'>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
<jid>
juliet@im.example.com/balcony 4db06f06-1ea4-11dc-aca3-000bcd821bfb
</jid>
</bind>
</iq>
If the server follows behavior #2, it sends a <conflict/> stanza
error (Section 8.3.3.2) in response to the resource binding attempt
of the newly connecting client but maintains the XML stream so that
the newly connecting client has an opportunity to negotiate a non-
conflicting resourcepart (i.e., the newly connecting client needs to
choose a different resourcepart before making another attempt to bind
a resource).
S: <iq id='wy2xa82b4' type='error'>
<error type='modify'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
If the server follows behavior #3, it returns a <conflict/> stream error (Section 4.9.3.3) to the currently connected client (as described under Section 4.9.3.3) and returns an IQ stanza of type "result" (indicating success) in response to the resource binding attempt of the newly connecting client. S: <iq id='wy2xa82b4' type='result'> <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'> <jid> juliet@im.example.com/balcony </jid> </bind> </iq>7.7.3. Retries
If an error occurs when a client submits a resourcepart, the server SHOULD allow a configurable but reasonable number of retries (at least 5 and no more than 10); this enables the client to tolerate incorrectly provided resourceparts (e.g., bad data formats or duplicate text strings) without being forced to reconnect. After the client has reached the retry limit, the server MUST close the stream with a <policy-violation/> stream error (Section 4.9.3.14).
(page 99 continued on part 5)