moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-30 21:22:15 -05:00
Code Issues Releases Wiki Activity

Added Support for TURN

Browse Source 
Added Support for TURN Discovery and Credentials Retrieval
This commit is contained in:
Thiago Camargo 2017-09-15 17:39:32 +02:00 committed by GitHub
parent 344a0dd771
commit 25d0dba271
1 changed files with 98 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
xep-0278.xml
View File

@ -3,6 +3,8 @@
<!ENTITY % ents SYSTEM 'xep.ent'> <!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY CHANNEL "&lt;channel/&gt;"> <!ENTITY CHANNEL "&lt;channel/&gt;">
<!ENTITY RELAY "&lt;relay/&gt;"> <!ENTITY RELAY "&lt;relay/&gt;">
<!ENTITY STUN "&lt;stun/&gt;">
<!ENTITY TURN "&lt;turn/&gt;">
<!ENTITY SERVICES "&lt;services/&gt;"> <!ENTITY SERVICES "&lt;services/&gt;">
<!ENTITY TRACKER "&lt;tracker/&gt;"> <!ENTITY TRACKER "&lt;tracker/&gt;">
%ents; %ents;
@ -32,6 +34,12 @@
<email>thiago@xmppjingle.com</email> <email>thiago@xmppjingle.com</email>
<jid>barata7@gmail.com</jid> <jid>barata7@gmail.com</jid>
</author> </author>
<revision>
<version>0.2</version>
<date>2017-09-14</date>
<initials>tc</initials>
<remark><p>Added TURN Credentials Service Support.</p></remark>
</revision>
<revision> <revision>
<version>0.2</version> <version>0.2</version>
<date>2011-06-21</date> <date>2011-06-21</date>
@ -115,6 +123,7 @@ All signalling, request, response and publishing is done via XMPP, not requiring
<services xmlns='http://jabber.org/protocol/jinglenodes'> <services xmlns='http://jabber.org/protocol/jinglenodes'>
<relay policy='public' address='montague.lit' protocol='udp'/> <relay policy='public' address='montague.lit' protocol='udp'/>
<tracker policy='public' address='capulet.lit' protocol='udp'/> <tracker policy='public' address='capulet.lit' protocol='udp'/>
<turn policy='public' address='stun.capulet.lit' protocol='udp'/>
<stun policy='public' address='200.111.111.111' port='3857' protocol='udp'/> <stun policy='public' address='200.111.111.111' port='3857' protocol='udp'/>
</services> </services>
</iq> </iq>
@ -194,6 +203,34 @@ All signalling, request, response and publishing is done via XMPP, not requiring
]]></example> ]]></example>
<p><em>After receiving the &CHANNEL; the requester MUST send his stream to 'host' and 'localport' pair and send a &CANDIDATE; containing the 'host' and 'remoteport' values.</em></p> <p><em>After receiving the &CHANNEL; the requester MUST send his stream to 'host' and 'localport' pair and send a &CANDIDATE; containing the 'host' and 'remoteport' values.</em></p>
</section2> </section2>
<section2 topic="Jingle Client Consuming TURN Credentials Service" anchor="clientconsumingturncredentials">
<p>A Jingle Client can request volative TURN credentials, to be used in cases where connectivity check is a requirement. Like, for example, WebRTC. The concept and mechanism is quite similar to the RFC draft <link url='https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00'>REST API For Access To TURN Services'.</link></p>
<p>TURN provides an access control mechanism described in &rfc5389;, where long-term credentials are provided as part of the TURN protocol. Therefore the credentials provided in this Jingle Nodes mechanism are time-limited, but SHOULD be used as long-term credentials, when authentication against a TURN Server.
</p>
<p>
<em>Note: There is no need to run TURN server or support within a Jingle Relay. This mechanism allows decoupled deployment of distributed TURN Servers, without the requirement of database based authentication. </em>
</p>
<example caption="TURN Credentials request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='uw72g176'
to='juliet@capulet.lit/balcony'
type='get'>
<turn xmlns='http://jabber.org/protocol/jinglenodes#turncredentials' protocol='udp'/>
</iq>
]]></example>
<example caption="TUNR Credentials Returned by the service"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='uw72g176'
to='romeo@montague.lit/orchard'
type='result'>
<turn ttl='60000'
uri='turn:200.20.2.10:1984?transport=udp'
username='1433895918506:romeocapulet'
password='1Dj9XZ5fwvKS6YoQZOoORcFnXaI='
/>
</iq>
]]></example>
</section2>
</section1> </section1>
<section1 topic="Services Definitions" anchor="servicesdefinition"> <section1 topic="Services Definitions" anchor="servicesdefinition">
<section2 topic="Relay Channel Service" anchor="relaychannelservice"> <section2 topic="Relay Channel Service" anchor="relaychannelservice">
@ -293,7 +330,7 @@ All signalling, request, response and publishing is done via XMPP, not requiring
</section3> </section3>
</section2> </section2>
<section2 topic="Services Element" anchor="def-services"> <section2 topic="Services Element" anchor="def-services">
<p>The &SERVICES; element MAY be empty or contain &RELAY; and/or &TRACKER; elements.</p> <p>The &SERVICES; element MAY be empty or contain &RELAY;, &STUN; and/or &TRACKER; elements.</p>
<p>The attributes of the &RELAY; and &TRACKER; element are as follows.</p> <p>The attributes of the &RELAY; and &TRACKER; element are as follows.</p>
<table caption="Attributes of Relay and Tracker Elements"> <table caption="Attributes of Relay and Tracker Elements">
<tr> <tr>
@ -323,6 +360,48 @@ All signalling, request, response and publishing is done via XMPP, not requiring
</tr> </tr>
</table> </table>
</section2> </section2>
<section2 topic="TURN Credentials Service Element" anchor="def-turn-credentials">
<p>The attributes of the &TURN; element are as follows.</p>
<table caption="Attributes of TURN Elements">
<tr>
<th>Attribute</th>
<th>Definition</th>
<th>Inclusion</th>
</tr>
<tr>
<td>ttl</td>
<td>The duration in seconds for which the provided credentials are valid.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>uri</td>
<td>The TURN Server URI.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>username</td>
<td>The username to be used on TURN authentication. THe recommended format is a colon-delimited concatenation of expiration timestamp and the requester bare JID.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>password</td>
<td>The ppassword to be used on TURN authentication. Is the result of 'base64(hmac(secret_key, username))'. Where 'secret_key' is shared between the TURN server and entity providing the credentials.</td>
<td>REQUIRED</td>
</tr>
</table>
<section3 topic="Ttl Attribute" anchor="def-ttlattribute">
<p>The duration in seconds for which the provided credentials are valid. The usual and recommended value is 86400 seconds (one day).</p>
</section3>
<section3 topic="URI Attribute" anchor="def-uriattribute">
<p>The TURN Server URI as described in <link url="https://tools.ietf.org/html/draft-petithuguenin-behave-turn-uris-03">I-D.petithuguenin-behave-turn-uris</link></p>
</section3>
<section3 topic="Username Attribute" anchor="def-ttlattribute">
<p>WebRTC's TURN request uses the 'username' value for its USERNAME and PASSWORD attributes, for the input to the MESSAGE-INTEGRITY hash.</p>
</section3>
<section3 topic="Password Attribute" anchor="def-ttlattribute">
<p>Along with 'username', WebRTC's TURN request uses the 'password' value for its USERNAME and PASSWORD attributes, for the input to the MESSAGE-INTEGRITY hash.</p>
</section3>
</section2>
</section1> </section1>
<section1 topic="Determining Support" anchor="support"> <section1 topic="Determining Support" anchor="support">
<p>To advertise its support for the Jingle Nodes support, when replying to &xep0030; information requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "http://jabber.org/protocol/jinglenodes" for this version&VNOTE;.</p> <p>To advertise its support for the Jingle Nodes support, when replying to &xep0030; information requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "http://jabber.org/protocol/jinglenodes" for this version&VNOTE;.</p>
@ -344,6 +423,7 @@ All signalling, request, response and publishing is done via XMPP, not requiring
<query xmlns='http://jabber.org/protocol/disco#info'> <query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/jinglenodes'/> <feature var='http://jabber.org/protocol/jinglenodes'/>
<feature var='http://jabber.org/protocol/jinglenodes#channel'/> <feature var='http://jabber.org/protocol/jinglenodes#channel'/>
<feature var='http://jabber.org/protocol/jinglenodes#turncredentials'/>
</query> </query>
</iq> </iq>
]]></example> ]]></example>
@ -356,6 +436,10 @@ All signalling, request, response and publishing is done via XMPP, not requiring
<em>Note: This use case is also similar to a Jingle to SIP Interoperability Service.</em> <em>Note: This use case is also similar to a Jingle to SIP Interoperability Service.</em>
</p> </p>
</section2> </section2>
<section2 topic="Jingle Client that uses WebRTC with TURN required" anchor="webrtcturn">
<p>A Jingle Client that uses WebRTC, therefore requiring a TURN Server and its credentials to successfully alocate channels. This specification describes a simple way of discovering TURN Services and retrieving credentials to successfully allocate channels.
This also simplifies deployment and distribution of TURN servers, since its stateless authentication does not require connectivity to database authoriztion services.</p>
</section2>
<section2 topic="Jingle Client with ICE-UDP Transport with STUN support but no TURN support" anchor="iceudpnoturn"> <section2 topic="Jingle Client with ICE-UDP Transport with STUN support but no TURN support" anchor="iceudpnoturn">
<p>A Jingle Client with STUN support but no TURN support can use Relay Node Services as the fallback candidate instead of a TURN candidate. For instance, after a connectivity check proccess, none of the direct candidates worked. The Client can use the Relay Node Candidate as the fallback candidate(the lowest priority candidate).</p> <p>A Jingle Client with STUN support but no TURN support can use Relay Node Services as the fallback candidate instead of a TURN candidate. For instance, after a connectivity check proccess, none of the direct candidates worked. The Client can use the Relay Node Candidate as the fallback candidate(the lowest priority candidate).</p>
</section2> </section2>
@ -420,6 +504,13 @@ All signalling, request, response and publishing is done via XMPP, not requiring
<xs:attribute name='expire' type='xs:string' use='required'/> <xs:attribute name='expire' type='xs:string' use='required'/>
</xs:element> </xs:element>
<xs:element name='turn'>
<xs:attribute name='ttl' type='xs:string' use='required'/>
<xs:attribute name='uri' type='xs:string' use='required'/>
<xs:attribute name='username' type='xs:string' use='required'/>
<xs:attribute name='password' type='xs:string' use='required'/>
</xs:element>
<xs:element name='services'> <xs:element name='services'>
<xs:complexType> <xs:complexType>
<xs:sequence> <xs:sequence>
@ -435,6 +526,10 @@ All signalling, request, response and publishing is done via XMPP, not requiring
type='serviceElementType' type='serviceElementType'
minOccurs='0' minOccurs='0'
maxOccurs='unbounded'/> maxOccurs='unbounded'/>
<xs:element name='turn'
type='serviceElementType'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence> </xs:sequence>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>