XEP-0215: STUN Server Discovery for Jingle

This document specifies methods for discovering STUN servers for use in negotiation of certain Jingle transport methods.

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 should not deploy implementations of this protocol until it advances to a status of Draft.

Document Information

Series: XEP
Number: 0215
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.1
Last Updated: 2007-05-16
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: NOT YET ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/STUN Server Discovery for Jingle (XEP-0215)>

Author Information

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Relation to XMPP

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

Conformance Terms

The following 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".

Table of Contents

1. Introduction

The administrator of an XMPP server may wish to deploy one or more STUN servers (see RFC 3489 [1] and draft-ietf-behave-rfc3489bis-06 [2]) in order to ease the process of negotiating media exchanges via Jingle ICE Transport Method [3]. A client can become aware of a STUN server in the following ways:

1. The server is specified in the client's default settings.
2. The server is manually added into the client's configuration by a human user.
3. The server is discovered via DNS SRV records (see RFC 2782 [4]) as specified in Section 9.1 of RFC 3489.

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.

Note: The protocol specified herein is functionally equivalent to the protocol currently used in the Google Talk service and documented at <http://code.google.com/apis/talk/jep_extensions/jingleinfo.html>.

2. Protocol

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 (see Protocol Namespaces regarding issuance of one or more permanent namespaces).

Example 1. Entity Requests STUN Server List from XMPP Server

<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>
  

The XMPP server SHOULD return the list of STUN servers, but MAY instead return an appropriate error, such as <service-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.

Example 2. XMPP Server Returns List

<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>
  

The syntax of the <server/> element is as follows:

• The <server/> element SHOULD be empty.
• 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. [5]
• The 'username' and 'password' attributes are OPTIONAL and are used as described below.

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. [6]

Example 3. XMPP Server Returns List With Credentials

<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>
  

An XMPP server MAY send an updated list of STUN servers by "pushing" the list to a client that has previously requested the list:

Example 4. List Push

<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>
  

3. Determining Support

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" (see Protocol Namespaces regarding issuance of one or more permanent namespaces) in response to a Service Discovery [7] information request:

Example 5. Service Discovery Information Request

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

Example 6. Service Discovery Information Response

<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>
  

4. XMPP Registrar Considerations

5. XML Schema

<?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>
  

Notes

Revision History

END