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

0.9

Browse Source
This commit is contained in:
stpeter 2011-09-13 15:24:43 -06:00
parent 48342fbe22
commit 6c6b1387dc
1 changed files with 37 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
xep-0260.xml
View File

@ -33,6 +33,12 @@
<email>klaus.hartke@googlemail.com</email> <email>klaus.hartke@googlemail.com</email>
<jid>nx@jabber.org</jid> <jid>nx@jabber.org</jid>
</author> </author>
<revision>
<version>0.9</version>
<date>2011-09-13</date>
<initials>psa</initials>
<remark><p>Further clarified use of the dstaddr attribute, especially when the responder shares a proxy candidate with the initiator.</p></remark>
</revision>
<revision> <revision>
<version>0.8</version> <version>0.8</version>
<date>2011-09-08</date> <date>2011-09-08</date>
@ -147,8 +153,13 @@ Initiator Responder
</section2> </section2>
<section2 topic='Exchanging Candidates' anchor='exchange'> <section2 topic='Exchanging Candidates' anchor='exchange'>
<p>Once the initiator has a set of candidates, it sends a Jingle session-initiate request that contains one or more transport candidates which are a mixture of <cite>XEP-0065</cite> streamhosts and ICE candidates used in <cite>XEP-0176</cite>.</p> <p>Once the initiator has a set of candidates, it sends a Jingle session-initiate request that contains one or more transport candidates which are a mixture of <cite>XEP-0065</cite> streamhosts and ICE candidates used in <cite>XEP-0176</cite>.</p>
<p>Just as with the &QUERY; element from <cite>XEP-0065</cite>, here the &lt;transport/&gt; element that contains the candidates MUST possess a 'sid' attribute that specifies the Stream ID for this bytestream. The &lt;transport/&gt; element MAY possess a 'mode' attribute whose value is "tcp" (the default) or "udp" (for the latter, see Section 8 of <cite>XEP-0065</cite>). The &lt;transport/&gt; element MAY also possess a 'dstaddr' attribute whose value is the initiator's calculated hash value for the SOCKS5 DST.ADDR field (see Section 7 of <cite>XEP-0065</cite>).</p> <p>Just as with the &QUERY; element from <cite>XEP-0065</cite>, here the &lt;transport/&gt; element contains the candidates. The following rules apply to the defined attributes of the &lt;transport/&gt; element when sent by the initiator in a Jingle session-initate message:</p>
<p>Note: As explained in Section 5.3.2 of <cite>XEP-0065</cite>, the DST.ADDR value in the SOCKS5 negotiation is the SHA1 hash of (SID + Requester JID + Target JID). In the context of Jingle SOCKS5 Bytestreams, the "Requester JID" is the XMPP address of the initiator and the "Target JID" is the XMPP address of the responder (in the examples used here, the values are "romeo@montague.lit/orchard" and "juliet@capulet.lit/balcony" respectively).</p> <ol>
<li>The 'sid' attribute MUST be included. This attribute specifies the Stream ID for this bytestream.</li>
<li>The 'dstaddr' attribute SHOULD be included if the initiator includes at least one candidate of the "proxy" type. This attribute enables the initiator to communicate the value it has calculated for the SOCKS5 DST.ADDR field (see Section 5.3.2 and Section 7 of <cite>XEP-0065</cite>) so that the responder can provide an accurate value to the proxy during SOCKS5 negotiation. Here the value is calculated as SHA1(SID + Initiator JID + Responder JID) since the initiator will be the entity that activates the bytestream at the proxy.</li>
<li>The 'mode' attribute MAY be included. This attribute specifies whether the underlying transport for the bytestream will be TCP (a value of "tcp", which is the default) or UDP (a value of "udp", see Section 8 of <cite>XEP-0065</cite>).</li>
</ol>
<p>In the following example, Romeo's client has two interfaces, one on port 5086 and the other on port 5087. The provided candidates are the IPv4 address of one interface, the IPv4 address of the second interface, and a proxy address at streamer.shakespeare.lit. Because Romeo's client has included a proxy candidate, it includes its computed value for the DST.ADDR field in the 'dstaddr' attribute (here computed as the SHA-1 hash of "vj3hs98yromeo@montague.lit/orchardjuliet@capulet.lit/balcony").</p>
<example caption="Initiator sends session-initiate"><![CDATA[ <example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='romeo@montague.lit/orchard'
id='xn28s7gk' id='xn28s7gk'
@ -161,6 +172,7 @@ Initiator Responder
<content creator='initiator' name='ex'> <content creator='initiator' name='ex'>
<description xmlns='urn:xmpp:example'/> <description xmlns='urn:xmpp:example'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1' <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
dstaddr='lyt79HKRymCVF/Z/hrUIEIYFLa0='
mode='tcp' mode='tcp'
sid='vj3hs98y'> sid='vj3hs98y'>
<candidate cid='hft54dqy' <candidate cid='hft54dqy'
@ -179,7 +191,7 @@ Initiator Responder
host='123.456.7.8' host='123.456.7.8'
jid='streamer.shakespeare.lit' jid='streamer.shakespeare.lit'
port='7625' port='7625'
priority='8258636' priority='7878787'
type='proxy'/> type='proxy'/>
</transport> </transport>
</content> </content>
@ -193,9 +205,15 @@ Initiator Responder
to='romeo@montague.lit/orchard' to='romeo@montague.lit/orchard'
type='result'/> type='result'/>
]]></example> ]]></example>
<p>Depending on the application type, a user agent controlled by a human user might need to wait for the user to affirm a desire to proceed with the session before continuing. When the user agent has received such affirmation (or if the user agent can automatically proceed for any reason, e.g. because no human intervention is expected or because a human user has configured the user agent to automatically accept sessions with a given entity), it returns a Jingle session-accept message. This message MUST contain a &TRANSPORT; element qualified by the 'urn:xmpp:jingle:transports:s5b:1' namespace, which SHOULD in turn contain one &lt;candidate/&gt; element for each SOCKS5 Bytestreams candidate generated by or known to the responder, but MAY instead be empty if the responder does not wish to offer any candidates or wishes to send each candidate as the payload of a transport-info message.</p> <p>Depending on the application type, a user agent controlled by a human user might need to wait for the user to affirm a desire to proceed with the session before continuing. When the user agent has received such affirmation (or if the user agent can automatically proceed for any reason, e.g. because no human intervention is expected or because a human user has configured the user agent to automatically accept sessions with a given entity), it returns a Jingle session-accept message.</p>
<p>If the responder sends candidates in the session-accept, the chances of a successful connection are increased. For example, the initiator might be behind a NAT or might have no access to an S5B proxy, whereas the responder might have a public IP address, might know about a proxy, or might have NAT penetration support like NAT-PMP in a router. However, the responder MUST NOT offer as a candidate any host/port combination that has already been offered by the initiator; this helps to prevent failure of negotiation with S5B proxies.</p> <p>This message MUST contain a &TRANSPORT; element qualified by the 'urn:xmpp:jingle:transports:s5b:1' namespace, which SHOULD in turn contain one &lt;candidate/&gt; element for each SOCKS5 Bytestreams candidate generated by or known to the responder, but MAY instead be empty if the responder does not wish to offer any candidates or wishes to send each candidate as the payload of a transport-info message. If the responder sends candidates in the session-accept, the chances of a successful connection are increased. For example, the initiator might be behind a NAT or might have no access to an S5B proxy, whereas the responder might have a public IP address, might know about a proxy, or might have NAT penetration support like NAT-PMP in a router. However, the responder MUST NOT offer as a candidate any host/port combination that has already been offered by the initiator; this helps to prevent failure of negotiation with S5B proxies.</p>
<p>In the following example, Juliet's client opens one port. The provided candidates are the (private) IPv4 address of the interface, a (public) IPv6 address, and the public IPv4 address created by mapping the private IP address/port using NAT-PMP.</p> <p>The following rules apply to the defined attributes of the &lt;transport/&gt; element when sent by the responder in a Jingle session-accept message:</p>
<ol>
<li>The 'sid' attribute MUST be included and MUST be the same Stream ID communicated by the initiator in the Jingle session-initiate message.</li>
<li>The 'dstaddr' attribute SHOULD be included if the responder includes at least one candidate of the "proxy" type. This attribute enables the responder to communicate the value it has calculated for the SOCKS5 DST.ADDR field (see Section 5.3.2 and Section 7 of <cite>XEP-0065</cite>) so that the initiator can provide an accurate value to the proxy during SOCKS5 negotiation. Here the value is calculated as SHA1(SID + Responder JID + Initiator JID) since the responder will be the entity that activates the bytestream at the proxy.</li>
<li>The 'mode' attribute MUST NOT be included since the underlying transport for the bytestream is determined by the initiator.</li>
</ol>
<p>In the following example, Juliet's client opens one port. The provided candidates are the (private) IPv4 address of the interface, a (public) IPv6 address, the public IPv4 address created by mapping the private IP address/port using NAT-PMP, and a proxy address. Because Juliet's client has included a proxy candidate, it includes its computed value for the DST.ADDR field in the 'dstaddr' attribute (here computed as the SHA-1 hash of "vj3hs98yjuliet@capulet.lit/balconyromeo@montague.lit/orchard").</p>
<example caption="Responder sends session-accept with candidates"><![CDATA[ <example caption="Responder sends session-accept with candidates"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='hwd987h' id='hwd987h'
@ -208,6 +226,7 @@ Initiator Responder
<content creator='initiator' name='ex'> <content creator='initiator' name='ex'>
<description xmlns='urn:xmpp:example'/> <description xmlns='urn:xmpp:example'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:1' <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
dstaddr='GhL7e8Yl5V8+1bKaU9vg5Kp9gLo='
mode='tcp' mode='tcp'
sid='vj3hs98y'> sid='vj3hs98y'>
<candidate cid='ht567dq' <candidate cid='ht567dq'
@ -216,18 +235,24 @@ Initiator Responder
port='6539' port='6539'
priority='8257636' priority='8257636'
type='direct'/> type='direct'/>
<candidate cid='hr65dqyd'
host='134.102.201.180'
jid='juliet@capulet.lit/balcony'
port='16453'
priority='7929856'
type='assisted'/>
<candidate cid='grt654q2' <candidate cid='grt654q2'
host='2001:638:708:30c9:219:d1ff:fea4:a17d' host='2001:638:708:30c9:219:d1ff:fea4:a17d'
jid='juliet@capulet.lit/balcony' jid='juliet@capulet.lit/balcony'
port='6539' port='6539'
priority='8257606' priority='8257606'
type='direct'/> type='direct'/>
<candidate cid='hr65dqyd'
host='134.102.201.180'
jid='juliet@capulet.lit/balcony'
port='16453'
priority='7929856'
type='assisted'/>
<candidate cid='pzv14s74'
host='234.567.8.9'
jid='proxy.marlowe.lit'
port='7676'
priority='7788877'
type='proxy'/>
</transport> </transport>
</content> </content>
</jingle> </jingle>