moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 10:12:19 -05:00
Code Issues Releases Wiki Activity

detailed protocol flows for Step 1 and Step 2

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1988 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-06-17 23:27:36 +00:00
parent 947fc5a196
commit a707bad489
1 changed files with 288 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

388
xep-0220.xml
View File

@ -7,7 +7,7 @@
<xep>
<header>
<title>Server Dialback</title>
<abstract>This specification defines the Server Dialback protocol, which is used between XMPP servers to provide identity verification. Server dialback uses the Domain Name System (DNS) as the basis for verifying identity; the basic approach is that when a receiving server receives a server-to-server connection requesting from an originating server, it does not accept the request until it has verified a key with an authoritative server for the domain asserted by the originating server. Although Server Dialback does not provide strong authentication or trusted federation and although it is subject to DNS poisoning attacks, since its development in the year 2000 it has effectively prevented most instances of address spoofing on the XMPP network.</abstract>
<abstract>This specification defines the Server Dialback protocol, which is used between XMPP servers to provide identity verification. Server dialback uses the Domain Name System (DNS) as the basis for verifying identity; the basic approach is that when a receiving server receives a server-to-server connection request from an originating server, it does not accept the request until it has verified a key with an authoritative server for the domain asserted by the originating server. Although Server Dialback does not provide strong authentication or trusted federation and although it is subject to DNS poisoning attacks, since its development in the year 2000 it has effectively prevented most instances of address spoofing on the XMPP network.</abstract>
&LEGALNOTICE;
<number>0220</number>
<status>Experimental</status>
@ -43,11 +43,13 @@
</header>
<section1 topic="Introduction" anchor="intro">
<section2 topic="Why Dialback?" anchor="intro-why">
<p>When Jabber technologies were first developed in 1998, they were conceived of as a client-server system similar to email, wherein a client would connect to a server in order to communicate with other clients. Similarly, servers would connect with peer servers to provide inter-domain communication (often called "federation"). In a system that allows federation, it is important for a server to be able to determine the identity of a peer server; accepting a connection from any peer without determining its identity would result in the use of merely asserted identities and a completely uncontrolled approach to federation, which would rapidly devolve into chaos on the open Internet. Clearly such a state of affairs would be unsustainable for a network protocol aiming for widespread deployment.</p>
<p>Unfortunately, that was the state of affairs on the Jabber network during the earliest releases of the original &jabberd; server codebase (up through the 1.0 release in May 2000). Therefore the open-source developer community designed a protocol ("Server Dialback") for weak identity verification based on the Domain Name System (DNS), built support for that protocol into the jabberd 1.2 server (released in October 2000), and mandated support for that protocol on the emerging Jabber server network.</p>
<p>When the core Jabber protocols were formalized by the XMPP Working Group of the &IETF; in 2002-2004, support for strong identity verification was added. That support takes the form of Transport Layer Security (TLS) for encryption of server-to-server XML streams and the Simple Authentication and Security Layer (SASL) for authentication of such streams, using digital certificates issued by trusted root certification authorities (CAs). Documentation of TLS and SASL within XMPP is provided in &xmppcore;. However, the Server Dialback protocol is still in wide use, and probably will be for the foreseeable future given the difficulty (real or perceived) of obtaining digital certificates issued by common certification authorities (CAs). Therefore it is important to maintain accurate documentation of the Server Dialback protocol. Such documentation was originally provided in &rfc3920;. Although that documentation was removed from &rfc3920bis;, it is still provided in this specification for the sake of interoperability.</p>
</section2>
<section2 topic="Federation Models" anchor="intro-models">
<p>There are at least four levels of server-to-server federation in Jabber/XMPP networks:</p>
<ol start='1'>
@ -59,11 +61,13 @@
<p>This specification documents the technology that enabled the Jabber server network to advance beyond Permissive Federation to Verified Federation. Combined with the use of TLS, Server Dialback can also result in Encrypted Federation. However, Trusted Federation is not possible with Server Dialback.</p>
<p>Note: For detailed examples showing the protocol flows and outcomes of dialback negotiation for a wide variety of federation scenarios, refer to &xep0238;.</p>
</section2>
<section2 topic="What Dialback Accomplishes" anchor="intro-what">
<p>Server Dialback is a method for weak identify verification. Such verification depends on the Domain Name System (DNS) and the use of keys based on a shared secret known to all XMPP servers within a given trust domain (e.g., the trust domain associated with a given second-level DNS domain such as "example.com" and all of its subdomains).</p>
<p>Since October 2000, the use of Server Dialback has made it more difficult to spoof the hostnames of servers (and therefore the addresses of sent messages) on the XMPP network. However, Server Dialback does not provide authentication between servers and is not a security mechanism. Domains requiring high security are advised to use TLS and SASL with certificates issued by trusted roots.</p>
<p>Server Dialback is uni-directional, and results in weak identity verification for one XML stream in one direction. Because Server Dialback is not an authentication mechanism, mutual authentication is not possible via dialback. Therefore, Server Dialback must be completed in each direction in order to enable bi-directional communication between two domains.</p>
</section2>
<section2 topic="When Dialback Is Used" anchor="intro-when">
<p>Server Dialback is typically used in two scenarios:</p>
<ol start='1'>
@ -74,6 +78,7 @@
<p>Dialback is not used if SASL is used for server-to-server authentication, since SASL provides strong authentication using certificates, pre-established passwords, or other credentials.</p>
<p>Note: Use of Server Dialback cannot proceed unless a server determines that its peer supports the Server Dialback protocol. For details, see the <link url='support'>Determining Support</link> section of this document.</p>
</section2>
<section2 topic="How Dialback Works" anchor="intro-howitworks">
<p>The basic idea behind Server Dialback is that a receiving server does not accept XMPP traffic from a sending server until it has "called back" the authoritative server for the domain asserted by the sending server, and verified that the sending server is truly authorized to generate XMPP traffic for that domain.</p>
<p>A helpful analogy might be the following telephone scenario:</p>
@ -86,12 +91,12 @@
<li>You then take the rep off hold and continue the conversation.</li>
</ol>
<p>In Server Dialback, the equivalent of the customer service representative is the ORIGINATING SERVER, i.e., the machine that wants to send a message to an entity at a destination domain and thus is attempting to establish a connection between the two servers. The equivalent of the person being called is the RECEIVING SERVER, i.e., the machine to which the originating server has opened a connection for the purpose of sending the message and thus is trying to authenticate that the Originating Server represents the domain which it claims to be. And the equivalent of the bank is the AUTHORITATIVE SERVER, i.e., the machine that answers to a DNS lookup for the domain asserted by the originating server (which is not necessarily the machine associated with the originating server); for basic environments this will be the Originating Server, but it could be a separate machine in the Originating Server's network (where "network" is defined by knowledge of a shared secret for verification of dialback keys).</p>
<p>The basic flow of events is as follows:</p>
<p>The basic flow of events in Server Dialback is as follows:</p>
<ol start='1'>
<li>The Originating Server performs a DNS lookup on the hostname of the Receiving Server, opens a TCP connection to the discovered IP address and port, and establishes an XML stream with the Receiving Server.</li>
<li>The Originating Server sends a locally-generated "key" value over its XML stream with the Receiving Server.</li>
<li>The Originating Server generates a dialback key and sends that value over its XML stream with the Receiving Server.</li>
<li>The Receiving Server does not immediately accept the connection but instead performs a DNS lookup on the hostname of the Authoritative Server, opens a TCP connection to the discovered IP address and port, and establishes an XML stream with the Authoritative Server.</li>
<li>The Receiving Server sends the same "key" value over its XML stream with the Authoritative Server for verification.</li>
<li>The Receiving Server sends the same dialback key over its XML stream with the Authoritative Server for verification.</li>
<li>The Authoritative Server replies that key is valid or invalid.</li>
<li>The Receiving Server informs the Originating Server whether its identify has been verified or not.</li>
</ol>
@ -109,32 +114,34 @@ Originating Receiving
| send dialback key | Server
| ----------------------> | -------------
| | |
| perform DNS lookup, |
| open TCP connection, |
| and establish stream |
| ----------------------> |
| |
| send verify request |
| ----------------------> |
| |
| send verify response |
| <---------------------- |
|
| | perform DNS lookup, |
| | open TCP connection, |
| | and establish stream |
| | ----------------------> |
| | |
| | send verify request |
| | ----------------------> |
| | |
| | send verify response |
| | <---------------------- |
| |
| report dialback result |
| <---------------------- |
| |
]]></code>
<p>Note: In Steps 1 and 3, it is not always necessary to open a new TCP connection and establish a new stream; for details, see the section on <link url='#reuse'>Reuse of Negotiated Connections</link>.</p>
<p>Note: In Steps 1 and 3, it is not always necessary to open a new TCP connection and establish a new stream; for details, see the section on <link url='#piggybacking'>Reuse of Negotiated Connections</link>.</p>
</section2>
</section1>
<section1 topic="Protocol" anchor="protocol">
<p>This section describes the detailed protocol interaction between the Originating Server, the Receiving Server, and the Authoritative Server.</p>
<p>This section uses the following domain names, IP addresses, stream IDs, and shared secret in the examples:</p>
<p>The examples in this section use the following domain names, IP addresses, stream IDs, and shared secret:</p>
<ul>
<li>The Originating Server is "example.org" (there is no IP address associated with this domain since it is merely asserted by the Originating Server).</li>
<li>The Receiving Server is "xmpp.example.com" and the discovered IP address for the XMPP service at that domain is "192.0.2.0".</li>
<li>The Authoritative Server is "example.org" and the discovered IP address for the XMPP service at that domain is "192.0.2.1".</li>
<li>The Receiving Server is "xmpp.example.com" and the discovered IP address for the XMPP service at that domain is "192.0.2.1" or "192.0.2.2" (see below).</li>
<li>The Authoritative Server is "example.org" and the discovered IP address for the XMPP service at that domain is "192.0.2.23".</li>
<li>The stream ID of the stream from the Originating Server to the Receiving Server is "D60000229F".</li>
<li>The shared secret known by the Authoritative Server's network is "s3cr3tf0rd14lb4ck".</li>
</ul>
@ -145,14 +152,30 @@ Originating Receiving
<li>"R2A:" -- packets sent from the Receiving Server to the Authoritative Server.</li>
<li>"A2R:" -- packets sent from the Authoritative Server to the Receiving Server.</li>
</ul>
<p>Note: A dialback namespace declaration is REQUIRED for all elements used in Server Dialback. The name of the dialback namespace MUST be 'jabber:server:dialback'. All elements qualified by this namespace MUST be prefixed. An implementation SHOULD generate only the 'db:' prefix for such elements and MAY accept only the 'db:' prefix.</p>
<p>Note: Any error that occurs during dialback negotiation MUST be considered a stream error, resulting in termination of the stream and potentially of the underlying TCP connection. The possible error conditions are specified in the protocol description below.</p>
<p>The flow of events is as follows.</p>
<section2 topic='Stream Setup Between Originating Server and Receiving Server' anchor='proto-setup-o2r'>
<p>The Originating Server (asserted to be "example.org") performs a DNS lookup for the Receiving Server (in accordance with the procedure described in <cite>RFC 3920</cite>) and establishes a TCP connection to the Receiving Server at the IP address and port discovered during the DNS lookup (here assumed to be "192.0.2.0" and "5269"). Alternatively, the Originating Server MAY reuse an existing TCP connnection to the Receiving Server here rather than opening a new TCP connection (see <link url='piggybacking'>Piggybacking</link>).</p>
<p>The Originating Server then sends a stream header to the Receiving Server:</p>
<example caption="Stream Header"><![CDATA[
<section2 topic='Stream Setup Between Originating Server and Receiving Server' anchor='o2r'>
<section3 topic='Originating Server Resolves Receiving Server' anchor='o2r-resolve'>
<p>Before opening a TCP connection to the Receiving Server, the Originating Server must first determine the appropriate IP address and port at which to connect. This is done by resolving the Receiving Server's hostname ("xmpp.example.com") using the Domain Name System. As described in <cite>XMPP Core</cite>, the Originating Server shall first attempt to resolve a TCP service of _xmpp-server for that hostname using DNS SRV records. Here we assume that example.com has the following records in its DNS configuration:</p>
<example caption="DNS SRV Record for Receiving Server"><![CDATA[
_xmpp-server._tcp.xmpp.example.com. 86400 IN SRV 10 0 5269 x1.example.com
_xmpp-server._tcp.xmpp.example.com. 86400 IN SRV 20 0 9625 x2.example.com
]]></example>
<p>These records show that server-to-server connections for the XMPP service "xmpp.example.com" are serviced by two machines: x1.example.com at port 5269 and x2.example.com at port 9625.</p>
<p>The Originating Server would then choose one of these machines to resolve further. Here we assume that the Originating Server chooses x2.example.com and that a standard A lookup for x2.example.com yields an IP address of "192.0.2.2".</p>
<p>Note: As described in <cite>XMPP Core</cite>, if the Receiving Server does not provide appropriate DNS SRV records then in order to resolve the hostname of the Receiving Server the Originating Server may fall back to normal IPv4/IPv6 address record resolution to determine the IP address and assume a port of 5269 as registered with the IANA.</p>
</section3>
<section3 topic='Originating Server Opens TCP Connection' anchor='o2r-connect'>
<p>Once the Originating Server has resolved "xmpp.example.com" to an IP address of 192.0.2.2 and port of 9625, it opens a TCP connection to that IP and port.</p>
<p>Note: Instead of opening a new TCP connection to the Receiving Server, the Originating Server MAY reuse an existing TCP connnection; for details, see the <link url='piggybacking'>Piggybacking</link> section of this document.</p>
</section3>
<section3 topic='Originating Server Sends Initial Stream Header' anchor='o2r-sendinitial'>
<p>Once the Originating Server has opened a TCP connection to the resolved IP address and port of the Receiving Server, it sends an initial stream header to the Receiving Server as described in <cite>XMPP Core</cite>.</p>
<example caption="Initial Stream Header"><![CDATA[
O2R: <stream:stream
xmlns='jabber:server'
xmlns:db='jabber:server:dialback'
@ -160,10 +183,21 @@ O2R: <stream:stream
from='example.org'
to='xmpp.example.com'
version='1.0'>
]]></example>
<p>Note: The inclusion of the xmlns:db namespace declaration with the name shown indicates to the Receiving Server that the Originating Server supports Server Dialback. If any of the namespace names provided by the Originating Server is incorrect, then the Receiving Server MUST generate an &lt;invalid-namespace/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. If the value of the 'to' address provided by the Originating Server does not match a hostname serviced by the Receiving Server, then the Receiving Server MUST generate a &lt;host-unknown/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<p>The Receiving Server SHOULD send a stream header back to the Originating Server over the same TCP connection, including a unique ID for this interaction:</p>
<example caption="Stream Header"><![CDATA[
]]></example>
<p>In addition to the core XMPP rules regarding initial stream headers, the following dialback-related rules apply to the initial stream header:</p>
<ol start='1'>
<li>It MUST include a declaration for the Server Dialback namespace.</li>
<li>The Server Dialback namespace MUST be 'jabber:server:dialback'.</li>
<li>The prefix for the Server Dialback namespace SHOULD be 'db:'.</li>
</ol>
<p>Note: An implementation MAY accept only the 'db:' namespace prefix.</p>
</section3>
<section3 topic='Receiving Server Processes Initial Stream Header' anchor='o2r-processinitial'>
<p>When the Receiving Server receives the initial stream header from the Originating Server, it MUST proceed as follows.</p>
<section4 topic='Success Case' anchor='o2r-processinitial-success'>
<p>If the Receiving Server can successfully process the initial stream header, it MUST return a response stream header to the Originating Server over the same TCP connection.</p>
<example caption="Response Stream Header"><![CDATA[
R2O: <stream:stream
xmlns='jabber:server'
xmlns:db='jabber:server:dialback'
@ -172,31 +206,233 @@ R2O: <stream:stream
id='D60000229F'
to='example.org'
version='1.0'>
]]></example>
<p>Note: The Receiving Server SHOULD reply but MAY silently terminate the XML stream and underlying TCP connection depending on local security policies; however, if the Receiving Server desires to proceed, it MUST send a stream header back to the Originating Server. If any of the namespace names provided by the Receiving Server is incorrect, then the Originating Server MUST generate an &lt;invalid-namespace/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. If the value of the 'to' address provided by the Receiving Server does not match a hostname serviced by the Originating Server, then the Originating Server MUST generate a &lt;host-unknown/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<p>The Receiving Server SHOULD also send stream features to the Originating Server, including the dialback feature:</p>
<example caption="Stream Features"><![CDATA[
]]></example>
<p>In addition to the core XMPP rules regarding response stream headers, the following dialback-related rules apply to the response stream header:</p>
<ol start='1'>
<li>If the initial stream header included a Server Dialback namespace declaration and the Receiving Server supports the Server Dialback protocol, the response stream header also MUST include a declaration for the Server Dialback namespace.</li>
<li>If the initial stream header did not include a Server Dialback namespace declaration and the Receiving Server supports the Server Dialback protocol, the response stream header MAY include a Server Dialback namespace declaration.</li>
<li>If the response stream header includes a Server Dialback namespace declaration, the Server Dialback namespace MUST be 'jabber:server:dialback' and the prefix for the Server Dialback namespace SHOULD be 'db:'.</li>
</ol>
<p>After sending the response stream header, the Receiving Server shall also send stream features to the Originating Server. The Receiving Server SHOULD include the dialback feature in its initial stream features advertisement, including an indication of whether Server Dialback negotiation is optional or required.</p>
<example caption="Stream Features"><![CDATA[
R2O: <stream:features>
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
<dialback xmlns='urn:xmpp:features:dialback'/>
<dialback xmlns='urn:xmpp:features:dialback'>
<required/>
</dialback>
</stream:features>
]]></example>
]]></example>
</section4>
<section4 topic='Error Cases' anchor='o2r-processinitial-error'>
<p>There are several reasons why processing of the initial stream header might fail:</p>
<ol start='1'>
<li>The Server Dialback namespace name provided by the Originating Server is incorrect.</li>
<li>The Server Dialback namespace prefix provided by the Originating Server is not supported by the Receiving Server (note: an implementation MAY accept only the 'db:' namespace prefix).</li>
<li>The value of the 'to' address provided by the Originating Server does not match a hostname serviced by the Receiving Server.</li>
<li>Communication with the hostname of the 'from' address provided by the Originating Server is not accepted by the Receiving Server.</li>
</ol>
<p>These error cases are described more fully in the rest of this section.</p>
<p>If the Server Dialback namespace name is incorrect, then the Receiving Server SHOULD generate an &lt;invalid-namespace/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Invalid Namespace"><![CDATA[
R2O: <stream:error>
<invalid-namespace
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
R2O: </stream:stream>
]]></example>
<p>If the Server Dialback namespace prefix is not supported by the Receiving Server, then the Receiving Server SHOULD generate a &lt;bad-namespace-prefix/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Bad Namespace Prefix"><![CDATA[
R2O: <stream:error>
<bad-namespace-prefix
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
R2O: </stream:stream>
]]></example>
<p>If the value of the 'to' address provided by the Originating Server does not match a hostname serviced by the Receiving Server, then the Receiving Server SHOULD generate a &lt;host-unknown/&gt; or &lt;host-gone/&gt; stream error condition (as appropriate) and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Host Unknown"><![CDATA[
R2O: <stream:error>
<host-unknown
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
R2O: </stream:stream>
]]></example>
<p>If the Receiving Server does not allow communication with the hostname of the 'from' address provided by the Originating Server, then the Receiving Server SHOULD generate a &lt;not-authorized/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Not Authorized"><![CDATA[
R2O: <stream:error>
<not-authorized
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
R2O: </stream:stream>
]]></example>
<p>Note: The foregoing error flows specify that the Receiving Server SHOULD return a stream error. However, depending on local security policies, the Receiving Server MAY silently terminate the XML stream and underlying TCP connection instead of returning a stream error (e.g., to prevent certain denial of service attacks).</p>
</section4>
</section3>
<section3 topic='Originating Server Processes Response Stream Header' anchor='o2r-processresponse'>
<p>When the Originating Server receives the response stream header from the Receiving Server, it MUST proceed as follows.</p>
<section4 topic='Success Case' anchor='o2r-processresponse-success'>
<p>If the response stream header can be successfully processed, the Originating Server MUST generate and send a dialback key as described under <link url='key'>Generation and Exchange of Dialback Key</link>.</p>
</section4>
<section4 topic='Error Cases' anchor='o2r-response-error'>
<p>There are several reasons why processing of the response stream header might fail:</p>
<ol start='1'>
<li>The Server Dialback namespace name provided by the Receiving Server is incorrect.</li>
<li>The Server Dialback namespace prefix provided by the Receiving Server is not supported by the Originating Server (note: an implementation MAY accept only the 'db:' namespace prefix).</li>
<li>The value of the 'to' address provided by the Receiving Server does not match a hostname serviced by the Originating Server.</li>
<li>Communication with the hostname of the 'from' address provided by the Receiving Server is not accepted by the Originating Server.</li>
</ol>
<p>These error cases are described more fully in the rest of this section.</p>
<p>If the Server Dialback namespace name is incorrect, then the Originating Server SHOULD generate an &lt;invalid-namespace/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Invalid Namespace"><![CDATA[
O2R: <stream:error>
<invalid-namespace
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>If the Server Dialback namespace prefix is not supported by the Originating Server, then the Originating Server SHOULD generate a &lt;bad-namespace-prefix/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Bad Namespace Prefix"><![CDATA[
O2R: <stream:error>
<bad-namespace-prefix
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>If the value of the 'to' address provided by the Receiving Server does not match a hostname serviced by the Originating Server, then the Originating Server SHOULD generate a &lt;host-unknown/&gt; or &lt;host-gone/&gt; stream error condition (as appropriate) and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Host Unknown"><![CDATA[
O2R: <stream:error>
<host-unknown
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>If the Originating Server does not allow communication with the hostname of the 'from' address provided by the Receiving Server, then the Originating Server SHOULD generate a &lt;not-authorized/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Not Authorized"><![CDATA[
O2R: <stream:error>
<not-authorized
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>Note: The foregoing error flows specify that the Originating Server SHOULD return a stream error. However, depending on local security policies, the Originating Server MAY silently terminate the XML stream and underlying TCP connection instead of returning a stream error (e.g., to prevent certain denial of service attacks).</p>
</section4>
</section3>
</section2>
<section2 topic='Dialback Key' anchor='proto-key'>
<p>The Originating Server MUST then send a dialback key to the Receiving Server:</p>
<example caption="Dialback Key"><![CDATA[
<section2 topic='Generation and Exchange of the Dialback Key' anchor='key'>
<section3 topic='Originating Server Generates Dialback Key' anchor='key-gen'>
<p>The method for generating (and verifying) the keys used in Server Dialback MUST take into account the following pieces of information:</p>
<ul>
<li>the hostname of the Originating Server</li>
<li>the hostname of the Receiving Server</li>
<li>the Stream ID</li>
<li>a shared secret known by the Authoritative Server's network</li>
</ul>
<p>The stream ID is security-critical in Server Dialback and therefore MUST be both unpredictable and non-repeating (see &rfc4086; for recommendations regarding randomness for security purposes).</p>
<p>It is RECOMMENDED for the dialback key to be the hexadecimal representation of a Keyed-Hash Message Authentication Code (see &nistfips198a;) generated using the SHA256 hashing algorithm (see &nistfips180-2;), as follows.</p>
<example caption="HMAC"><![CDATA[
HMAC-SHA256
(
SHA256(secret),
{Receiving Server, ' ', Originating Server, ' ', Stream ID}
)
]]></example>
<p>The shared secret SHOULD either be set up in a configuration option for each host or process within the Authoritative Server's network or generated as a random string when starting each host or process. The secret's length SHOULD be at least 128 bits or 16 characters long.</p>
<p>Consider the following scenario:</p>
<ul>
<li>The Originating Server is "example.org"</li>
<li>The Receiving Server is "xmpp.example.com"</li>
<li>The Stream ID is "D60000229F"</li>
<li>The secret is "s3cr3tf0rd14lb4ck"</li>
</ul>
<p>The resulting dialback key would be:</p>
<example caption="A Key"><![CDATA[
HMAC-SHA256
(
SHA256(secret),
{Receiving Server, ' ', Originating Server, ' ', Stream ID}
)
that is,
HMAC-SHA256
(SHA256('s3cr3tf0rd14lb4ck'),
{'xmpp.example.net',' ','example.org',' ','D60000229F'})
that is,
HMAC-SHA256
('a7136eb1f46c9ef18c5e78c36ca257067c69b3d518285f0b18a96c33beae9acc',
{'xmpp.example.com chat.example.org D60000229F'})
that is,
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
]]></example>
</section3>
<section3 topic='Originating Server Sends Dialback Key' anchor='key-send'>
<p>Once the Originating Server has processed the response stream header from the Receiving Server and has generated a dialback key for verification by the Receiving Server, it MUST then send that key to the Receiving Server. This is done by creating a &lt;db:result/&gt; element whose XML character data is the dialback key; the element SHOULD possess a 'from' attribute whose value is the hostname of the Originating Server and SHOULD possess a 'to' attribute whose value is the hostname of the Receiving Server.</p>
<p>Note: All XML elements qualified by the Server Dialback namespace MUST be prefixed with the namespace prefix advertised on the stream header originally sent by the entity sending the element.</p>
<example caption="Originating Server Sends Dialback Key"><![CDATA[
O2R: <db:result
from='example.org'
to='xmpp.example.com'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</db:result>
]]></example>
<p>If the value of the 'to' address provided by the Originating Server does not match a hostname serviced by the Receiving Server, then the Receiving Server MUST generate a &lt;host-unknown/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. The key generated by the Originating Server MUST be verifiable only by servers in the Authoritative Server's network, based on information known only to those servers. Any verifiable method MAY be used to generate the key; however, the method specified under <link url='#generation'>Dialback Key Generation</link> is RECOMMENDED. The key is not examined by the Receiving Server, since the key is validated by the Authoritative Server.</p>
]]></example>
</section3>
<section3 topic='Receiving Server Processes Dialback Key' anchor='key-process'>
<p>When the Receiving Server receives the dialback key, it MUST proceed as follows.</p>
<p>If the Server Dialback namespace prefix is not supported by the Originating Server, then the Originating Server SHOULD generate a &lt;bad-namespace-prefix/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Bad Namespace Prefix"><![CDATA[
O2R: <stream:error>
<bad-namespace-prefix
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>If the value of the 'to' address provided by the Originating Server does not match a hostname serviced by the Receiving Server, then the Receiving Server SHOULD generate a &lt;host-unknown/&gt; or &lt;host-gone/&gt; stream error condition (as appropriate) and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Host Unknown"><![CDATA[
O2R: <stream:error>
<host-unknown
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>If the Originating Server does not allow communication with the hostname of the 'from' address provided by the Receiving Server, then the Originating Server SHOULD generate a &lt;not-authorized/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
<example caption="Not Authorized"><![CDATA[
O2R: <stream:error>
<not-authorized
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
O2R: </stream:stream>
]]></example>
<p>Otherwise, the Receiving Server MUST attempt to open a connection to the Authoritative Server and then ask the Authoritative Server to validate the key provided by the Originating Server, as described in the following sections.</p>
<p>Note: The dialback key is not examined by the Receiving Server, since the key is validated by the Authoritative Server.</p>
</section3>
</section2>
<section2 topic='Stream Setup Between Receiving Server and Authoritative Server' anchor='proto-setup-r2a'>
<p>The Receiving Server performs a DNS lookup for the Authoritative Server (in accordance with the procedure described in RFC 3920) and establishes a TCP connection to the Authoritative Server at the IP address and port discovered during the DNS lookup (here assumed to be "192.0.2.1" and "5269"). If the Receiving Server cannot connect to the Authoritive Server, it MUST return a &lt;remote-connection-failed/&gt; stream error to the Originating Server and terminate both the XML stream and the underlying TCP connection.</p>
<section2 topic='Stream Setup Between Receiving Server and Authoritative Server' anchor='r2a'>
<p>The Receiving Server performs a DNS lookup for the Authoritative Server (in accordance with the procedure described in RFC 3920) and establishes a TCP connection to the Authoritative Server at the IP address and port discovered during the DNS lookup (here assumed to be "192.0.2.23" and "5269"). If the Receiving Server cannot connect to the Authoritive Server, it MUST return a &lt;remote-connection-failed/&gt; stream error to the Originating Server and terminate both the XML stream and the underlying TCP connection.</p>
<p>The Receiving Server sends a stream header to the Authoritative Server:</p>
<example caption="Stream Header"><![CDATA[
R2A: <stream:stream
@ -229,7 +465,7 @@ A2R: <stream:features>
]]></example>
</section2>
<section2 topic='Verification Request' anchor='proto-verify'>
<section2 topic='Exchange of Verification Request between Receiving Server and Authoritative Server' anchor='verify'>
<p>The Receiving Server sends the Authoritative Server a request for verification of a key:</p>
<example caption="Verification Request"><![CDATA[
R2A: <db:verify
@ -240,6 +476,9 @@ R2A: <db:verify
</db:verify>
]]></example>
<p>Note: Passed here are the hostnames of the Receiving Server ('from') and the Originating Server ('to'), the original identifier from the Receiving Server's stream header to the Originating Server in Step 3, and the key that the Originating Server sent to the Receiving Server in Step 5. Based on this information, as well as shared secret information within the Authoritative Server's network, the Authoritative Server determines whether the key is valid or invalid. If the value of the 'to' address does not match a hostname serviced by the Authoritative Server, then the Authoritative Server MUST generate a &lt;host-unknown/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. If the value of the 'from' address does not match the hostname sent by the Receiving Server in the 'from' address of the stream header it sent to the Authoritative Server in Step 7, then the Authoritative Server MUST generate an &lt;invalid-from/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection.</p>
</section2>
<section2 topic='Validation of Verification Request by Authoritative Server' anchor='validate'>
<p>The Authoritative Server determines whether the key was valid or invalid and informs the Receiving Server of its determination, where the &lt;db:verify/&gt; element SHOULD include the key sent by the Receiving Server:</p>
<example caption="Key is Valid"><![CDATA[
A2R: <db:verify
@ -263,7 +502,7 @@ A2R: <db:verify
<p>Note: If the ID does not match that provided by the Receiving Server in Step 3, then the Receiving Server MUST generate an &lt;invalid-id/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. If the value of the 'to' address does not match a hostname serviced by the Receiving Server, then the Receiving Server MUST generate a &lt;host-unknown/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. If the value of the 'from' address does not match the hostname represented by the Originating Server in the 'from' address of the stream header it sent to the Receiving Server in Step 2, then the Receiving Server MUST generate an &lt;invalid-from/&gt; stream error condition and terminate both the XML stream and the underlying TCP connection. After receiving the verification from the Authoritative Server, the Receiving Server SHOULD terminate the stream between them and the underlying TCP connection.</p>
</section2>
<section2 topic='Result' anchor='proto-result'>
<section2 topic='Communication of Result From Receiving Server to Originating Server' anchor='result'>
<p>The Receiving Server informs the Originating Server of the result, where the &lt;db:result/&gt; element SHOULD include the key sent by the Originating Server:</p>
<example caption="Result"><![CDATA[
R2O: <db:result
@ -280,7 +519,7 @@ R2O: <db:result
</section2>
</section1>
<section1 topic="Reuse of Negotiated Connections" anchor="reuse">
<section1 topic="Reuse of Negotiated Connections" anchor="piggybacking">
<p>After the Receiving Server has validated the connection from the Originating Server, the Originating Server may wish to reuse that connection for validation of additional domains. This feature is called PIGGYBACKING. Support for piggybacking is OPTIONAL.</p>
<p>One common motivation for such reuse is the existence of additional services associated with the Originating Server but hosted at subdomains of the Originating Server (the use of subdomains helps to ensure proper routing of XML stanzas to the hosted services). For example, the "example.org" XMPP server may host a groupchat service at "chat.example.org". In order to accept XML stanzas from rooms at "chat.example.org" intended for addresses at "xmpp.example.com", the "xmpp.example.com" domain will need to validate the "chat.example.org" domain (just as it already did for the "example.org" domain). Thus the "example.org" server would now initiate a dialback negotiation with "xmpp.example.com" but specify the Originating Server as "chat.example.org".</p>
<p>However, because the "example.org" server already has a validated connection open to the Receiving Server ("xmpp.example.com"), it MAY send a &lt;db:result/&gt; element with the key to be validated for the new Originating Server ("chat.example.org") over the XML stream that has already been negotiated, rather than opening a new TCP connection and XML stream.</p>
@ -311,57 +550,6 @@ R2O: <db:result
]]></example>
</section1>
<section1 topic="Dialback Key Generation" anchor="generation">
<p>The method for generating and verifying the keys used in Server Dialback MUST take into account the following pieces of information:</p>
<ul>
<li>the hostname of the Originating Server</li>
<li>the hostname of the Receiving Server</li>
<li>the Stream ID</li>
<li>a shared secret known by the Authoritative Server's network</li>
</ul>
<p>The stream ID is security-critical in Server Dialback and therefore MUST be both unpredictable and non-repeating (see &rfc4086; for recommendations regarding randomness for security purposes).</p>
<p>It is RECOMMENDED for the dialback key to be the hexadecimal representation of a Keyed-Hash Message Authentication Code (see &nistfips198a;) generated using the SHA256 hashing algorithm (see &nistfips180-2;), as follows.</p>
<example caption="HMAC"><![CDATA[
HMAC-SHA256
(
SHA256(secret),
{Receiving Server, ' ', Originating Server, ' ', Stream ID}
)
]]></example>
<p>The shared secret SHOULD either be set up in a configuration option for each host or process within the Authoritative Server's network or generated as a random string when starting each host or process. The secret's length SHOULD be at least 128 bits or 16 characters long.</p>
<p>Consider the following scenario:</p>
<ul>
<li>The Originating Server is "example.org"</li>
<li>The Receiving Server is "xmpp.example.com"</li>
<li>The Stream ID is "D60000229F"</li>
<li>The secret is "s3cr3tf0rd14lb4ck"</li>
</ul>
<p>The resulting dialback key would be:</p>
<example caption="A Key"><![CDATA[
HMAC-SHA256
(
SHA256(secret),
{Receiving Server, ' ', Originating Server, ' ', Stream ID}
)
that is,
HMAC-SHA256
(SHA256('s3cr3tf0rd14lb4ck'),
{'xmpp.example.net',' ','example.org',' ','D60000229F'})
that is,
HMAC-SHA256
('a7136eb1f46c9ef18c5e78c36ca257067c69b3d518285f0b18a96c33beae9acc',
{'xmpp.example.com chat.example.org D60000229F'})
that is,
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
]]></example>
</section1>
<section1 topic="Determining Support" anchor="support">
<p>Support for the Server Dialback protocol can be indicated in two ways:</p>
<ol start='1'>
@ -473,12 +661,12 @@ that is,
<xs:element name='dialback'>
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs='1' maxOccurs='1'>
<xs:element name='required'
minOccurs='0'
maxOccurs='1'
type='empty'/>
</xs:sequence>
<xs:element name='required'
type='empty'/>
</xs:choice>
</xs:complexType>
<xs:simpleType name='empty'>