XEP-0166: Jingle

1. Introduction¶

The purpose of Jingle is to enable one-to-one, peer-to-peer media sessions between XMPP entities, where the negotiation occurs over the XMPP signalling channel and the media is exchanged over a data channel that is usually a dedicated non-XMPP transport. Jingle is designed in a modular way:

• Developers can easily plug in support for a wide variety of application types, such as voice and video chat (see Jingle RTP Sessions (XEP-0167) [1]), file transfer (see Jingle File Transfer (XEP-0234) [2]), application sharing, collaborative editing, whiteboarding, and secure transmission of end-to-end XML streams (see Jingle XML Streams (XEP-0247) [3]).

• The transport methods are also pluggable, so that Jingle implementations can use any appropriate datagram transport such as User Datagram Protocol (UDP; RFC 768 [4]) as negotiated via Jingle Raw UDP Transport Method (XEP-0177) [5] or Jingle ICE-UDP Transport Method (XEP-0176) [6], or any appropriate streaming transport such as Transmission Control Protocol (TCP; RFC 793 [7]), SOCKS5 Bytestreams (XEP-0065) [8] as negotiated via Jingle SOCKS5 Bytestreams Transport Method (XEP-0260) [9], and In-Band Bytestreams (XEP-0047) [10] as negotiated via Jingle In-Band Bytestreams Transport Method (XEP-0261) [11].

• This modular approach also extends to the security preconditions that need to be met before application data can be exchanged over a given transport, such as negotiation of Transport Layer Security (TLS; RFC 5246 [12]) for streaming transports and negotiation of Datagram Transport Layer Security (DTLS; RFC 4347 [13]) for datagram transports.

It is expected that most application types, transport methods, and security preconditions will be documented in specifications produced by the XMPP Standards Foundation (XSF) [14] or the Internet Engineering Task Force (IETF) [15]; however, developers can also define proprietary methods for custom functionality.

Although Jingle provides a general framework for session management, the original target application for Jingle was simple voice and video chat. We stress the word "simple". The purpose of Jingle was not to build a full-fledged telephony application that supports call waiting, call forwarding, call transfer, hold music, IVR systems, find-me-follow-me functionality, conference calls, and the like. These features are of interest to some user populations, but adding support for them to the core Jingle layer would introduce unnecessary complexity into a technology that is designed for simple but generalized session negotiation.

Furthermore, Jingle is not intended to supplant or replace existing Internet technologies based on the Session Initiation Protocol (SIP; RFC 3261 [16]). Because dual-stack XMPP+SIP clients are difficult to build, Jingle was designed as a pure XMPP signalling protocol. However, Jingle is at the same time designed to interwork with SIP so that the millions of deployed XMPP clients can be added onto existing Voice over Internet Protocol (VoIP) networks, rather than limiting XMPP users to a separate and distinct network.

2. How It Works¶

This section provides a friendly introduction to Jingle.

In essence, Jingle enables two XMPP entities (e.g., romeo@montague.lit and juliet@capulet.lit) to set up, manage, and tear down a multimedia session. The negotiation takes place over XMPP, and the media transfer typically takes place outside of XMPP. A simplified session flow would be as follows: [17]

Romeo                         Juliet
  |                             |
  |   session-initiate          |
  |---------------------------->|
  |   ack                       |
  |<----------------------------|
  |   session-accept            |
  |<----------------------------|
  |   ack                       |
  |---------------------------->|
  |   MEDIA SESSION             |
  |<===========================>|
  |   session-terminate         |
  |<----------------------------|
  |   ack                       |
  |---------------------------->|
  |                             |

To illustrate the basic flow, we show a truncated example with a "stub" application format and transport method (skipping non-essential steps to enforce the most essential concepts and ignoring security preconditions for now).

<iq from='romeo@montague.lit/orchard'
    id='zid615d9'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='this-is-a-stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:stub:0'/>
    </content>
  </jingle>
</iq>

In this example, the initiator (romeo@montague.lit/orchard) sends a session initiation offer to the responder (juliet@capulet.lit/balcony), where the session is defined as the exchange of "stub" media over a "stub" transport.

After the responding client acknowledges receipt of the session-initiate message (not shown here), it prompts the responding user (if any) to choose whether she wants to proceed with the session (however, it does not need to prompt the user if for example she has configured her client to automatically accept session requests from this particular initiator). If she wants to proceed she selects the appropriate interface element and her client sends a session-accept message to the initiator.

<iq from='juliet@capulet.lit/balcony'
    id='rc61n59s'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='this-is-a-stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:stub:0'/>
    </content>
  </jingle>
</iq>

The initiating client acknowledges receipt of the session-accept message (not shown here) and the parties can exchange "stub" media data over the "stub" transport.

Eventually, one of the parties (here the responder) will terminate the session.

<iq from='juliet@capulet.lit/balcony'
    id='le71fa63'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <success/>
    </reason>
  </jingle>
</iq>

The initiating client acknowledges receipt of the session-terminate message (not shown here) and the session is ended.

We now "fill in the blanks" for the <description/> and <transport/> elements with a more complex example: a voice chat session, where the application type is a Jingle RTP session (with several different codec possibilities) and the transport method is ICE-UDP.

<iq from='romeo@montague.lit/orchard'
    id='ph37a419'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='96' name='speex' clockrate='16000'/>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
        <payload-type id='0' name='PCMU' />
        <payload-type id='103' name='L16' clockrate='16000' channels='2'/>
        <payload-type id='98' name='x-ISAC' clockrate='8000'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
                 pwd='asd88fgpdd777uzjYhagZg'
                 ufrag='8hhy'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='el0747fg11'
                   ip='10.0.1.1'
                   network='1'
                   port='8998'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
        <candidate component='1'
                   foundation='2'
                   generation='0'
                   id='y3s2b30v3r'
                   ip='192.0.2.3'
                   network='1'
                   port='45664'
                   priority='1694498815'
                   protocol='udp'
                   rel-addr='10.0.1.1'
                   rel-port='8998'
                   type='srflx'/>
      </transport>
    </content>
  </jingle>
</iq>

Upon receiving the session-initiate message, the responder determines whether it can proceed with the negotiation. If there is no error, the responder acknowledges the session initiation request.

<iq from='juliet@capulet.lit/balcony'
    id='ph37a419'
    to='romeo@montague.lit/orchard'
    type='result'/>

When the responding user affirms that she would like to proceed with the session, the responding client sends a session-accept message to the initiator (including in this example the subset of offered codecs that the responding client supports and one or more transport candidates generated by the responder).

<iq from='juliet@capulet.lit/balcony'
    id='yd71f495'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='or2ii2syr1'
                   ip='192.0.2.1'
                   network='0'
                   port='3478'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
      </transport>
    </content>
  </jingle>
</iq>

And the initiating client acknowledges session acceptance:

<iq from='romeo@montague.lit/orchard'
    id='yd71f495'
    to='juliet@capulet.lit/balcony'
    type='result'/>

Once the parties finish the transport negotiation, they would then exchange media using any of the acceptable codecs.

Eventually, one of the parties (here the responder) will terminate the session.

<iq from='juliet@capulet.lit/balcony'
    id='vua614d9'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <success/>
      <text>Sorry, gotta go!</text>
    </reason>
  </jingle>
</iq>

The other party then acknowledges termination of the session:

<iq from='romeo@montague.lit/orchard'
    id='vua614d9'
    to='juliet@capulet.lit/balcony'
    type='result'/>

3. 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 (including but not limited to voice and video) within XMPP.
2. When a peer-to-peer connection cannot be negotiated, make it possible to fall back to relayed communications.
3. Clearly separate the signalling channel (XMPP) from the data channel.
4. Clearly separate the application format (e.g., RTP audio) from the transport method (e.g., UDP).
5. Make it possible to add, modify, and remove both application types and transport methods in an existing session.
6. Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.
7. 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:

• Various application formats (audio, video, etc.) and, where possible, mapping of those types to the Session Description Protocol (SDP; see RFC 4566 [18]); examples include Jingle RTP Sessions and Jingle File Transfer.

• Various transport methods; examples include Jingle ICE-UDP Transport Method, Jingle Raw UDP Transport Method, Jingle In-Band Bytestreams Transport Method, and Jingle SOCKS5 Bytestreams Transport Method.

• Various methods of securing the transport before using it to send application data; the only method defined so far is Transport Layer Security as described in Jingle XTLS [19].

• Procedures for mapping the Jingle signalling protocol to existing signalling standards such as the IETF's Session Initiation Protocol (SIP) and the ITU's H.323 protocol (see H.323 [20]); see for example draft-ietf-stox-media [21].

4. Terminology¶

5. Concepts and Approach¶

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

1. Overall session management
2. Application types (the "what")
3. Transport methods (the "how")

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

At the most basic level, the process for initial negotiation of a Jingle session is as follows:

1. One user (the "initiator") sends to another user (the "responder") a session-initiate message containing at least one content definition, each of which defines one application type, one transport method, and optionally one security precondition.
2. If the responder wishes to proceed, it sends a session-accept message to the initiator, optionally including one or more transport candidates (depending on the transport method specified in the session-initiate message).
3. The parties attempt to establish connectivity over the offered transport method as defined in the relevant specification, which might involve the exchange of transport-info messages for additional transport candidates; if connectivity cannot be established then the parties might attempt to fall back to another transport method using the transport-replace and transport-accept messages.
4. Optionally, the parties attempt to establish security for the transport method before using it to exchange application data.
5. Optionally, either party can add or remove content definitions, or change the direction of the media flow, using the content-add, content-remove, and content-modify messages.
6. Optionally, either party can send session-info messages (e.g., to inform the other party that its device is ringing).
7. As soon as the initiator and responder determine that data can flow over the negotiated transport (potentially only after a security precondition has been met), they start sending application data over the transport.

Even after application data is being exchanged, the parties can adjust the session definition by sending additional Jingle messages, such as content-modify, content-remove, content-add, description-info, security-info, session-info, and transport-replace.

         o
         |
         | session-initiate
         |
         | +---------->--------------+
         |/                          |
PENDING  o-----------------------+   |
         |   | content-accept,   |   |
         |   | content-add,      |   |
         |   | content-modify,   |   |
         |   | content-reject,   |   |
         |   | content-remove,   |   |
         |   | description-info, |   |
        \|/  | session-info,     |   |
         |   | transport-accept, |   |
         |   | transport-info,   |   |
         |   | transport-reject, |   |
         |   | transport-replace |   |
         |   +-------------------+   |
         |                           |
         | session-accept           \|/
         |                           |
 ACTIVE  o-----------------------+   |
         |   | content-accept,   |   |
         |   | content-add,      |   |
         |   | content-modify,   |   |
         |   | content-reject,   |   |
         |   | content-remove,   |   |
         |   | description-info, |   |
        \|/  | session-info,     |   |
         |   | transport-accept, |   |
         |   | transport-info,   |   |
         |   | transport-reject, |   |
         |   | transport-replace |   |
         |   +-------------------+   |
         |                           |
         +------------>--------------+
                                     |
                                     | session-terminate
                                     |
                                     o ENDED
    

6. Session Flow¶

This section defines the high-level flow of a Jingle session. More detailed descriptions are provided in the specifications for Jingle application formats and transport methods.

<iq from='romeo@montague.lit/orchard'
    id='xs51r0k4'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='96' name='speex' clockrate='16000'/>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
        <payload-type id='0' name='PCMU' />
        <payload-type id='103' name='L16' clockrate='16000' channels='2'/>
        <payload-type id='98' name='x-ISAC' clockrate='8000'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
                 pwd='asd88fgpdd777uzjYhagZg'
                 ufrag='8hhy'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='el0747fg11'
                   ip='10.0.1.1'
                   network='1'
                   port='8998'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
        <candidate component='1'
                   foundation='2'
                   generation='0'
                   id='y3s2b30v3r'
                   ip='192.0.2.3'
                   network='1'
                   port='45664'
                   priority='1694498815'
                   protocol='udp'
                   rel-addr='10.0.1.1'
                   rel-port='8998'
                   type='srflx'/>
      </transport>
    </content>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='result'/>

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

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

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='modify'>
    <redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
      xmpp:voicemail@capulet.lit
    </redirect>
  </error>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='wait'>
    <resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

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

<iq from='juliet@capulet.lit/balcony'
    id='jd82f517'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='or2ii2syr1'
                   ip='192.0.2.1'
                   network='0'
                   port='3478'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
      </transport>
    </content>
  </jingle>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='jd82f517'
    to='juliet@capulet.lit/balcony'
    type='result'/>

<iq from='juliet@capulet.lit/balcony'
    id='bv81gs75'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <success/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='hr81fs63'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <busy/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='ky47g295'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <decline/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='ay3r2b86'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <alternative-session>
        <sid>b84tkkwlmb48kgfb</sid>
      </alternative-session>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='h82bs51g'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <unsupported-transports/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='pe81ga88'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <failed-transport/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='yd62vd67'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <unsupported-applications/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='kd82vs71'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <failed-application/>
    </reason>
  </jingle>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='hb3m59s7'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <incompatible-parameters/>
    </reason>
  </jingle>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='h82bs51g'
    to='juliet@capulet.lit/balcony'
    type='result'/>

<iq from='romeo@montague.lit/orchard'
    id='ur71vs62'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unknown-session xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='hq7rg186'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-info'
          sid='a73sjjvkla37jfea'>
    <ringing xmlns='urn:xmpp:jingle:apps:rtp:1:info'/>
  </jingle>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='hq7rg186'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='modify'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported-info xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

<iq from='juliet@capulet.lit/balcony'
    id='ug37vb25'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-info'
          sid='a73sjjvkla37jfea'/>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='ug37vb25'
    to='juliet@capulet.lit/balcony'
    type='result'/>

7. Formal Definition¶

<iq from='romeo@montague.lit/orchard'
    id='hb2f164w'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <tie-break xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

8. Transport Types¶

Jingle defines two types of transport methods.

9. Security Preconditions¶

The initiator MAY include a <security/> element in its offer to signal that it wishes to enforce some security precondition on the session. A stub example follows.

<iq from='romeo@montague.lit/orchard'
    id='tiw51bv9'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='this-is-a-stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:stub:0'/>
      <security xmlns='urn:xmpp:jingle:security:stub:0'/>
    </content>
  </jingle>
</iq>

Currently the only security precondition that is envisioned will enforce the use of end-to-end encryption for the transport before application data can be exchanged. This document does not define any security preconditions, just as it does not define any application types or transport methods. See Jingle XTLS [19] for an in-progress description of a security precondition using Transport Layer Security (TLS).

In order to exchange information about the establishment or maintenance of a security precondition, either party might send a Jingle security-info message. For example, when attempting to negotiate the use of TLS the initiator might send hints about his supported TLS methods (e.g., X.509 certificates and Secure Remote Password) in his session-initiate message and the responder might also send hints about her supported methods (e.g., X.509 and SRP) in her session-accept message; however, it is possible that the initiator might be able to verify the responder's certificate and therefore needs to inform the responder (via a security-info message) that he can in the end support only the X.509 method for this negotiation. An example follows.

<iq from='romeo@montague.lit/orchard'
    id='zyw6m167'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='security-info'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='xmlstream'>
      <security xmlns='urn:xmpp:jingle:security:xtls:0'>
        <method name='x509'/>
      </security>
    </content>
  </jingle>
</iq>

If one of the parties attempts to send information over the unsecured XMPP signalling channel that the other party expects to receive over the encrypted data channel, the receiving party SHOULD return a <not-acceptable/> error to the sender, including a <security-required/> element qualified by the 'urn:xmpp:jingle:errors:1' namespace. An example follows.

<iq from='romeo@montague.lit/orchard'
    id='bsi381f5'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='cancel'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <security-required xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

10. Error Handling¶

The Jingle-specific error conditions are as follows. These condition elements are qualified by the 'urn:xmpp:jingle:errors:1' namespace (see Namespace Versioning regarding the possibility of incrementing the version number).

11. Determining Support¶

If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:jingle:1" (see Namespace Versioning regarding the possibility of incrementing the version number) in response to a Service Discovery (XEP-0030) [30] information request. The response MUST also include features for the application formats and transport methods supported by the responding entity, as described in the relevant specifications.

<iq from='kingclaudius@shakespeare.lit/castle'
    id='ku6e51v3'
    to='laertes@shakespeare.lit/castle'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq from='laertes@shakespeare.lit/castle'
    id='ku6e51v3'
    to='kingclaudius@shakespeare.lit/castle'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:jingle:1'/>
    <feature var='urn:xmpp:jingle:apps:rtp:1'/>
    <feature var='urn:xmpp:jingle:apps:rtp:audio'/>
    <feature var='urn:xmpp:jingle:apps:rtp:video'/>
  </query>
</iq>

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in Entity Capabilities (XEP-0115) [31]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

12. Conformance by Using Protocols¶

13. Security Considerations¶

14. IANA Considerations¶

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

15. XMPP Registrar Considerations¶

<application>
  <name>The name of the application format.</name>
  <desc>A natural-language summary of the application format.</desc>
  <transport>
    Whether the media can be sent over a "streaming" transport,
    a "datagram" transport, or "both".
  </transport>
  <doc>The document in which the application format is specified.</doc>
</application>

<transport>
  <name>The name of the transport method.</name>
  <desc>A natural-language summary of the transport method.</desc>
  <type>
    Whether the transport method can be "streaming", "datagram",
    or "both".
  </type>
  <doc>The document in which this transport method is specified.</doc>
</transport>

16. XML Schemas¶

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

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

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0166: http://www.xmpp.org/extensions/xep-0166.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='jingle'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='content'
                    type='contentElementType'
                    minOccurs='0'
                    maxOccurs='unbounded'/>
        <xs:element name='reason'
                    type='reasonElementType'
                    minOccurs='0'
                    maxOccurs='1'/>
        <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </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-modify'/>
            <xs:enumeration value='content-reject'/>
            <xs:enumeration value='content-remove'/>
            <xs:enumeration value='description-info'/>
            <xs:enumeration value='security-info'/>
            <xs:enumeration value='session-accept'/>
            <xs:enumeration value='session-info'/>
            <xs:enumeration value='session-initiate'/>
            <xs:enumeration value='session-terminate'/>
            <xs:enumeration value='transport-accept'/>
            <xs:enumeration value='transport-info'/>
            <xs:enumeration value='transport-reject'/>
            <xs:enumeration value='transport-replace'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='initiator' type='xs:string' use='optional'/>
      <xs:attribute name='responder' type='xs:string' use='optional'/>
      <xs:attribute name='sid' type='xs:NMTOKEN' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='alternativeSessionElementType'>
    <xs:sequence>
      <xs:element name='sid'
                  minOccurs='0'
                  maxOccurs='1'
                  type='xs:NMTOKEN'/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name='contentElementType'>
    <xs:sequence>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
    </xs:sequence>
    <xs:attribute name='creator'
                  use='required'>
      <xs:simpleType>
        <xs:restriction base='xs:NCName'>
          <xs:enumeration value='initiator'/>
          <xs:enumeration value='responder'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name='disposition'
                  use='optional'
                  type='xs:NCName'
                  default='session'/>
    <xs:attribute name='name'
                  use='required'
                  type='xs:string'/>
    <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='none'/>
          <xs:enumeration value='responder'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
  </xs:complexType>

  <xs:complexType name='reasonElementType'>
    <xs:sequence>
      <xs:choice>
        <xs:element name='alternative-session'
                    type='alternativeSessionElementType'/>
        <xs:element name='busy' type='empty'/>
        <xs:element name='cancel' type='empty'/>
        <xs:element name='connectivity-error' type='empty'/>
        <xs:element name='decline' type='empty'/>
        <xs:element name='expired' type='empty'/>
        <xs:element name='failed-application' type='empty'/>
        <xs:element name='failed-transport' type='empty'/>
        <xs:element name='general-error' type='empty'/>
        <xs:element name='gone' type='empty'/>
        <xs:element name='incompatible-parameters' type='empty'/>
        <xs:element name='media-error' type='empty'/>
        <xs:element name='security-error' type='empty'/>
        <xs:element name='success' type='empty'/>
        <xs:element name='timeout' type='empty'/>
        <xs:element name='unsupported-applications' type='empty'/>
        <xs:element name='unsupported-transports' type='empty'/>
      </xs:choice>
      <xs:element name='text' type='xs:string' minOccurs='0' maxOccurs='1'/>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='1'/>
    </xs:sequence>
  </xs:complexType>

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

</xs:schema>

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:jingle:errors:1'
    xmlns='urn:xmpp:jingle:errors:1'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0166: http://www.xmpp.org/extensions/xep-0166.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='out-of-order' type='empty'/>
  <xs:element name='tie-break' type='empty'/>
  <xs:element name='unknown-session' type='empty'/>
  <xs:element name='unsupported-info' type='empty'/>

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

</xs:schema>

17. History¶

Until Jingle was developed, there existed no widely-adopted standard for initiating and managing peer-to-peer interactions between XMPP entities. Although several large service providers and Jabber client teams had written and implemented their own proprietary XMPP extensions for peer-to-peer signalling (usually only for voice), those technologies were not open and did not always take into account requirements to interoperate with SIP-based technologies. The only existing open protocol was A Transport for Initiating and Negotiating Sessions (XEP-0111) [35], which made it possible to initiate and manage peer-to-peer sessions, but which did not provide enough of the key signalling semantics to be easily implemented in Jabber/XMPP clients. [36]

The result was an unfortunate fragmentation within the XMPP community regarding signalling protocols. Essentially, there were two possible 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 might not be feasible on all the computing platforms for which Jabber clients have been written, or even desirable on platforms where it is feasible. [37] Therefore, it seemed reasonable to define an XMPP signalling protocol that could provide the necessary session management semantics while also making it relatively straightforward to interoperate with existing Internet standards.

As a result of feedback received on XEP-0111, the original authors of this document (Joe Hildebrand and Peter Saint-Andre) began to define such a signalling protocol, code-named Jingle. Upon communication with members of the Google Talk team, [38] 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 herein is, therefore, substantially equivalent to the original Google Talk protocol, with several adjustments based on feedback received from implementors as well as for publication by the XMPP Standards Foundation.

18. Acknowledgements¶

The authors would like to thank Rohan Mahy for his valuable input on early versions of the Jingle specifications. Thiago Camargo, Diana Cionoiu, Olivier Crête, Dafydd Harries, Antti Ijäs, Tim Julien, Lauri Kaila, Justin Karneges, Jussi Laako, Steffen Larsen, Marcus Lundblad, Dirk Meyer, Anthony Minessale, Akito Nozaki, Matt O'Gorman, Mike Ruprecht, Rob Taylor, Will Thompson, Matt Tucker, Justin Uberti, Saku Vainio, Unnikrishnan Vikrama Panicker, Brian West, Jeff Williams, and others have also provided helpful input. Thanks also to those who have commented on the Standards SIG [39] and Jingle [40] mailing lists.

Appendices

Appendix A: Document Information¶

Series

XEP

Number

0166

Publisher

XMPP Standards Foundation

Status

Draft

Type

Standards Track

Version

1.1.2

Last Updated

2018-09-19

Approving Body

XMPP Council

Dependencies

XMPP Core

Supersedes

XEP-0095

Superseded By

None

Short Name

jingle

Schema

XML Schema for the 'jingle' namespace: <http://xmpp.org/schemas/jingle.xsd>

XML Schema for the 'jingle:errors' namespace: <http://xmpp.org/schemas/jingle-errors.xsd>

Registry

<http://xmpp.org/registrar/jingle.html>

Source Control

HTML

This document in other formats: XML  PDF

Appendix B: Author Information¶

Scott Ludwig

Email

scottlu@google.com

JabberID

scottlu@google.com

Joe Beda

Email

jbeda@google.com

JabberID

jbeda@google.com

Peter Saint-Andre

Email

xsf@stpeter.im

JabberID

peter@jabber.org

URI

http://stpeter.im/

Robert McQueen

Email

robert.mcqueen@collabora.co.uk

JabberID

robert.mcqueen@collabora.co.uk

Sean Egan

Email

seanegan@google.com

JabberID

seanegan@google.com

Joe Hildebrand

Email

jhildebr@cisco.com

JabberID

hildjj@jabber.org

Appendix C: Legal Notices¶

Appendix D: Relation to XMPP¶

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

Appendix E: Discussion Venue¶

There exists a special venue for discussion related to the technology described in this document: the <jingle@xmpp.org> mailing list.

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance¶

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

Appendix G: Notes¶

Appendix H: Revision History¶

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

1. Version 1.1.2 (2018-09-19)¶

   Add missing security-info in section 5.1, forgotten in version 0.35.

   egp
2. Version 1.1.1 (2016-05-17)¶

   Fix broken reference to draft-ietf-stox-media

   ssw
3. Version 1.1 (2009-12-23)¶

   Specified handling of duplicate name attributes on content element; clarified recommended usage of Jingle when exchanging multiple content-types; declared the principle that application types ought not to be mixed beyond necessity within a single session; clarified use of the reason element in cases other than termination.

   psa/jjh
4. Version 1.0 (2009-06-10)¶

   Per a vote of the XMPP Council, advanced specification from Experimental to Draft; also required inclusion of the creator attribute per list consensus.

   psa
5. Version 0.38 (2009-05-27)¶

   Clarified and tightened handling of the initiator, responder, creator, and senders attributes.

   psa
6. Version 0.37 (2009-04-20)¶

   Specified tie-breaking for session-initiate action; incremented errors namespace to match core namespace; clarified some ambiguities in the text, examples, and state machine.

   psa
7. Version 0.36 (2009-03-11)¶

   Added none value for senders attribute.

   psa
8. Version 0.35 (2009-03-06)¶
   • Added the concept of a security precondition to the Jingle framework, where preconditions are defined in separate specifications (just as application types and transport methods are).
   • Defined a new Jingle action of security-info.
   • Incremented the namespace to urn:xmpp:jingle:1 in order to reflect the addition of security preconditions and the security-info action.
   • Clarified a number of points about the overall session flow and state machine.
   • Added Jingle reasons for failed-application, failed-transport, and incompatible-parameters.
   psa
9. Version 0.34 (2009-02-17)¶

   Clarified the definitions and conformance requirements for datagram and streaming transports; tightened the security requirements regarding the initiator and responder attributes; updated examples to reflect changes to XEP-0176.

   psa
10. Version 0.33 (2008-12-18)¶
    • Clarified handling of session timeouts.
    • Added description-info action.
    • Added cancel, expired, gone, security-error, and timeout reason conditions.
    • Changed XMPP error condition for Jingle <unknown-session/> condition from <bad-request/> to <item-not-found/>.
    • Changed XMPP error condition for Jingle tie breaks from <unexpected-request/> to <conflict/> and defined Jingle-specific condition of <tie-break/>.
    • Corrected schema.
    psa
11. Version 0.32 (2008-10-07)¶

    Added content-reject action to mirror content-accept for replies to content-add; also added transport-reject action to mirror transport-accept for replies to transport-replace.

    psa
12. Version 0.31 (2008-09-25)¶

    Added disposition attribute to content element for mapping to SIP Content-Disposition header.

    psa
13. Version 0.30 (2008-09-23)¶
    • Allowed content-add in PENDING state.
    • Clarified that session-accept action accepts only the content definition(s) in the session-initiate.
    • Added optional thread element.
    • Clarified tie breaks for transport-replace.
    • Modified namespaces to incorporate namespace versioning.
    • Cleaned up XML schemas.
    ram/psa
14. Version 0.29 (2008-07-31)¶
    • Changed "reliable" vs. "lossy" to "streaming" vs. "datagram", since reliability or dependability is orthogonal to the streaming nature of the transport.
    • Deleted the "content-remove" action.
    • Added "transport-replace" action (answered by "transport-accept").
    • Removed <condition/> element as container for Jingle condition elements inside <reason/>, since it introduced an unnecessary layer of indirection.
    • Modified state machine to allow content removal during PENDING state.
    • Noted that a session can have more than one content instance of the same type.
    • Noted that the 'name' attribute is unique to a creator.
    • Changed examples to once again use voice chat instead of file transfer.
    psa/ram
15. Version 0.28 (2008-06-16)¶

    Modified state machine to allow content-replace during PENDING state for more seamless handling of fallback scenarios.

    psa
16. Version 0.27 (2008-06-04)¶

    Updated examples to track changes to XEP-0167 and retraction of XEP-0180; corrected definition of name attribute to allow semantic meaning.

    psa
17. Version 0.26 (2008-05-28)¶

    Corrected several errors in the state diagrams.

    psa
18. Version 0.25 (2008-02-29)¶

    More clearly specified the content-replace action (essentially similar to content-add); specified that content-accept shall be sent in response to content-replace; removed content-modify and content-accept from PENDING state; adjusted text regarding initial session negotiation.

    psa
19. Version 0.24 (2008-02-28)¶

    Added content-replace action; modified reasoncode and reasontext to use elements instead of attributes; added sid element to handle alternative-session condition; modified examples to use file transfer instead of voice chat; moved profile element to XEP-0167 and XEP-0180.

    ram/psa
20. Version 0.23 (2008-01-11)¶

    Removed content-accept after content-remove; removed errors for unsupported-content and unsupported-transports since they are handled via session-terminate; clarified handling of responder attribute.

    psa
21. Version 0.22 (2007-12-06)¶

    Modified session flows for busy, unsupported application formats, and unsupported transport methods to enable separation between Jingle core and distinct modules for applications and transports; moved resource determination recommendations to XEP-208.

    psa
22. Version 0.21 (2007-11-27)¶

    Further editorial review.

    psa
23. Version 0.20 (2007-11-15)¶

    Editorial review and consistency check; moved voice chat scenarios to XEP-0167.

    psa
24. Version 0.19 (2007-11-13)¶

    Added scenario for handling of busy state, including Jingle-specific error code and modified error flow (no longer an instance of decline).

    psa
25. Version 0.18 (2007-11-08)¶

    Added scenarios for various session flows; clarified handling of content-add, content-modify, and content-remove actions; clarified rules for codec priority.

    psa
26. Version 0.17 (2007-06-20)¶

    Added <unsupported-info/> error.

    psa
27. Version 0.16 (2007-06-06)¶

    Clarified resource determination process and updated text to reflect modifications to XEP-0168.

    psa
28. Version 0.15 (2007-05-25)¶

    Rewrote introduction and moved historical text to separate section.

    psa
29. Version 0.14 (2007-04-17)¶

    Clarified session lifetime; defined reason attribute and associated registry; further specified conformance requirements.

    psa
30. Version 0.13 (2007-03-23)¶

    Simplified signalling process and state chart; Removed session-redirect action (use redirect error instead); removed content-decline action; removed transport-* actions (except transport-info for ICE negotiation); removed description-* actions; simplified syntax to allow only one transport per content type; corrected syntax of creator attribute to be either initiator or responder (not JIDs); added profile attribute to content element in order to specify RTP profile in use.

    psa/ram
31. Version 0.12 (2006-12-21)¶

    Added creator attribute to content element for prevention of race condition; modified spec to use provisional namespace before advancement to Draft (per XEP-0053).

    psa/ram
32. Version 0.11 (2006-10-31)¶

    Completed clarifications and corrections throughout; added section on Jingle Actions.

    psa
33. Version 0.10 (2006-09-29)¶

    Made several corrections to the state machines and examples.

    ram/psa
34. Version 0.9 (2006-09-08)¶

    Further cleaned up state machines and state-related actions.

    ram/psa
35. 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
36. Version 0.7 (2006-07-17)¶

    Added implementation note about handling multiple content types.

    psa
37. Version 0.6 (2006-07-12)¶

    Changed media type to content type.

    se/psa
38. 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
39. Version 0.4 (2006-03-01)¶

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

    psa/jb
40. 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
41. 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
42. Version 0.1 (2005-12-15)¶

    Initial version.

    psa
43. Version 0.0.10 (2005-12-11)¶

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

    psa
44. Version 0.0.9 (2005-12-08)¶

    Restructured document flow; provided example of burst mode.

    psa
45. 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
46. Version 0.0.7 (2005-11-08)¶

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

    psa
47. Version 0.0.6 (2005-10-27)¶

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

    psa
48. Version 0.0.5 (2005-10-21)¶

    Separated method description formats from signalling protocol.

    psa/sl
49. Version 0.0.4 (2005-10-19)¶

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

    psa/sl
50. Version 0.0.3 (2005-10-10)¶

    Added more detail to basic session flow.

    psa
51. Version 0.0.2 (2005-10-07)¶

    Protocol cleanup.

    psa/jjh
52. Version 0.0.1 (2005-10-06)¶

    First draft.

    psa/jjh

END