XEP-0215: External Service Discovery

Abstract:This document specifies an XMPP protocol extension for discovering services external to the XMPP network.
Authors:Peter Saint-Andre, Sean Egan, Marcus Lundblad
Copyright:© 1999 - 2015 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Experimental
Type:Standards Track
Version:0.6
Last Updated:2014-02-27

WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a status of Draft.

Table of Contents


1. Introduction
2. Protocol
3. Use Cases
    3.1. Requesting All Services
    3.2. Requesting Selected Services
    3.3. Requesting Credentials
4. Extended Information
5. Determining Support
6. Internationalization Considerations
7. Security Considerations
8. XMPP Registrar Considerations
    8.1. Protocol Namespaces
    8.2. Protocol Versioning
    8.3. External Service Types Registry
       8.3.1. Process
       8.3.2. Registration
9. XML Schema
10. Acknowledgements

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

1. Introduction

An XMPP client or other entity might 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 TURN relays (see RFC 5766 [2]) for the sake of negotiating media exchanges via the Jingle ICE-UDP Transport Method (XEP-0176) [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:

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 might 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 (XEP-0030) [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 'urn:xmpp:extdisco:1' 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.

Table 1: Attributes

Name Definition Inclusion
host Either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6). REQUIRED
name A friendly (human-readable) name or label for the service. OPTIONAL
password A service- or server-generated password for use at the service. * OPTIONAL
port The communications port to be used at the host. RECOMMENDED
transport The underlying transport protocol to be used when communicating with the service (typically either TCP or UDP). RECOMMENDED
type The service type as registered with the XMPP Registrar [12]. REQUIRED
username A service- or server-generated username for use at the service. * OPTIONAL

* 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

3.1 Requesting All Services

A requesting entity requests all services by sending a <services/> element to its server or a discovery service.

Example 1. Entity Requests All External Services

<iq from='bard@shakespeare.lit/globe'
    id='ul2bc7y6'
    to='shakespeare.lit'
    type='get'>
  <services xmlns='urn:xmpp:extdisco:1'/>
</iq>

Example 2. XMPP Server Returns List

<iq from='shakespeare.lit'
    id='ul2bc7y6'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <services xmlns='urn:xmpp:extdisco:1'>
    <service host='stun.shakespeare.lit'
             port='9998'
             transport='udp'
             type='stun'/>
    <service host='relay.shakespeare.lit'
             password='jj929jkj5sadjfj93v3n'
             port='9999'
             transport='udp'
             type='turn'
             username='nb78932lkjlskjfdb7g8'/>
    <service host='192.0.2.1'
             port='8888'
             transport='udp'
             type='stun'/>
    <service host='192.0.2.1'
             port='8889'
             password='93jn3bakj9s832lrjbbz'
             transport='udp'
             type='turn'
             username='auu98sjl2wk3e9fjdsl7'/>
    <service host='ftp.shakespeare.lit' 
             name='Shakespearean File Server'
             password='guest' 
             port='20' 
             transport='tcp' 
             type='ftp' 
             username='guest'/>
  </services>
</iq>

3.2 Requesting Selected Services

A requesting entity requests services of a particular type by sending a <services/> element including a 'type' attribute specifying the service type of interest.

Example 3. Entity Requests Selected Services

<iq from='bard@shakespeare.lit/globe'
    id='yv2c19f7'
    to='shakespeare.lit'
    type='get'>
  <services xmlns='urn:xmpp:extdisco:1' type='turn'/>
</iq>

Example 4. XMPP Server Returns List

<iq from='shakespeare.lit'
    id='yv2c19f7'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <services xmlns='urn:xmpp:extdisco:1'
            type='turn'>
    <service host='turn.shakespeare.lit'
             password='jj929jkj5sadjfj93v3n'
             port='9999'
             transport='udp'
             type='turn'
             username='nb78932lkjlskjfdb7g8'/>
    <service host='192.0.2.1'
             port='8889'
             password='93jn3bakj9s832lrjbbz'
             transport='udp'
             type='turn'
             username='auu98sjl2wk3e9fjdsl7'/>
  </services>
</iq>

If a requesting entity requests services of a particular type, the responding service MAY as needed send an updated list of the relevant services by "pushing" the list to a requesting entity that has previously requested the list. However, it MUST NOT push updates to the requesting entity unless it has presence information about the requesting entity (e.g., because the requesting entity is connected to the XMPP server or because the requesting entity has shared presence with a remote discovery service). A push is an IQ set to the requesting entity containing a <service/> payload with updated data about services matching the requested type (e.g., new services or updated credentials)

Example 5. Services Push

<iq from='shakespeare.lit'
    id='lh3f1vc7'
    to='bard@shakespeare.lit/globe'
    type='set'>
  <services xmlns='urn:xmpp:extdisco:1'
            type='turn'>
    <service host='stun.shakespeare.lit' 
             port='9999' 
             transport='udp'
             type='turn'
             username='1nas9dlm3hzl89d0b9v' 
             password='gh9023ljjdk109iajqn'>
    <service host='192.0.2.2' 
             port='7778' 
             transport='udp'
             type='turn'
             username='bnsv120afg48snsdozp' 
             password='zxp023na98dsfahn1kk'/>
  </services>
</iq>

Upon receiving a push, the requesting entity would then send an IQ-result to the responding service in accordance with XMPP Core [13].

3.3 Requesting Credentials

An entity might know about an external service via DNS or some other means, but still might need short-term credentials to use the service. The entity can request credentials by sending a special request to the server.

Example 6. Entity Requests Credentials at a Service

<iq from='bard@shakespeare.lit/globe'
    id='xi2cax48'
    to='shakespeare.lit'
    type='get'>
  <credentials xmlns='urn:xmpp:extdisco:1'>
    <service host='turn.shakespeare.lit'/>
  </credentials>
</iq>

The server then returns credentials if possible.

Example 7. Server Returns Credentials

<iq from='shakespeare.lit'
    id='xi2cax48'
    to='bard@shakespeare.lit/globe'
    type='get'>
  <credentials xmlns='urn:xmpp:extdisco:1'>
    <service host='turn.shakespeare.lit'
             password='jj929jkj5sadjfj93v3n'
             username='nb78932lkjlskjfdb7g8'/>
  </credentials>
</iq>

For TURN, the server might construct time-limited credentials as described in A REST API for Access to TURN Services [14].

If the server cannot obtain credentials at the service, it returns an appropriate stanza error, such as <item-not-found/>, <remote-server-not-found/>, <remote-server-timeout/>, or <not-authorized/>.

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 (XEP-0004) [15]); this <x/> element SHOULD be a child of the <service/> element qualified by the 'urn:xmpp:extdisco:1' 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='urn:xmpp:extdisco:1'>
    <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 Field Standardization for Data Forms (XEP-0068) [16], 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 (XEP-0128) [17] specifies that an XMPP entity MUST NOT supply extended information about associated children communicated via the 'http://jabber.org/protocol/disco#info' 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 XMPP entity supports this protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:1" (see Protocol Namespaces regarding issuance of one or more permanent namespaces) in response to a Service Discovery (XEP-0030) [18] information request:

Example 8. Service Discovery Information Request

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

Example 9. Service Discovery Information Response

<iq from='montague.lit'
    id='ix61z3m9'
    to='romeo@montague.lit/orchard'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:extdisco:1'/>
  </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

8.1 Protocol Namespaces

This specification defines the following XML namespace:

Upon advancement of this specification from a status of Experimental to a status of Draft, the XMPP Registrar [19] shall add the foregoing namespace to the registry located at <http://xmpp.org/registrar/namespaces.html>, as described in Section 4 of XMPP Registrar Function (XEP-0053) [20].

8.2 Protocol Versioning

If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.

8.3 External Service Types Registry

The XMPP Registrar shall maintain a registry of external service types and their associated transport protocol(s). Such service types will probably be derived from the IANA Port Numbers Registry [21], defined DNS SRV record types, defined DDDS records for NAPTR, S-NAPTR, and U-NAPTR, and IANA Service Location Protocol, Version 2 (SLPv2) Templates [22].

8.3.1 Process

In order to submit new values to this registry, the registrant shall define an XML fragment of the following form and either include it in the relevant XMPP Extension Protocol or send it to the email address <registrar@xmpp.org>:

<service>
  <name>the XML character data of the service type</name>
  <desc>a natural-language description of the service type</desc>
  <doc>the document that best defines the service type</doc>
</service>

The registrant can register more than one service type at a time, each contained in a separate <service/> element.

8.3.2 Registration

<service>
  <name>stun</name>
  <desc>a server that provides Session Traversal Utilities for NAT (STUN)</desc>
  <doc>RFC 5389</doc>
</service>

<service>
  <name>turn</name>
  <desc>a server that provides Traversal Using Relays around NAT (TURN)</desc>
  <doc>RFC 5766</doc>
</service>

9. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:extdisco:1'
    xmlns='urn:xmpp:extdisco:1'
    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='credentials'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='service' minOccurs='0' maxOccurs='1'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='service'>
    <xs:complexType>
      <xs:sequence xmlns:xdata='jabber:x:data'>
        <xs:element ref='xdata:x' minOccurs='0'/>
      </xs:sequence>
      <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:complexType>
  </xs:element>

</xs:schema>

10. Acknowledgements

Thanks to Philipp Hancke, Justin Karneges, Evgeniy Khramtsov, and Unnikrishnan Vikrama Panicker for their feedback.

Appendices

Appendix A: Document Information

Series: XEP
Number: 0215
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.6
Last Updated: 2014-02-27
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: extdisco
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Peter Saint-Andre

Email: peter@andyet.net
JabberID: stpeter@stpeter.im
URI: https://stpeter.im/

Sean Egan

Email: seanegan@google.com
JabberID: seanegan@google.com

Marcus Lundblad

Email: ml@update.uu.se
JabberID: mlundblad@jabber.org

Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2014 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) 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 can 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

1. RFC 5389: Session Traversal Utilities for NAT (STUN) <http://tools.ietf.org/html/rfc5389>.

2. RFC 5766: Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN) <http://tools.ietf.org/html/rfc5766>.

3. XEP-0176: Jingle ICE-UDP Transport Method <http://xmpp.org/extensions/xep-0176.html>.

4. The protocol specified herein is functionally equivalent to the protocol currently used in the Google Talk service for discovery of STUN servers, as documented at <http://code.google.com/apis/talk/jep_extensions/jingleinfo.html>, but has been broadened in scope to address additional use cases if desired.

5. RFC 2782: A DNS RR for specifying the location of services (DNS SRV) <http://tools.ietf.org/html/rfc2782>.

6. RFC 2608: Service Location Protocol, Version 2 <http://tools.ietf.org/html/rfc2608>.

7. RFC 3401: Dynamic Delegation Discovery System (DDDS) Part One: The Comprehensive DDDS <http://tools.ietf.org/html/rfc3401>.

8. RFC 3403: Dynamic Delegation Discovery System (DDDS) Part Three: The Domain Name System (DNS) Database <http://tools.ietf.org/html/rfc3403>.

9. RFC 3958: Domain-Based Application Service Location Using SRV RRs and the Dynamic Delegation Discovery Service (DDDS) <http://tools.ietf.org/html/rfc3958>.

10. RFC 4848: Domain-Based Application Service Location Using URIs and the Dynamic Delegation Discovery Service (DDDS) <http://tools.ietf.org/html/rfc4848>.

11. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

12. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

13. RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core <http://tools.ietf.org/html/rfc6120>.

14. A REST API For Access To TURN Services <http://tools.ietf.org/html/draft-uberti-behave-turn-rest>. Work in progress.

15. XEP-0004: Data Forms <http://xmpp.org/extensions/xep-0004.html>.

16. XEP-0068: Field Data Standardization for Data Forms <http://xmpp.org/extensions/xep-0068.html>.

17. XEP-0128: Service Discovery Extensions <http://xmpp.org/extensions/xep-0128.html>.

18. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

19. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

20. XEP-0053: XMPP Registrar Function <http://xmpp.org/extensions/xep-0053.html>.

21. IANA registry of port numbers <http://www.iana.org/assignments/port-numbers>.

22. IANA registry of parameters related to the Service Location Protocol templates <http://www.iana.org/assignments/svrloc-templates.htm>.

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.6 (2014-02-27)

Updated references to IETF specifications.

(psa)

Version 0.5 (2010-02-17)

Added ability to request credentials from a particular service; incremented the protocol version number to reflect the new feature.

(psa)

Version 0.4 (2009-02-17)

Revived the spec by popular demand; updated namespace to use XMPP URN; defined registry process and several initial entries.

(psa/ml)

Version 0.3 (2007-08-30)

Added name attribute for human-readable labels; added internationalization considerations; added security considerations.

(psa)

Version 0.2 (2007-08-28)

Broadened scope from discovery of STUN servers to discovery of any external (non-XMPP) service.

(psa)

Version 0.1 (2007-05-16)

Initial published version.

(psa/se)

Version 0.0.5 (2007-05-10)

Added attributes for username and password; reverted to IQ method since credentials are individualized.

(psa)

Version 0.0.4 (2007-04-18)

Modified to use a well-known publish-subscribe node instead of a dedicated IQ exchange.

(psa)

Version 0.0.3 (2007-03-30)

Made port mandatory since spec assumes that SRV is not available; added XML schema.

(psa)

Version 0.0.2 (2007-03-27)

Made port optional.

(psa)

Version 0.0.1 (2007-03-23)

First draft.

(psa/se)

END