<p>An XMPP client 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 &rfc3489; and &rfc3489bis;) and STUN relays (see &turn;) for the sake of negotiating media exchanges via &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 <<linkurl='http://code.google.com/apis/talk/jep_extensions/jingleinfo.html'>http://code.google.com/apis/talk/jep_extensions/jingleinfo.html</link>>, but has been broadened in scope to address additional use cases if desired.</note> An XMPP client can already discover such external services in several ways, including:</p>
<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 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 client or server. This method does not use &xep0030; since that technology is designed for discovery of XMPP entities, not entities outside an XMPP network.</p>
<p>In order to learn about external services known to an XMPP server, a client sends an IQ-get containing an empty <services/> element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace &NSNOTE;, typically to its own server (but perhaps to a dedicated discovery service).</p>
<p>The XMPP server (or service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as &unavailable; if the server 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.</p>
<p>Note: The processes by which an XMPP server discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p>
<p>The <service/> element MAY be empty or MAY include extended information about the service as described in the <linkurl='#extended'>Extended Information</link> section of this document.</p>
<p>The attributes of the <service/> element are summarized in the following table.</p>
<tablecaption='Attributes'>
<tr>
<th>Name</th>
<th>Definition</th>
<th>Inclusion</th>
</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>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>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 ®ISTRAR;.</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>
<section1topic='Use Cases'anchor='usecases'>
<section2topic='Requesting All Services'anchor='all'>
<p>A client requests all services by sending a <services/> element to its server.</p>
<examplecaption='Entity Requests All External Services'><