S:
4.6.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 element will
contain two or three child elements.
Saint-Andre Expires January 1, 2011 [Page 58]
Internet-Draft XMPP Core June 2010
C:
My keyboard layout is:
QWERTYUIOP{}|
ASDFGHJKL:"
ZXCVBNM<>?
S:
Some special application diagnostic information!
4.7. Simplified Stream Examples
This section contains two simplified examples of a stream-based
connection between a client and a server; these examples are included
for the purpose of illustrating the concepts introduced thus far.
Saint-Andre Expires January 1, 2011 [Page 59]
Internet-Draft XMPP Core June 2010
A basic connection:
C:
S:
[ ... channel encryption ... ]
[ ... authentication ... ]
[ ... resource binding ... ]
C:
Art thou not Romeo, and a Montague?
S:
Neither, fair saint, if either thee dislike.
C:
S:
Saint-Andre Expires January 1, 2011 [Page 60]
Internet-Draft XMPP Core June 2010
A connection gone bad:
C:
S:
[ ... channel encryption ... ]
[ ... authentication ... ]
[ ... resource binding ... ]
C:
No closing tag!
S:
More detailed examples are provided under Section 9.
5. STARTTLS Negotiation
Saint-Andre Expires January 1, 2011 [Page 61]
Internet-Draft XMPP Core June 2010
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, specifically a "STARTTLS"
extension that is modelled 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'.
Support for STARTTLS is REQUIRED in XMPP client and server
implementations. An administrator of a given deployment MAY specify
that TLS is obligatory 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.2. Stream Negotiation Rules
5.2.1. Mandatory-to-Negotiate
If the receiving entity advertises only the STARTTLS feature or if
the receiving entity includes the child element as
explained under Section 5.3.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.2.2. Restart
After TLS negotiation, the parties MUST restart the stream.
5.2.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 element qualified by the
'urn:ietf:params:xml:ns:xmpp-tls' namespace at depth=1 of the stream
as sent by the initiating entity, until the last character of the
element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls'
namespace at depth=1 of the stream 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
Saint-Andre Expires January 1, 2011 [Page 62]
Internet-Draft XMPP Core June 2010
readability.
5.2.4. Order of Negotiation
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.2.5. Renegotiation
XMPP entities MUST NOT attempt TLS renegotiation, and if either party
to a TLS-protected stream detects a TLS renegotiation attempt 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; see Section 13.3).
5.2.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.3. Process
5.3.1. Exchange of Stream Headers and Stream Features
The initiating entity resolves the hostname 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; if the initiating entity is
capable of STARTTLS negotiation, it MUST include the 'version'
attribute set to a value of at least "1.0" in the initial stream
header.
I:
The receiving entity MUST send a response stream header to the
initiating entity over the TCP connection opened by the initiating
Saint-Andre Expires January 1, 2011 [Page 63]
Internet-Draft XMPP Core June 2010
entity; if the receiving entity is capable of STARTTLS negotiation,
it MUST include the 'version' attribute set to a value of at least
"1.0" in the response stream header.
R: element qualified by the
'urn:ietf:params:xml:ns:xmpp-tls' namespace.
If the receiving entity considers STARTTLS negotiation to be
mandatory, the element SHOULD contain an empty
child element.
R:
5.3.2. Initiation of STARTTLS Negotiation
5.3.2.1. STARTTLS Command
In order to begin the STARTTLS negotiation, the initiating entity
issues the STARTTLS command (i.e., a 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:
The receiving entity MUST reply with either a element
(proceed case) or a element (failure case) qualified by
the 'urn:ietf:params:xml:ns:xmpp-tls' namespace.
Saint-Andre Expires January 1, 2011 [Page 64]
Internet-Draft XMPP Core June 2010
5.3.2.2. Failure Case
If the failure case occurs, the receiving entity MUST return a
element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls'
namespace and close the XML stream.
R:
R:
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.4.
5.3.2.3. Proceed Case
If the proceed case occurs, the receiving entity MUST return a
element qualified by the 'urn:ietf:params:xml:ns:xmpp-tls'
namespace.
R:
The receiving entity MUST consider the TLS negotiation to have begun
immediately after sending the closing '>' character of the
element to the initiating entity. The initiating entity MUST
consider the TLS negotiation to have begun immediately after
receiving the closing '>' character of the element from
the receiving entity.
The entities now proceed to TLS negotiation as explained in the next
section.
Saint-Andre Expires January 1, 2011 [Page 65]
Internet-Draft XMPP Core June 2010
5.3.3. TLS Negotiation
5.3.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 cipher suites
specified under Section 13.8, the receiving entity MUST present a
certificate.
3. So that mutual authentication will be possible, the receiving
entity SHOULD send a certificate request to the initiating entity
and the initiating entity SHOULD send a certificate (if
available) to the receiving entity.
4. The initiating entity MUST validate the certificate to determine
if the TLS negotiation will succeed; see Section 13.7.2 regarding
certificate validation procedures.
5. The receiving entity SHOULD choose which certificate to present
based on the 'to' attribute of the initial stream header.
6. Following successful TLS negotiation, all further data
transmitted by either party MUST be encrypted.
Security Note: See Section 13.8 regarding ciphers that MUST be
supported for TLS; naturally, other ciphers MAY be supported as
well.
5.3.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 tag before
terminating the TCP connection, since the receiving entity and
initiating entity MUST consider the original stream to be replaced
upon failure of the TLS negotiation.
The initiating entity MAY attempt to reconnect as explained under
Section 3.4, with or without attempting TLS negotiation (in
accordance with local service policy, user-configured prefernces,
Saint-Andre Expires January 1, 2011 [Page 66]
Internet-Draft XMPP Core June 2010
etc.).
5.3.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.
I:
Implementation Note: The initiating entity MUST NOT send a
closing 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.
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 re-using the old stream ID).
R: