XEP-0220: Server Dialback

Originating               Receiving
  Server                    Server
-----------               ---------
    |                          |
    |  [if necessary,          |
    |   perform DNS lookup     |
    |   on Target Domain,      |
    |   open TCP connection,   |
    |   and establish stream]  |
    | -----------------------> |
    |                          |                   Authoritative
    |   send dialback key      |                       Server
    | -------(STEP 1)--------> |                   -------------
    |                          |                          |
    |                          |  [if necessary,          |
    |                          |   perform DNS lookup,    |
    |                          |   on Sender Domain,      |
    |                          |   open TCP connection,   |
    |                          |   and establish stream]  |
    |                          | -----------------------> |
    |                          |                          |
    |                          |   send verify request    |
    |                          | -------(STEP 2)--------> |
    |                          |                          |
    |                          |   send verify response   |
    |                          | <------(STEP 3)--------- |
    |                          |
    |  report dialback result  |
    | <-------(STEP 4)-------- |
    |                          |
    

2.1.1 Dialback Request and Response

This subsection describes the interaction between the Originating Server and the Receiving Server, from the perspective of the Originating Server.

When the Originating Server has stanzas to send for the DOMAIN PAIR (Sender Domain/Target Domain), does not have a verified connection, or is currently attempting to get a verified connection for this domain pair, it sends a new 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.

Example 1. Originating Server Sends Dialback Key (step 1)

send: <db:result
          from='sender.tld'
          to='target.tld'>
       1e701f120f66824b57303384e83b51feba858024fd2221d39f7acc52dcf767a9
     </db:result>
      

The key sent is generated as described in Dialback Key Generation and Validation [8]:

key = HMAC-SHA256( 
        SHA256('s3cr3tf0rd14lb4ck'), 
          { 'target.tld', ' ', 'sender.tld', ' ', 'D60000229F' }
      )
      

Note: the Receiving Server MAY use any method to determine the validity of the dialback key and the identity of the Originating Sever. The Originating Server MUST NOT make any assumptions about how the Receiving Server verifies the key. This includes the assumption that the key is ever verified by the Receiving Server.

After that, the Originating Server waits for the verification result. Any stanzas for this domain pair have to be queued. The Originating Server MUST NOT attempt to reverify the domain pair on this TCP connection.

Note: While waiting for the verification result, the Originating Server SHOULD continue to send stanzas for any pair of domains that have been verified on that connection. It MAY send out additional dialback keys for different domain pairs and issue dialback verification requests as described in section 2.1.2. To avoid Denial-of-Service attacks, the Originating Server MAY impose a timeout on key verification.

If the stream or the underlying TCP connection is closed by the remote side while waiting for the verification result, this is to be handled similar to receiving an error as described below.

After the Receiving Server has verified the request, the Originating Server receives the verification result:

Example 2. Originating Server Receives Valid Verification Result from Receiving Server (step 4)

recv: <db:result
          from='target.tld'
          to='sender.tld'
          type='valid'/>
      

Example 3. Originating Server Receives Invalid Verification Result from Receiving Server (step 4)

recv: <db:result
          from='target.tld'
          to='sender.tld'
          type='invalid'/>
      

If the value of the 'type' attribute is "valid", then the connection between the domain pair is considered verified and the Originating Server can send any queued stanzas.

If the value of the 'type' attribute is "invalid", this means that the Originating Server's identity (as valid for the Sender Domain) could not be verified by the Receiving Server. Queued stanzas MUST be returned to the respective senders with a <internal-server-error> stanza error and the underlying stream MAY be closed unless it is being used by other domain pairs. Note that the Receiving Server may choose to terminate the TCP connection.

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 in section 2.4. Such an error is to be considered non-fatal for the XML stream, but queued stanzas MUST be returned to the respective senders with a <remote-server-timeout/> stanza error.

Example 4. Originating Server Receives Dialback Error from Receiving Server (step 4)

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

2.1.2 Verify Request and Response

This subsection describes the interaction between the Receiving Server and the Authoritative Server, from the perspective of the Receiving Server.

To determine the validity of a dialback key, the Receiving Server needs to establish communications with the Authoritative 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 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 (here the machine is authority.sender.tld).

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; 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 identifier from the Receiving Server's response stream header to the Originating Server. 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.

Example 5. Receiving Server Sends Verification Request to Authoritative Server (step 2)

send: <db:verify
          from='target.tld'
          id='417GAF25'
          to='sender.tld'>
       38b501ec606752318f72ad53de17ac6d15f86257485b0d8f5d54e1f619e6b869
     </db:verify>
      

After that, the Receiving Server waits for the verification result. While doing so, it can still use the connection to send any valid stanzas or dialback packets.

Example 6. Receiving Server is Informed by Authoritative Server that Key is Valid (step 3)

recv: <db:verify
          from='sender.tld'
          id='417GAF25'
          to='target.tld'
          type='valid'>
     </db:verify>
      

Or:

Example 7. Receiving Server is Informed by Authoritative Server that Key is Invalid (step 3)

recv: <db:verify
          from='target.tld'
          id='417GAF25'
          to='sender.tld'
          type='invalid'>
     </db:verify>
      

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

Example 8. Receiving Server Receives Dialback Error from Authoritative Server (step 3)

recv: <db:verify
          from='sender.tld'
          to='target.tld'
          id='417GAF25'
          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.

After receiving the validation result from the Authoritative Server, the Receiving Server determines the incoming 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 incoming connection is found that matches this combination, the verification result MAY be dropped silently. If an incoming connection is found, the Receiving Server uses it to communicate the verification result to the Originating Server. A positive result indicates the readyness of the Receiving Server to accept stanzas from the Originating Server for this domain pair.

2.2.1 Dialback Request and Response

This subsection describes the interaction between the Originating Server and the Receiving Server, from the perspective of the Receiving Server.

Example 9. Receiving Server Receives Dialback Key from Originating Server (step 1)

recv: <db:result
          from='sender.tld'
          to='target.tld'>
       1e701f120f66824b57303384e83b51feba858024fd2221d39f7acc52dcf767a9
     </db:result>
      

This key MUST be verified before the Sender Domain ('sender.tld') is authorized to send stanzas. The verification process might fail prematurely, for example, if the Receiving Server's policy states that connections from the Sender Domain are not allowed.

The usual method for verifying that the Originating Server is authorized to send stanzas for the Sender Domain is to "dial back" the Authoritative Server for the Sender Domain and asking it to validate the dialback key which is contained in the XML character data of the request. Other methods can be used for verifying the identity of the Originating Server, but are out of scope for this document.

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 in section 2.4, is not a stream error and therefore MUST NOT result in termination of the stream and the underlying TCP connection, which might already be used for sending XML stanzas for other domain pairs.

Example 10. Receiving Server Sends Dialback Error to Originating Server (step 4)

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

After the validity of the key has been established (for example, by the Authoritative Server), the domain pair is to be considered as verified and the Receiving Server MUST accept stanzas from the Originating Server.

In addition, the Originating Server is notified of the result. 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".

Example 11. Receiving Server Sends Valid Verification Result to Originating Server (step 4)

send: <db:result
          from='target.tld'
          to='sender.tld'
          type='valid'/>
      

Or:

Example 12. Receiving Server Sends Invalid Verification Result to Originating Server (step 4)

send: <db:result
          from='target.tld'
          to='sender.tld'
          type='invalid'/>
      

If the type is 'invalid', the Originating Server is attempting to spoof the Sender Domain. The Receiving Server MUST terminate the XML stream and the underlying TCP connection and SHOULD log the attempt.

As mentioned, Server Dialback results in weak identity verification of the Sender Domain by the Target Domain. In order to proceed with bi-directional communication so that the Target Domain can send XML stanzas to the Sender Domain, the Receiving Server has to initiate a dialback negotiation with the Originating Server (i.e., assume the role of an originating server in a new dialback negotiation on a new TCP connection).

2.2.2 Verify Request and Response

This subsection describes the interaction between the Receiving Server and the Authoritative Server, from the perspective of the Authoritative Server.

Example 13. Authoritative Server Receives Verification Request from Receiving Server (step 2)

recv: <db:verify
          from='target.tld'
          id='417GAF25'
          to='sender.tld'>
       fed84f34d39682fd80bd04e01894f98c4149cf9df47575b134eeb6d2c7fe9fee
     </db:verify>
      

If the Target Domain as given in the 'to' attribute of the element does not match a configured local domain, this results in a dialback error. This error, which is explained further in section 2.4, is not a stream error and therefore MUST NOT result in termination of the stream and the underlying TCP connection, which might already be used for sending XML stanzas for other domain pairs.

Example 14. Authoritative Server Sends Dialback Error to Receiving Server (step 3)

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

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'), 
          { 'sender.tld', ' ', 'target.tld', ' ', '417GAF25' }
      )
    = fed84f34d39682fd80bd04e01894f98c4149cf9df47575b134eeb6d2c7fe9fee
      

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".

Example 15. Authoritative Server Informs Receiving Server that Key is Valid (step 3)

send: <db:verify
          from='sender.tld'
          id='417GAF25'
          to='target.tld'
          type='valid'/>
      

Or:

Example 16. Authoritative Server Informs Receiving Server that Key is Invalid (step 3)

send: <db:verify
          from='sender.tld'
          id='417GAF25'
          to='target.tld'
          type='invalid'/>
      

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

<stream:stream 
    xmlns='jabber:server'
    xmlns:db='jabber:server:dialback'
    xmlns:stream='http://etherx.jabber.org/streams'
    from='target.tld'
    to='sender.tld'>
    

Table 1: Dialback error conditions

2.5.1 Multiplexing Sender Domains

In order to accept XML stanzas from rooms at "chat.sender.tld" intended for addresses at "target.tld", the "target.tld" domain will need to validate the "chat.sender.tld" domain (just as it already did for the "sender.tld" domain). Thus the Originating Server would now initiate a dialback negotiation with "target.tld" but specify the Sender Domain as "chat.sender.tld". Specifying different Sender Domains is called "SENDER PIGGYBACKING" and MAY be used without further negotation.

2.5.2 Multiplexing Target Domains

Likewise, to send stanzas to rooms at "chat.target.tld" from addresses at "sender.tld", the Originating Server would initiate dialback negotiation with "chat.target.tld" on the same connection that may already be used to send stanzas from "sender.tld" to "target.tld", specifiying the Target Domain as "chat.target.tld". Specifiyng different target domains is called "TARGET PIGGYBACKING".

The Originating Server SHOULD NOT use Target Piggybacking unless the Receiving Server has signalled support for dialback error handling via <stream:features/>. The Originating Server MAY then attempt to multiplex a Sender Domain 'B' on the stream to the Receiving Server that is already used for Sender Domain 'A' if the hostname and port resolution results in the same IP address and port combination. For example:

Example 19. DNS SRV Record for the sender.tld Zone

_xmpp-server._tcp.target.tld.      86400 IN SRV 10 0 5269 receiver.target.tld
_xmpp-server._tcp.chat.target.tld. 86400 IN SRV 10 0 5269 receiver.target.tld
receiver.target.tld.               86400 IN A                       10.44.0.4
    

Because DNS lookups for both "target.tld" and "chat.target.tld" resolve to the same IP address (10.44.0.4) and port (5269), "sender.tld" may initiate a dialback negotation from "sender.tld" to "chat.target.tld" over the same XML stream that is already used to send stanzas from "sender.tld" to "target.tld".

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:server:dialback'
    xmlns='jabber:server:dialback'
    elementFormDefault='qualified'>

  <xs:element name='result'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:NMTOKEN'>
          <xs:attribute name='from' type='xs:string' use='required'/>
          <xs:attribute name='to' type='xs:string' use='required'/>
          <xs:attribute name='type' use='optional'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='error'/>
                <xs:enumeration value='invalid'/>
                <xs:enumeration value='valid'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='verify'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:NMTOKEN'>
          <xs:attribute name='from' type='xs:string' use='required'/>
          <xs:attribute name='id' type='xs:NMTOKEN' use='required'/>
          <xs:attribute name='to' type='xs:string' use='required'/>
          <xs:attribute name='type' use='optional'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='error'/>
                <xs:enumeration value='invalid'/>
                <xs:enumeration value='valid'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
    

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:features:dialback'
    xmlns='urn:xmpp:features:dialback'
    elementFormDefault='qualified'>

  <xs:element name='sm'>
    <xs:complexType>
      <xs:sequence>
        <xs:choice>
          <xs:element name='optional' type='empty'/>
          <xs:element name='required' type='empty'/>
        </xs:choice>
        <xs:element name='errors' minOccurs='0' type='empty'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
    

Added policy-violation and not-authorized error conditions

• Changed description and order of steps.
• Made clear that dialback consists of two mostly independent subprotocols.
• Further piggybacking clarifications.
• Defined extended usage of dialback errors, obsoleting stream errors.
• Specified extended error conditions.
• Added stream feature details for new-style error behavior.
• Added multiplexing notes.
• Updated schemas.

Completed copy edit; clarified several points in the text; corrected several examples.

• Rewrote introduction.
• Provided motivating text about why dialback is used.
• Added text about different federation models.
• More clearly described what dialback accomplishes and what it does not accomplish.
• Added explanatory text about scenarios in which Server Dialback is used and not used.
• Clarified basic description of how dialback works.
• Clarified discovery of dialback support.
• Separated sections into subsections, as has been done for rfc3920bis and rfc3921bis.
• Described the protocol flows in much greater detail.
• Explained and illustrated failure cases more completely.
• Clarified reuse of negotiated connections, a.k.a. piggybacking.

Initial published version.

Content moved from rfc3920bis.