xep-0215.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>External Service Discovery</title>
  <abstract>This document specifies an XMPP protocol extension for discovering services external to the XMPP network.</abstract>
  &LEGALNOTICE;
  <number>0215</number>
  <status>Draft</status>
  <lastcall>2022-07-27</lastcall>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>extdisco</shortname>
  &stpeter;
  &seanegan;
  &mlundblad;
  &lance;
  <revision>
    <version>1.0.0</version>
    <date>2022-08-23</date>
    <initials>XEP Editor (jsc)</initials>
    <remark>Accept as Stable as per Council Vote from 2022-08-03.</remark>
  </revision>
  <revision>
    <version>0.7.2</version>
    <date>2021-10-23</date>
    <initials>egp</initials>
    <remark>
      <p>Fix the schema to:</p>
      <ul>
        <li>Allow more than a single &lt;service/&gt; in &lt;services/&gt;.</li>
        <li>Restrict the 'port' attribute to xs:unsignedShort, but make it optional as per section 3.3.</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.7.1</version>
    <date>2021-08-31</date>
    <initials>ka</initials>
    <remark><p>Fix incorrect type on IQ response in example 7</p></remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2015-10-20</date>
    <initials>ls</initials>
    <remark>
      <ul>
        <li>Clarified which attributes are needed to identify a service when requesting credentials.</li>
        <li>Added 'action' attribute to indicate if a service is being added/removed/updated in a push update.</li>
        <li>Added 'expires' attribute to indicate when provided credentials will expire.</li>
        <li>Added 'restricted' attribute to indicate the need for fetching credentials for a service.</li>
        <li>Bumped namespace version.</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2014-02-27</date>
    <initials>psa</initials>
    <remark><p>Updated references to IETF specifications.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2010-02-17</date>
    <initials>psa</initials>
    <remark><p>Added ability to request credentials from a particular service; incremented the protocol version number to reflect the new feature.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2009-02-17</date>
    <initials>psa/ml</initials>
    <remark><p>Revived the spec by popular demand; updated namespace to use XMPP URN; defined registry process and several initial entries.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2007-08-30</date>
    <initials>psa</initials>
    <remark><p>Added name attribute for human-readable labels; added internationalization considerations; added security considerations.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2007-08-28</date>
    <initials>psa</initials>
    <remark><p>Broadened scope from discovery of STUN servers to discovery of any external (non-XMPP) service.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2007-05-16</date>
    <initials>psa/se</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.5</version>
    <date>2007-05-10</date>
    <initials>psa</initials>
    <remark><p>Added attributes for username and password; reverted to IQ method since credentials are individualized.</p></remark>
  </revision>
  <revision>
    <version>0.0.4</version>
    <date>2007-04-18</date>
    <initials>psa</initials>
    <remark><p>Modified to use a well-known publish-subscribe node instead of a dedicated IQ exchange.</p></remark>
  </revision>
  <revision>
    <version>0.0.3</version>
    <date>2007-03-30</date>
    <initials>psa</initials>
    <remark><p>Made port mandatory since spec assumes that SRV is not available; added XML schema.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2007-03-27</date>
    <initials>psa</initials>
    <remark><p>Made port optional.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2007-03-23</date>
    <initials>psa/se</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>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 &rfc5389;) and TURN relays (see &rfc5766;) for the sake of negotiating media exchanges via the &xep0176;. <note>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 &lt;<link url='http://code.google.com/apis/talk/jep_extensions/jingleinfo.html'>http://code.google.com/apis/talk/jep_extensions/jingleinfo.html</link>&gt;, but has been broadened in scope to address additional use cases if desired.</note> An XMPP entity can already discover such external services in several ways, including:</p>
  <ol>
    <li>The service is specified in the application's default settings.</li>
    <li>The service is manually added into the application's configuration by a human user.</li>
    <li>The service is discovered via non-XMPP service discovery protocols, such as:
      <ul>
        <li>DNS SRV records (&rfc2782;)</li>
        <li>Service Location Protocol (SLP; &rfc2608;)</li>
        <li>The Dynamic Delegation Discovery System (DDDS; &rfc3401;)</li>
        <li>The NAPTR profile of DDDS (&rfc3403;)</li>
        <li>The S-NAPTR profile of DDDS (&rfc3958;)</li>
        <li>The U-NAPTR profile of DDDS (&rfc4848;)</li>
      </ul>
    </li>
  </ol>
  <p>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 &xep0030; since that technology is designed for discovery of XMPP entities, not entities outside an XMPP network.</p>
</section1>

<section1 topic='Protocol' anchor='protocol'>
  <p>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 &lt;services/&gt; element qualified by the 'urn:xmpp:extdisco:2' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.</p>
  <p>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 &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 &lt;service/&gt; element.</p>
  <p>Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p>
  <p>The &lt;service/&gt; element MAY be empty or MAY include extended information about the service as described in the <link url='#extended'>Extended Information</link> section of this document.</p>
  <p>The attributes of the &lt;service/&gt; element are summarized in the following table.</p>
  <table caption='Attributes'>
    <tr>
      <th>Name</th>
      <th>Definition</th>
      <th>Inclusion</th>
    </tr>
    <tr>
      <td>action</td>
      <td>When sending a push update, the action value indicates if the service is being added or deleted from the set of known services (or simply being modified). The defined values are "add", "remove", and "modify", where "add" is the default.</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>expires</td>
      <td>A timestamp indicating when the provided username and password credentials will expire. The format MUST adhere to the dateTime format specified in &xep0082; and MUST be expressed in UTC.</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>host</td>
      <td>Either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6).</td>
      <td>REQUIRED</td>
    </tr>
    <tr>
      <td>name</td>
      <td>A friendly (human-readable) name or label for the service.</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>password</td>
      <td>A service- or server-generated password for use at the service. *</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>port</td>
      <td>The communications port to be used at the host.</td>
      <td>RECOMMENDED</td>
    </tr>
    <tr>
      <td>restricted</td>
      <td>A boolean value indicating that username and password credentials are required and will need to be requested if not already provided (see <link url="#credentials">Requesting Credentials</link>).</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>transport</td>
      <td>The underlying transport protocol to be used when communicating with the service (typically either TCP or UDP).</td>
      <td>RECOMMENDED</td>
    </tr>
    <tr>
      <td>type</td>
      <td>The service type as registered with the &REGISTRAR;.</td>
      <td>REQUIRED</td>
    </tr>
    <tr>
      <td>username</td>
      <td>A service- or server-generated username for use at the service. *</td>
      <td>OPTIONAL</td>
    </tr>
  </table>
  <p>* 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.</p>
</section1>

<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Requesting All Services' anchor='all'>
    <p>A requesting entity requests all services by sending a &lt;services/&gt; element to its server or a discovery service.</p>
    <example caption='Entity Requests All External Services'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
    id='ul2bc7y6'
    to='shakespeare.lit'
    type='get'>
  <services xmlns='urn:xmpp:extdisco:2'/>
</iq>
]]></example>
    <example caption='XMPP Server Returns List'><![CDATA[
<iq from='shakespeare.lit'
    id='ul2bc7y6'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <services xmlns='urn:xmpp:extdisco:2'>
    <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>
]]></example>
  </section2>
  <section2 topic='Requesting Selected Services' anchor='select'>
    <p>A requesting entity requests services of a particular type by sending a &lt;services/&gt; element including a 'type' attribute specifying the service type of interest.</p>
    <example caption='Entity Requests Selected Services'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
    id='yv2c19f7'
    to='shakespeare.lit'
    type='get'>
  <services xmlns='urn:xmpp:extdisco:2' type='turn'/>
</iq>
]]></example>
    <example caption='XMPP Server Returns List'><![CDATA[
<iq from='shakespeare.lit'
    id='yv2c19f7'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <services xmlns='urn:xmpp:extdisco:2'
            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>
]]></example>
    <p>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 &lt;services/&gt; payload with updated data about services matching the requested type (e.g., new services or updated credentials). Each &lt;service/&gt; element SHOULD contain an 'action' attribute indicating if the service is being added, deleted, or modified.</p>
    <example caption='Services Push'><![CDATA[
<iq from='shakespeare.lit'
    id='lh3f1vc7'
    to='bard@shakespeare.lit/globe'
    type='set'>
  <services xmlns='urn:xmpp:extdisco:2'
            type='turn'>
    <service action='add'
             host='stun.shakespeare.lit'
             port='9999'
             transport='udp'
             type='turn'
             username='1nas9dlm3hzl89d0b9v'
             password='gh9023ljjdk109iajqn'>
    <service action='add'
             host='192.0.2.2'
             port='7778'
             transport='udp'
             type='turn'
             username='bnsv120afg48snsdozp'
             password='zxp023na98dsfahn1kk'/>
    <service action='delete'
             host='192.0.2.1'
             port='8889'
             type='turn'/>
  </services>
</iq>
]]></example>
    <p>Upon receiving a push, the requesting entity would then send an IQ-result to the responding service in accordance with &xmppcore;.</p>
  </section2>
  <section2 topic='Requesting Credentials' anchor='credentials'>
      <p>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 composed of a &lt;credentials/&gt; element qualified by the 'urn:xmpp:extdisco:2' namespace and contains a &lt;service/&gt; element which MUST include the 'host' and 'type' attributes to identify the desired service (the 'port' attribute MAY be provided if there are multiple services with the same host and type but different ports).</p>
    <example caption='Entity Requests Credentials at a Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
    id='xi2cax48'
    to='shakespeare.lit'
    type='get'>
  <credentials xmlns='urn:xmpp:extdisco:2'>
    <service host='turn.shakespeare.lit' type='turn' />
  </credentials>
</iq>
]]></example>
    <p>The server then returns credentials if possible.</p>
    <example caption='Server Returns Credentials'><![CDATA[
<iq from='shakespeare.lit'
    id='xi2cax48'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <credentials xmlns='urn:xmpp:extdisco:2'>
    <service host='turn.shakespeare.lit'
             type='turn'
             password='jj929jkj5sadjfj93v3n'
             username='nb78932lkjlskjfdb7g8'/>
  </credentials>
</iq>
]]></example>
    <p>For TURN, the server might construct time-limited credentials as described in &turn-rest;.</p>
    <p>There MAY be multiple &lt;service/&gt; elements in the result if more than one service matched the requested service identity (e.g., the same host provides service on multiple ports).</p>
    <p>If the server cannot obtain credentials at the service, it returns an appropriate stanza error, such as &notfound;, &remoteserver;, &timeout;, or &notauthorized;.</p>
  </section2>
</section1>

<section1 topic='Extended Information' anchor='extended'>
  <p>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 &lt;value/&gt; child of a distinct &lt;field/&gt; element, with the entire set of fields contained within an &lt;x/&gt; element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this &lt;x/&gt; element SHOULD be a child of the &lt;service/&gt; element qualified by the 'urn:xmpp:extdisco:2' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:</p>
  <code><![CDATA[
<iq type='result'>
  <services xmlns='urn:xmpp:extdisco:2'>
    <service>
      <x type='result' xmlns='jabber:x:data'>
        <field var='[var-name]' label='[optional]'>
          <value>[var-value]</value>
        </field>
        [ ... ]
      </x>
    </service>
  </services>
</iq>]]></code>
  <p>Note: A &lt;field/&gt; element MAY contain more than one &lt;value/&gt; child if appropriate.</p>
  <p>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 &xep0068;, resulting in the inclusion of a &lt;field/&gt; element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".</p>
  <p>Note: Although &xep0128; 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.</p>
</section1>

<section1 topic='Determining Support' anchor='disco'>
  <p>If an XMPP entity supports this protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:2" &NSNOTE; in response to a &xep0030; information request:</p>
  <example caption="Service Discovery Information Request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='ix61z3m9'
    to='montague.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption="Service Discovery Information Response"><![CDATA[
<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:2'/>
  </query>
</iq>
]]></example>
</section1>

<section1 topic='Internationalization Considerations' anchor='i18n'>
  <p>If the requesting entity includes an 'xml:lang' attribute with its request, the responding entity SHOULD include appropriately internationalized text as the value of the 'name' attribute. No other attributes are human-readable.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>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.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:extdisco:2</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
  <section2 topic='External Service Types Registry' anchor='registrar-services'>
    <p>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 &ianaports;, defined DNS SRV record types, defined DDDS records for NAPTR, S-NAPTR, and U-NAPTR, and &ianaslp;.</p>
    <section3 topic='Process' anchor='registrar-methods-process'>
      &REGPROCESS;
      <code><![CDATA[
<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>
]]></code>
      <p>The registrant can register more than one service type at a time, each contained in a separate &lt;service/&gt; element.</p>
    </section3>
    <section3 topic='Registration' anchor='registrar-methods-init'>
      <code><![CDATA[
<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>
]]></code>
    </section3>
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:extdisco:2'
    xmlns='urn:xmpp:extdisco:2'
    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' maxOccurs='unbounded'>
        <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='unbounded'/>
      </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='action' use='optional' default='add'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='add'/>
            <xs:enumeration value='delete'/>
            <xs:enumeration value='modify'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='expires' type='xs:dateTime' use='optional'/>
      <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:unsignedShort' use='optional'/>
      <xs:attribute name='restricted' type='xs:boolean' use='optional'/>
      <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>
]]></code>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Philipp Hancke, Justin Karneges, Evgeniy Khramtsov, and Unnikrishnan Vikrama Panicker for their feedback.</p>
</section1>

</xep>