JEP-0166: Jingle

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

1. Introduction

2. Requirements

3. Concepts and Approach

3.1. Session Management

3.2. Media Description Formats

3.3. Transport Methods

4. Protocol

4.1. Resource Determination

4.2. Initiation

4.3. Target Entity Response

4.4. Redirection

4.5. Decline

4.6. Acceptance

4.7. Modifying an Active Session

4.8. Termination

4.9. Informational Messages

5. Error Handling

6. Security Considerations

6.1. Denial of Service

6.2. Communication Through Gateways

7. IANA Considerations

8. Jabber Registrar Considerations

8.1. Protocol Namespaces

8.2. Jingle Media Description Formats Registry

8.3. Jingle Transport Methods Registry

9. XML Schemas

9.1. Jingle

9.2. Jingle Errors

10. Open Issues

11. Acknowledgements

Notes

Revision History

3.1 Session Management

The state machine for session management is as follows:

         o
         |
         | session-initiate
         |
         | +----------------------+
         |/                       |
PENDING  o------------------+     |
         |  | session-info, |     |
         |  | media-*,      |     |
         |  | transport-*   |     |
         |  +---------------+     |
         |                        |
         | session-accept         |
         |                        |
 ACTIVE  o------------------+     |
         |  | session-info, |     |
         |  | media-*,      |     |
         |  | transport-*   |     |
         |  +---------------+     |
         |                        |
         +------------------------+ 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. session-initiate (request a new session)
2. session-accept (definitively accept a session request)
3. session-redirect (redirect an initiate request to another address)
4. session-info (session-level information / messages)
5. session-terminate (end an existing session)

The actions related to management of media description formats are:

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

The actions related to management of transport methods are:

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

This specification defines the state machine for overall session management. Each media description format and transport method will also have its own state machine, but these are out of scope here.

3.2 Media Description Formats

The media description format specifies the "what" of the session (e.g., bidirectional audio). When negotiating the session, the entities involved in the session need to exchange media description formats. The approach taken herein is to specify pure session description information in separate specifications, one for each media description format (audio, video, etc.). [10] The session negotiation must contain some media description format(s), which are to be defined in separate specifications. Those specifications will also define the state chart for the media description format in question.

3.3 Transport Methods

The transport method defines "how" the data shall be exchanged. As with the media description formats, the transport methods are specified in separate specifications. Possible transport methods include peer-to-peer RTP, local UDP, and SSL-TCP. Those specifications will also define the state chart for the transport method in question.

4.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 media description format. If a contact has only one XMPP resource, this task MUST be completed using Service Discovery [11] or the presence-based profile of service discovery specified in Entity Capabilities [12].

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 media description formats and transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to JEP-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 media 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 media description format, it is RECOMMENDED for a client to use Resource Application Priority [13] in order to determine which is the best resource with which to initiate the desired Jingle session.

4.2 Initiation

Once the initiating entity has discovered which of the target entity's XMPP resources is ideal for the desired media 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; for initiation the 'action' attribute MUST have a value of "initiate" and the <jingle/> element MUST contain one or more <description/> child elements that specify the desired media description formats and one or more <transport/> child elements that specify the desired transport methods. Here is an example:

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='initiate'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <description ...>
    <transport ...>
  </jingle>
</iq>
    

Note: The syntax and semantics of the description and transport elements are out of scope for this specification.

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

• The 'action' attribute is REQUIRED; it specifies a Jingle action as listed in this document (e.g., "initiate").
• The 'initiator' attribute is the full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).
• The 'responder' attribute (see examples below) is the full JID of the entity that has replied to the initiation (which may be different from the 'to' address on the IQ-set).
• The 'sid' attribute is a random session identifier generated by the initiator; this SHOULD match the XML Nmtoken production [14] so that XML character escaping is not needed for characters such as &. (Note: the 'sid' attribute effectively maps to the SIP "Call-ID" parameter.)

4.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).
• The target entity does not support Jingle.
• The target entity does not support any of the specified media description formats.
• The target entity does not support any of the specified transport methods.
• The initiation request was malformed.

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 media description formats, it MUST return a <feature-not-implemented/> error with a Jingle-specific error condition of <unsupported-media/>.

Example 5. Target Entity Does Not Support Any Media 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-media xmlns='http://jabber.org/protocol/jingle#errors'/>
  </error>
</iq>
    

If the target entity does not support any of the specified 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>
    

4.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='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.

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

4.6 Acceptance

If (after negotiation of transport methods and media 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 10. 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='accept'
          initiator='romeo@montague.net/orchard'
          responder='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'/>
</iq>
    

The <jingle/> element in the accept stanza MAY contain one or more <description/> elements that specify the desired media description format(s) and MAY contain one or more <transport/> elements that specify the desired transport methodl(s). 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 o the JID provided in the 'responder' attribute.

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

Example 11. 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 media over the negotiated connection.

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

4.7 Modifying an Active Session

In order to modify an active session, either party may send a "media-modify" or "transport-modify" action to the other party containing a modified media description format or transport method. 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.

4.8 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 12. 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='terminate'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'/>
</iq>
    

The initiating entity MUST then acknowledge termination of the session:

Example 13. 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 media description format and transport method MUST be completed through negotiation of a new session:

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

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

Example 14. 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.

4.9 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 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 takes the form of an IQ-set containing a <jingle/> element whose 'action' attribute is set to a value of "session-info", "media-info", or "transport-info"; the <jingle/> element MUST further contain a "payload" child element that specifies the information being communicated. The syntax of this payload element is undefined in this signalling specification and shall be defined by a companion document specifying a media description format or transport method. (A future version of this specification will define payloads related to the "session-info" action.)

6.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 media sessions only from known entities and only if the entity's device is able to process such sessions.

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

8.1 Protocol Namespaces

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

8.2 Jingle Media Description Formats Registry

The Jabber Registrar shall maintain a registry of Jingle media description formats. All media description format registrations shall be defined in separate documents (not in this JEP). Media description formats defined within the JEP series MUST be registered with the Jabber Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/media/name" (where "name" is the registered name of the media 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 Jabber Enhancement Proposal or send it to the email address <registrar@jabber.org>:

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

8.3 Jingle Transport Methods Registry

The Jabber Registrar shall maintain a registry of Jingle transport methods. All transport method registrations shall be defined in separate documents (not in this JEP). Transport methods defined within the JEP series MUST be registered with the Jabber Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/transport/name" (where "name" is the registered name of the 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 Jabber Enhancement Proposal or send it to the email address <registrar@jabber.org>:

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

9.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:choice>
        <xs:sequence>
          <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
        </xs:sequence>
      </xs:choice>
      <xs:attribute name='action' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='media-accept'/>
            <xs:enumeration value='media-decline'/>
            <xs:enumeration value='media-info'/>
            <xs:enumeration value='media-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:schema>
    

9.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-media' 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>
    

1. JEP-0111: A Transport for Initiating and Negotiating Sessions (TINS <http://www.jabber.org/jeps/jep-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 media 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 2327: SDP: Session Description Protocol <http://www.ietf.org/rfc/rfc2327.txt>.

7. JEP-0167: Jingle Audio Media Description Format <http://www.jabber.org/jeps/jep-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. While it is possible to send raw Session Description Protocol (SDP) data for the session descriptions (the approach that was taken in JEP-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.

11. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

12. JEP-0115: Entity Capabilities <http://www.jabber.org/jeps/jep-0115.html>.

13. JEP-0168: Resource Application Priority <http://www.jabber.org/jeps/jep-0168.html>.

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

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

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

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

18. Before this specification was accepted as a Jabber Enhancement Proposal, 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/>.

Version 0.3 (2006-02-24)

Version 0.2 (2006-02-13)

Version 0.1 (2005-12-15)

Version 0.0.10 (2005-12-11)

Version 0.0.9 (2005-12-08)

Version 0.0.8 (2005-12-05)

Version 0.0.7 (2005-11-08)

Version 0.0.6 (2005-10-27)

Version 0.0.5 (2005-10-21)

Version 0.0.4 (2005-10-19)

Version 0.0.3 (2005-10-10)

Version 0.0.2 (2005-10-07)

Version 0.0.1 (2005-10-06)