XEP-0220: Server Dialback

Authoritative Server

The machine that is discovered by means of a DNS lookup for the Sender Domain; for simple deployments this will be the Initiating Server, but it could be a separate machine in the Initiating Server's network (where "network" is defined by knowledge of a shared secret for verification of dialback keys).

Domain Pair

The combination of the Sender Domain and Target Domain.

Initiating Server

The machine that wants to send a message from an entity at the Sender Domain to an entity at the Target Domain (and thus the machine that is attempting to establish a domain name association between (a) the Target Domain and (b) the XML stream from the Initiating Server to the Receiving Server). Note well that in older documentation of the Server Dialback protocol, this was called the Originating Server.

Receiving Server

The machine to which the Initiating Server has opened a connection for the purpose of sending a message from the Sender Domain to the Target Domain (and thus the machine that is trying to verify that the Initiating Server represents the Sender Domain).

Sender Domain

The domain name asserted by the Initiating Server as the domainpart of the XMPP 'from' address of stanzas that will flow over the XML stream from the Initiating Server to the Receiving Server.

Target Domain

The domain name specified by the Initiating Server as the domainpart of the XMPP 'to' address of stanzas that will flow over the XML stream from the Initiating Server to the Receiving Server.

2.1.1 Initiating Server Generates Outbound Request for Authorization by Receiving Server¶

This subsection describes the interaction between the server hosting capulet.example (acting as an Initiating Server) and the server hosting montague.example (acting as a Receiving Server), from the outbound perspective of the Initiating Server.

When the Initiating Server has stanzas to send from the Sender Domain to the Target Domain, does not have a verified connection, is currently not attempting to get a verified connection for this domain pair, it sends a new dialback key to the Receiving Server.

To do so, either it can reuse an existing XML stream or it needs to establish a new connection. To establish a new connection, the Initiating Server performs a DNS lookup on the Target Domain, thus finding the IP address and port for server-to-server communication at an authoritative machine for the Target Domain (here that is "home.montague.example").

After the XML stream is established from the Initiating Server to the Receiving Server, the Initiating Server sends a dialback key to the Receiving Server. This is done by creating a <db:result/> element whose XML character data is the dialback key; the element MUST possess a 'from' attribute whose value is the Sender Domain and MUST possess a 'to' attribute whose value is the Target Domain.

send: <db:result
          from='capulet.example'
          to='montague.example'>
        b4835385f37fe2895af6c196b59097b16862406db80559900d96bf6fa7d23df3
      </db:result>

The key sent is generated as described in Dialback Key Generation and Validation (XEP-0185) [12]:

key = HMAC-SHA256(
        SHA256('s3cr3tf0rd14lb4ck'),
          { 'montague.example', ' ', 'capulet.example', ' ', 'D60000229F' }
      )
    = b4835385f37fe2895af6c196b59097b16862406db80559900d96bf6fa7d23df3
      

Note: The Receiving Server MAY use any method to determine the validity of the dialback key and the identity of the Initiating Server. The Initiating Server MUST NOT make any assumptions about how the Receiving Server verifies the key, including even the assumption that the key is actively verified by the Receiving Server through communication with the Authoritative Server.

After sending the dialback key, the Initiating Server waits for the verification result from the Receiving Server. If the Initiating Server wishes to send any stanzas for this domain pair, it MUST queue them for sending after it has received authorization to send stanzas from the Receiving Server, and MUST NOT attempt to send stanzas until it has received such authorization.

Note: While waiting for the verification result, the Initiating Server SHOULD continue to send stanzas for any domain pair that has already been verified on that connection. It MAY send out additional dialback keys for different domain pairs and issue dialback verification requests as described under Section 2.1.2. To avoid denial of service attacks (RFC 4732 [13]) or deadlock situations, the Initiating Server MAY impose a timeout on dialback operations, i.e. it ought to consider dialback operations as having failed when there is no response after a certain amount of time.

If the stream or the underlying TCP connection is closed by the Receiving Server while the Initiating Server is waiting for the verification result, the Initiating Server shall behave as it does when receiving a dialback error as described below.

After the Receiving Server has verified the request, the Initiating Server receives the verification result in the form of a <db:result/> element with a the 'type' attribute whose value is "valid" or "invalid" (for the value of "error", see below). The Initiating Server MUST ensure that the 'from' and 'to' attributes in this response correlate to a request that was sent over the same XML stream (see Section 3.1).

Thus the result is either valid...

recv: <db:result
          from='montague.example'
          to='capulet.example'
          type='valid'/>

... or invalid ...

recv: <db:result
          from='montague.example'
          to='capulet.example'
          type='invalid'/>

Note: There are no examples for Step 2 and Step 3 in this section of the document; see the examples under Sections 2.1.2 and 2.2.2.

If the value of the 'type' attribute is "valid", then the connection between the domain pair is considered verified and the Initiating Server can send any outbound stanzas it has queued up for routing to the Receiving Server for the domain pair (i.e., from the Sender Domain to the Target Domain). Naturally, the Initiating Server can also enable or negotiate other stream features at this point.

If the value of the 'type' attribute is "invalid", then the Receiving Server is reporting that that Initiating Server's identity (as valid for the Sender Domain) was deemed bogus by the Authoritative Server. In this case, the Initiating Server MUST NOT attempt to send any outbound stanzas it has queued up for routing to the Receiving Server for the domain pair but instead MUST return such stanzas to the respective senders at the Sender Domain with an <internal-server-error/> stanza error. Since the Receiving Server will most likely close the stream and the underlying TCP connection if that occurs (see Section 2.2.1), the Initiating Server SHOULD NOT attempt to send further stanzas for other domain pairs that have already been authorized.

If the value of the 'type' attribute is "error", this indicates a problem which is not related to the validity of the dialback key provided. The error conditions are explained in detail under Dialback with Error Handling. Such an error is non-fatal for the XML stream, but the Initiating Server MUST return any queued stanzas to the respective senders at the Sender Domain with a <remote-server-timeout/> stanza error.

recv: <db:result
          from='montague.example'
          to='capulet.example'
          type='error'>
        <error type='cancel'>
          <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
        </error>
      </db:result>

2.1.2 Receiving Server Generates Outbound Request for Verification of Initiating Server by Authoritative Server¶

This subsection describes the interaction between the server hosting capulet.example (acting as a Receiving Server) and the server hosting montague.example (acting as an Authoritative Server), from the outbound perspective of the Receiving Server.

To determine the validity of a dialback key received from the Initiating Server, the Receiving Server needs to establish communications with the Authoritative Server. To do so, it can reuse an existing XML stream or establish a new connection. To establish a new connection, the Receiving Server performs a DNS lookup on the Sender Domain, thus finding the IP address and port for server-to-server communication at an authoritative machine for the Sender Domain asserted by the Initiating Server (here the machine is "orchard.capulet.example").

After the XML stream is established from the Receiving Server to the Authoritative Server, the Receiving Server sends a verification request. This is done by creating a <db:verify/> element whose XML character data is the dialback key received from the Initiating Server; the element MUST possess a 'from' attribute whose value is the Target Domain, MUST possess a 'to' attribute whose value is the Sender Domain as provided in the 'from' attribute of Step 1, and MUST possess an 'id' attribute whose value is the stream ID of the response stream header sent from the Receiving Server to the Initiating Server (here "417GAF25"). The combination of 'from', 'to', and 'id' attributes makes it possible for the Receiving Server to uniquely identify the TCP connection on which it received the original request in Step 1.

Note: An implementation MAY open a separate connection to the Authoritative Server for the sole purpose of doing key verification. Such an implementation SHOULD close the connection immediately after receiving the verification result. Not using TLS or any other stream features can reduce the number of round trips in that case.

send: <db:verify
          from='capulet.example'
          id='417GAF25'
          to='montague.example'>
       225cc5aa6a071133249d25fef42ae516fc7a86c523aa1c6980a7f73e784c972d
     </db:verify>

After that, the Receiving Server waits for the verification result. While doing so, it can still use the connection to send dialback packets or to send stanzas for domain pairs that have already been validated.

Here again, the result is either valid...

recv: <db:verify
          from='montague.example'
          id='417GAF25'
          to='capulet.example'
          type='valid'/>

... or invalid ...

recv: <db:verify
          from='montague.example'
          id='417GAF25'
          to='capulet.example'
          type='invalid'/>

In addition to the values "valid" and "invalid", the 'type' attribute can also have a value of "error"; see Dialback with Error Handling for a detailed explanation.

recv: <db:verify
          from='montague.example'
          id='417GAF25'
          to='capulet.example'
          type='error'>
        <error type='cancel'>
          <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
        </error>
     </db:verify>

Note: If the underlying TCP connection is closed by the remote side while there are pending verification requests, those requests SHOULD be considered failed and therefore be treated like an error response.

The Receiving Server MUST ensure that the values of the 'from', 'to' and 'id attributes correlate to a request that was sent over the same XML stream (see Section 3.1).

After receiving the validation result from the Authoritative Server, the Receiving Server determines the inbound connection that the dialback key was originally received on. This connection is uniquely identified by the combination of the 'from', 'to', and 'id' attributes. If no inbound connection is found that matches this combination, the verification result SHOULD be dropped silently. If an inbound connection is found, the Receiving Server uses it to communicate the verification result to the Initiating Server. A positive result indicates the readiness of the Receiving Server to accept stanzas from the Initiating Server for this domain pair.

When receiving a verification result of type "invalid", the Receiving Server MAY choose not to relay this result to the Initiating Server. Instead, it might send a dialback error such as <forbidden/> to the Initiating Server. Compared to sending a result of type "invalid", this behavior will not result in the loss of the whole stream and any previously domain pairs previously negotiated, while at the same time not accepting stanzas from the spoofed domain. Even when not forwarding the "invalid" result, the incident ought to be logged.

2.2.1 Receiving Server Handles Inbound Authorization Request from Initiating Server¶

This subsection describes the interaction between the server hosting capulet.example (acting as an Initiating Server) and the server hosting montague.net (acting as a Receiving Server), from the inbound perspective of the Receiving Server (i.e., this section is the mirror image of Section 2.1.1).

recv: <db:result
          from='capulet.example'
          to='montague.example'>
        b4835385f37fe2895af6c196b59097b16862406db80559900d96bf6fa7d23df3
      </db:result>

Before the Receiving Server allows the Initiating Server to send stanzas from the Sender Domain (here "capulet.example") to the Target Domain (here "montague.example"), it MUST verify the identity of the Initiating Server. Depending on how the server dialback protocol is used, this can be done by verifying the dialback key or by using some out-of-band method as in the POSH prooftype for XMPP domain name associations. Note that the verification process might fail prematurely, for example, if the Receiving Server's policy states that connections from the Initiating Server or the Sender Domain are not allowed.

Note: The Receiving Server MUST continue to accept and process stanzas for already verified domain pairs, and MUST continue to process both <db:result/> and <db:verify/> elements.

If the Target Domain as given in the 'to' attribute of the element is not a configured domain of the Receiving Server, this results in a dialback error. This error, which is explained further under Section 2.4.2, is not a stream error and therefore MUST NOT result in closing of the stream as described in Section 4.4 of RFC 6120, since the stream might already be used to exchange XML stanzas for other domain pairs.

send: <db:result
          from='montague.example'
          to='capulet.example'
          type='error'>
        <error type='cancel'>
          <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
        </error>
      </db:result>

After the validity of the dialback request has been established (for example, by the Authoritative Server), the Receiving Server can safely accept stanzas from the Initiating Server for the verified domain pair.

In addition, the Receiving Server SHALL notify the Initiating Server of the result and thus signal its willingness to accept stanzas from the Initiating Server for the verified domain pair. This is done by creating a <db:result/> element which MUST possess a 'from' attribute whose value is the Target Domain, MUST possess a 'to' attribute whose value is the Sender Domain, and MUST possess a 'type' attribute whose value is either "valid" or "invalid" (or "error", as shown above).

Therefore, here again the result is either valid (this is the same as Example 2)...

send: <db:result
          from='montague.example'
          to='capulet.example'
          type='valid'/>

... or invalid (this is the same as Example 3)...

send: <db:result
          from='montague.example'
          to='capulet.example'
          type='invalid'/>

If the result is "invalid", the Initiating Server is either attempting to spoof the Sender Domain or is misconfigured. The Receiving Server MUST NOT accept stanzas from the Initiating Server for the Sender Domain and ought to log the attempt. If no other valid domain pairs exist for this connection (i.e., if this is the first attempt), the Receiving Server SHOULD send a result with type "invalid" and MUST close the XML stream. If there exist other valid domain pairs for this connection, the Initiating Server might merely have a misconfiguration for the Sender Domain. In this case, the Receiving Server MAY (instead of closing the connection) return an error condition of <forbidden/> as described under Section 2.5 of this document.

2.2.2 Authoritative Server Handles Inbound Verification Request from Receiving Server¶

This subsection describes the interaction between the server hosting capulet.example (acting as a Receiving Server) and the server hosting montague.example (acting as an Authoritative Server), from the inbound perspective of the Authoritative Server (i.e., this section is the mirror image of Section 2.1.2 and the following example is the same as Example 5).

recv: <db:verify
          from='capulet.example'
          id='417GAF25'
          to='montague.example'>
       225cc5aa6a071133249d25fef42ae516fc7a86c523aa1c6980a7f73e784c972d
     </db:verify>

If the Target Domain as given in the 'to' attribute of the element does not match a configured local domain according to the Authoritative Server, this results in a dialback error. This error, which is explained further under Section 2.4, is not a stream error and therefore MUST NOT result in closing of the stream (as described in Section 4.4 of RFC 6120), since the stream might already be used for sending XML stanzas for other domain pairs. (The following example is the same as Example 8.)

send: <db:verify
          from='montague.example'
          id='417GAF25'
          to='capulet.example'
          type='error'>
        <error type='cancel'>
          <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
        </error>
      </db:verify>

Upon receiving this <db:verify/> element, the Authoritative Server determines the validity of the dialback key provided in the XML character data of the element. This can be achieved for example by comparing the character data with the output of applying the same key generation mechanism that was (presumably) used for the generation of the key, using as input the values of the 'from', 'to', and 'id' attributes contained in the verification request and the secret known only to the Sender Domain:

key = HMAC-SHA256(
        SHA256('d14lb4ck43v3r'),
          { 'capulet.example', ' ', 'montague.example', ' ', '417GAF25' }
      )
    = 225cc5aa6a071133249d25fef42ae516fc7a86c523aa1c6980a7f73e784c972d
      

The Authoritative Server then notifies the Receiving Server whether the key is valid. This is done by creating a <db:verify/> element which MUST possess 'from' and 'to' attributes whose values are swapped from the request, MUST possess an 'id' attribute whose value is copied from the 'id' value of the request, and MUST possess a 'type' attribute whose value is either "valid" or "invalid".

Therefore, here again the result is either valid (this is the same as Example 6)...

send: <db:verify
          from='montague.example'
          id='417GAF25'
          to='capulet.example'
          type='valid'/>

... or invalid (this is the same as Example 7)...

send: <db:verify
          from='montague.example'
          id='417GAF25'
          to='capulet.example'
          type='invalid'/>

There are several reasons why the key might be invalid (e.g., the Authoritative Server has a different secret key or the Authoritative Server doesn't know anything about the StreamID communicated in the <db:result/> element it received from the Receiving Server).

2.4.1 Traditional Dialback¶

Support for the traditional server dialback protocol (originally specified in RFC 3920) is indicated by inclusion of the dialback namespace declaration in the stream header.

<stream:stream
    xmlns='jabber:server'
    xmlns:db='jabber:server:dialback'
    xmlns:stream='http://etherx.jabber.org/streams'
    from='montague.example'
    to='capulet.example'>

Note: Although in general advertising protocol support by means of an XML namespace declaration has been superseded by the use of stream features as originally defined in RFC 3920 and updated in RFC 6120, the server dialback protocol predates the existence of stream features and therefore the namespace declaration method is still used in this instance.

Note: It is conventional to use a namespace prefix of "db" for Server Dialback elements. Although the prefix is allowed to be other than "db" according to the XML namespaces specification (Namespaces in XML [14]), some existing implementations and deployments might accept only the "db" prefix.

2.4.2 Dialback with Error Handling¶

If a server supports graceful handling of dialback errors as described in this document, it MUST advertise that via a stream feature which is a <dialback/> element qualified by the 'urn:xmpp:features:dialback' namespace, including an empty <errors/> element.

<stream:features>
  <dialback xmlns='urn:xmpp:features:dialback'>
    <errors/>
  </dialback>
</stream:features>

Note: As a general rule, stream feature elements containing child elements that advertise particular sub-features are not encouraged. The format shown above is used for the sake of backward compatiblity with existing implementations and deployments.

2.6.1 Multiplexing Sender Domains¶

In order to accept XML stanzas from rooms at "rooms.capulet.example" intended for addresses at "montague.example", the "montague.example" domain will need to validate the "rooms.capulet.example" domain (just as it already did for the "capulet.example" domain). Thus the server hosting both capulet.example and rooms.capulet.example would now initiate a dialback negotiation with the server hosting montague.example but specify the Sender Domain as "rooms.capulet.example". Specifying different Sender Domains is called "sender multiplexing" and MAY be used without further negotation.

2.6.2 Multiplexing Target Domains¶

Likewise, to send stanzas to rooms at "chat.montague.example" from addresses at "capulet.example", the server hosting both capulet.example and rooms.capulet.example would initiate dialback negotiation with the server hosting chat.montague.example (probably on the same connection that is already used to send stanzas from "capulet.example" to "montague.example"), specifying the Target Domain as "chat.montague.example". Specifying different target domains is called "target multiplexing".

The Initiating Server SHOULD NOT use target multiplexing unless the Receiving Server has signalled support for dialback error handling via <stream:features/> as described under Dialback with Error Handling. The Initiating Server MAY then attempt to multiplex a new Sender Domain on the stream to the Receiving Server that is already used for another Sender Domain if the hostname and port resolution results in the same IP address and port combination. For example:

_xmpp-server._tcp.montague.example.      86400 IN SRV 10 0 5269 home.montague.example
_xmpp-server._tcp.chat.montague.example. 86400 IN SRV 10 0 5269 home.montague.example
home.montague.example.                   86400 IN A                     10.44.0.4

Because DNS SRV lookups for both "montague.example" and "chat.montague.example" point to the same target ("home.montague.example") and port (5269), or eventually resolve to the same IP address (10.44.0.4) and port (5269), "capulet.example" MAY initiate a dialback negotation from "capulet.example" to "chat.montague.example" over the same XML stream that is already used to send stanzas from "capulet.example" to "montague.example".

Bidirectional Server-to-Server Connections (XEP-0288) [6] extends those rules since any domain that has been used as a source domain can be used as a target domain without further negotiation.