nonrepeating (see [RANDOM] for recommendations regarding
randomness for security purposes). There SHOULD NOT be an ’id’
attribute on the XML stream header sent from the initiating entity
to the receiving entity; however, if an ’id’ attribute is
included, it SHOULD be silently ignored by the receiving entity.
o xml:lang -- An ’xml:lang’ attribute (as defined in Section 2.12 of
[XML]) SHOULD be included by the initiating entity on the header
for the initial stream to specify the default language of any
human-readable XML character data it sends over that stream. If
the attribute is included, the receiving entity SHOULD remember
that value as the default for both the initial stream and the
response stream; if the attribute is not included, the receiving
entity SHOULD use a configurable default value for both streams,
which it MUST communicate in the header for the response stream.
For all stanzas sent over the initial stream, if the initiating
entity does not include an ’xml:lang’ attribute, the receiving
entity SHOULD apply the default value; if the initiating entity
does include an ’xml:lang’ attribute, the receiving entity MUST
NOT modify or delete it (see also xml:lang (Section 9.1.5)). The
value of the ’xml:lang’ attribute MUST be an NMTOKEN (as defined
in Section 2.3 of [XML]) and MUST conform to the format defined in
RFC 3066 [LANGTAGS].
o version -- The presence of the version attribute set to a value of
at least "1.0" signals support for the stream-related protocols
(including stream features) defined in this specification.
Detailed rules regarding the generation and handling of this
attribute are defined below.
We can summarize as follows:
| initiating to receiving | receiving to initiating
---------+---------------------------+-----------------------
to | hostname of receiver | silently ignored
from | silently ignored | hostname of receiver
id | silently ignored | session key
xml:lang | default language | default language
version | signals XMPP 1.0 support | signals XMPP 1.0 support
4.4.1. Version Support
The version of XMPP specified herein is "1.0"; in particular, this
encapsulates the stream-related protocols (Use of TLS (Section 5),
Use of SASL (Section 6), and Stream Errors (Section 4.7)), as well as
the semantics of the three defined XML stanza types (<message/>,
<presence/>, and <iq/>). The numbering scheme for XMPP versions is
"<major>.<minor>". The major and minor numbers MUST be treated as
separate integers and each number MAY be incremented higher than a
single digit. Thus, "XMPP 2.4" would be a lower version than "XMPP
2.13", which in turn would be lower than "XMPP 12.3". Leading zeros
(e.g., "XMPP 6.01") MUST be ignored by recipients and MUST NOT be
sent.
The major version number should be incremented only if the stream and
stanza formats or required actions have changed so dramatically that
an older version entity would not be able to interoperate with a
newer version entity if it simply ignored the elements and attributes
it did not understand and took the actions specified in the older
specification. The minor version number indicates new capabilities,
and MUST be ignored by an entity with a smaller minor version number,
but used for informational purposes by the entity with the larger
minor version number. For example, a minor version number might
indicate the ability to process a newly defined value of the ’type’
attribute for message, presence, or IQ stanzas; the entity with the
larger minor version number would simply note that its correspondent
would not be able to understand that value of the ’type’ attribute
and therefore would not send it.
The following rules apply to the generation and handling of the
’version’ attribute within stream headers by implementations:
1. The initiating entity MUST set the value of the ’version’
attribute on the initial stream header to the highest version
number it supports (e.g., if the highest version number it
supports is that defined in this specification, it MUST set the
value to "1.0").
2. The receiving entity MUST set the value of the ’version’
attribute on the response stream header to either the value
supplied by the initiating entity or the highest version number
supported by the receiving entity, whichever is lower. The
receiving entity MUST perform a numeric comparison on the major
and minor version numbers, not a string match on
"<major>.<minor>".
3. If the version number included in the response stream header is
at least one major version lower than the version number included
in the initial stream header and newer version entities cannot
interoperate with older version entities as described above, the
initiating entity SHOULD generate an <unsupported-version/>
stream error and terminate the XML stream and underlying TCP
connection.
4. If either entity receives a stream header with no ’version’
attribute, the entity MUST consider the version supported by the
other entity to be "0.0" and SHOULD NOT include a ’version’
attribute in the stream header it sends in reply.
4.5. Namespace Declarations
The stream element MUST possess both a streams namespace declaration
and a default namespace declaration (as "namespace declaration" is
defined in the XML namespaces specification [XML-NAMES]). For
detailed information regarding the streams namespace and default
namespace, see Namespace Names and Prefixes (Section 11.2).
4.6. Stream Features
If the initiating entity includes the ’version’ attribute set to a
value of at least "1.0" in the initial stream header, the receiving
entity MUST send a <features/> child element (prefixed by the streams
namespace prefix) to the initiating entity in order to announce any
stream-level features that can be negotiated (or capabilities that
otherwise need to be advertised). Currently, this is used only to
advertise Use of TLS (Section 5), Use of SASL (Section 6), and
Resource Binding (Section 7) as defined herein, and for Session
Establishment as defined in [XMPP-IM]; however, the stream features
functionality could be used to advertise other negotiable features in
the future. If an entity does not understand or support some
features, it SHOULD silently ignore them. If one or more security
features (e.g., TLS and SASL) need to be successfully negotiated
before a non-security-related feature (e.g., Resource Binding) can be
offered, the non-security-related feature SHOULD NOT be included in
the stream features that are advertised before the relevant security
features have been negotiated.
4.7. Stream Errors
The root stream element MAY contain an <error/> child element that is
prefixed by the streams namespace prefix. The error child MUST be
sent by a compliant entity (usually a server rather than a client) if
it perceives that a stream-level error has occurred.
4.7.1. Rules
The following rules apply to stream-level errors:
o It is assumed that all stream-level errors are unrecoverable;
therefore, if an error occurs at the level of the stream, the
entity that detects the error MUST send a stream error to the
other entity, send a closing </stream> tag, and terminate the
underlying TCP connection.
o If the error occurs while the stream is being set up, the
receiving entity MUST still send the opening <stream> tag, include
the <error/> element as a child of the stream element, send the
closing </stream> tag, and terminate the underlying TCP
connection. In this case, if the initiating entity provides an
unknown host in the ’to’ attribute (or provides no ’to’ attribute
at all), the server SHOULD provide the server’s authoritative
hostname in the ’from’ attribute of the stream header sent before
termination.
4.7.2. Syntax
The syntax for stream errors is as follows:
<stream:error>
<defined-condition xmlns=’urn:ietf:params:xml:ns:xmpp-streams’/>
<text xmlns=’urn:ietf:params:xml:ns:xmpp-streams’
xml:lang=’langcode’>
OPTIONAL descriptive text
</text>
[OPTIONAL application-specific condition element]
</stream:error>
The <error/> element:
o MUST contain a child element corresponding to one of the defined
stanza error conditions defined below; this element MUST be
qualified by the ’urn:ietf:params:xml:ns:xmpp-streams’ namespace
o MAY contain a <text/> child containing XML character data that
describes the error in more detail; this element MUST be qualified
by the ’urn:ietf:params:xml:ns:xmpp-streams’ namespace and SHOULD
possess an ’xml:lang’ attribute specifying the natural language of
the XML character data
o MAY contain a child element for an application-specific error
condition; this element MUST be qualified by an
application-defined namespace, and its structure is defined by
that namespace
The <text/> element is OPTIONAL. If included, it SHOULD be used only
to provide descriptive or diagnostic information that supplements the
meaning of a defined condition or application-specific condition. It
SHOULD NOT be interpreted programmatically by an application. It
SHOULD NOT be used as the error message presented to a user, but MAY
be shown in addition to the error message associated with the
included condition element (or elements).
4.7.3. Defined Conditions
The following stream-level error conditions are defined:
o <bad-format/> -- the entity has sent XML that cannot be processed;
this error MAY be used instead of the more specific XML-related
errors, such as <bad-namespace-prefix/>, <invalid-xml/>,
<restricted-xml/>, <unsupported-encoding/>, and
<xml-not-well-formed/>, although the more specific errors are
preferred.
o <bad-namespace-prefix/> -- the entity has sent a namespace prefix
that is unsupported, or has sent no namespace prefix on an element
that requires such a prefix (see XML Namespace Names and Prefixes
(Section 11.2)).
o <conflict/> -- the server is closing the active stream for this
entity because a new stream has been initiated that conflicts with
the existing stream.
o <connection-timeout/> -- the entity has not generated any traffic
over the stream for some period of time (configurable according to
a local service policy).
o <host-gone/> -- the value of the ’to’ attribute provided by the
initiating entity in the stream header corresponds to a hostname
that is no longer hosted by the server.
o <host-unknown/> -- the value of the ’to’ attribute provided by the
initiating entity in the stream header does not correspond to a
hostname that is hosted by the server.
o <improper-addressing/> -- a stanza sent between two servers lacks
a ’to’ or ’from’ attribute (or the attribute has no value).
o <internal-server-error/> -- the server has experienced a
misconfiguration or an otherwise-undefined internal error that
prevents it from servicing the stream.
o <invalid-from/> -- the JID or hostname provided in a ’from’
address does not match an authorized JID or validated domain
negotiated between servers via SASL or dialback, or between a
client and a server via authentication and resource binding.
o <invalid-id/> -- the stream ID or dialback ID is invalid or does
not match an ID previously provided.
o <invalid-namespace/> -- the streams namespace name is something
other than "http://etherx.jabber.org/streams" or the dialback
namespace name is something other than "jabber:server:dialback"
(see XML Namespace Names and Prefixes (Section 11.2)).
o <invalid-xml/> -- the entity has sent invalid XML over the stream
to a server that performs validation (see Validation (Section
11.3)).
o <not-authorized/> -- the entity has attempted to send data before
the stream has been authenticated, or otherwise is not authorized
to perform an action related to stream negotiation; the receiving
entity MUST NOT process the offending stanza before sending the
stream error.
o <policy-violation/> -- the entity has violated some local service
policy; the server MAY choose to specify the policy in the <text/>
element or an application-specific condition element.
o <remote-connection-failed/> -- the server is unable to properly
connect to a remote entity that is required for authentication or
authorization.
o <resource-constraint/> -- the server lacks the system resources
necessary to service the stream.
o <restricted-xml/> -- the entity has attempted to send restricted
XML features such as a comment, processing instruction, DTD,
entity reference, or unescaped character (see Restrictions
(Section 11.1)).
o <see-other-host/> -- the server will not provide service to the
initiating entity but is redirecting traffic to another host; the
server SHOULD specify the alternate hostname or IP address (which
MUST be a valid domain identifier) as the XML character data of
the <see-other-host/> element.
o <system-shutdown/> -- the server is being shut down and all active
streams are being closed.
o <undefined-condition/> -- the error condition is not one of those
defined by the other conditions in this list; this error condition
SHOULD be used only in conjunction with an application-specific
condition.
o <unsupported-encoding/> -- the initiating entity has encoded the
stream in an encoding that is not supported by the server (see
Character Encoding (Section 11.5)).
o <unsupported-stanza-type/> -- the initiating entity has sent a
first-level child of the stream that is not supported by the
server.
o <unsupported-version/> -- the value of the ’version’ attribute
provided by the initiating entity in the stream header specifies a
version of XMPP that is not supported by the server; the server
MAY specify the version(s) it supports in the <text/> element.
o <xml-not-well-formed/> -- the initiating entity has sent XML that
is not well-formed as defined by [XML].
4.7.4. Application-Specific Conditions
As noted, an application MAY provide application-specific stream
error information by including a properly-namespaced child in the
error element. The application-specific element SHOULD supplement or
further qualify a defined element. Thus the <error/> element will
contain two or three child elements:
<stream:error>
<xml-not-well-formed
xmlns=’urn:ietf:params:xml:ns:xmpp-streams’/>
<text xml:lang=’en’ xmlns=’urn:ietf:params:xml:ns:xmpp-streams’>
Some special application diagnostic information!
</text>
<escape-your-data xmlns=’application-ns’/>
</stream:error>
</stream:stream>
4.8. Simplified Stream Examples
This section contains two simplified examples of a stream-based
"session" of a client on a server (where the "C" lines are sent from
the client to the server, and the "S" lines are sent from the server
to the client); these examples are included for the purpose of
illustrating the concepts introduced thus far.
A basic "session":
C: <?xml version=’1.0’?>
<stream:stream
to=’example.com’
xmlns=’jabber:client’
xmlns:stream=’http://etherx.jabber.org/streams’
version=’1.0’>
S: <?xml version=’1.0’?>
<stream:stream
from=’example.com’
id=’someid’
xmlns=’jabber:client’
xmlns:stream=’http://etherx.jabber.org/streams’
version=’1.0’>
... encryption, authentication, and resource binding ...
C: <message from=’juliet@example.com’
to=’romeo@example.net’
xml:lang=’en’>
C: <body>Art thou not Romeo, and a Montague?</body>
C: </message>
S: <message from=’romeo@example.net’
to=’juliet@example.com’
xml:lang=’en’>
S: <body>Neither, fair saint, if either thee dislike.</body>
S: </message>
C: </stream:stream>
S: </stream:stream>
A "session" gone bad:
C: <?xml version=’1.0’?>
<stream:stream
to=’example.com’
xmlns=’jabber:client’
xmlns:stream=’http://etherx.jabber.org/streams’
version=’1.0’>
S: <?xml version=’1.0’?>
<stream:stream
from=’example.com’
id=’someid’
xmlns=’jabber:client’
xmlns:stream=’http://etherx.jabber.org/streams’
version=’1.0’>
... encryption, authentication, and resource binding ...
C: <message xml:lang=’en’>
<body>Bad XML, no closing body tag!
</message>
S: <stream:error>
<xml-not-well-formed
xmlns=’urn:ietf:params:xml:ns:xmpp-streams’/>
</stream:error>
S: </stream:stream>
5. Use of TLS
5.1. Overview
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 [TLS], along with a
"STARTTLS" extension that is modelled after similar extensions for
the IMAP [IMAP], POP3 [POP3], and ACAP [ACAP] protocols as described
in RFC 2595 [USINGTLS]. The namespace name for the STARTTLS
extension is ’urn:ietf:params:xml:ns:xmpp-tls’.
An administrator of a given domain MAY require the use of TLS for
client-to-server communications, server-to-server communications, or
both. Clients SHOULD use TLS to secure the streams prior to
attempting the completion of SASL negotiation (Section 6), and
servers SHOULD use TLS between two domains for the purpose of
securing server-to-server communications.
The following rules apply:
1. An initiating entity that complies with this specification MUST
include the ’version’ attribute set to a value of "1.0" in the
initial stream header.
2. If the TLS negotiation occurs between two servers, communications
MUST NOT proceed until the Domain Name System (DNS) hostnames
asserted by the servers have been resolved (see Server-to-Server
Communications (Section 14.4)).
3. When a receiving entity that complies with this specification
receives an initial stream header that includes the ’version’
attribute set to a value of at least "1.0", after sending a
stream header in reply (including the version flag), it MUST
include a <starttls/> element (qualified by the
’urn:ietf:params:xml:ns:xmpp-tls’ namespace) along with the list
of other stream features it supports.
4. If the initiating entity chooses to use TLS, TLS negotiation MUST
be completed before proceeding to SASL negotiation; this order of
negotiation is required 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 provided during prior TLS negotiation.
5. During TLS negotiation, an entity MUST NOT send any white space
characters (matching production [3] content of [XML]) within the
root stream element as separators between elements (any white
space characters shown in the TLS examples below are included for
the sake of readability only); this prohibition helps to ensure
proper security layer byte precision.
6. The receiving entity MUST consider the TLS negotiation to have
begun immediately after sending the closing ">" character of the
<proceed/> element. 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.
7. The initiating entity MUST validate the certificate presented by
the receiving entity; see Certificate Validation (Section 14.2)
regarding certificate validation procedures.
8. Certificates MUST be checked against the hostname as provided by
the initiating entity (e.g., a user), not the hostname as
resolved via the Domain Name System; e.g., if the user specifies
a hostname of "example.com" but a DNS SRV [SRV] lookup returned
"im.example.com", the certificate MUST be checked as
"example.com". If a JID for any kind of XMPP entity (e.g.,
client or server) is represented in a certificate, it MUST be
represented as a UTF8String within an otherName entity inside the
subjectAltName, using the [ASN.1] Object Identifier
"id-on-xmppAddr" specified in Section 5.1.1 of this document.
9. If the TLS negotiation is successful, the receiving entity MUST
discard any knowledge obtained in an insecure manner from the
initiating entity before TLS takes effect.
10. If the TLS negotiation is successful, the initiating entity MUST
discard any knowledge obtained in an insecure manner from the
receiving entity before TLS takes effect.
11. If the TLS negotiation is successful, the receiving entity MUST
NOT offer the STARTTLS extension to the initiating entity along
with the other stream features that are offered when the stream
is restarted.
12. If the TLS negotiation is successful, the initiating entity MUST
continue with SASL negotiation.
13. If the TLS negotiation results in failure, the receiving entity
MUST terminate both the XML stream and the underlying TCP
connection.
14. See Mandatory-to-Implement Technologies (Section 14.7) regarding
mechanisms that MUST be supported.
5.1.1. ASN.1 Object Identifier for XMPP Address
The [ASN.1] Object Identifier "id-on-xmppAddr" described above is
defined as follows:
id-pkix OBJECT IDENTIFIER ::= { iso(1) identified-organization(3)
dod(6) internet(1) security(5) mechanisms(5) pkix(7) }
id-on OBJECT IDENTIFIER ::= { id-pkix 8 } -- other name forms
id-on-xmppAddr OBJECT IDENTIFIER ::= { id-on 5 }
XmppAddr ::= UTF8String
This Object Identifier MAY also be represented in the dotted display
format as "1.3.6.1.5.5.7.8.5".
5.2. Narrative
When an initiating entity secures a stream with a receiving entity
using TLS, the steps involved are as follows:
1. The initiating entity opens a TCP connection and initiates the
stream by sending the opening XML stream header to the receiving
entity, including the ’version’ attribute set to a value of at
least "1.0".
2. The receiving entity responds by opening a TCP connection and
sending an XML stream header to the initiating entity, including
the ’version’ attribute set to a value of at least "1.0".
3. The receiving entity offers the STARTTLS extension to the
initiating entity by including it with the list of other
supported stream features (if TLS is required for interaction