XEP-0220: Server Dialback

Originating               Receiving
  Server                    Server
-----------               ---------
    |                         |
    |   perform DNS lookup,   |
    |   open TCP connection,  |
    |   and establish stream  |
    | ----------------------> |
    |                         |                   Authoritative
    |   send dialback key     |                       Server
    | --------(1)-----------> |                   -------------
    |                         |                         |
    |                         |   perform DNS lookup,   |
    |                         |   open TCP connection,  |
    |                         |   and establish stream  |
    |                         | ----------------------> |
    |                         |                         |
    |                         |   send verify request   |
    |                         | ---------(2)----------> |
    |                         |                         |
    |                         |   send verify response  |
    |                         | <--------(3)----------- |
    |                         |
    |  report dialback result |
    | <-------(4)------------ |
    |                         |
    

2.1.1 Dialback Request and Response

This subsection describes the protocol used by the Originating Server ('example.org') to achive validation of a pair of domains on the XML stream by the Receiving Server ('xmpp.example.com').

When the Originating Server has stanzas for the domain pair (Originating Server/Receiving Server), 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 hostname of the Originating Server and MUST possess a 'to' attribute whose value is the hostname of the Receiving Server.

Example 1. Send Dialback Key (step 1)

send: <db:result
         from='example.org'
         to='xmpp.example.com'>
       37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
     </db:result>
      

Note: see Dialback Key Generation and Validation [6] for the recommended key generation method. The key sent is generated as

key = HMAC-SHA256( 
                   SHA256('s3cr3tf0rd14lb4ck'), 
                   { 'xmpp.example.com', ' ', 'example.org', ' ', 'D60000229F'}
                 )
      

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 this domain pair on this 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 a negative result as described below.

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

Example 2. Receive Verification Result (step 4)

recv: <db:result
         from='xmpp.example.com'
         to='example.org'
         type='valid'/>
      

Example 3. Receive Verification Result (step 4)

recv: <db:result
         from='xmpp.example.com'
         to='example.org'
         type='invalid'/>
      

If the value of the 'type' attribute is 'valid', then the connection between the domain pair is considered verified and any queued stanzas are sent. If the value of the 'type' attribute is 'invalid', this means that our identity could not be established by the Receiving Server. Queued stanzas MUST be bounced back to the respective senders with a <remote-server-timeout/> stanza error and the underlying stream MAY be closed unless it is not used by other domain pairs.

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.

Example 4. Receive Dialback Error (step 4)

recv: <db:result
         from='xmpp.example.com'
         to='example.org'
         type='error'/>
      

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. An example of this is that the Receiving Server is not configured to serve for the hostname given in the 'to' attribute of the dialback request. The original value given there is used in the 'from' attribute of the error reply (note: this does not imply that the Receiving Server is serving this domain). This error is to be considered non-fatal for the XML stream, but queued stanzas MUST be bounced to the respective senders with a <remote-server-timeout/> stanza error.

Note Well: Use of the "error" value was unspecified in RFC 3920. The usage herein is similar to the <host-unknown/> stream error in RFC3920, however this error is non-fatal and does not result in termination of the stream and the underlying TCP connection, which may already be used for sending XML stanzas for other domain pairs.

2.1.2 Verify Request and Response

This subsection describes a protocol used in the role of a Receiving Server ('example.org') to establish the identity of the Originating Server ('xmpp.example.com') by sending the dialback key provided to an Authorative Server. Alternative verification methods for determining are out of scope for this document.

To determine the validity of a dialback key, the Receiving Server needs to establish communications with the Authoritative Server. To do so, it may either reuse an existing XML stream or needs to establish a new connection.

After the XML stream is established, the Receiving Server sends the 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 hostname of the Receiving Server, MUST possess a 'to' attribute whose value is the hostname of the Originating Server 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 that the original request was received on in step 1.

Note: Implementations may open a separate connection to the Authorative Server for the sole purpose of doing key verification.

Example 5. Send Verification Request (step 2)

send: <db:verify
         from='example.org'
         id='417GAF25'
         to='xmpp.example.com'>
       38b501ec606752318f72ad53de17ac6d15f86257485b0d8f5d54e1f619e6b869
     </db:verify>
      

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

Example 6. Key is Valid (step 3)

recv: <db:verify
         from='xmpp.example.com'
         id='417GAF25'
         to='example.org'
         type='valid'>
     </db:verify>
      

Or:

Example 7. Key is Invalid (step 3)

recv: <db:verify
         from='xmpp.example.com'
         id='417GAF25'
         to='example.org'
         type='invalid'>
     </db:verify>
      

In addition to the values 'valid' and 'invalid', the 'type' attribute may also have a value of 'error'. This is usually an indication that the Authoritative Server is not authoritative for the domain.

Note: Use of the "error" value was unspecified in RFC3920.

Example 8. Dialback Error (step 3)

recv: <db:verify
         from='xmpp.example.com'
         to='example.org'
         id='417GAF25'
         type='error'>
     </db:verify>
      

Note: if the underlying TCP connection is closed by the remote side while there are pending verification requests, those requests may be considered failed and should be treated like a 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 can 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 willingness of the Receiving Server to accept stanzas from the Originating Domain for the Receiving Domain from the Originating Server.

2.2.1 Dialback Request and Response

Example 9. Receiving Server Processes Key (step 1)

recv: <db:result
         from='example.org'
         to='xmpp.example.com'>
       37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
     </db:result>
      

This key must be verified before the Originating Domain ('example.org') is authorized to send stanzas. This may fail prematurely, for example, if the Receiving Server's policy states that connections from the Receiving Domain are not allowed.

The usual method for verifying that the Originating Server is authorized to send stanzas for the Originating Domain is to 'dial-back' the Authoritative Server for the Originating Domain and asking it to validate the dialback key which is contained in the XML character data of the request. Other methods may 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 Receiving 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 is not a stream error and therefore MUST NOT result in termination of the stream and the underlying TCP connection, which may already be used for sending XML stanzas for other domain pairs.

Example 10. Send Dialback Error (step 6)

send: <db:result
         from='xmpp.example.com'
         to='example.org'
         type='error'/>
      

Note: Use of the "error" value was unspecified in RFC3920.

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 connection MUST accept stanzas. If the key validation failed, no action is to be taken.

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 hostname of the Receiving Server, MUST possess a 'to' attribute whose value is the hostname of the Originating Server, and MUST possess a 'type' attribute whose value is either "valid" or "invalid".

Example 11. Send Valid Verification Result (step 6)

send: <db:result
         from='xmpp.example.com'
         to='example.org'
         type='valid'/>
      

Or:

Example 12. Send Invalid Verification Result (step 6)

send: <db:result
         from='xmpp.example.com'
         to='example.org'
         type='invalid'/>
      

2.2.2 Verify Request and Response

Example 13. Receiving Server Sends Verification Request (step 2)

recv: <db:verify
         from='example.org'
         id='417GAF25'
         to='xmpp.example.com'>
       38b501ec606752318f72ad53de17ac6d15f86257485b0d8f5d54e1f619e6b869
     </db:verify>
      

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

Example 14. Dialback error (step 3)

send: <db:verify
         from='xmpp.example.com'
         to='example.org' 
         id='417GAF25'
         type='error'/>
      

Upon receiving this <db:verify/> element, the validity of the dialback key provided in the XML character data of the element is determined. This may be achived for example by comparing the character data with the output of applying the key generation mechanism for the values of the 'from', 'to' and 'id' attributes as described in XEP 0185:

key = HMAC-SHA256( 
                   SHA256('d14lb4ck43v3r'), 
                   { 'example.org', ' ', 'xmpp.example.com', ' ', '417GAF25'}
                 )
    = 38b501ec606752318f72ad53de17ac6d15f86257485b0d8f5d54e1f619e6b869 (key is valid)
      

The Receiving Server is then notified of the validity of the key. 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. Key is Valid (step 3)

send: <db:verify
         from='xmpp.example.com'
         id='417GAF25'
         to='example.org'
         type='valid'/>
      

Or:

Example 16. Key is Invalid (step 3)

send: <db:verify
         from='xmpp.example.com'
         id='417GAF25'
         to='example.org'
         type='invalid'/>
      

<?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>
    

• Changed description and order of steps.
• Made clear that dialback consists of two mostly independent subprotocols.
• Further piggybacking clarifications.
• Extended usage of dialback errors, obsoleting stream errors.

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.