xeps/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>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 client's default settings.</li>
    <li>The server is manually added into the client's configuration by a human user.</li>
    <li>The server is discovered via DNS SRV records (see &rfc2782;) 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 &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;.</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 &lt;stun/&gt; element qualified by the "http://www.xmpp.org/extensions/xep-0215.html#ns" namespace &NSNOTE;.</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>
  <p>The XMPP server SHOULD return the list of STUN servers, but 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 list of STUN servers.</p>
  <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>The syntax of the &lt;server/&gt; element is as follows:</p>
  <ul>
    <li>The &lt;server/&gt; element SHOULD be empty.</li>
    <li>The 'host' attribute is REQUIRED and specifies either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6).</li>
    <li>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></li>
    <li>The 'username' and 'password' attributes are OPTIONAL and are used as described below.</li>
  </ul>
  <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. <note>Other implementations are possible, and long-term credentials could be used instead; see <cite>RFC 3489</cite> and <cite>rfc3489bis</cite> for details).</note></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>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.lit/orchard'
    to='montague.lit'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  ]]></example>
  <example caption="Service Discovery Information Response"><![CDATA[
<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>
  ]]></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 &REGISTRAR; 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>