JEP-0176: Jingle ICE Transport

This document defines a Jingle transport method that results in sending data between two entities using Interactive Connectivity Establishment (ICE) methodology.

WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software 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.

JEP Information

Author Information

Legal Notice

Discussion Venue

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 Jabber Software 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 JEP 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".

1. Introduction
2. Requirements
3. Protocol Description
4. Implementation Notes
5. Deployment Notes
6. Security Considerations
7. IANA Considerations
8. Jabber Registrar Considerations
9. XML Schemas
Notes
Revision History

1. Introduction

Note: This specification is out of sync with the IETF's Interactive Connectivity Establishment (ICE) document, which is a work in progress. It will be brought into synchronization after publication of version 10 of the ICE specification.

Jingle [1] defines a framework for negotiating and managing out-of-band data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor content (session) types, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data connections between XMPP entities, using the Interactive Connectivity Establishment (ICE) methodology currently being developed within the IETF (see Interactive Connectivity Establishment (ICE) [2]).

2. Requirements

The Jingle transport method defined herein is designed to meet the following requirements:

3. Protocol Description

3.1 Transport Initiation

In order for the initiating entity in a Jingle exchange to start the negotiation, it MUST send a Jingle "session-initiate" stanza as described in JEP-0166. This stanza MUST include at least one transport method. If the initiating entity wishes to negotiate the ICE transport, it MUST include an empty <transport/> child element qualified by the 'http://jabber.org/protocol/jingle/transport/ice' namespace.

Example 1. Initiation Example

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='jingle1' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle' 
          action='session-initiate' 
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <description ...>
    <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'/>
  </jingle>
</iq>

3.2 Target Entity Response

As described in JEP-0166, to provisionally accept the session initiation request, the target entity returns an IQ-result:

Example 2. Target Entity Provisionally Accepts the Session Request

<iq type='result' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'/>

3.3 Negotiation

As soon as the target entity provisionally accepts the session initiation request, the next phase of the session flow begins: negotiation of connectivity by exchanging XML-formatted candidate transports for the channel. The process for this negotiation is largely the same in Jingle as it is in Interactive Connectivity Establishment (ICE). The main exception is that Jingle takes advantage of the request-response semantics of the XMPP <iq/> stanza type by sending each candidate transport in a separate IQ exchange. The candidate syntax and negotiation flow described below.

Note: Earlier versions of JEP-0166 (from which this document has been split) contained the concept of a "default candidate"; that functionality is now described in Jingle Raw UDP Transport Method [3].

3.3.1 Syntax of Candidate Element

In contrast to ICE, in Jingle candidates are encoded into XML rather than into SDP. In addition, in Jingle a candidate is a single XML element (rather than the candidate pairs recommended in ICE).

The following is an example of the candidate format:

Example 3. Initiating Entity Sends a Candidate Transport

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='info1' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle' 
          action='transport-info'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
      <candidate name='myrtpvoice1'
                 protocol='udp'
                 preference='1.0'
                 username='/38UHtocC941jdS4' 
                 password='pcd+Z/WmsthSFIcz'
                 type='local'
                 network='0'
                 generation='0' 
                 ip='10.1.1.104' 
                 port='13540'/>
    </transport>
  </jingle>
</iq>

The attributes of the <candidate/> element are as follows:

The 'channel' attribute identifies a channel within the context of the specified session type; possible values might include 'myrtpvoice' (for Real-time Transfer Protocol) and 'myrtcpvoice' (for Real-Time Control Protocol).
The allowable values for the 'protocol' attribute are: "udp" (when standard ICE is used); "tcp", "tcp-act", and "tcp-pass" (when TCP Candidates with Interactive Connectivity Establishment (ICE) [4] is used); and "ssltcp" (definition to follow).
The 'username', 'password', and 'preference' attributes directly map to the same entities in ICE.
The 'type' attribute is used for diagnostics; the allowable values are "local", "stun" (see RFC 3489 [5]), and "relay".
The 'network' attribute is also used for diagnostics; it is an index, starting at 0, referencing which network this candidate is on for a given peer (useful if the calling hardware has more than one Network Interface Card or NIC).
The 'generation' attribute is an index, starting at 0, that enables the parties to keep track of updates to the candidate throughout the life of the session (see below).
The 'ip' attribute specifies the Internet Protocol (IP) address for the candidate transport mechanism; this may be either an IPv4 address or an IPv6 address.
The 'port' attribute specifies the port at the candidate IP address.

3.3.2 Negotiation Flow

The first step in negotiating connectivity is for each client to immediately begin sending candidate transport methods to the other client. These candidates SHOULD be gathered by following the procedure specified in Section 7.1 of ICE and prioritied by following the procedure specified in Section 7.2 of ICE. Each candidate MUST be sent in a <jingle/> element with an action of "transport-info".

If the target entity successfully receives the candidate, it returns an IQ-result (if not, for example because the candidate data is improperly formatted, it returns an error).

Note well that the target entity is only indicating receipt of the candidate, not telling the initiating entity that the candidate will be used.

The initiating entity keeps sending candidates, one after the other (without stopping to receive an acknowledgement of receipt from the target entity for each candidate) until it has exhausted its supply of possible or desirable candidate transports: [6] For each candidate, the target entity acknowledges receipt.

At the same time (i.e., immediately after provisionally accepting the session, not waiting for the initiating entity to begin or finish sending candidates), the target entity also begins sending candidates that may work for it. As above, the initiating entity acknowledges receipt of the candidates.

As the initiating entity and target entity receive candidates, they probe the various candidate transports for connectivity. In performing these connectivity checks, client SHOULD follow the procedure specified in Section 7.6 of ICE.

Example 4. Initiating Entity Sends a Candidate

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='info1' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle' 
          action='transport-info' 
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
      <candidate name='myrtpvoice1'
                 protocol='udp'
                 preference='1.0'
                 username='/38UHtocC941jdS4' 
                 password='pcd+Z/WmsthSFIcz'
                 type='local'
                 network='0'
                 generation='0' 
                 ip='10.1.1.104' 
                 port='13540'/>
    </transport>
  </jingle>
</iq>

Example 5. Initiating Entity Sends a Second Candidate

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='info2' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle' 
          action='transport-info' 
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
      <candidate name='myrtpvoice2'
                 protocol='udp'
                 preference='0.8'
                 type='stun'
                 username='ld6Hi+PfVtnmU8cf'
                 password='gzoufy3aMXBRtiWs'
                 network='1'
                 generation='0' 
                 ip='1.2.3.4' 
                 port='6459'/>
    </transport>
  </jingle>
</iq>

Example 6. Initiating Entity Sends a Third Candidate

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='info3' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle' 
          action='transport-info' 
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
      <candidate name='myrtpvoice3'
                 protocol='udp'
                 preference='0.1'
                 type='relay'
                 username='XKqUmqiftjPUYAbF'
                 password='G4116MkgTzb8+1N/'
                 network='2'
                 generation='0' 
                 ip='5.6.7.8' 
                 port='9823'/>
    </transport>
  </jingle>
</iq>

For each candidate received, the other party MUST acknowledge receipt or return an error:

Example 7. Receiving Entity Acknowledges Receipt

<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='info1' type='result'/>

<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='info2' type='result'/>

<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='info3' type='result'/>

3.4 Acceptance

If, based on STUN connectivity checks, either entity determines that it will be able to establish a connection, it sends a <jingle/> element with an action of 'transport-accept' to the initiating entity, specifying the acceptable candidate:

Example 8. Juliet Definitively Accepts the Call

<iq type='set' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='accept1'>
  <jingle xmlns='http://jabber.org/protocol/jingle'
          action='transport-accept' 
          initiator='romeo@montague.net/orchard'
          responder='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
      <candidate name='myrtpvoice3'
                 protocol='udp'
                 preference='0.1'
                 type='relay'
                 username='XKqUmqiftjPUYAbF'
                 password='G4116MkgTzb8+1N/'
                 network='2'
                 generation='0' 
                 ip='5.6.7.8' 
                 port='9823'/>
    </transport>
  </jingle>
</iq>

The <jingle/> element in the transport-accept stanza SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity. If provided, all future commmunications SHOULD be sent to the JID provided in the 'responder' attribute.

The initiating entity then acknowledges the target entity's acceptance:

Example 9. Romeo Acknowledges Definitive Acceptance

<iq type='result' to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='accept1'/>

Now the initiating entity and target entity can begin sending data over the negotiated connection.

In the event that the target entity cannot find a suitable candidate transport, it SHOULD terminate the session as described below.

3.5 Termination

In order to gracefully end the session, either the target entity or the initiating entity MUST a send a "terminate" action to the other party:

Example 10. Juliet Terminates the Session

<iq from='juliet@capulet.com/balcony' 
    id='term1' 
    to='romeo@montague.net/orchard' 
    type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle'
          action='terminate' 
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'/>
</iq>

The initiating entity then acknowledges termination of the session:

Example 11. Romeo Acknowledges Termination

<iq type='result' to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='term1'/>

Unfortunately, not all sessions end gracefully. The following events MUST be considered session-ending events, and any further communication for the session type MUST be completed through negotiation of a new session:

Receipt of a 'redirect' or 'terminate' action from the other party.
Receipt of <presence type='unavailable'/> from the other party.

In particular, one party MUST consider the session to be in the ENDED state if it receives presence of type "unavailable" from the other party:

Example 12. Juliet Goes Offline

<presence from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='unavailable'/>

Naturally, in this case there is nothing for the initiating entity to acknowledge.

3.6 Informational Messages

The syntax and semantics informational message payloads specific to the ICE transport method will be defined in a future version of this specification.

4. Implementation Notes

4.1 DTMF

If it is necessary to send Dual Tone Multi-Frequency (DTMF) tones, it is REQUIRED to use the XML format specified Jingle DTMF [7].

5. Deployment Notes

This specification applies exclusively to Jabber/XMPP clients and places no additional requirements on Jabber/XMPP servers. However, service administrators may wish to deploy a STUN server and/or data relay service in order to ease the client-to-client negotiation process.

6. Security Considerations

6.1 End-to-End Data Encryption

In order to secure the end-to-end data stream, implementations SHOULD use encryption methods appropriate to the transport method in use.

7. IANA Considerations

This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [8].

8. Jabber Registrar Considerations

8.1 Protocol Namespaces

The Jabber Registrar [9] shall include 'http://jabber.org/protocol/jingle/transport/ice' in its registry of protocol namespaces.

8.2 Jingle Transport Methods

The Jabber Registrar shall include "http://jabber.org/protocol/jingle/transport/ice" in its registry of Jingle transport methods. The registry submission is as follows:

In order to submit new values to this registry, the registrant must define an XML fragment of the following form and either include it in the relevant Jabber Enhancement Proposal or send it to the email address <registrar@jabber.org>:

<transport>
  <name>ice</name>
  <desc>
    A method for negotiation of out-of-band connections with built-in NAT and firewall traversal, 
    similar to the IETF's Interactive Connectivity Establishment (ICE) methodology.
  </desc>
  <doc>JEP-0176</doc>
</transport>

9. XML Schemas

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/jingle/transports/ice'
    xmlns='http://jabber.org/protocol/jingle/transports/ice'
    elementFormDefault='qualified'>

  <xs:element name='transport'>
    <xs:complexType>
      <xs:choice>
        <xs:sequence>
          <xs:element ref='candidate' minOccurs='0' maxOccurs='1'/>
        </xs:sequence>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:element name='candidate'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='generation' type='xs:unsignedByte' use='required'/>
          <xs:attribute name='ip' type='xs:string' use='required'/>
          <xs:attribute name='name' type='xs:string' use='optional'/>
          <xs:attribute name='network' type='xs:unsignedByte' use='required'/>
          <xs:attribute name='password' type='xs:string' use='required'/>
          <xs:attribute name='port' type='xs:unsignedShort' use='required'/>
          <xs:attribute name='preference' type='xs:decimal' use='required'/>
          <xs:attribute name='username' type='xs:string' use='required'/>
        </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

1. JEP-0166: Jingle <http://www.jabber.org/jeps/jep-0166.html>.

2. Interactive Connectivity Establishment (ICE): A Methodology for Network Address Translator (NAT) Traversal for Offer/Answer Protocols <http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-09.txt>. Work in progress.

3. JEP-0177: Jingle Raw UDP Transport Method <http://www.jabber.org/jeps/jep-0177.html>.

4. TCP Candidates with Interactive Connectivity Establishment (ICE) <http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-tcp-00.txt>. Work in progress.

5. RFC 3489: STUN - Simple Traversal of User Datagram Protocol (UDP) Through Network Address Translators (NATs) <http://www.ietf.org/rfc/rfc3489.txt>.

6. Because certain candidates may be more "expensive" in terms of bandwidth or processing power, the initiator may not want to advertise their existence unless necessary.

7. JEP-0181: Jingle DTMF <http://www.jabber.org/jeps/jep-0181.html>.

8. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

9. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.