XEP-0166: Jingle

This document defines a framework for initiating and managing peer-to-peer sessions (e.g., voice and video exchanges) between Jabber/XMPP clients in a way that is interoperable with existing Internet standards.


NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the JSF standards process.


XEP Information

Status: Proposed
Type: Standards Track
Number: 0166
Version: 0.10
Last Updated: 2006-09-29
Publishing Organization: Jabber Software Foundation
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: jingle
Wiki Page: <http://wiki.jabber.org/index.php/Jingle (XEP-0166)>

Author Information

Scott Ludwig

Email: scottlu@google.com
JID: scottlu@google.com

Joe Beda

Email: jbeda@google.com
JID: jbeda@google.com

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Joe Hildebrand

Email: jhildebrand@jabber.com
JID: hildjj@jabber.org

Sean Egan

Email: seanegan@google.com
JID: seanegan@google.com

Robert McQueen

Email: robert.mcqueen@collabora.co.uk
JID: robert.mcqueen@collabora.co.uk

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF'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-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

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 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
2. Requirements
3. Glossary
4. Concepts and Approach
4.1. Overall Session Management
4.2. Session Content
4.2.1. Content Description Formats
4.2.2. Content Transport Methods
5. Protocol
5.1. Resource Determination
5.2. Initiation
5.3. Target Entity Response
5.4. Redirection
5.5. Decline
5.6. Negotiation
5.7. Acceptance
5.8. Modifying an Active Session
5.9. Termination
5.10. Informational Messages
6. Error Handling
7. Implementation Notes
8. Security Considerations
8.1. Denial of Service
8.2. Communication Through Gateways
9. IANA Considerations
10. XMPP Registrar Considerations
10.1. Protocol Namespaces
10.2. Jingle Content Description Formats Registry
10.3. Jingle Content Transport Methods Registry
11. XML Schemas
11.1. Jingle
11.2. Jingle Errors
12. Acknowledgements
Notes
Revision History


1. Introduction

There exists no widely-adopted standard for initiating and managing peer-to-peer (p2p) interactions (such as voice, video, or file sharing exchanges) from within Jabber/XMPP clients. Although several large service providers and Jabber/XMPP clients have written and implemented their own proprietary XMPP extensions for p2p signalling (usually only for voice), those technologies are not open and do not always take into account requirements to interoperate with the Public Switched Telephone Network (PSTN) or emerging SIP-based Internet voice networks. By contrast, the only existing open protocol has been A Transport for Initiating and Negotiating Sessions [1], which made it possible to initiate and manage p2p sessions, but which did not provide enough of the key signalling semantics to be easily implemented in Jabber/XMPP clients. [2]

The result has been an unfortunate fragmentation within the XMPP community regarding signalling protocols. There are, essentially, two approaches to solving the problem:

  1. Recommend that all client developers implement a dual-stack (XMPP + SIP) solution.
  2. Define a full-featured protocol for XMPP signalling.

Implementation experience indicates that a dual-stack approach may not be feasible on all the computing platforms for which Jabber clients have been written, or even desirable on platforms where it is feasible. [3] Therefore, it seems reasonable to define an XMPP signalling protocol that can provide the necessary signalling semantics while also making it possible to interoperate with existing Internet standards.

As a result of feedback received on XEP-0111, the second and fourth authors of this document began to define such a signalling protocol, code-named Jingle. Upon communication with members of the Google Talk team, [4] it was discovered that the emerging Jingle approach was conceptually (and even syntactically) quite similar to the signalling protocol used in the Google Talk application. Therefore, in the interest of interoperability and adoption, we decided to harmonize the two approaches. The signalling protocol specified therein is, therefore, substantially equivalent to the existing Google Talk protocol, with several adjustments based on feedback received from implementors as well as for publication within the Jabber Software Foundation's standards process.

2. Requirements

The protocol defined herein is designed to meet the following requirements:

  1. Make it possible to manage a wide variety of peer-to-peer sessions (not limited to voice and video) within XMPP. [5]
  2. Make it possible to add, modify, and remove content types from an existing session.
  3. Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.
  4. Where communication with non-XMPP entities is needed, push as much complexity as possible onto server-side gateways between the XMPP network and the non-XMPP network.

This document defines the signalling protocol only. Additional documents specify the following:

3. Glossary

Table 1: Glossary

Term Definition
Session A number of pairs of negotiated content transport methods and content description formats connecting two entities. It is delimited in time by an initiate request and session ending events. During the lifetime of a session, pairs of content descriptions and content transport methods can be added or removed.
Content Type A formal declaration of the purpose(s) of the session. Common sessions might include types such as "voice", both "voice" and "video", and "file sharing". A session consists of at least one active negotiated content type at a time. Depending on the content type and the content description, one content description may require multiple components to be communicated by the transport. This is the 'what' of the session. In Jingle XML syntax the content type is the namespace of the <description/> element.
Content Description The details of the content type being established. For instance, this might describe the acceptable codecs when establishing a voice conversation. The XML elements for the content description are qualified by the namespace of the content type. The content description defines the bits to be transferred.
Transport Method The method for establishing data stream(s) between entities. Possible transports might include Jingle RTP-ICE Transport Method [10], Jingle Raw UDP Transport Method [11], inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the <transport/> element. The content transport method defines how to transfer bits from one host to another.
Component A component is a numbered stream of data which needs to be transmitted between the endpoints for a given content type in the context of a given session. It is up to the transport to negotiate the details of each component. For instance, the voice content type might use two components, one to transmit an RTP stream, and another to transmit RTCP timing information.

4. Concepts and Approach

Jingle consists of three parts, each with its own syntax, semantics, and state machine:

  1. Overall session management
  2. Content description formats (the "what")
  3. Content transport methods (the "how")

This document defines the semantics and syntax for overall session management, and provides pluggable "slots" for content description formats and content transport methods, which are specified in separate documents.

4.1 Overall Session Management

The state machine for overall session management (i.e., the state per Session ID) is as follows:

         o
         |
         | session-initiate
         |
         | +-----------------------+
         |/                        |
PENDING  o---------------------+   |
         |  | session-info,    |   |
         |  | content-remove,  |   |
         |  | content-modify,  |   |
         |  | content-accept,  |   |
         |  | content-decline, |   |
         |  +------------------+   |
         |                         |
         | session-accept          |
         |                         |
 ACTIVE  o---------------------+   |
         |  | session-info,    |   |
         |  | content-add,     |   |
         |  | content-remove,  |   |
         |  | content-modify,  |   |
         |  | content-accept,  |   |
         |  | content-decline, |   |
         |  +------------------+   |
         |                         |
         +-------------------------+
                                   |
                                   | session-redirect,
                                   | session-terminate
                                   |
                                   o ENDED
    

There are three overall session states:

  1. PENDING
  2. ACTIVE
  3. ENDED

The actions related to management of the overall Jingle session are:

  1. content-accept (accept a content-add, content-modify, or content-remove; implicitly also serves as a description-accept and transport-accept)
  2. content-add (add one or more new content types to the session; this MUST NOT be sent while the session is in the PENDING state)
  3. content-decline (reject a content-add or content-modify)
  4. content-modify (change an existing content type, mainly the directionality)
  5. content-remove (remove one or more content types from the session)
  6. session-accept (definitively accept a session request; implicitly also serves as a description-accept and transport-accept)
  7. session-initiate (request a new Jingle session)
  8. session-info (session-level information / messages)
  9. session-redirect (redirect an initiate request to another address)
  10. session-terminate (end an existing session)

4.2 Session Content

The content type of a session is made up of two aspects:

  1. The content description format specifies the "what" of the session (e.g., audio).
  2. The content transport method defines "how" the data shall be exchanged (e.g., raw UDP).

The <content/> element also specifies who will be sending content (the initiator, the recipient, or both).

4.2.1 Content Description Formats

When negotiating the session and its content type, the entities involved in the session need to exchange content description formats. The approach taken herein is to specify pure session description information in separate specifications, one for each content description format (audio, video, etc.). [12] The session negotiation must contain some content description format(s), which are defined in separate specifications. Those specifications also define the state chart for the content description format in question.

The generic state machine for management of any given content description format is as follows:

         START
           o  
           |   
           | session-initiate
           | content-add
           |
[PENDING]  o-------------+
           |   |         | description-info
           |   |_________| description-modify
           |
           | content-accept
           | description-accept
           | session-accept
           |
           |  _____________________o [MODIFYING]
           | / description-modify / \
           |/                    /   |
 [ACTIVE]  o--------------------/    | 
           |\  description-decline   |
           | \______________________/
           |   description-accept
           |
           | content-remove
           | session-terminate
           |
           o [ENDED]
      

The states related to management of content description formats are:

  1. PENDING
  2. ACTIVE
  3. MODIFYING
  4. ENDED

The actions related to management of content description formats are:

  1. description-info (description-level information / messages)
  2. description-modify (request a change to a content description format)
  3. description-accept (accept a proposed content change)
  4. description-decline (decline a proposed content change)

4.2.2 Content Transport Methods

As with the content description formats, the content transport methods are specified in separate specifications. Possible content transport methods include Real-time Transport Protocol (RTP) with Interactive Connectivity Establishment (ICE) and raw UDP. Those specifications will also define the state chart for the content transport method in question.

The generic state machine for any given content transport method is as follows:

         START
           o  
           |   
           | session-initiate
           | content-add
           |
[PENDING]  o-------------+
           |   |         | transport-info
           |   |_________| transport-modify
           |
           | content-accept
           | session-accept
           | transport-accept
           |
           |  ___________________o [MODIFYING]
           | / transport-modify / \
           |/                  /   |
 [ACTIVE]  o------------------/    | 
           |\  transport-decline   |
           | \____________________/
           |   transport-accept
           |
           | content-remove
           | session-terminate
           |
           o [ENDED]
      

The states related to management of content transport methods are:

  1. PENDING
  2. ACTIVE
  3. MODIFYING
  4. ENDED

The actions related to management of content transport methods are:

  1. transport-info (transport-level information / messages)
  2. transport-modify (request a change to the content transport methods)
  3. transport-accept (accept a proposed transport change)
  4. transport-decline (decline a proposed transport change)

5. Protocol

5.1 Resource Determination

In order to initiate a Jingle session, the initiating entity must determine which of the target entity's XMPP resources is best for the desired content description format. If a contact has only one XMPP resource, this task MUST be completed using Service Discovery [13] or the presence-based profile of service discovery specified in Entity Capabilities [14].

Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use Entity Capabilities, whereby support for Jingle and various Jingle content description formats and content transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to XEP-0115 for details.

If a contact has more than one XMPP resource, it may be that only one of the resources supports Jingle and the desired content description format, in which case the user MUST initiate the Jingle signalling with that resource.

If a contact has more than one XMPP resource that supports Jingle and the desired content description format, it is RECOMMENDED for a client to use Resource Application Priority [15] in order to determine which is the best resource with which to initiate the desired Jingle session.

5.2 Initiation

Once the initiating entity has discovered which of the target entity's XMPP resources is ideal for the desired content description format, it sends a session initiation request to the target entity. This request is an IQ-set containing a <jingle/> element qualified by the 'http://jabber.org/protocol/jingle' namespace. The <jingle/> element MUST possess the 'action', 'initiator', and 'sid' attributes (the latter two uniquely identify the session). For initiation, the 'action' attribute MUST have a value of "session-initiate" and the <jingle/> element MUST contain one or more <content/> elements, each of which defines a content type to be transferred during the session; each <content/> element in turn contains one <description/> child element that specifies a desired content description format and one or more <transport/> child elements that specify potential content transport methods.

The following example shows a Jingle session initiation request for a session that contains both audio and video content:

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'>
    <content name='this-is-the-audio-content'>
      <description xmlns='http://jabber.org/protocol/jingle/description/audio'>
        ...
      </description>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
        ...
      </transport>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
        ...
      </transport>
    </content>
    <content name='this-is-the-video-content'>
      <description xmlns='http://jabber.org/protocol/jingle/description/video'>
        ...
      </description>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
        ...
      </transport>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
        ...
      </transport>
    </content>
  </jingle>
</iq>
    

Note: The syntax and semantics of the <description/> and <transport/> elements are out of scope for this specification, but are defined in related specifications.

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

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

5.3 Target Entity Response

Unless an error occurs, the target entity MUST acknowledge receipt of the initiation request:

Example 2. Target Entity Acknowledges Receipt of Initiation Request

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

If the target entity acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.

There are several reasons why the target entity might return an error instead of acknowledging receipt of the initiation request:

The initiating entity is unknown to the target entity (e.g., via presence subscription) and the target entity has a policy of not communicating via Jingle with unknown entities, it MUST return a <service-unavailable/> error.

Example 3. Initiating Entity Unknown to Target Entity

<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If the target entity does not support Jingle, it MUST return a <service-unavailable/> error.

Example 4. Target Entity Does Not Support Jingle

<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If the target entity does not support any of the specified content description formats, it MUST return a <feature-not-implemented/> error with a Jingle-specific error condition of <unsupported-content/>.

Example 5. Target Entity Does Not Support Any Content Description Formats

<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported-content xmlns='http://jabber.org/protocol/jingle#errors'/>
  </error>
</iq>
    

If the target entity does not support any of the specified content transport methods, it MUST return a <feature-not-implemented/> error with a Jingle-specific error condition of <unsupported-transports/>.

Example 6. Target Entity Does Not Support Any Transport Methods

<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported-transports xmlns='http://jabber.org/protocol/jingle#errors'/>
  </error>
</iq>
    

If the initiation request was malformed, the target entity MUST return a <bad-request/> error.

Example 7. Initiation Request Malformed

<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
  <error type='cancel'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

5.4 Redirection

After acknowledging receipt of the initiation request, the target entity MAY redirect the session to another address (e.g., because the principal is not answering at the original resource). This is done by sending a Jingle redirect action to the initiating entity:

Example 8. Target Entity Redirects the Session

<iq from='juliet@capulet.com/balcony'
    id='jingle2'
    to='romeo@montague.net/orchard'
    type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle'
          action='session-redirect'
          initiator='romeo@montague.net/orchard'
          responder='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <redirect>xmpp:voicemail@capulet.com</redirect>
  </jingle>
</iq>
    

The recipient then acknowledges the redirection:

Example 9. Initiating Entity Acknowledges Redirection

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

Both entities MUST now consider the original session to be in the ENDED state, and if the initiating entity wishes to initiate a session with the redirected address it MUST do so by sending a session initiation request to that address with a new session ID.

5.5 Decline

In order to decline the session initiation request, the target entity MUST acknowledge receipt of the session initiation request, then terminate the session as described in the Termination section of this document.

5.6 Negotiation

In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, content description formats, and content transport methods. The potential combinations of parameters to be negotiated are many, and not all are shown herein (some are shown in the relevant specifications for various content description formats and content transport methods).

One session-level negotiation is to remove a content types. For example, let us imagine that Juliet is having a bad hair day. She certainly does not want to include video in her Jingle session with Romeo, so she sends a "content-remove" request to Romeo:

Example 10. Content Type Removal

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='reduce1' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle'
          action='content-remove'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <content name='this-is-the-video-content'/>
  </jingle>
</iq>
    

The entity receiving the session reduction request then acknowledges the request:

Example 11. Acknowledgement

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

If the reduction results in no more content types for the session, the entity that receives the session-reduce SHOULD send a session-terminate action to the other party (since a session with no content types is void).

Another session-level negotiation is to add a content type; however, this MUST NOT be done during while the session is in the PENDING state and is allowed only while the session is in the ACTIVE state (see below).

5.7 Acceptance

If (after negotiation of content transport methods and content description formats) the target entity determines that it will be able to establish a connection, it sends a definitive acceptance to the initiating entity:

Example 12. Target Entity 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='session-accept'
          initiator='romeo@montague.net/orchard'
          responder='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <content name='some-opaque-name'>
      <description xmlns='http://jabber.org/protocol/jingle/description/audio'>
        ...
      </description>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
        ...
      </transport>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
        ...
      </transport>
    </content>
    <content name='another-opaque-name'>
      <description xmlns='http://jabber.org/protocol/jingle/description/video'>
        ...
      </description>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
        ...
      </transport>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
        ...
      </transport>
  </jingle>
</iq>
    

The <jingle/> element in the accept stanza MUST contain one or more <content/> elements, each of which MUST contain only one <description/> element and one or more <transport/> elements. The <jingle/> element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity, and the initiating entity SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute.

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

Example 13. Initiating Entity 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 content over the negotiated connection.

If one of the parties cannot find a suitable content transport method, it SHOULD terminate the session as described below.

5.8 Modifying an Active Session

In order to modify an active session, either party may send a "content-remove", "content-add", "content-modify", "description-modify", or "transport-modify" action to the other party. The receiving party then sends an appropriate "-accept" or "-decline" action, and may first send an appropriate "-info" action.

If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an <unexpected-request/> error to the other party.

One example of modifying an active session is to add a content type. For example, let us imagine that Juliet gets her hair in order and now wants to add video. She now sends a "content-add" request to Romeo:

Example 14. Adding a Content Type

<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='add1' type='set'>
  <jingle xmlns='http://jabber.org/protocol/jingle'
          action='content-add'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <content name='video-is-back'>
      <description xmlns='http://jabber.org/protocol/jingle/description/video'>
        ...
      </description>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
        ...
      </transport>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
        ...
      </transport>
    </content>
  </jingle>
</iq>
    

The entity receiving the session extension request then acknowledges the request and, if it is acceptable, returns a content-accept:

Example 15. Acknowledgement

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

Example 16. Content Acceptance

<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='add2' type='set'/>
  <jingle xmlns='http://jabber.org/protocol/jingle'
          action='content-add'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <content name='video-is-back'>
      <description xmlns='http://jabber.org/protocol/jingle/description/video'>
        ...
      </description>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
        ...
      </transport>
      <transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
        ...
      </transport>
    </content>
  </jingle>
</iq>
    

The other party then acknowledges the acceptance.

Example 17. Acknowledgement

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

5.9 Termination

In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the target entity or the initiating entity MUST a send a "terminate" action to the other party:

Example 18. Target Entity 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='session-terminate'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'/>
</iq>
    

The initiating entity MUST then acknowledge termination of the session:

Example 19. Initiating Entity 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 Jingle communication for the negotiated content description format and content transport method MUST be completed through negotiation of a new session:

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 20. Target Entity 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.

5.10 Informational Messages

At any point after initiation of a Jingle session, either entity MAY send an informational message to the other party, for example to change a content transport method or content description format parameter, inform the other party that a session initiation request is queued, that a device is ringing, or that a scheduled event has occurred or will occur. An information message MUST be an IQ-set containing a <jingle/> element whose 'action' attribute is set to a value of "session-info", "description-info", or "transport-info"; the <jingle/> element MUST further contain a payload child element (speciific to the session, content description format, or content transport method) that specifies the information being communicated. (A future version of this specification will define payloads related to the "session-info" action.)

6. Error Handling

The Jingle-specific error conditions are as follows.

Table 2: Other Error Conditions

Jingle Condition XMPP Condition Description
<out-of-order/> <unexpected-request/> The request cannot occur at this point in the state machine (e.g., initiate after accept).
<unknown-session/> <bad-request/> The 'sid' attribute specifies a session that is unknown to the recipient.
<unsupported-content/> <not-acceptable/> The recipient does not support any of the desired content description formats.
<unsupported-transports/> <not-acceptable/> The recipient does not support any of the desired content transport methods.

7. Implementation Notes

There is a one-to-one relationship between content types and sessions. This reduces the complexity of managing a given session, since it avoids the need to de-multiplex traffic for different content types sent over the same connection. However, it may be desirable to share different kinds of content at the same time (e.g., during a video chat one party may want to share a file); in order to do this, the parties must establish a separate session for each content type. Management of multiple sessions is a client implementation matter and is not discussed in this specification.

8. Security Considerations

Note: This section is not yet complete.

8.1 Denial of Service

Jingle sessions may be resource-intensive. Therefore, it is possible to launch a denial-of-service attack against an entity by burdening it with too many Jingle sessions. Care must be taken to accept content sessions only from known entities and only if the entity's device is able to process such sessions.

8.2 Communication Through Gateways

Jingle communications may be enabled through gateways to non-XMPP networks, whose security characteristics may be quite different from those of XMPP networks. (For example, on some SIP networks authentication is optional and "from" addresses can be easily forged.) Care must be taken in communicating through such gateways.

9. IANA Considerations

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

10. XMPP Registrar Considerations

10.1 Protocol Namespaces

The XMPP Registrar [18] shall include 'http://jabber.org/protocol/jingle' and 'http://jabber.org/protocol/jingle#errors' in its registry of protocol namespaces.

10.2 Jingle Content Description Formats Registry

The XMPP Registrar shall maintain a registry of Jingle content description formats. All content description format registrations shall be defined in separate specifications (not in this document). Content description formats defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/description/name" (where "name" is the registered name of the content description format).

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 XMPP Extension Protocol or send it to the email address <registrar@jabber.org>:

<content>
  <name>the name of the content description format (e.g., "audio")</name>
  <desc>a natural-language summary of the content description format</desc>
  <doc>the document in which this content description format is specified</doc>
</content>
    

10.3 Jingle Content Transport Methods Registry

The XMPP Registrar shall maintain a registry of Jingle content transport methods. All content transport method registrations shall be defined in separate specifications (not in this document). Content transport methods defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/transport/name" (where "name" is the registered name of the content transport method).

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 XMPP Extension Protocol or send it to the email address <registrar@jabber.org>:

<transport>
  <name>the name of the content transport method (e.g., "raw-udp")</name>
  <desc>a natural-language summary of the content transport method</desc>
  <doc>the document in which this content transport method is specified</doc>
</transport>
    

11. XML Schemas

11.1 Jingle

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

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

  <xs:element name='jingle'>
    <xs:complexType>
      <xs:sequence minOccurs='1' maxOccurs='unlimited'>
        <xs:element ref='content'/>
      </xs:sequence>
      <xs:attribute name='action' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='content-accept'/>
            <xs:enumeration value='content-add'/>
            <xs:enumeration value='content-decline'/>
            <xs:enumeration value='content-modify'/>
            <xs:enumeration value='content-remove'/>
            <xs:enumeration value='description-accept'/>
            <xs:enumeration value='description-decline'/>
            <xs:enumeration value='description-info'/>
            <xs:enumeration value='description-modify'/>
            <xs:enumeration value='session-accept'/>
            <xs:enumeration value='session-info'/>
            <xs:enumeration value='session-initiate'/>
            <xs:enumeration value='session-redirect'/>
            <xs:enumeration value='session-terminate'/>
            <xs:enumeration value='transport-accept'/>
            <xs:enumeration value='transport-decline'/>
            <xs:enumeration value='transport-info'/>
            <xs:enumeration value='transport-modify'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='initiator' type='xs:string' use='required'/>
      <xs:attribute name='responder' type='xs:string' use='optional'/>
      <xs:attribute name='sid' type='xs:NMTOKEN' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='content'>
    <xs:complexType>
      <xs:choice minOccurs='0'>
        <xs:sequence>
          <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
        </xs:sequence>
      </xs:choice>
      <xs:attribute name='senders' use='optional' default='both'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='both'>
            <xs:enumeration value='initiator'>
            <xs:enumeration value='responder'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

</xs:schema>
    

11.2 Jingle Errors

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

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

  <xs:element name='out-of-order' type='empty'/>
  <xs:element name='unknown-session' type='empty'/>
  <xs:element name='unsupported-content' type='empty'/>
  <xs:element name='unsupported-transports' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

12. Acknowledgements

The authors would like to thank Rohan Mahy for his valuable input on early versions of this document. Rob Taylor, Dafydd Harries, Jussi Laako, Saku Vainio, Antti Ijäs, Brian West, Anthony Minessale, Matt O'Gorman, and others have also provided helpful input. Thanks also to those who have commented on the Standards JIG [19] and (earlier) Jingle [20] mailing lists.


Notes

1. XEP-0111: A Transport for Initiating and Negotiating Sessions <http://www.xmpp.org/extensions/xep-0111.html>.

2. It is true that TINS made it relatively easy to implement an XMPP-to-SIP gateway; however, in line with the long-time Jabber philosophy of "simple clients, complex servers", it would be better to force complexity onto the server-side gateway and to keep the client as simple as possible.

3. For example, one large ISP recently decided to switch to a pure XMPP approach after having implemented and deployed a dual-stack client for several years.

4. Google Talk is a messaging and voice chat service and client provided by Google; see <http://www.google.com/talk/>.

5. Possible other content description formats include file sharing, application casting, application sharing, whiteboarding, torrent broadcasting, shared real-time editing, and distributed musical performance, to name but a few.

6. RFC 4566: SDP: Session Description Protocol <http://www.ietf.org/rfc/rfc4566.txt>.

7. XEP-0167: Jingle Audio Content Description Format <http://www.xmpp.org/extensions/xep-0167.html>.

8. RFC 3261: Session Initiation Protocol (SIP) <http://www.ietf.org/rfc/rfc3261.txt>.

9. ITU Recommendation H.323: Packet-based Multimedia Communications Systems (September 1999).

10. XEP-0176: Jingle RTP-ICE Transport Method <http://www.xmpp.org/extensions/xep-0176.html>.

11. XEP-0177: Jingle Raw UDP Transport Method <http://www.xmpp.org/extensions/xep-0177.html>.

12. While it is possible to send raw Session Description Protocol (SDP) data for the session descriptions (the approach that was taken in XEP-0111), this is not necessarily helpful, since SDP is not structured data, not all SDP data is needed or used in the most common use cases, and SDP has been heavily extended in several useful directions that are not captured in the core SDP specification.

13. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.

14. XEP-0115: Entity Capabilities <http://www.xmpp.org/extensions/xep-0115.html>.

15. XEP-0168: Resource Application Priority <http://www.xmpp.org/extensions/xep-0168.html>.

16. See <http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken>

17. 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/>.

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

19. The Standards JIG is a standing Jabber Interest Group devoted to development of XMPP Extension Protocols. The discussion list of the Standards JIG is the primary venue for discussion of Jabber/XMPP protocols, as well as for announcements by the XMPP Extensions Editor and XMPP Registrar. To subscribe to the list or view the list archives, visit <http://mail.jabber.org/mailman/listinfo/standards-jig/>.

20. Before this specification was accepted as a XMPP Extension Protocol specification, it was discussed on the semi-private <jingle@jabber.org> mailing list; although that list is no longer used (the Standards-JIG list is the preferred discussion venue), for historical purposes it is publicly archived at <http://mail.jabber.org/pipermail/jingle/>.


Revision History

Version 0.10 (2006-09-29)

Made several corrections to the state machines and examples.

(ram/psa)

Version 0.9 (2006-09-08)

Further cleaned up state machines and state-related actions.

(ram/psa)

Version 0.8 (2006-08-23)

Changed channels to components in line with ICE; changed various action names for consistency; added session-extend and session-reduce actions to add and remove description/transport pairs; added description-modify action; added sender attribute to specify directionality.

(ram/psa)

Version 0.7 (2006-07-17)

Added implementation note about handling multiple content types.

(psa)

Version 0.6 (2006-07-12)

Changed media type to content type.

(se/psa)

Version 0.5 (2006-03-20)

Further clarified state machine diagrams; specified that session accept must include agreed-upon media format and transport description; moved deployment notes to appropriate transport spec.

(psa/jb)

Version 0.4 (2006-03-01)

Added glossary; clarified state machines; updated to reflect publication of XEP-0176 and XEP-0177.

(psa/jb)

Version 0.3 (2006-02-24)

Provided more detail about modify scenarios; defined media-specific and transport-specific actions and adjusted state machine accordingly.

(psa/jb)

Version 0.2 (2006-02-13)

Per agreement among the co-authors, moved transport definition to separate specification, simplified state machine, and made other associated changes to the text, examples, and schemas; also harmonized redirect, decline, and terminate processes.

(psa/jb)

Version 0.1 (2005-12-15)

Initial version.

(psa)

Version 0.0.10 (2005-12-11)

More fully documented burst mode, connectivity checks, error cases, etc.

(psa)

Version 0.0.9 (2005-12-08)

Restructured document flow; provided example of burst mode.

(psa)

Version 0.0.8 (2005-12-05)

Distinguished between dribble mode and burst mode, including mode attribute, service discovery features, and implementation notes; provided detailed resource discovery examples; corrected state chart; specified session termination; specified error conditions; specified semantics of informational messages; began to define security considerations; added Joe Beda as co-author.

(psa/sl/jb)

Version 0.0.7 (2005-11-08)

Added more detail to basic session flow; harmonized candidate negotiation process with ICE.

(psa)

Version 0.0.6 (2005-10-27)

Added XMPP Registrar considerations; defined schema; completed slight syntax cleanup.

(psa)

Version 0.0.5 (2005-10-21)

Separated methoddescription formats from signalling protocol.

(psa/sl)

Version 0.0.4 (2005-10-19)

Harmonized basic session flow with Google Talk protocol; added Scott Ludwig as co-author.

(psa/sl)

Version 0.0.3 (2005-10-10)

Added more detail to basic session flow.

(psa)

Version 0.0.2 (2005-10-07)

Protocol cleanup.

(psa/jjh)

Version 0.0.1 (2005-10-06)

First draft.

(psa/jjh)


END