moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 02:02:16 -05:00
Code Issues Releases Wiki Activity

0.35: added concept of security preconditions, defined security-info action, incremented namespace to urn:xmpp:jingle:1

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2835 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-03-06 23:44:21 +00:00
parent 5d587243fa
commit c420adf23e
1 changed files with 275 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

393
xep-0166.xml
View File

@ -27,6 +27,20 @@
&robmcqueen;
&seanegan;
&hildjj;
<revision>
<version>0.35</version>
<date>2009-03-06</date>
<initials>psa</initials>
<remark>
<ul>
<li>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).</li>
<li>Defined a new Jingle action of security-info.</li>
<li>Incremented the namespace to urn:xmpp:jingle:1 in order to reflect the addition of security preconditions and the security-info action.</li>
<li>Clarified a number of points about the overall session flow and state machine.</li>
<li>Added Jingle reasons for failed-application, failed-transport, and incompatible-parameters.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.34</version>
<date>2009-02-17</date>
@ -322,10 +336,15 @@
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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 "channel" and the media is exchanged outside the XMPP channel using technologies such as the Real-time Transport Protocol (RTP; &rfc3550;), the User Datagram Protocol (UDP; &rfc0768;), and &ice;.</p>
<p>One target application for Jingle is simple voice and video chat (see &xep0167;). We stress the word "simple". The purpose of the core Jingle technology is 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 basic multimedia interaction.</p>
<p>In addition, the purpose of Jingle is not to supplant or replace existing Internet technologies based on the Session Initiation Protocol (SIP; &rfc3261;). 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.</p>
<p>Jingle is designed in a modular way so that developers can easily add support for multimedia session types other than voice and video chat, such as application sharing, file transfer, collaborative editing, whiteboarding, and torrent broadcasting. The transport methods are also modular, so that Jingle implementations can use any appropriate media transport (including proprietary methods not standardized through the XMPP Standards Foundation).</p>
<p>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:</p>
<ul>
<li><p>Developers can easily plug in support for a wide variety of application types, such as voice and video chat (see &xep0167;), file transfer (see &xep0234;), application sharing, collaborative editing, whiteboarding, and secure transmission of end-to-end XML streams (see &xep0247;).</p></li>
<li><p>The transport methods are also pluggable, so that Jingle implementations can use any appropriate datagram transport such as User Datagram Protocol (UDP; &rfc0768;) as negotiated via &xep0177; or &xep0176;, or any appropriate streaming transport such as Transmission Control Protocol (TCP; &rfc0793;), &xep0065; as negotiated via &xep0260;, and &xep0047; as negotiated via &xep0261;.</p></li>
<li><p>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; &rfc5246;) for streaming transports and negotiation of Datagram Transport Layer Security (DTLS; &rfc4347;) for datagram transports.</p></li>
</ul>
<p>It is expected that most application types, transport methods, and security preconditions will be documented in specifications produced by the &XSF; or the &IETF;; however, developers can also define proprietary methods for custom functionality.</p>
<p>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.</p>
<p>Furthermore, Jingle is not intended to supplant or replace existing Internet technologies based on the Session Initiation Protocol (SIP; &rfc3261;). 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.</p>
</section1>
<section1 topic='How It Works' anchor='howitworks'>
<p>This section provides a friendly introduction to Jingle.</p>
@ -349,49 +368,50 @@ Romeo Juliet
|---------------------------->|
| |
]]></code>
<p>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 important concepts).</p>
<p>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).</p>
<example caption="Initiator sends session-initiate (stub)"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='jingle1'
id='zid615d9'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
<jingle xmlns='urn:xmpp:jingle:1'>
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<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>
]]></example>
<p>After the responder acknowledges receipt of the session-initiate and the parties negotiate some parameters (not shown here), the responder would eventually send a session-accept to the initiator.</p>
<p>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.</p>
<p>After the responding client acknowledges receipt of the session-initiate message, 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.</p>
<example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='accept1'
id='rc61n59s'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-accept'
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<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>
]]></example>
<p>The initiator acknowledges receipt of the session-accept (not shown here) and the parties can exchange "stub" media data over the "stub" transport.</p>
<p>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.</p>
<p>Eventually, one of the parties (here the responder) will terminate the session.</p>
<example caption="Responder terminates the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term1'
id='le71fa63'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -401,14 +421,14 @@ Romeo Juliet
</jingle>
</iq>
]]></example>
<p>The recipient acknowledges receipt of the session-terminate (not shown here) and the session is ended.</p>
<p>The initiator's acknowledges receipt of the session-terminate message (not shown here) and the session is ended.</p>
<p>We now "fill in the blanks" for the &DESCRIPTION; and &TRANSPORT; elements with a more complex example: a voice chat session, where application type is a Jingle RTP session (with several different codec possibilities) and the transport method is &xep0176;.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='jingle1'
id='ph37a419'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
<jingle xmlns='urn:xmpp:jingle:1'>
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -451,20 +471,20 @@ Romeo Juliet
</jingle>
</iq>
]]></example>
<p>Upon receiving the session-initiate stanza, the responder determines whether it can proceed with the negotiation. If there is no error, the responder acknowledges the session initiation request.</p>
<p>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.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='ph37a419'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>After successful transport negotiation (not shown here), the responder accepts the session by sending a session-accept action to the initiator (including the negotiated transport details and the subset of offered codecs that the responder supports).</p>
<p>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).</p>
<example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='accept1'
id='yd71f495'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-accept'
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
@ -490,21 +510,21 @@ Romeo Juliet
</jingle>
</iq>
]]></example>
<p>And the initiator acknowledges session acceptance:</p>
<p>And the initiating client acknowledges session acceptance:</p>
<example caption="Initiator acknowledges session acceptance"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='accept1'
id='yd71f495'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>The initiator and responder would then exchange media using any of the acceptable codecs.</p>
<p>Once the parties finish the transport negotiation, they would then exchange media using any of the acceptable codecs.</p>
<p>Eventually, one of the parties (here the responder) will terminate the session.</p>
<example caption="Responder terminates the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term1'
id='vua614d9'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -518,7 +538,7 @@ Romeo Juliet
<p>The other party then acknowledges termination of the session:</p>
<example caption="Initiator acknowledges termination"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='term1'
id='vua614d9'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
@ -530,15 +550,16 @@ Romeo Juliet
<li>Make it possible to manage a wide variety of peer-to-peer sessions (including but not limited to voice and video) within XMPP.</li>
<li>When a peer-to-peer connection cannot be negotiated, make it possible to fall back to relayed communications.</li>
<li>Clearly separate the signalling channel (XMPP) from the data channel.</li>
<li>Clearly separate the application formats (e.g., audio) from the transport methods (e.g., RTP).</li>
<li>Clearly separate the application format (e.g., RTP audio) from the transport method (e.g., UDP).</li>
<li>Make it possible to add, modify, and remove both application types and transport methods in an existing session.</li>
<li>Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.</li>
<li>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.</li>
</ol>
<p>This document defines the signalling protocol only. Additional documents specify the following:</p>
<ul>
<li><p>Various application formats (audio, video, etc.) and, where possible, mapping of those types to the Session Description Protocol (SDP; see &rfc4566;); examples include <cite>Jingle RTP Sessions</cite> and &xep0234;.</p></li>
<li><p>Various transport methods; examples include <cite>Jingle ICE-UDP Transport</cite> and &xep0177;.</p></li>
<li><p>Various application formats (audio, video, etc.) and, where possible, mapping of those types to the Session Description Protocol (SDP; see &rfc4566;); examples include <cite>Jingle RTP Sessions</cite> and <cite>Jingle File Transfer</cite>.</p></li>
<li><p>Various transport methods; examples include <cite>Jingle ICE-UDP Transport Method</cite>, <cite>Jingle Raw UDP Transport Method</cite>, <cite>Jingle In-Band Bytestreams Transport Method</cite>, and <cite>Jingle SOCKS5 Bytestreams Transport Method</cite>.</p></li>
<li><p>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 &xmppe2e;.</p></li>
<li><p>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 &h323;); see for example &xmppsipmedia;.</p></li>
</ul>
</section1>
@ -567,15 +588,15 @@ Romeo Juliet
</tr>
<tr>
<td>Transport Method</td>
<td>The method for establishing data stream(s) between entities. Possible transports might include ICE-UDP, ICE-TCP, Raw UDP, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The transport method defines how to transfer bits from one host to another. Each transport method MUST specify whether it is "datagram" or "streaming".</td>
<td>The method for establishing data stream(s) between entities. Possible transports might include ICE-UDP, ICE-TCP, Raw UDP, In-Band Bytestreams, SOCKS5 Bytestreams, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The transport method defines how to transfer bits from one host to another. Each transport method MUST specify whether it is "datagram" or "streaming" as described in the <link url='#transports'>Transport Types</link> sectio of this document.</td>
</tr>
</table>
</section2>
<section2 topic='Conventions' anchor='terms-conventions'>
<p>In diagrams, the following conventions are used:</p>
<ul>
<li>Dashed lines (---) represent Jingle stanzas that are sent via the XMPP signalling channel.</li>
<li>Double-dashed lines (===) represent media packets that are sent via the media channel, which typically is not an XMPP channel but a direct or mediated channel between the endpoints.</li>
<li>Single-dashed lines (---) represent Jingle stanzas that are sent via the XMPP signalling channel.</li>
<li>Double-dashed lines (===) represent media packets that are sent via the data channel, which typically is not an XMPP channel (although the <cite>Jingle In-Band Bytestreams Transport Method</cite> is an exception) but instead is a direct or mediated channel between the endpoints.</li>
</ul>
</section2>
</section1>
@ -589,15 +610,15 @@ Romeo Juliet
<p>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.</p>
<p>At the most basic level, the process for initial negotiation of a Jingle session is as follows:</p>
<ol>
<li>One user (the "initiator") sends to another user (the "responder") a session initiation request with at least one content definition.</li>
<li>If the responder wants to proceed, it acknowledges the session initiation request by sending an IQ result.</li>
<li>The parties attempt to set up data transmission over the designated transport method as defined in the relevant specification, which might involve the exchange of transport-info actions.</li>
<li>Optionally, either party can add or remove content definitions, or change the direction of the media flow.</li>
<li>Optionally, either party can send session-info actions (to inform the other party that it is attempting transport negotiation, that its device is ringing, etc.).</li>
<li>As soon as the responder determines that data can flow over the designated transport, it sends to the initiator a session-accept action.</li>
<li>The parties start sending data over the transport.</li>
<li>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.</li>
<li>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).</li>
<li>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.</li>
<li>Optionally, the parties attempt to establish security for the transport method before using it to exchange application data.</li>
<li>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.</li>
<li>Optionally, either party can send session-info messages (e.g., to inform the other party that its device is ringing).</li>
<li>As soon as the responder determines 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.</li>
</ol>
<p>After the initial session negotiation has been completed and the session is in the ACTIVE state, the parties can adjust the session definition by sending additional Jingle actions, such as content-modify, content-remove, content-add, description-info, and transport-replace. In addition, certain transport methods allow continued sending of transport-info actions while in the ACTIVE state. And naturally the parties can send session-info actions at any time.</p>
<p>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.</p>
<section2 topic='Overall Session Management' anchor='concepts-session'>
<p>The state machine for overall session management (i.e., the state per Session ID) is as follows:</p>
<code>
@ -649,7 +670,8 @@ PENDING o----------------------+ |
<li>ACTIVE</li>
<li>ENDED</li>
</ol>
<p>The actions related to management of the overall Jingle session are as follows (detailed definitions are provided in under <link url='#def-action'>Action Attribute</link>).</p>
<p>Note: While it is allowed to send all actions while in the PENDING state, typically the responder will send a session-accept message as quickly as possible in order to expedite the transport negotiation; see the <link url='#sec'>Security Considerations</link> section of this document regarding informatino exposure when the responder sends transport candidates to the initiator.</p>
<p>The actions related to management of the overall Jingle session are as follows (detailed definitions are provided in the <link url='#def-action'>Action Attribute</link> section of this document).</p>
<ul>
<li>content-accept -- Accept a content-add action received from another party.</li>
<li>content-add -- Add one or more new content definitions to the session.</li>
@ -671,16 +693,16 @@ PENDING o----------------------+ |
<section1 topic='Session Flow' anchor='session'>
<p>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.</p>
<section2 topic='Resource Determination' anchor='session-resource'>
<p>In order to initiate a Jingle session, the initiator needs to determine which of the responder's XMPP resources is best for the desired application format. Methods for doing so are out of scope for this specification. However, see the <link url='#support'>Determining Support</link> section of this document (and associated specifications) for relevant information.</p>
<p>In order to initiate a Jingle session, the initiator needs to determine which of the responder's XMPP resources is best for the desired application format. Methods for doing so are out of scope for this specification. However, see the <link url='#support'>Determining Support</link> section of this document for relevant information.</p>
</section2>
<section2 topic='Initiation' anchor='protocol-initiate'>
<p>Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'urn:xmpp:jingle:0' namespace &VNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method. If either party wishes to propose the use of multiple transport methods for the same application format, it MUST include multiple &CONTENT; elements.</p>
<p>Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'urn:xmpp:jingle:1' namespace &VNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method, as well as (optionally) one &lt;security/&gt; element that specifies a security precondition that needs to be met before the parties can exchange application data over the negotiated transport.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='jingle1'
id='xs51r0k4'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -723,14 +745,14 @@ PENDING o----------------------+ |
</jingle>
</iq>
]]></example>
<p>Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this document, since they are defined in related specifications. The syntax and semantics of the &JINGLE; and &CONTENT; elements are specified in this document under <link url='#def'>Formal Definition</link>.</p>
<p>Note: The syntax and semantics of the &DESCRIPTION;, &TRANSPORT;, and &lt;security/&gt; elements are out of scope for this document, since they are defined in related specifications. The syntax and semantics of the &JINGLE; and &CONTENT; elements are specified in this document under <link url='#def'>Formal Definition</link>.</p>
</section2>
<section2 topic='Responder Response' anchor='protocol-response'>
<section3 topic='Acknowledgement' anchor='protocol-response-ack'>
<p>Unless one of the following errors occurs, the responder SHOULD acknowledge receipt of the initiation request.</p>
<p>Unless one of the following errors occurs, the responder MUST acknowledge receipt of the initiation request.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='xs51r0k4'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
@ -748,7 +770,7 @@ PENDING o----------------------+ |
<p>If the initiator is unknown to the responder (e.g., via presence subscription as defined in &rfc3921;) and the responder has a policy of not communicating via Jingle with unknown entities, it MUST return a &unavailable; error.</p>
<example caption="Initiator is unknown to responder"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='xs51r0k4'
to='romeo@montague.lit/orchard'
type='error'>
<error type='cancel'>
@ -759,7 +781,7 @@ PENDING o----------------------+ |
<p>If the responder does not support Jingle, it MUST return a &unavailable; error.</p>
<example caption="Responder does not support Jingle"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='xs51r0k4'
to='romeo@montague.lit/orchard'
type='error'>
<error type='cancel'>
@ -770,7 +792,7 @@ PENDING o----------------------+ |
<p>If the responder wishes to redirect the request to another address, it MUST return a &redirect; error.</p>
<example caption="Responder redirection"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='xs51r0k4'
to='romeo@montague.lit/orchard'
type='error'>
<error type='cancel'>
@ -783,7 +805,7 @@ PENDING o----------------------+ |
<p>If the responder does not have sufficient resources to participate in a session, it MUST return a &constraint; error.</p>
<example caption="Responder has insufficent resources"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='xs51r0k4'
to='romeo@montague.lit/orchard'
type='error'>
<error type='wait'>
@ -794,7 +816,7 @@ PENDING o----------------------+ |
<p>If the initiation request was malformed, the responder MUST return a &badrequest; error.</p>
<example caption="Initiation request malformed"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
id='xs51r0k4'
to='romeo@montague.lit/orchard'
type='error'>
<error type='cancel'>
@ -805,7 +827,7 @@ PENDING o----------------------+ |
</section3>
</section2>
<section2 topic='Negotiation' anchor='session-negotiation'>
<p>In general, negotiation will be necessary before the parties can agree on an acceptable set of application formats and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.</p>
<p>Although in general it is preferable for the responder to send a session-accept message as soon as possible, some forms of negotiation might be necessary before the parties can agree on an acceptable set of application formats and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.</p>
<p>The allowable negotiations (e.g., content-level and transport-level negotiations) include:</p>
<ul>
<li>Exchanging particular transport candidates via the transport-info action.</li>
@ -814,15 +836,16 @@ PENDING o----------------------+ |
<li>Adding a content type via the content-add action.</li>
<li>Removing a content type via the content-remove action.</li>
</ul>
<p>These forms of negotiation can also occur after the session has been accepted.</p>
</section2>
<section2 topic='Acceptance' anchor='session-acceptance'>
<p>If (after negotiation of transport methods and application formats as well as checking of transport candidates) the responder determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.</p>
<p>As soon as possible after receiving the session-initiate message, the responder informs the initiator that she wishes to proceed with the session by sending a session-accept message.</p>
<example caption="Responder accepts the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='accept1'
id='jd82f517'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-accept'
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
@ -848,29 +871,29 @@ PENDING o----------------------+ |
</jingle>
</iq>
]]></example>
<p class='box'>Note: The protocol-level "session-accept" action is not to be confused with an interface-level acceptance of the session request. After receiving and acknowledging the "session-initiate" action received from the initiator, the responder's client SHOULD present an interface element that enables a human user to explicitly agree to proceeding with the session (e.g., an "Accept Incoming Call?" pop-up window including "Yes" and "No" buttons). However, the responder's client SHOULD NOT return a "session-accept" action to the initiator until the responder has explicitly agreed to proceed with the session (unless the initiator is on a list of entities whose sessions are automatically accepted).</p>
<p>The initiator then acknowledges the responder's definitive acceptance, after which the parties can exchange media over the negotiated connection.</p>
<p class='box'>Note: After receiving and acknowledging the "session-initiate" action received from the initiator, the responding client SHOULD present an interface element that enables a human user to explicitly agree to proceeding with the session (e.g., an "Accept Incoming Call?" pop-up window including "Yes" and "No" buttons). However, the responding client SHOULD NOT return a "session-accept" action to the initiator until the responder has explicitly agreed to proceed with the session (unless the initiator is on a list of entities whose sessions are automatically accepted).</p>
<p>The initiator then acknowledges the responder's definitive acceptance.</p>
<example caption="Initiator acknowledges session acceptance"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='accept1'
id='jd82f517'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>If one of the parties cannot find a suitable transport method or candidate, it SHOULD terminate the session as described below.</p>
<p>The session is now in the ACTIVE state. However, this does not necessarily mean that the parties can exchange application data yet, because further negotiation might be necessary (e.g., to fall back from the offered transport method to a suitable alternative).</p>
</section2>
<section2 topic='Modifying an Active Session' anchor='session-modify'>
<p>Once a session is in the ACTIVE state, it might be modified via a content-add, content-modify, content-remove, or transport-info action. Examples of such modifications are shown in the specifications for various application formats and transport methods.</p>
<p>Once a session is in the ACTIVE state, it might be modified via a content-add, content-modify, content-remove, or transport-info message. Examples of such modifications are shown in the specifications for various application formats and transport methods.</p>
</section2>
<section2 topic='Termination' anchor='session-terminate'>
<p>In order to gracefully end the session (which can be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a session-terminate action to the other party.</p>
<p>In order to gracefully end the session (which can be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a session-terminate message to the other party.</p>
<p>The party that terminates the session SHOULD include a &lt;reason/&gt; element that specifies why the session is being terminated. Examples follow.</p>
<p>Probably the primary reason for terminating a session is that the call has ended successfully; in this case, the recommended condition is &lt;success/&gt;.</p>
<p>Probably the primary reason for terminating a session is that the session has ended successfully (e.g., because a file has been sent or a voice call has completed); in this case, the recommended condition is &lt;success/&gt;.</p>
<example caption="Terminating the session (busy)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term0'
id='bv81gs75'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -883,10 +906,10 @@ PENDING o----------------------+ |
<p>Another reason for terminating the session is that the terminating party is busy; in this case, the recommended condition is &lt;busy/&gt;.</p>
<example caption="Terminating the session (busy)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term1'
id='hr81fs63'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -899,10 +922,10 @@ PENDING o----------------------+ |
<p>Another reason for terminating the session is that the terminating party wishes to formally decline the session; in this case, the recommended condition is &lt;decline/&gt;.</p>
<example caption="Terminating the session (session formally declined)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term2'
id='ky47g295'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -915,10 +938,10 @@ PENDING o----------------------+ |
<p>Another reason for terminating the session is that the terminating party already has an existing session with the other party and wishes to use that session rather than initiate a new session; in this case, the recommended condition is &lt;alternative-session/&gt; and the terminating party SHOULD include the session ID of the alternative session in the &lt;sid/&gt; element.</p>
<example caption="Terminating the session (existing session)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term3'
id='ay3r2b86'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -928,31 +951,15 @@ PENDING o----------------------+ |
</alternative-session>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party does not support any of the offered application formats; in this case, the recommended condition is &lt;unsupported-applications/&gt;.</p>
<example caption="Terminating the session (no offered application format supported)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term4'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<unsupported-applications/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party does not support any of the offered transport methods; in this case, the recommended condition is &lt;unsupported-transports/&gt;.</p>
<example caption="Terminating the session (no offered transport method supported)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term5'
id='h82bs51g'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -960,20 +967,84 @@ PENDING o----------------------+ |
<unsupported-transports/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party has determined that transport setup has failed in an unrecoverable fashion (e.g., all transport methods have been exhausted even after fallback and the last method attempted has failed); in this case, the recommended condition is &lt;failed-transport/&gt;.</p>
<example caption="Terminating the session (transport negotiation failed)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='pe81ga88'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<failed-transport/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party does not support any of the offered application types; in this case, the recommended condition is &lt;unsupported-applications/&gt;.</p>
<example caption="Terminating the session (no offered application type supported)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='yd62vd67'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<unsupported-applications/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party has determined that setup of the application type has failed in an unrecoverable fashion (e.g., the client cannot initialize audio processing for a voice call); in this case, the recommended condition is &lt;failed-application/&gt;.</p>
<example caption="Terminating the session (application setup failed)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='kd82vs71'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<failed-application/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party supports the offered application type but does not support the offered or negotiated parameters (e.g., in a voice call none of the payload types); in this case, the recommended condition is &lt;incompatible-parameters/&gt;.</p>
<example caption="Terminating the session (incompatible parameters)"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='yd62vd67'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<incompatible-parameters/>
</reason>
</jingle>
</iq>
]]></example>
<p>Note: Other reasons for terminating the session might apply, and the foregoing list is not exhaustive.</p>
<p>Upon receiving an action of "session-terminate", the other party MUST then acknowledge termination of the session:</p>
<p>Upon receiving session-terminate message, the other party MUST then acknowledge termination of the session:</p>
<example caption="Acknowledging termination"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='term1'
id='h82bs51g'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>Note: As soon as an entity sends a session-terminate action, it MUST consider the session to be in the ENDED state (even before receiving acknowledgement from the other party). If the terminating entity receives additional Jingle-related IQ-sets from the other party after sending the session-terminate action, it MUST reply with an &lt;unknown-session/&gt; error.</p>
<example caption="Unknown-session error"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='term1'
id='ur71vs62'
to='juliet@capulet.lit/balcony'
type='error'>
<error type='cancel'>
@ -982,16 +1053,16 @@ PENDING o----------------------+ |
</error>
</iq>
]]></example>
<p>Not all Jingle sessions end gracefully. When the parties to a Jingle session also exchange XMPP presence information, receipt of &UNAVAILABLE; from the other party SHOULD be considered a session-ending event that justifies proactively sending a session-terminate action to the seemingly unavailable party -- if, that is, no other communication has been received within 5 or 10 seconds from the seemingly unavailable party in the form of XMPP signalling traffic, connectivity checks, or continued media transfer.</p>
<p>Not all Jingle sessions end gracefully. When the parties to a Jingle session also exchange XMPP presence information, receipt of &UNAVAILABLE; from the other party SHOULD be considered a session-ending event that justifies proactively sending a session-terminate message to the seemingly unavailable party -- if, that is, no other communication has been received within 5 or 10 seconds from the seemingly unavailable party in the form of XMPP signalling traffic, connectivity checks, or continued media transfer.</p>
</section2>
<section2 topic='Informational Messages' anchor='session-info'>
<p>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 device is ringing.</p>
<example caption="Responder sends ringing message"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='ringing1'
id='hq7rg186'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
@ -1002,7 +1073,7 @@ PENDING o----------------------+ |
<p>An informational 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 SHOULD further contain a payload child element (specific to the application format or transport method) that specifies the information being communicated. If the party that receives an informational message does not understand the payload, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-info/&gt;.</p>
<example caption="Responder returns unsupported-info error"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ringing1'
id='hq7rg186'
to='juliet@capulet.lit/balcony'
type='error'>
<error type='modify'>
@ -1011,13 +1082,13 @@ PENDING o----------------------+ |
</error>
</iq>
]]></example>
<p>However, the &JINGLE; element associated with a session-info action MAY be empty. If either party receives an empty session-info action for an active session, it MUST send an empty IQ result; this usage functions as a "ping" to determine session vitality via the XMPP signalling channel.</p>
<p>However, the &JINGLE; element associated with a session-info message MAY be empty. If either party receives an empty session-info message for an active session, it MUST send an empty IQ result; this usage functions as a "ping" to determine session vitality via the XMPP signalling channel.</p>
<example caption="Responder sends session ping"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='ping1'
id='ug37vb25'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
<jingle xmlns='urn:xmpp:jingle:1'
action='session-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'/>
@ -1025,7 +1096,7 @@ PENDING o----------------------+ |
]]></example>
<example caption="Initiator returns IQ-result"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ping1'
id='ug37vb25'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
@ -1065,7 +1136,7 @@ PENDING o----------------------+ |
</table>
</section2>
<section2 topic='Action Attribute' anchor='def-action'>
<p>The value of the 'action' attribute MUST be one of the following. If an entity receives a value not defined here, it MUST ignore the attribute and MUST return a &badrequest; error to the sender.</p>
<p>The value of the 'action' attribute MUST be one of the following. If an entity receives a value not defined here, it MUST ignore the attribute and MUST return a &badrequest; error to the sender. There is no default value for the 'action' attribute.</p>
<section3 topic='content-accept' anchor='def-action-content-accept'>
<p>The <strong>content-accept</strong> action is used to accept a content-add action received from another party.</p>
</section3>
@ -1079,13 +1150,16 @@ PENDING o----------------------+ |
<p>The <strong>content-reject</strong> action is used to reject a content-add action received from another party.</p>
</section3>
<section3 topic='content-remove' anchor='def-action-content-remove'>
<p>The <strong>content-remove</strong> action is used to remove one or more content definitions from the session. The sender MUST specify only the removed content definition(s), not the removed content definition(s) plus the remaining content definition(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content definition(s). Upon receiving a content-remove from the other party, the recipient MUST NOT send a content-accept and MUST NOT continue to negotiate the transport method related to that content definition or send application data related to that content definition. <note>If the content-remove results in zero content definitions for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content definitions is void).</note></p>
<p>The <strong>content-remove</strong> action is used to remove one or more content definitions from the session. The sender MUST specify only the removed content definition(s), not the removed content definition(s) plus the remaining content definition(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content definition(s). Upon receiving a content-remove from the other party, the recipient MUST NOT send a content-accept and MUST NOT continue to negotiate the transport method or send application data related to that content definition. <note>If the content-remove results in zero content definitions for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content definitions is void).</note></p>
</section3>
<section3 topic='description-info' anchor='def-action-description-info'>
<p>The <strong>description-info</strong> action is used to send informational hints about parameters related to the application type, such as the suggested height and width of a video display area or suggested configuration for an audio stream.</p>
</section3>
<section3 topic='security-info' anchor='def-action-security-info'>
<p>The <strong>security-info</strong> action is used to send information related to establishment or maintenance of security preconditions.</p>
</section3>
<section3 topic='session-accept' anchor='def-action-session-accept'>
<p>The <strong>session-accept</strong> action is used to definitively accept a session negotiation (implicitly this action also serves as a content-accept). A session-accept action indicates acceptance <em>only</em> of the content definition(s) whose disposition type is "session" (the default value of the &CONTENT; element's 'disposition' attribute), not any content definition(s) whose disposition type is something other than "session" (e.g., "early-session" for early media). In the session-accept stanza, the &JINGLE; element MUST contain one or more &lt;content/&gt; elements, each of which MUST contain one &lt;description/&gt; element and one &lt;transport/&gt; element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity; after sending acknowledgement of the session-accept, the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute and note the new JID in the user interface.</p>
<p>The <strong>session-accept</strong> action is used to definitively accept a session negotiation (implicitly this action also serves as a content-accept). A session-accept action indicates a willingness to proceed with the session (which might necessitate further negotiation before media can be exchanged). The session-accept action indicates acceptance <em>only</em> of the content definition(s) whose disposition type is "session" (the default value of the &CONTENT; element's 'disposition' attribute), not any content definition(s) whose disposition type is something other than "session" (e.g., "early-session" for early media). In the session-accept stanza, the &JINGLE; element MUST contain one or more &lt;content/&gt; elements, each of which MUST contain one &lt;description/&gt; element and one &lt;transport/&gt; element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity; after sending acknowledgement of the session-accept, the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute and note the new JID in the user interface.</p>
</section3>
<section3 topic='session-info' anchor='def-action-session-info'>
<p>The <strong>session-info</strong> action is used to send session-level information, such as a session ping or (for Jingle RTP sessions) a ringing message.</p>
@ -1112,7 +1186,7 @@ PENDING o----------------------+ |
<p>It is possible that two instances of certain actions can be sent at the same time in the context of an existing session, one by each party; for example, both parties might simulaneously attempt to send a content-add action. In all such cases, the action sent by the initiator MUST overrule the action sent by the responder; i.e., both parties MUST accept the action sent by the initiator and the initiator MUST return an &conflict; error to the responder for the duplicate action, which SHOULD include a Jingle-specific condition of &lt;tie-break/&gt;.</p>
<example caption="Initiator returns unexpected-request error"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='add1'
id='hb2f164w'
to='juliet@capulet.lit/balcony'
type='error'>
<error type='cancel'>
@ -1190,6 +1264,14 @@ PENDING o----------------------+ |
<td>&lt;expired/&gt;</td>
<td>The session length has exceeded a pre-defined time limit (e.g., a meeting hosted at a conference service).</td>
</tr>
<tr>
<td>&lt;failed-application/&gt;</td>
<td>The party has been unable to initialize processing related to the application type.</td>
</tr>
<tr>
<td>&lt;failed-transport/&gt;</td>
<td>The party has been unable to establish connectivity for the transport method.</td>
</tr>
<tr>
<td>&lt;general-error/&gt;</td>
<td>The action is related to a non-specific application error.</td>
@ -1198,6 +1280,10 @@ PENDING o----------------------+ |
<td>&lt;gone/&gt;</td>
<td>The entity is going offline or is no longer available.</td>
</tr>
<tr>
<td>&lt;incompatible-parameters/&gt;</td>
<td>The party supports the offered application type but does not support the offered or negotiated parameters.</td>
</tr>
<tr>
<td>&lt;media-error/&gt;</td>
<td>The action is related to media processing problems.</td>
@ -1225,12 +1311,12 @@ PENDING o----------------------+ |
</table>
</section2>
<section2 topic='Thread Element' anchor='def-thread'>
<p>The syntax and semantics of the &lt;thread/&gt; element exactly matches that of the &lt;thread/&gt; element for the &MESSAGE; stanza (qualified by the 'jabber:client' namespace) as defined in &xmppim;. It is used to associate a Jingle session or sessions with an ongoing conversation, so that user interfaces with the ability to present multiple interactions in the same window can show an association between the conversation and the Jingle session(s).</p>
<p>The syntax and semantics of the &lt;thread/&gt; element exactly match the &lt;thread/&gt; element for the &MESSAGE; stanza (qualified by the 'jabber:client' namespace) as defined in &xmppim;. This element is used to associate a Jingle session or sessions with an ongoing conversation, so that user interfaces with the ability to present multiple interactions in the same window can show an association between the conversation and the Jingle session(s).</p>
</section2>
</section1>
<section1 topic='Transports' anchor='transports'>
<p>Jingle defines two transport types.</p>
<section1 topic='Transport Types' anchor='transports'>
<p>Jingle defines two types of transport methods.</p>
<section2 topic='Datagram' anchor='transports-datagram'>
<p>A datagram transport has one or more components with which to exchange packets with UDP-like behavior. Packets might be of arbitrary length, might be received out of order, and might not be received at all (i.e., the transport is lossy). Each component is assigned a string identifier and has a maximum packet length.</p>
<p>Applications compatible with datagram transports MUST specify how many components are necessary, what identifier to assign each component, and how each component will be used.</p>
@ -1241,6 +1327,58 @@ PENDING o----------------------+ |
</section2>
</section1>
<section1 topic='Security Preconditions' anchor='preconditions'>
<p>The initiator MAY include a &lt;security/&gt; element in its offer to signal that it wishes to enforce some security precondition on the session. A stub example follows.</p>
<example caption="Initiator sends session-initiate with security precondition (stub)"><![CDATA[
<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>
]]></example>
<p>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 &xmppe2e; for an in-progress description of a security precondition using Transport Layer Security (TLS).</p>
<p>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.</p>
<example caption="Initiator sends security-info message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='zyw6m167'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'>
action='security-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='xmlstream'>
<security xmlns='urn:xmpp:jingle:security:xtls:0'>
<method name='x509'/>
</security>
</content>
</jingle>
</iq>
]]></example>
<p>If one of the parties attempts to send information over the unsecured XMPP signalling channel tha t the other party expects to receive over the encrypted data channel, the receiving party SHOULD return a &notacceptable; error to the sender, including a &lt;security-required/&gt; element qualified by the 'urn:xmpp:jingle:errors:1' namespace. An example follows.</p>
<example caption="Initiator sends security-required error"><![CDATA[
<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:0'/>
</error>
</iq>
]]></example>
</section1>
<section1 topic='Error Handling' anchor='errors'>
<p>The Jingle-specific error conditions are as follows. These condition elements are qualified by the 'urn:xmpp:jingle:errors:0' namespace &VNOTE;.</p>
<table caption='Error Conditions'>
@ -1273,10 +1411,10 @@ PENDING o----------------------+ |
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:jingle:0" &VNOTE; in response to a &xep0030; 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.</p>
<p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:jingle:1" &VNOTE; in response to a &xep0030; 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.</p>
<example caption="Service Discovery Information Request"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='disco1'
id='ku6e51v3'
to='laertes@shakespeare.lit/castle'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
@ -1284,11 +1422,14 @@ PENDING o----------------------+ |
]]></example>
<example caption="Service Discovery Information Response"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='disco1'
id='ku6e51v3'
to='kingclaudius@shakespeare.lit/castle'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:0'/>
<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>
]]></example>
@ -1316,9 +1457,20 @@ PENDING o----------------------+ |
<li>If the transport supports multiple components.</li>
</ol>
</section2>
<section2 topic='Security Preconditions' anchor='conformance-preconditions'>
<p>A document that specifies a Jingle security precondition MUST define:</p>
<ol>
<li>A &lt;security/&gt; element and associated semantics for representing the security precondition.</li>
<li>Whether the security precondition applies to streaming transport methods, datagram transport methods, or both.</li>
<li>When the precondition is met so that application data can be sent over the negotiated transport.</li>
</ol>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<section2 topic='Transport Security' anchor='security-transport'>
<p>It is strongly recommended to protect the transport method using an appropriate security precondition (e.g., Transport Layer Security). However, methods for doing so are out of scope for this specification.</p>
</section2>
<section2 topic='Denial of Service' anchor='security-dos'>
<p>Jingle sessions can 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 sessions only from known entities and only if the entity's device is able to process such sessions.</p>
</section2>
@ -1341,7 +1493,7 @@ PENDING o----------------------+ |
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespaces:</p>
<ul>
<li>urn:xmpp:jingle:0</li>
<li>urn:xmpp:jingle:1</li>
<li>urn:xmpp:jingle:errors:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
@ -1387,8 +1539,8 @@ PENDING o----------------------+ |
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:0'
xmlns='urn:xmpp:jingle:0'
targetNamespace='urn:xmpp:jingle:1'
xmlns='urn:xmpp:jingle:1'
elementFormDefault='qualified'>
<xs:element name='jingle'>
@ -1417,6 +1569,7 @@ PENDING o----------------------+ |
<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'/>
@ -1487,8 +1640,11 @@ PENDING o----------------------+ |
<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'/>
@ -1531,6 +1687,7 @@ PENDING o----------------------+ |
elementFormDefault='qualified'>
<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'/>