XEP-0215: External Service Discovery

Copyright (c) 1999 - 2009 XMPP Standards Foundation. See Legal Notices.

This document specifies an XMPP protocol extension for discovering services external to the XMPP network.

WARNING: Consideration of this document has been Deferred by the XMPP Standards Foundation. Implementation of the protocol described herein is not recommended.

Table of Contents

1. Introduction

An XMPP client or other entity may need to discover services external to the XMPP network in order to complete certain XMPP-related use cases. One example is the discovery of STUN servers (see RFC 5389 [1]) and STUN relays (see TURN [2]) for the sake of negotiating media exchanges via Jingle ICE-UDP Transport Method [3]. [4] An XMPP entity can already discover such external services in several ways, including:

1. The service is specified in the application's default settings.
2. The service is manually added into the application's configuration by a human user.
3. The service is discovered via non-XMPP service discovery protocols, such as:
   • DNS SRV records (RFC 2782 [5])
   • Service Location Protocol (SLP; RFC 2608 [6])
   • The Dynamic Delegation Discovery System (DDDS; RFC 3401 [7])
   • The NAPTR profile of DDDS (RFC 3403 [8])
   • The S-NAPTR profile of DDDS (RFC 3958 [9])
   • The U-NAPTR profile of DDDS (RFC 4848 [10])

Unfortunately, some of the foregoing methods are subject to human error and others are either not widely available or cannot be deployed in wide range of scenarios (e.g., when the administrators of an XMPP service do not have access to DNS SRV records). Therefore, this document defines a way for an XMPP server or discovery service to provide information about external services, which may include extended information such as temporary credentials for authentication at such services. This method should be used only as a fallback when the relevant service discovery technologies (DNS SRV, DDDS, SLP, S-NAPTR, U-NAPTR, etc.) are not available to the XMPP entities involved (typically a client and server). This method does not use Service Discovery [11] since that technology is designed for discovery of XMPP entities, not entities outside an XMPP network.

2. Protocol

In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty <services/> element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace (see Protocol Namespaces regarding issuance of one or more permanent namespaces), typically to its own server but perhaps alternatively to a dedicated discovery service.

The responding entity (XMPP server or discovery service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as <service-unavailable/> if the responding entity does not support this protocol or <forbidden/> if the requesting entity does not have permission to receive the list of external services. Each service is encapsulated via a <service/> element.

Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.

The <service/> element MAY be empty or MAY include extended information about the service as described in the Extended Information section of this document.

The attributes of the <service/> element are summarized in the following table.

* Note: The processes by which an external service might generate or an XMPP server might negotiate the username and password are outside the scope of this specification. One possible approach is for the XMPP server to generate a short-term authentication credential based on a private key shared with the external service.

3. Use Cases

<iq type='get'
    from='bard@shakespeare.lit/globe'
    to='shakespeare.lit'
    id='all1'>
  <services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'/>
</iq>
    

<iq type='result'
    from='shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='all1'>
  <services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'>
    <service host='stun.shakespeare.lit' port='9998' transport='udp' type='stun'/>
    <service host='stun.shakespeare.lit'
             password='jj929jkj5sadjfj93v3n'
             port='9999'
             type='stun-relay'
             username='nb78932lkjlskjfdb7g8'/>
    <service host='192.0.2.1' port='8888' transport='udp' type='stun'/>
    <service host='192.0.2.1'
             port='8889'
             password='93jn3bakj9s832lrjbbz'
             type='stun-relay'
             username='auu98sjl2wk3e9fjdsl7'/>
    <service host='ftp.shakespeare.lit' 
             name='Shakespearean File Server'
             password='guest' 
             port='20' 
             transport='tcp' 
             type='ftp' 
             username='guest'/>
  </services>
</iq>
    

<iq type='get'
    from='bard@shakespeare.lit/globe'
    to='shakespeare.lit'
    id='selected1'>
  <services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'
            type='stun-relay'/>
</iq>
    

<iq type='result'
    from='shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='selected1'>
  <services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'
            type='stun-relay'>
    <service host='stun.shakespeare.lit'
             password='jj929jkj5sadjfj93v3n'
             port='9999'
             type='stun-relay'
             username='nb78932lkjlskjfdb7g8'/>
    <service host='192.0.2.1'
             port='8889'
             password='93jn3bakj9s832lrjbbz'
             type='stun-relay'
             username='auu98sjl2wk3e9fjdsl7'/>
  </services>
</iq>
    

<iq type='set'
    from='shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='push1'>
  <services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'
            type='stun-relay'>
    <server host='stun.shakespeare.lit' 
            port='9999' 
            username='1nas9dlm3hzl89d0b9v' 
            password='gh9023ljjdk109iajqn'>
    <server host='192.0.2.2' 
            port='7778' 
            username='bnsv120afg48snsdozp' 
            password='zxp023na98dsfahn1kk'/>
  </services>
</iq>
    

4. Extended Information

If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the <value/> child of a distinct <field/> element, with the entire set of fields contained within an <x/> element of type "result" qualified by the 'jabber:x:data' namespace (see Data Forms [13]); this <x/> element SHOULD be a child of the <service/> element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace (see Protocol Namespaces regarding issuance of one or more permanent namespaces). Thus the IQ result SHOULD be of the following form:

<iq type='result'>
  <services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'>
    <service>
      <x type='result' xmlns='jabber:x:data'>
        <field var='[var-name]' label='[optional]'>
          <value>[var-value]</value>
        </field>
        [ ... ]
      </x>
    </service>
  </services>
</iq>

Note: A <field/> element MAY contain more than one <value/> child if appropriate.

If the data fields are to be used in the context of a protocol approved by the XMPP Standards Foundation, they SHOULD be registered in accordance with the rules defined in XEP-0068, resulting in the inclusion of a <field/> element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".

Note: Although Service Discovery Extensions [14] specifies that an XMPP entity MUST NOT supply extended information about associated children communicated via the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace, that rule does not apply to External Service Discovery since services external to the XMPP network cannot communicate via XMPP.

5. Determining Support

If an entity supports the STUN Server Discovery protocol, it MUST report that fact by including a service discovery feature of "http://www.xmpp.org/extensions/xep-0215.html#ns" (see Protocol Namespaces regarding issuance of one or more permanent namespaces) in response to a Service Discovery [15] information request:

Example 6. Service Discovery Information Request

<iq type='get'
    from='romeo@montague.lit/orchard'
    to='montague.lit'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  

Example 7. Service Discovery Information Response

<iq type='result'
    from='montague.lit'
    to='romeo@montague.lit/orchard'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://www.xmpp.org/extensions/xep-0215.html#ns'/>
    ...
  </query>
</iq>
  

6. Internationalization Considerations

If the requesting entity includes an 'xml:lang' attribute with its request, the responding entity SHUOLD include appropriately internationalized text as the value of the 'name' attribute. No other attributes are human-readable.

7. Security Considerations

Because the responding entity (XMPP server or discovery service) functions as a "proxy" from external services to the XMPP network, it could modify the information it receives before passing it on to the requesting entity.

8. XMPP Registrar Considerations

9. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://www.xmpp.org/extensions/xep-0215.html#ns'
    xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'
    elementFormDefault='qualified'>

  <xs:import
      namespace='jabber:x:data'
      schemaLocation='http://www.xmpp.org/schemas/x-data.xsd'/>

  <xs:element name='services'>
    <xs:complexType>
      <xs:sequence minOccurs='0'>
        <xs:element ref='service'/>
      </xs:sequence>
      <xs:attribute name='type' type='xs:NCName' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='service'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='host' type='xs:string' use='required'/>
          <xs:attribute name='name' type='xs:string' use='optional'/>
          <xs:attribute name='password' type='xs:string' use='optional'/>
          <xs:attribute name='port' type='xs:string' use='required'/>
          <xs:attribute name='transport' type='xs:NCName' use='optional'/>
          <xs:attribute name='type' type='xs:NCName' use='required'/>
          <xs:attribute name='username' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
  

Appendices

Appendix A: Document Information

Series: XEP
Number: 0215
Publisher: XMPP Standards Foundation
Status: Deferred
Type: Standards Track
Version: 0.3
Last Updated: 2007-08-30
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: NOT YET ASSIGNED
Source Control: HTML  RSS

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata may be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

Appendix H: Revision History

END