mirror of https://github.com/moparisthebest/xeps
209 lines
8.9 KiB
XML
209 lines
8.9 KiB
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>STUN Server Discovery for Jingle</title>
|
||
|
|
<abstract>This document specifies methods for discovering STUN servers for use in negotiation of certain Jingle transport methods.</abstract>
|
||
|
|
&LEGALNOTICE;
|
||
|
|
<number>0215</number>
|
||
|
|
<status>Experimental</status>
|
||
|
|
<type>Standards Track</type>
|
||
|
|
<sig>Standards</sig>
|
||
|
|
<approver>Council</approver>
|
||
|
|
<dependencies>
|
||
|
|
<spec>XMPP Core</spec>
|
||
|
|
</dependencies>
|
||
|
|
<supersedes/>
|
||
|
|
<supersededby/>
|
||
|
|
<shortname>NOT YET ASSIGNED</shortname>
|
||
|
|
&stpeter;
|
||
|
|
&seanegan;
|
||
|
|
<revision>
|
||
|
|
<version>0.1</version>
|
||
|
|
<date>2007-05-16</date>
|
||
|
|
<initials>psa</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>The administrator of an XMPP server may wish to deploy one or more STUN servers (see &rfc3489; and &rfc3489bis;) in order to ease the process of negotiating media exchanges via &xep0176;. A client can become aware of a STUN server in the following ways:</p>
|
||
|
|
<ol>
|
||
|
|
<li>The server is specified in the default settings for the client.</li>
|
||
|
|
<li>The server is manually added by a human user into the client's configuration.</li>
|
||
|
|
<li>The server is discovered via DNS SRV records as specified in Section 9.1 of <cite>RFC 3489</cite>.</li>
|
||
|
|
</ol>
|
||
|
|
<p>Unfortunately, the foregoing methods are subject to human error or cannot be deployed in wide range of scenarios. Therefore, this document defines a way for an XMPP server to advertise a list of STUN servers and provide credentials for use by an XMPP client at a STUN server. This method SHOULD be used only as a fallback when DNS SRV lookups are not possible for the client or server.</p>
|
||
|
|
<p>Note: The protocol specified herein is functionally equivalent to the protocol currently used in the Google Talk service and documented at <<link url='http://code.google.com/apis/talk/jep_extensions/jingleinfo.html'>http://code.google.com/apis/talk/jep_extensions/jingleinfo.html</link>>.</p>
|
||
|
|
</section1>
|
||
|
|
|
||
|
|
<section1 topic='Protocol' anchor='protocol'>
|
||
|
|
<p>In order to learn about available STUN servers associated with or known by an XMPP server, a client sends an IQ-get containing a <stun/> element qualified by the "http://www.xmpp.org/extensions/xep-0215.html#ns" namespace &NSNOTE;.</p>
|
||
|
|
<p>An example of the payload format for this node is as follows:</p>
|
||
|
|
<example caption='Entity Requests STUN Server List from XMPP Server'><![CDATA[
|
||
|
|
<iq type='get'
|
||
|
|
from='bard@shakespeare.lit/globe'
|
||
|
|
to='shakespeare.lit'
|
||
|
|
id='get1'>
|
||
|
|
<stun xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'/>
|
||
|
|
</iq>
|
||
|
|
]]></example>
|
||
|
|
<example caption='XMPP Server Returns List'><![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='shakespeare.lit'
|
||
|
|
to='bard@shakespeare.lit/globe'
|
||
|
|
id='get1'>
|
||
|
|
<stun xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'>
|
||
|
|
<server host='stun.shakespeare.lit' port='9999'/>
|
||
|
|
<server host='192.0.2.1' port='10001'/>
|
||
|
|
</stun>
|
||
|
|
</iq>
|
||
|
|
]]></example>
|
||
|
|
<p>(Naturally, the XMPP MAY instead return an appropriate error, such as &unavailable; if the server does not support the STUN Server Discovery protocol or &forbidden; if the requesting entity does not have permission to receive the server list.)</p>
|
||
|
|
<p>The 'host' attribute is REQUIRED and specifies either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6). The 'port' attribute is REQUIRED and specifies the communications port to be used at the host. <note>The port is necessary since this specification assumes that DNS SRV lookups are not possible.</note></p>
|
||
|
|
<p>A STUN server may require a username and password in order to accept STUN binding requests and/or STUN allocate requests. In this case, the XMPP server would typically generate a short-term authentication credential based on a private key shared with the STUN server (naturally, other implementations are possible, and long-term credentials could be used instead; see <cite>RFC 3489</cite> and <cite>rfc3489bis</cite> for details).</p>
|
||
|
|
<example caption='XMPP Server Returns List With Credentials'><![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='shakespeare.lit'
|
||
|
|
to='bard@shakespeare.lit/globe'
|
||
|
|
id='get1'>
|
||
|
|
<stun xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'>
|
||
|
|
<server host='stun.shakespeare.lit'
|
||
|
|
port='9999'
|
||
|
|
username='nb78932lkjlskjfdb7g8'
|
||
|
|
password='jj929jkj5sadjfj93v3n'>
|
||
|
|
<server host='192.0.2.1'
|
||
|
|
port='10001'
|
||
|
|
username='auu98sjl2wk3e9fjdsl7'
|
||
|
|
password='93jn3bakj9s832lrjbbz'/>
|
||
|
|
</stun>
|
||
|
|
</iq>
|
||
|
|
]]></example>
|
||
|
|
<p>The 'username' and 'password' attributes are OPTIONAL.</p>
|
||
|
|
<p>An XMPP server MAY send an updated list of STUN servers by "pushing" the list to a client that has previously requested the list:</p>
|
||
|
|
<example caption='List Push'><![CDATA[
|
||
|
|
<iq type='set'
|
||
|
|
from='shakespeare.lit'
|
||
|
|
to='bard@shakespeare.lit/globe'
|
||
|
|
id='push1'>
|
||
|
|
<stun xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'>
|
||
|
|
<server host='stun.shakespeare.lit'
|
||
|
|
port='9999'
|
||
|
|
username='1nas9dlm3hzl89d0b9v'
|
||
|
|
password='gh9023ljjdk109iajqn'>
|
||
|
|
<server host='192.0.2.2'
|
||
|
|
port='10002'
|
||
|
|
username='bnsv120afg48snsdozp'
|
||
|
|
password='zxp023na98dsfahn1kk'/>
|
||
|
|
</stun>
|
||
|
|
</iq>
|
||
|
|
]]></example>
|
||
|
|
</section1>
|
||
|
|
|
||
|
|
<section1 topic='Determining Support' anchor='disco'>
|
||
|
|
<p>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" &NSNOTE; in response to a &xep0030; information request:</p>
|
||
|
|
<example caption="Service Discovery Information Request"><![CDATA[
|
||
|
|
<iq type='get'
|
||
|
|
from='romeo@montague.net/orchard'
|
||
|
|
to='juliet@capulet.com/balcony'
|
||
|
|
id='disco1'>
|
||
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
||
|
|
</iq>
|
||
|
|
]]></example>
|
||
|
|
<example caption="Service Discovery Information Response"><![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='juliet@capulet.com/balcony'
|
||
|
|
to='romeo@montague.net/orchard'
|
||
|
|
id='disco1'>
|
||
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||
|
|
...
|
||
|
|
<feature var='http://www.xmpp.org/extensions/xep-0215.html#ns'/>
|
||
|
|
...
|
||
|
|
</query>
|
||
|
|
</iq>
|
||
|
|
]]></example>
|
||
|
|
</section1>
|
||
|
|
|
||
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||
|
|
<section2 topic='Protocol Namespaces' anchor='ns'>
|
||
|
|
<p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0215.html#ns"; upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
|
||
|
|
</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='http://www.xmpp.org/extensions/xep-0215.html#ns'
|
||
|
|
xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'
|
||
|
|
elementFormDefault='qualified'>
|
||
|
|
|
||
|
|
<xs:element name='stun'>
|
||
|
|
<xs:complexType>
|
||
|
|
<xs:sequence minOccurs='0'>
|
||
|
|
<xs:element ref='server'/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='server'>
|
||
|
|
<xs:complexType>
|
||
|
|
<xs:simpleContent>
|
||
|
|
<xs:extension base='empty'>
|
||
|
|
<xs:attribute name='host' type='xs:string' use='required'/>
|
||
|
|
<xs:attribute name='password' type='xs:string' use='optional'/>
|
||
|
|
<xs:attribute name='port' type='xs:string' 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>
|
||
|
|
]]></code>
|
||
|
|
</section1>
|
||
|
|
|
||
|
|
</xep>
|