mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-24 18:22:24 -05:00
0.23
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2583 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre
parent
ef3ba1855f
commit
757661af39
267
xep-0176.xml
267
xep-0176.xml
@ -8,7 +8,7 @@
|
||||
<xep>
|
||||
<header>
|
||||
<title>Jingle ICE-UDP Transport Method</title>
|
||||
<abstract>This specification defines a Jingle transport method that results in sending media data using raw datagram sockets via the User Datagram Protocol (UDP). This transport method is negotiated via the Interactive Connectivity Establishment (ICE) methodology defined by the IETF and thus provides robust NAT traversal for media traffic.</abstract>
|
||||
<abstract>This specification defines a Jingle transport method that results in sending media data using raw datagram associations via the User Datagram Protocol (UDP). This transport method is negotiated via the Interactive Connectivity Establishment (ICE) methodology, which provides robust NAT traversal for media traffic.</abstract>
|
||||
&LEGALNOTICE;
|
||||
<number>0176</number>
|
||||
<status>Proposed</status>
|
||||
@ -21,12 +21,19 @@
|
||||
</dependencies>
|
||||
<supersedes/>
|
||||
<supersededby/>
|
||||
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||
<shortname>N/A</shortname>
|
||||
<discuss>jingle</discuss>
|
||||
&joebeda;
|
||||
&scottlu;
|
||||
&stpeter;
|
||||
&hildjj;
|
||||
&seanegan;
|
||||
<revision>
|
||||
<version>0.23</version>
|
||||
<date>2008-12-19</date>
|
||||
<initials>psa</initials>
|
||||
<remark><p>Specified id attribute and added it to the examples; updated namespaces to reflect changes to other Jingle specifications; completed editorial review.</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.22</version>
|
||||
<date>2008-09-30</date>
|
||||
@ -186,7 +193,7 @@
|
||||
<p>The Jingle transport method defined herein are designed to meet the following requirements:</p>
|
||||
<ol>
|
||||
<li>Make it possible to establish and manage out-of-band connections between two XMPP entities, even if they are behind Network Address Translators (NATs) or firewalls.</li>
|
||||
<li>Enable use of UDP as the transport protocol itself.</li>
|
||||
<li>Enable use of UDP as the transport protocol.</li>
|
||||
<li>Make it relatively easy to implement support 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>
|
||||
@ -201,60 +208,47 @@
|
||||
</ol>
|
||||
</section1>
|
||||
<section1 topic='Protocol Description' anchor='protocol'>
|
||||
<section2 topic='Flow' anchor='protocol-flow'>
|
||||
<section2 topic='Overall Flow' anchor='protocol-flow'>
|
||||
<p>The overall protocol flow for negotiation of the Jingle ICE-UDP Transport Method is as follows (note: many of these events happen simultaneously, not in sequence).</p>
|
||||
<code><![CDATA[
|
||||
INITIATOR RESPONDER
|
||||
| |
|
||||
| Jingle session-initiate |
|
||||
|----------------------------------->|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|<-----------------------------------|
|
||||
| Jingle transport-info (candidate) |
|
||||
|----------------------------------->|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|<-----------------------------------|
|
||||
| Jingle transport-info (candidate) |
|
||||
|----------------------------------->|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|<-----------------------------------|
|
||||
| Jingle transport-info (candidate) |
|
||||
|<-----------------------------------|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|----------------------------------->|
|
||||
| STUN Binding Request |
|
||||
| (dropped) |
|
||||
| x=================================|
|
||||
| STUN Binding Request |
|
||||
|===================================>|
|
||||
| STUN Binding Result |
|
||||
|<===================================|
|
||||
| STUN Binding Request |
|
||||
|<===================================|
|
||||
| STUN Binding Result |
|
||||
|===================================>|
|
||||
| Jingle session-accept |
|
||||
|<-----------------------------------|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|----------------------------------->|
|
||||
|<========MEDIA NOW FLOWS===========>|
|
||||
| |
|
||||
INITIATOR RESPONDER
|
||||
| |
|
||||
| Jingle session-initiate stanza |
|
||||
|------------------------------------->|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|<-------------------------------------|
|
||||
| multiple Jingle transport-info |
|
||||
| stanzas (one candidate per stanaza) |
|
||||
|<------------------------------------>|
|
||||
| multiple Jingle acks |
|
||||
| (XMPP IQ-result stanzas) |
|
||||
|<------------------------------------>|
|
||||
| multiple STUN Binding Requests |
|
||||
|<====================================>|
|
||||
| multiple STUN Binding Results |
|
||||
|<====================================>|
|
||||
| Jingle session-accept stanza |
|
||||
|<-------------------------------------|
|
||||
| Jingle ack (XMPP IQ-result) |
|
||||
|------------------------------------->|
|
||||
|<=========MEDIA NOW FLOWS============>|
|
||||
| |
|
||||
]]></code>
|
||||
<p>Note: The examples in this document follow the scenario described in Section 17 of &icecore;, except that we substitute the Shakespearean characters "Romeo" and "Juliet" for the generic entities "L" and "R".</p>
|
||||
</section2>
|
||||
<section2 topic='Transport Initiation' anchor='protocol-initiate'>
|
||||
<p>In order for the initiator in a Jingle exchange to start the negotiation, it MUST send a Jingle "session-initiate" stanza as described in <cite>XEP-0166</cite>. A content type MUST include one transport method. If the initiator wishes to negotiate the ice-udp transport method for an application format, it MUST include an empty &TRANSPORT; child element qualified by the 'urn:xmpp:jingle:transports:ice-udp:0' namespace &VNOTE;.</p>
|
||||
<p>In order for the initiator in a Jingle exchange to start the negotiation, it sends a Jingle "session-initiate" stanza that includes at least one content type, as described in <cite>XEP-0166</cite>. If the initiator wishes to negotiate the ice-udp transport method for an application format, it MUST include an empty &TRANSPORT; child element qualified by the 'urn:xmpp:jingle:transports:ice-udp:0' namespace &VNOTE;.</p>
|
||||
<example caption="Initiation"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='jingle1'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='session-initiate'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content name='this-is-the-audio-content'>
|
||||
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
|
||||
<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'/>
|
||||
@ -294,30 +288,43 @@ INITIATOR RESPONDER
|
||||
<section2 topic='Response' anchor='protocol-response'>
|
||||
<p>As described in <cite>XEP-0166</cite>, to acknowledge receipt of the session initiation request, the responder returns an IQ-result:</p>
|
||||
<example caption="Responder acknowledges receipt of session-initiate request"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='jingle1'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
</section2>
|
||||
<section2 topic='Candidate Negotiation' anchor='protocol-candidates'>
|
||||
<p>Once the responder acknowledges receipt of the session initiation request as shown above, both initiator and responder MUST immediately negotiate connectivity over the ICE transport by exchanging XML-formatted candidate transports for the channel. This negotiation proceeds immediately in order to maximize the possibility that media can be exchanged as quickly as possible. <note>Concurrent with negotiation of the ICE candidates, it is possible for the initiator and responder to negotiate which content types the session will include, which transport methods will be tried for each content type, etc. Those negotiation flows are shown in other specifications, such as <cite>XEP-0166</cite>. This document specifies only negotiation of the ICE transport method.</note></p>
|
||||
<p>Note: In order to expedite session establishment, the initiator MAY send transport candidates immediately after sending the "session-initiate" message and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery as mandated by &xmppcore;, the responder will receive such "transport-info" messages after receiving the "session-initiate" message; if not, it is appropriate for the responder to return <unknown-session/> errors since according to its state machine the session does not exist. If either party receives an <unknown-session/> from the other party, it MUST terminate the negotiation and the session.</p>
|
||||
<p>Once the responder acknowledges receipt of the session initiation request as shown above, both initiator and responder MUST immediately negotiate connectivity over ICE by exchanging XML-formatted transport "candidates" for the channel. This negotiation proceeds immediately in order to maximize the possibility that media can be exchanged as quickly as possible. <note>Concurrent with negotiation of the ICE candidates, it is possible for the initiator and responder to negotiate which content types the session will include, which transport methods will be tried for each content type, etc. Those negotiation flows are shown in other specifications, such as <cite>XEP-0166</cite>. This document specifies only negotiation of the ICE transport method.</note></p>
|
||||
<p>In order to expedite session establishment, the initiator MAY send transport candidates immediately after sending the "session-initiate" message and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery as mandated by &xmppcore;, the responder will receive such "transport-info" messages after receiving the "session-initiate" message; if not, it is appropriate for the responder to return <unknown-session/> errors since according to its state machine the session does not exist.</p>
|
||||
<example caption="Responder returns unknown-session error"><![CDATA[
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='jingle1'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='error'>
|
||||
<error type='cancel'>
|
||||
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
<unknown-session xmlns='urn:xmpp:jingle:errors:0'/>
|
||||
</error>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>If either party receives an <unknown-session/> error from the other party, it MUST terminate the negotiation and the session.</p>
|
||||
<p>Note: See the <link url='#security'>Security Considerations</link> section of this document regarding the exposure of IP addresses on behalf by the responder's client.</p>
|
||||
<p>The candidate syntax and negotiation flow are described below.</p>
|
||||
<section3 topic='Syntax of Candidate Element' anchor='protocol-candidates-syntax'>
|
||||
<p>The following is an example of the candidate format:</p>
|
||||
<example caption="A candidate transport"><![CDATA[
|
||||
<code><![CDATA[
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='el0747fg11'
|
||||
ip='10.0.1.1'
|
||||
network='0'
|
||||
port='8998'
|
||||
priority='2130706431'
|
||||
protocol='udp'
|
||||
type='host'/>
|
||||
]]></example>
|
||||
]]></code>
|
||||
<p>The attributes of the <candidate/> element are described in the following table:</p>
|
||||
<table caption='Candidate Attributes'>
|
||||
<tr>
|
||||
@ -344,6 +351,12 @@ INITIATOR RESPONDER
|
||||
<td>N/A</td>
|
||||
<td>0</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>id</td>
|
||||
<td>A unique identifier for the candidate.</td>
|
||||
<td>N/A</td>
|
||||
<td>el0747fg11</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ip</td>
|
||||
<td>The Internet Protocol (IP) address for the candidate transport mechanism; this may be either an IPv4 address or an IPv6 address.</td>
|
||||
@ -372,7 +385,7 @@ INITIATOR RESPONDER
|
||||
</tr>
|
||||
<tr>
|
||||
<td>protocol</td>
|
||||
<td>The protocol to be used. The only allowable value is "udp".</td>
|
||||
<td>The protocol to be used. The only value defined by this specification is "udp".</td>
|
||||
<td>Transport protocol field in a=candidate line</td>
|
||||
<td>udp</td>
|
||||
</tr>
|
||||
@ -412,17 +425,17 @@ INITIATOR RESPONDER
|
||||
<p>The first step in negotiating connectivity is for each party to immediately begin sending transport candidates to the other party. <note>The fact that both parties send candidates means that Jingle requires each party to be a full implementation of ICE, not a lite implementation as specified in &icecore;.</note> These candidates SHOULD be gathered by following the procedure specified in Section 4.1.1 of &icecore; (typically by communicating with a standalone STUN server in order to discover the client's public IP address and port) and prioritized by following the procedure specified in Section 4.1.2 of &icecore;.</p>
|
||||
<p>Each candidate or set of candidates shall be sent as <candidate/> children of a &TRANSPORT; element qualified by the 'urn:xmpp:jingle:transports:ice-udp:0' namespace. The &TRANSPORT; element shall be sent via a Jingle action of "transport-info" as shown in the examples below.</p>
|
||||
<p>Either party MAY include multiple <candidate/> elements in one &TRANSPORT; element. Sending one candidate per transport-info action typically results in a faster negotiation because the candidates most likely to succeed are sent first and it is not necessary to gather all candidates before beginning to send any candidates. Furthermore, because certain candidates can be more "expensive" in terms of bandwidth or processing power, the initiator might not want to advertise their existence unless it is necessary to do so after other candidates have failed. However, sending multiple candidates in a single "transport-info" action can help to ensure interoperability with entities that implement the SDP offer/answer model described in <cite>RFC 3264</cite>. An entity SHOULD send one candidate per "transport-info" action and send multiple such actions, instead of sending multiple candidates in a single "transport-info" action; the only exception is if the other party advertises support for the "urn:ietf:rfc:3264" service discovery feature as described in the <link url='#support-sdp'>SDP Offer / Answer Support</link> section of this document.</p>
|
||||
<p>If the responder receives and can successfully process a given candidate or set of candidates, it returns an IQ-result (if not, for example because the candidate data is improperly formatted, it returns an IQ-error). Note: The responder is only indicating receipt of the candidate or set of candidates, not telling the initiator that the candidate will be used.</p>
|
||||
<p>If the responder receives and can successfully process a given candidate or set of candidates, it returns an IQ-result (if not, for example because the candidate data is improperly formatted, it returns an IQ-error). At this point, the responder is only indicating receipt of the candidate or set of candidates, not telling the initiator that the candidate will be used.</p>
|
||||
<p>The initiator keeps sending candidates (without stopping to receive an acknowledgement of receipt from the responder for each candidate) until it has exhausted its supply of possible or desirable candidate transports. For each candidate or set of candidates, the responder acknowledges receipt.</p>
|
||||
<p>At the same time (i.e., immediately after acknowledging receipt of the session-initiate request, not waiting for the initiator to begin or finish sending candidates), the responder also begins sending potential candidates, in order of desirability according to the responder. As above, the initiator acknowledges receipt of the candidates.</p>
|
||||
<example caption="Initiator sends some candidates"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='info1'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-info'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -431,6 +444,7 @@ INITIATOR RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='el0747fg11'
|
||||
ip='10.0.1.1'
|
||||
network='1'
|
||||
port='8998'
|
||||
@ -442,13 +456,13 @@ INITIATOR RESPONDER
|
||||
</jingle>
|
||||
</iq>
|
||||
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='info2'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-info'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -457,6 +471,7 @@ INITIATOR RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='2'
|
||||
generation='0'
|
||||
id='y3s2b30v3r'
|
||||
ip='192.0.2.3'
|
||||
network='1'
|
||||
port='45664'
|
||||
@ -472,14 +487,14 @@ INITIATOR RESPONDER
|
||||
]]></example>
|
||||
<p>For each candidate received, the other party (in this case the responder) MUST acknowledge receipt or return an error.</p>
|
||||
<example caption="Responder acknowledges receipt"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='info1'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='info2'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>At the same time (i.e., immediately after acknowledging the session-initation request, not waiting for the initiator to begin or finish sending candidates), the responder also sends candidates that may work for it.</p>
|
||||
@ -499,6 +514,7 @@ INITIATOR RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='or2ii2syr1'
|
||||
ip='192.0.2.1'
|
||||
network='0'
|
||||
port='3478'
|
||||
@ -523,7 +539,7 @@ INITIATOR RESPONDER
|
||||
<p>As the initiator and responder receive candidates, they probe the various candidate transports for connectivity. In performing these connectivity checks, each party SHOULD follow the procedure specified in Section 7 of &icecore;. The following business rules apply:</p>
|
||||
<ol>
|
||||
<li>Each party sends a STUN Binding Request (see &rfc5389;) from each local candidate it generated to each remote candidate it received.</li>
|
||||
<li>In accordance with &icecore;, the STUN Binding Request MUST include the PRIORITY attribute (computed according to Section 7.1.1.1. of &icecore;).</li>
|
||||
<li>In accordance with &icecore;, the STUN Binding Requests MUST include the PRIORITY attribute (computed according to Section 7.1.1.1. of &icecore;).</li>
|
||||
<li>For the purposes of the Jingle ICE-UDP Transport Method, both parties are full ICE implementations and therefore the controlling role MUST be assumed by the initiator and the controlled role MUST be assumed by the responder.</li>
|
||||
<li>The STUN Binding Requests generated by the initiator MAY include the USE-CANDIDATE attribute to indicate that the initiator wishes to cease checks for this component.</li>
|
||||
<li>The STUN Binding Requests generated by the initiator MUST include the ICE-CONTROLLING attribute.</li>
|
||||
@ -536,7 +552,7 @@ INITIATOR RESPONDER
|
||||
<li>The source IP address and port of the response equals the destination IP address and port to which the Binding Request was sent.</li>
|
||||
<li>The destination IP address and port of the response match the source IP address and port from which the Binding Request was sent.</li>
|
||||
</ol>
|
||||
<p>For the candidates exchanged in the previous section, the connectivity checks would be as follows. In particular, the parties send one STUN Binding Request from each of their local candidates to each of the remote candidates.</p>
|
||||
<p>For the candidates exchanged in the previous section, the connectivity checks would be as follows (this diagram mirrors the example in &icecore;).</p>
|
||||
<code><![CDATA[
|
||||
INITIATOR NAT RESPONDER
|
||||
| | |
|
||||
@ -565,7 +581,7 @@ INITIATOR NAT RESPONDER
|
||||
| map 192.0.2.3:45664 | |
|
||||
|<======================| |
|
||||
| | |
|
||||
|==============Media Now Can Flow==============>|
|
||||
|<==Media Now Can Flow==| |
|
||||
| | |
|
||||
| | STUN Binding Request |
|
||||
| | from 192.0.2.1:3478 |
|
||||
@ -586,7 +602,7 @@ INITIATOR NAT RESPONDER
|
||||
| | map 192.0.2.1:3478 |
|
||||
| |======================>|
|
||||
| | |
|
||||
|==============Media Now Can Flow==============>|
|
||||
| |==Media Now Can Flow==>|
|
||||
| | |
|
||||
]]></code>
|
||||
<p>Note: Here the initiator (controlling agent) is using "aggressive nomination" as described in Section 8.1.1.2 of &icecore; and therefore includes the USE-CANDIDATE attribute in the STUN Binding Requests it sends.</p>
|
||||
@ -599,17 +615,17 @@ INITIATOR NAT RESPONDER
|
||||
</ol>
|
||||
<p>First, the responder sends a session-accept action to the initiator, specifying the candidate that succeeded. The session-accept MUST contain information about the nominated pair, including the "rem-addr" and "rem-port" attributes (which specify the IP address and port for the responder's end of the pair, which is a "remote address" according to the initiator). This enables both parties to explicitly agree to both ends of the connection pair (i.e., the local address+port and the remote address+port).</p>
|
||||
<example caption="Responder definitively accepts the successful candidate"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='accept1'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='session-accept'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
responder='juliet@capulet.com/balcony'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
responder='juliet@capulet.lit/balcony'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
|
||||
<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>
|
||||
@ -617,6 +633,7 @@ INITIATOR NAT RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='y3s2b30v3r'
|
||||
ip='192.0.2.3'
|
||||
network='1'
|
||||
port='45664'
|
||||
@ -632,39 +649,38 @@ INITIATOR NAT RESPONDER
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The &JINGLE; element in the session-accept stanza SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity. If the 'responder' attribute is provided, all future commmunications SHOULD be sent to the JID provided in the 'responder' attribute.</p>
|
||||
<p>Since according to the connectivity checks the initiator can also send data over that candidate, it acknowledges the responder's acceptance:</p>
|
||||
<example caption="Initiator acknowledges acceptance of successful candidate"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='accept1'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>Now the initiator and responder can begin sending media data over the negotiated connection (in fact, they could have sent data as soon as the connectivity checks succeeded, as shown in the preceding examples).</p>
|
||||
<p>If a candidate succeeded for the responder but the initiator cannot send data over that candidate, it MUST return a ¬acceptable; error in response to the responder's acceptance of the successful candidate:</p>
|
||||
<example caption="Initiator returns error in response to acceptance of successful candidate"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='accept1'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='error'>
|
||||
<error type='cancel'>
|
||||
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
</error>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>If the responder cannot find a suitable candidate transport or it receives a ¬acceptable; error from the initiator in response to its acceptance of a suitable transport, it SHOULD terminate the session as described in Section 6.7 of <cite>XEP-0166</cite>.</p>
|
||||
<p>If the responder cannot find a suitable candidate transport or it receives a ¬acceptable; error from the initiator in response to its acceptance of a suitable transport, it SHOULD terminate the session as described in <cite>XEP-0166</cite>.</p>
|
||||
</section2>
|
||||
<section2 topic='Modifying an Existing Candidate' anchor='protocol-modify'>
|
||||
<p>The creator of a content type MAY modify an existing, in-use candidate at any time during the session, for example to change the IP address or port. This is done by sending a transport-replace action with the changed candidate information, where the value of the 'generation' attribute is incremented to specify that the candidate information is a modification to an existing candidate.</p>
|
||||
<p>An example follows (change to IP address and port).</p>
|
||||
<example caption="Initiator modifies the in-use candidate"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='rep2'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-replace'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -673,6 +689,7 @@ INITIATOR NAT RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='1'
|
||||
id='y3s2b30v3r'
|
||||
ip='192.0.2.3'
|
||||
network='1'
|
||||
port='45665'
|
||||
@ -686,21 +703,21 @@ INITIATOR NAT RESPONDER
|
||||
]]></example>
|
||||
<p>The recipient then acknowledges receipt.</p>
|
||||
<example caption="Recipient acknowledges transport-replace"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='rep2'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>If the transport-replace is acceptable, the recipient then sends a transport-accept action (if not, the recipient sends a transport-reject action).</p>
|
||||
<example caption="Responder definitively accepts the replaced candidate"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='accept2'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-accept'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
responder='juliet@capulet.com/balcony'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
responder='juliet@capulet.lit/balcony'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -709,6 +726,7 @@ INITIATOR NAT RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='1'
|
||||
id='y3s2b30v3r'
|
||||
ip='192.0.2.3'
|
||||
network='1'
|
||||
port='45665'
|
||||
@ -722,23 +740,23 @@ INITIATOR NAT RESPONDER
|
||||
]]></example>
|
||||
<p>The initiator then acknowledges the responder's acceptance:</p>
|
||||
<example caption="Initiator acknowledges content acceptance"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='accept2'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>The parties then use the modified candidate in subsequent communications.</p>
|
||||
</section2>
|
||||
<section2 topic='Negotiating a New Candidate' anchor='protocol-renegotiate'>
|
||||
<p>Even after content acceptance or session acceptance, either party MAY continue to send additional candidates to the other party (e.g., because the user agent has become aware of a new media proxy or NIC). As above, such candidates are shared by sending a transport-info action.</p>
|
||||
<p>Even after content acceptance or session acceptance, either party MAY continue to send additional candidates to the other party (e.g., because the user agent has become aware of a new media proxy or network interface card). As above, such candidates are shared by sending a transport-info action.</p>
|
||||
<example caption="Initiator sends a fourth candidate"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='info4'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-info'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -747,6 +765,7 @@ INITIATOR NAT RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='m3110wc4nd'
|
||||
ip='10.0.1.2'
|
||||
network='0'
|
||||
port='9001'
|
||||
@ -760,21 +779,21 @@ INITIATOR NAT RESPONDER
|
||||
]]></example>
|
||||
<p>The receiving party MUST acknowledge receipt of the candidate.</p>
|
||||
<example caption="Recipient acknowledges receipt"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='info4'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>The parties SHOULD check the newly-offered candidate for connectivity, as described previously. If the parties determine that media can flow over the candidate, the initiating party shall send a transport-replace action to the responder.</p>
|
||||
<p>The parties SHOULD check the newly-offered candidate for connectivity, as described previously. If the parties determine that media can flow over the candidate, the initiating party MAY send a transport-replace action to the responder in order to use the new candidate.</p>
|
||||
<example caption="Initiator sends transport-replace"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='rep3'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-replace'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
responder='juliet@capulet.com/balcony'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
responder='juliet@capulet.lit/balcony'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -783,6 +802,7 @@ INITIATOR NAT RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='m3110wc4nd'
|
||||
ip='10.0.1.2'
|
||||
network='0'
|
||||
port='9001'
|
||||
@ -796,21 +816,21 @@ INITIATOR NAT RESPONDER
|
||||
]]></example>
|
||||
<p>The responder then acknowledges the replaced transport definition.</p>
|
||||
<example caption="Responder acknowledges transport-replace"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='rep3'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>The responder then accepts the replaced transport definition.</p>
|
||||
<example caption="Responder definitively accepts the replaced transport definition"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='accept3'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:0'
|
||||
action='transport-accept'
|
||||
initiator='romeo@montague.net/orchard'
|
||||
responder='juliet@capulet.com/balcony'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
responder='juliet@capulet.lit/balcony'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='this-is-the-audio-content'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'
|
||||
@ -819,6 +839,7 @@ INITIATOR NAT RESPONDER
|
||||
<candidate component='1'
|
||||
foundation='1'
|
||||
generation='0'
|
||||
id='m3110wc4nd'
|
||||
ip='10.0.1.2'
|
||||
network='0'
|
||||
port='9001'
|
||||
@ -832,9 +853,9 @@ INITIATOR NAT RESPONDER
|
||||
]]></example>
|
||||
<p>The initiator then acknowledges content acceptance.</p>
|
||||
<example caption="Initiator acknowledges content acceptance"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='accept3'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>The parties then use the new candidate in subsequent communications.</p>
|
||||
@ -900,7 +921,7 @@ Romeo Gateway Juliet
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='voice'>
|
||||
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
|
||||
<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'/>
|
||||
@ -929,7 +950,7 @@ Romeo Gateway Juliet
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='voice1'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:0'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:1'>
|
||||
<candidate generation='0'
|
||||
id='a9j3mnbtu1'
|
||||
ip='10.1.1.104'
|
||||
@ -956,7 +977,7 @@ Romeo Gateway Juliet
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='responder' name='voice2'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:0'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:1'>
|
||||
<candidate generation='0'
|
||||
id='a9j3mnbtu1'
|
||||
ip='10.1.1.104'
|
||||
@ -985,10 +1006,10 @@ Romeo Gateway Juliet
|
||||
responder='juliet@capulet.lit/balcony'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='voice'>
|
||||
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
|
||||
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
|
||||
<payload-type id='18' name='G729'/>
|
||||
</description>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:0'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:1'>
|
||||
<candidate generation='0'
|
||||
id='a9j3mnbtu1'
|
||||
ip='10.1.1.104'
|
||||
@ -1004,8 +1025,7 @@ Romeo Gateway Juliet
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>The endpoints now begin to exchange session media.</p>
|
||||
<p>The endpoints can continue the session as long as desired.</p>
|
||||
<p>The endpoints now begin to exchange session media, and can continue the session as long as desired.</p>
|
||||
<p>Eventually, one of the endpoints terminates the session.</p>
|
||||
<example caption="Responder terminates the session"><![CDATA[
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
@ -1036,22 +1056,20 @@ Romeo Gateway Juliet
|
||||
<section2 topic='ICE Support' anchor='support-ice'>
|
||||
<p>If an entity supports the Jingle ice-udp transport, it MUST return a feature of "urn:xmpp:jingle:transports:ice-udp:0" &VNOTE; in response to &xep0030; information requests.</p>
|
||||
<example caption="Service discovery information request"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='disco1'
|
||||
to='juliet@capulet.com/balcony'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='get'>
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<example caption="Service discovery information response"><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='disco1'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'>
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||||
...
|
||||
<feature var='urn:xmpp:jingle:transports:ice-udp:0'/>
|
||||
...
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
@ -1060,7 +1078,7 @@ Romeo Gateway Juliet
|
||||
<section2 topic='SDP Offer / Answer Support' anchor='support-sdp'>
|
||||
<p>If an entity supports the SDP offer / answer model described in <cite>RFC 3264</cite> and therefore prefers to receive multiple candidates in a single "transport-info" action, it MUST advertise support for the "urn:ietf:rfc:3264" service discovery feature. Typically this feature will be advertised only by gateways between Jingle and SIP.</p>
|
||||
<example caption="Service discovery information request"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='disco2'
|
||||
to='sip.shakespeare.lit'
|
||||
type='get'>
|
||||
@ -1070,7 +1088,7 @@ Romeo Gateway Juliet
|
||||
<example caption="Service discovery information response"><![CDATA[
|
||||
<iq from='sip.shakespeare.lit'
|
||||
id='disco2'
|
||||
to='romeo@montague.net/orchard'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'>
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||||
...
|
||||
@ -1085,11 +1103,10 @@ Romeo Gateway Juliet
|
||||
|
||||
<section1 topic='Implementation Notes' anchor='impl'>
|
||||
<p>In order to speed the negotiation process so that media can flow as quickly as possible, the initiator SHOULD gather and prioritize candidates in advance, or as soon as the principal begins the process of initiating a session.</p>
|
||||
<p>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>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Deployment Notes' anchor='deploy'>
|
||||
<p>This specification applies exclusively to Jabber/XMPP clients and places no additional requirements on Jabber/XMPP servers. However, service administrators might wish to deploy a STUN server in order to ease the client-to-client negotiation process. See &xep0215; for related information.</p>
|
||||
<p>This specification applies exclusively to Jabber/XMPP clients and places no additional requirements on Jabber/XMPP servers. However, service administrators might wish to deploy a STUN server in order to ease the client-to-client negotiation process, and a TURN server for media relaying (see &turn;).</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Security Considerations' anchor='security'>
|
||||
@ -1119,7 +1136,7 @@ Romeo Gateway Juliet
|
||||
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
|
||||
</section2>
|
||||
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
|
||||
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
|
||||
&NSVER;
|
||||
</section2>
|
||||
<section2 topic='Service Discovery Features' anchor='registrar-features'>
|
||||
<p>If an entity supports the SDP offer / answer model described in <cite>RFC 3264</cite> and therefore prefers to receive one "transport-info" action with multiple candidates, it MUST advertise support for the "urn:ietf:rfc:3264" feature.</p>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user