mirror of https://github.com/moparisthebest/xeps
text adjustments
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1009 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre
parent
b7e2c3a898
commit
92efceba46
50
xep-0180.xml
50
xep-0180.xml
|
|
@ -83,14 +83,14 @@
|
|||
</revision>
|
||||
</header>
|
||||
<section1 topic='Introduction' anchor='intro'>
|
||||
<p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is video exchange. This document specifies a format for describing Jingle video sessions, where the media exchange occurs using the Real-time Transport Protocol (see &rfc3550;). Such sessions require the use of a lossy transport method such as &xep0177; or the "ice-udp" method specified in &xep0176;.</p>
|
||||
<p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is video exchange. This document specifies a format for describing Jingle video sessions, where the media exchange occurs using the Real-time Transport Protocol (see &rfc3550;).</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Requirements' anchor='reqs'>
|
||||
<p>The Jingle content description format defined herein is designed to meet the following requirements:</p>
|
||||
<ol>
|
||||
<li>Enable negotiation of parameters necessary for video exchange.</li>
|
||||
<li>Map these parameters to Session Description Protocol (SDP; see &rfc4566;) to enable interoperability.</li>
|
||||
<li>Map these parameters to the Session Description Protocol (SDP; see &rfc4566;) to enable interoperability.</li>
|
||||
<li>Define informational messages related to video chat.</li>
|
||||
</ol>
|
||||
</section1>
|
||||
|
|
@ -112,7 +112,7 @@
|
|||
</section1>
|
||||
|
||||
<section1 topic='Content Description Format' anchor='format'>
|
||||
<p>A Jingle video session is described by one or more encodings contained within a wrapper &DESCRIPTION; element. In the language of <cite>RFC 4566</cite> these encodings are payload-types; therefore, each <payload-type/> child element specifies an encoding that can be used for the video stream. Such encodings are often used in the context of the Real-time Transfer Protocol (RTP; see <cite>RFC 3550</cite>) but may be used in other contexts as well. The most common encodings for the Audio/Video Profile (AVP) of RTP are listed in &rfc3551; (these "static" types are reserved from payload ID 0 through payload ID 95), although other encodings are allowed (these "dynamic" types use payload IDs 96 to 127) in accordance with the dynamic assignment rules described in Section 3 of <cite>RFC 3551</cite>. The &PAYLOADTYPE; element's 'id' attribute is REQUIRED and its 'name' attribute is RECOMMENDED. The encodings SHOULD be provided in order of preference.</p>
|
||||
<p>A Jingle video session is described by one or more encodings contained within a wrapper &DESCRIPTION; element qualified by the 'http://www.xmpp.org/extensions/xep-0180.html#ns' namespace &NSNOTE;. In the language of <cite>RFC 4566</cite> these encodings are payload-types; therefore, each <payload-type/> child element specifies an encoding that can be used for the video stream. Such encodings are often used in the context of the Real-time Transfer Protocol (RTP; see <cite>RFC 3550</cite>) but may be used in other contexts as well. The most common encodings for the Audio/Video Profile (AVP) of RTP are listed in &rfc3551; (these "static" types are reserved from payload ID 0 through payload ID 95), although other encodings are allowed in accordance with the dynamic assignment rules described in Section 3 of <cite>RFC 3551</cite> (these "dynamic" types use payload IDs 96 to 127). The &PAYLOADTYPE; element's 'id' attribute is REQUIRED and its 'name' attribute is RECOMMENDED. The encodings SHOULD be provided in order of preference.</p>
|
||||
<example caption="Video Description Format"><![CDATA[
|
||||
<description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
|
||||
<payload-type id='96' name='theora' clockrate='90000' height='720' width='1280'>
|
||||
|
|
@ -195,7 +195,7 @@
|
|||
<td>OPTIONAL</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>Each <payload-type/> element MAY contain one or more child elements that specify particular parameters related to the payload. For example, as described in &rtptheora;, the "configuration", "configuration-uri", "delivery-method", and "sampling" parameters may be specified in relation to usage of the Theora <note>See <<link url='http://www.theora.org/'>http://www.theora.org/</link>>.</note> codec. Where such parameters are encoded via the "fmtp" SDP attribute, they shall be represented in Jingle via the following format:</p>
|
||||
<p>Each <payload-type/> element MAY contain one or more child elements that specify particular parameters related to the payload. For example, as described in &rtptheora;, the "configuration", "configuration-uri", "delivery-method", and "sampling" parameters may be specified in relation to usage of the Theora <note>See <<link url='http://www.theora.org/'>http://www.theora.org/</link>>.</note> codec. Where such parameters are encoded via the "fmtp" SDP attribute, they shall be represented in Jingle via the following format, where the <parameter/> element is a child of the &PAYLOADTYPE; element:</p>
|
||||
<code><![CDATA[
|
||||
<parameter name='foo' value='bar'/>
|
||||
]]></code>
|
||||
|
|
@ -229,7 +229,7 @@
|
|||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Upon receiving the session-initiate stanza, the receiver determines whether it can provisionally accept the session and proceed with the negotiation. The general Jingle error cases are specified in <cite>XEP-0166</cite>. In addition, the receiver must determine if it supports any of the payload types advertised by the initiator; if it does not, it MUST reject the session by sending a <unsupported-codecs/> error:</p>
|
||||
<p>Upon receiving the session-initiate stanza, the receiver determines whether it can provisionally accept the session and proceed with the negotiation. The general Jingle error cases are specified in <cite>XEP-0166</cite>. In addition, the receiver must determine if it supports any of the payload types advertised by the initiator; if it does not, it MUST reject the session by sending a ¬acceptable; error, which SHOULD include a Jingle-specific error condition of <unsupported-codecs/>:</p>
|
||||
<example caption="Receiver Does Not Support Codecs"><![CDATA[
|
||||
<iq type='error'
|
||||
from='juliet@capulet.com/balcony'
|
||||
|
|
@ -237,7 +237,7 @@
|
|||
id='jinglevideo1'>
|
||||
<error type='cancel'>
|
||||
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
<unsupported-codecs xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-errors'/>
|
||||
<unsupported-codecs xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns-errors'/>
|
||||
</error>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
|
@ -268,7 +268,7 @@
|
|||
<payload-type id='32' name='MPV' clockrate='90000'/>
|
||||
<payload-type id='33' name='MP2T' clockrate='90000'/>
|
||||
</description>
|
||||
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
|
||||
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
|
||||
</content>
|
||||
</jingle>
|
||||
</iq>
|
||||
|
|
@ -278,7 +278,7 @@
|
|||
<iq from='romeo@montegue.net/orchard'
|
||||
to='juliet@capulet.com/balcony'
|
||||
id='jinglevideo2'
|
||||
type='result' />
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>After successful transport negotiation (not shown here), the receiver then accepts the session:</p>
|
||||
<example caption="Receiver Definitively Accepts the Session"><![CDATA[
|
||||
|
|
@ -324,11 +324,12 @@
|
|||
<code><![CDATA[
|
||||
m=<media> <port> <transport> <fmt list>
|
||||
]]></code>
|
||||
<p>In the context of Jingle video sessions, the <media> is "video", the <port> is the preferred port for such communications (which may be determined dynamically), the <transport> is whatever transport method is negotiated via the Jingle negotiation (e.g., "RTP/AVT"), and the <fmt list> is the payload-type ID.</p>
|
||||
<p>In the context of Jingle video sessions, the <media> is "video", the <port> is the preferred port for such communications (which may be determined dynamically), the <transport> is whatever transport method is negotiated via the Jingle negotiation (e.g., "RTP/AVP"), and the <fmt list> is the payload-type ID.</p>
|
||||
<p>For example, consider the following static payload-type:</p>
|
||||
<example caption="Jingle Format for Static Payload-Type"><![CDATA[
|
||||
<payload-type id="28" name="nv"/>
|
||||
]]></example>
|
||||
<p>That Jingle-formatted information would be mapped to SDP as follows:</p>
|
||||
<example caption="SDP Mapping of Static Payload-Type"><![CDATA[
|
||||
m=video 9000 RTP/AVP 28
|
||||
]]></example>
|
||||
|
|
@ -337,12 +338,13 @@ m=video 9000 RTP/AVP 28
|
|||
<example caption="Jingle Format for Dynamic Payload-Type"><![CDATA[
|
||||
<payload-type id='98' name='vc1' height='288' width='352'/>
|
||||
]]></example>
|
||||
<p>That Jingle-formatted information would be mapped to SDP as follows:</p>
|
||||
<example caption="SDP Mapping of Dynamic Payload-Type"><![CDATA[
|
||||
m=video 49170 RTP/AVP 98
|
||||
a=rtpmap:98 vc1/90000
|
||||
a=fmtp:98 width=352;height=288;
|
||||
]]></example>
|
||||
<p>As noted, if additional parameters are to be specified, they shall be represented as attributes of the <payload-type/> element of the child <parameter/> element, as in the following example.</p>
|
||||
<p>As noted, if additional parameters are to be specified, they shall be represented as attributes of the <payload-type/> element or its child <parameter/> element, as in the following example.</p>
|
||||
<example caption="Jingle Format for Dynamic Payload-Type With Parameters"><![CDATA[
|
||||
<payload-type id='96' name='theora' height='720' width='1280'>
|
||||
<parameter name='delivery-method' value='inline'/>
|
||||
|
|
@ -350,6 +352,7 @@ a=fmtp:98 width=352;height=288;
|
|||
<parameter name='sampling' value='YCbCr-4:2:2'/>
|
||||
</payload-type>
|
||||
]]></example>
|
||||
<p>That Jingle-formatted information would be mapped to SDP as follows:</p>
|
||||
<example caption="SDP Mapping of Dynamic Payload-Type With Parameters"><![CDATA[
|
||||
m=video 49170 RTP/AVP 98
|
||||
a=rtpmap:96 theora/90000
|
||||
|
|
@ -359,7 +362,7 @@ delivery-method=inline; configuration=somebase16string;
|
|||
</section1>
|
||||
|
||||
<section1 topic='Determining Support' anchor='support'>
|
||||
<p>If an entity supports Jingle video exchanges via RTP, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0180.html#ns" in response to &xep0030; information requests.</p>
|
||||
<p>If an entity supports Jingle video exchanges via RTP, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0180.html#ns" in response to &xep0030; information requests &NSNOTE;.</p>
|
||||
<example caption="Service Discovery Information Request"><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
id='disco1'
|
||||
|
|
@ -384,7 +387,7 @@ delivery-method=inline; configuration=somebase16string;
|
|||
</section1>
|
||||
|
||||
<section1 topic='Informational Messages' anchor='info'>
|
||||
<p>Informational messages may be sent by either party within the context of Jingle to communicate the status of a Jingle video session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info", where the informational message is a payload element qualified by the 'http://www.xmpp.org/extensions/xep-0180.html#ns-info' namespace. No payload elements have yet been defined, but may be specified in a future version of this document.</p>
|
||||
<p>Informational messages may be sent by either party within the context of Jingle to communicate the status of a Jingle video session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info". No informational message payload elements have yet been defined, but they may be specified in a future version of this document.</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Implementation Notes' anchor='impl'>
|
||||
|
|
@ -403,7 +406,7 @@ delivery-method=inline; configuration=somebase16string;
|
|||
|
||||
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||
<section2 topic='Protocol Namespaces' anchor='ns'>
|
||||
<p>Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0180.html#ns" and "http://www.xmpp.org/extensions/xep-0180.html#ns-info"; upon advancement of this specification, the ®ISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
|
||||
<p>Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0180.html#ns" and "http://www.xmpp.org/extensions/xep-0180.html#ns-errors"; upon advancement of this specification, the ®ISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
|
||||
</section2>
|
||||
<section2 topic='Jingle Content Description Formats' anchor='registrar-content'>
|
||||
<p>The XMPP Registrar shall include "video-rtp" in its registry of Jingle content description formats. The registry submission is as follows:</p>
|
||||
|
|
@ -462,6 +465,27 @@ delivery-method=inline; configuration=somebase16string;
|
|||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
</xs:schema>
|
||||
]]></code>
|
||||
</section2>
|
||||
<section2 topic='Errors' anchor='schema-errors'>
|
||||
<code><![CDATA[
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
|
||||
<xs:schema
|
||||
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
||||
targetNamespace='http://www.xmpp.org/extensions/xep-0180.html#ns-errors'
|
||||
xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns-errors'
|
||||
elementFormDefault='qualified'>
|
||||
|
||||
<xs:element name='unsupported-codecs' type='empty'/>
|
||||
|
||||
<xs:simpleType name='empty'>
|
||||
<xs:restriction base='xs:string'>
|
||||
<xs:enumeration value=''/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
</xs:schema>
|
||||
]]></code>
|
||||
</section2>
|
||||
|
|
|
|||
53
xep-0181.xml
53
xep-0181.xml
|
|
@ -73,10 +73,10 @@
|
|||
<p>The format for the XML DTMF representation is as follows &NSNOTE;:</p>
|
||||
<example caption="Basic DTMF Format"><![CDATA[
|
||||
<dtmf xmlns='http://www.xmpp.org/extensions/xep-0181.html#ns'
|
||||
action='button-down'
|
||||
action='[button-down|button-up]'
|
||||
code='integer'/>
|
||||
]]></example>
|
||||
<p>The <dtmf/> element SHOULD possess one 'action' attribute, which MUST be either "button-up" or "button-down", specifying whether the button is being depressed or released. This allows DTMF tones to be reconstructed in real-time. If the 'action' attribute is not included, the recipient MUST assume this to be a "button-down" event, and imply a "button-up" event after a reasonable timeout (100 milliseconds is RECOMMENDED) or when another DMTF event is received.</p>
|
||||
<p>The <dtmf/> element SHOULD possess an 'action' attribute, the value of which MUST be either "button-up" or "button-down" (specifying whether the button is being depressed or released). This enables DTMF tones to be reconstructed in real time. If the 'action' attribute is not included, the recipient MUST assume that the action is a "button-down" event and act as if a "button-up" event occurs after a reasonable timeout (100 milliseconds is RECOMMENDED) or when another DMTF event is received.</p>
|
||||
<p>Unless the 'action' attribute has a value of "button-up", the <dmtf/> element MUST possess a 'code' attribute that specifies the tone to be generated. The value of the 'code' attribute SHOULD be one the following characters: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and * -- however, the characters A, B, C, and D MAY be sent as well. <note>Although A, B, C, and D were originally defined as part of DTMF, they were never deployed to telephony consumers and were used only for control purposes at private branch exchanges (PBXs) and central office operator stations; however, they are used in certain non-telephony applications of DTMF, such as ham radio.</note></p>
|
||||
<p>The <dtmf> element SHOULD be sent as the payload of a Jingle session-info message as illustrated in the following example &NSNOTE;.</p>
|
||||
<example caption="Entity Sends DTMF Message"><![CDATA[
|
||||
|
|
@ -90,7 +90,7 @@
|
|||
sid='a73sjjvkla37jfea'>
|
||||
<dtmf xmlns='http://www.xmpp.org/extensions/xep-0181.html#ns'
|
||||
code='7'
|
||||
action='button-up'/>
|
||||
action='button-down'/>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
|
@ -101,7 +101,7 @@
|
|||
id='dtmf1'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>If the receiving entity does not understand or cannot process the payload, it MUST return an error &feature; with a Jingle-specific error condition of <unsupported-info/>.</p>
|
||||
<p>If the receiving entity does not understand or cannot process the payload, it MUST return a &feature; stanza error, which SHOULD include a Jingle-specific error condition of <unsupported-info/>.</p>
|
||||
<example caption="Receiving Does Not Understand DTMF Info Message"><![CDATA[
|
||||
<iq from='ivr.shakespeare.lit'
|
||||
to='juliet@capulet.com/balcony'
|
||||
|
|
@ -138,7 +138,7 @@
|
|||
id='dtmf2'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>If the recipient does not support the requested DTMF method, it MUST return an error of a <feature-not-implemented/> error with a DTMF-specific error condition of <unsupported-dtmf-method/>:</p>
|
||||
<p>If the recipient does not support the requested DTMF method, it MUST return a <feature-not-implemented/> stanza error, which SHOULD include a DTMF-specific error condition of <unsupported-dtmf-method/>:</p>
|
||||
<example caption="Recipient Refuses Request"><![CDATA[
|
||||
<iq from='ivr.shakespeare.lit'
|
||||
to='juliet@capulet.com/balcony'
|
||||
|
|
@ -175,7 +175,8 @@
|
|||
</section1>
|
||||
|
||||
<section1 topic='XML Schema' anchor='schema'>
|
||||
<code><![CDATA[
|
||||
<section2 topic='DTMF' anchor='schema-dtmf'>
|
||||
<code><![CDATA[
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
|
||||
<xs:schema
|
||||
|
|
@ -202,6 +203,22 @@
|
|||
</xs:simpleContent>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='dtmf-method'>
|
||||
<xs:complexType>
|
||||
<xs:simpleContent>
|
||||
<xs:extension base='empty'>
|
||||
<xs:attribute name='role' use='optional' default='xmpp'>
|
||||
<xs:simpleType>
|
||||
<xs:restriction base='xs:NCName'>
|
||||
<xs:enumeration value='rtp'/>
|
||||
<xs:enumeration value='xmpp'/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
</xs:attribute>
|
||||
</xs:extension>
|
||||
</xs:simpleContent>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:simpleType name="DTMFString">
|
||||
|
|
@ -217,6 +234,28 @@
|
|||
</xs:simpleType>
|
||||
|
||||
</xs:schema>
|
||||
]]></code>
|
||||
]]></code>
|
||||
</section2>
|
||||
<section2 topic='DTMF Errors' anchor='schema-dtmferrors'>
|
||||
<code><![CDATA[
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
|
||||
<xs:schema
|
||||
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
||||
targetNamespace='http://www.xmpp.org/extensions/xep-0181.html#ns-errors'
|
||||
xmlns='http://www.xmpp.org/extensions/xep-0181.html#ns-errors'
|
||||
elementFormDefault='qualified'>
|
||||
|
||||
<xs:element name='unsupported-dtmf-method' type='empty'/>
|
||||
|
||||
<xs:simpleType name='empty'>
|
||||
<xs:restriction base='xs:string'>
|
||||
<xs:enumeration value=''/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
</xs:schema>
|
||||
]]></code>
|
||||
</section2>
|
||||
</section1>
|
||||
</xep>
|
||||
|
|
|
|||
|
|
@ -49,12 +49,12 @@
|
|||
</header>
|
||||
|
||||
<section1 topic='Introduction' anchor='intro'>
|
||||
<p>&xep0166; defines a framework for negotiating and managing out-of-band data exchange sessions over XMPP. Unfortunately, most developers of XMPP clients have limited experience with multimedia applications such as voice and video, making it difficult to get started with implementation of Jingle technologies. Therefore this document provides a simple transport and session type that client developers can use to bootstrap Jingle implementations.</p>
|
||||
<p><em>Note: The methods specified herein are provided for experimentation and unit testing only and are not intended for inclusion in released software or production environments.</em></p>
|
||||
<p>&xep0166; defines a framework for using XMPP to negotiate and manage out-of-band media sessions. Unfortunately, most developers of XMPP clients have limited experience with multimedia applications such as voice and video, making it difficult to get started with implementation of Jingle technologies. Therefore this document provides a simple transport and session type that client developers can use to bootstrap Jingle implementations.</p>
|
||||
<p><em>Note: The methods specified herein are provided for experimentation and unit testing only. They are not intended for inclusion in released software or production environments.</em></p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Protocol Flow' anchor='protocol'>
|
||||
<p>The intent of this simple Jingle profile is to enable exchange of data using the Echo Protocol specified in &rfc0862;, but using a port other than 7 -- the default port for this usage is 17777. The protocol flow is as follows. (The following examples use &xep0177; as the transport protocol; although it is possible to complete echo protocol exchanges via TCP, that is deemed less useful and there is no Jingle transport for direct TCP exchanges.)</p>
|
||||
<p>The intent of this simple Jingle profile is to enable exchange of data using the Echo Protocol specified in &rfc0862;, but using a port other than 7 (the default port for this experimental usage is 17777). The protocol flow is as follows. (The following examples use &xep0177; as the transport protocol; although it is possible to complete echo protocol exchanges via TCP, that is deemed less useful and there is no Jingle transport for direct TCP exchanges.)</p>
|
||||
<example caption='Initiatior Creates Session'><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='jingle1' type='set'>
|
||||
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
|
||||
|
|
@ -70,7 +70,6 @@
|
|||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: The port SHOULD be 17777.</p>
|
||||
<example caption='Receiver Provisionally Accepts the Session Request'><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='result' id='jingle1'/>
|
||||
]]></example>
|
||||
|
|
@ -87,7 +86,7 @@
|
|||
<iq type='result' to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='accept1'/>
|
||||
]]></example>
|
||||
<p>The parties may now exchange data using the echo protocol in order to test the connection.</p>
|
||||
<p>Note: Protocol flows for additional use cases (e.g., renegotiation) will be added to future versions of this specification.</p>
|
||||
<p>Note: Protocol flows for additional use cases (e.g., renegotiation) may be added to future versions of this specification.</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Security Considerations' anchor='security'>
|
||||
|
|
|
|||
30
xep-0215.xml
30
xep-0215.xml
|
|
@ -63,17 +63,16 @@
|
|||
<section1 topic='Introduction' anchor='intro'>
|
||||
<p>The administrator of an XMPP server may wish to deploy one or more STUN servers (see &rfc3489; and &rfc3489bis;) in order to ease the process of negotiating media exchanges via &xep0176;. A client can become aware of a STUN server in the following ways:</p>
|
||||
<ol>
|
||||
<li>The server is specified in the default settings for the client.</li>
|
||||
<li>The server is manually added by a human user into the client's configuration.</li>
|
||||
<li>The server is discovered via DNS SRV records as specified in Section 9.1 of <cite>RFC 3489</cite>.</li>
|
||||
<li>The server is specified in the client's default settings.</li>
|
||||
<li>The server is manually added into the client's configuration by a human user.</li>
|
||||
<li>The server is discovered via DNS SRV records (see &rfc2782;) as specified in Section 9.1 of <cite>RFC 3489</cite>.</li>
|
||||
</ol>
|
||||
<p>Unfortunately, the foregoing methods are subject to human error or cannot be deployed in wide range of scenarios. Therefore, this document defines a way for an XMPP server to advertise a list of STUN servers and provide credentials for use by an XMPP client at a STUN server. This method SHOULD be used only as a fallback when DNS SRV lookups are not possible for the client or server.</p>
|
||||
<p>Unfortunately, the foregoing methods are subject to human error or cannot be deployed in wide range of scenarios. Therefore, this document defines a way for an XMPP server to advertise a list of STUN servers and provide credentials for use by an XMPP client at a STUN server. This method should be used only as a fallback when DNS SRV lookups are not possible for the client or server.</p>
|
||||
<p>Note: The protocol specified herein is functionally equivalent to the protocol currently used in the Google Talk service and documented at <<link url='http://code.google.com/apis/talk/jep_extensions/jingleinfo.html'>http://code.google.com/apis/talk/jep_extensions/jingleinfo.html</link>>.</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Protocol' anchor='protocol'>
|
||||
<p>In order to learn about available STUN servers associated with or known by an XMPP server, a client sends an IQ-get containing a <stun/> element qualified by the "http://www.xmpp.org/extensions/xep-0215.html#ns" namespace &NSNOTE;.</p>
|
||||
<p>An example of the payload format for this node is as follows:</p>
|
||||
<example caption='Entity Requests STUN Server List from XMPP Server'><![CDATA[
|
||||
<iq type='get'
|
||||
from='bard@shakespeare.lit/globe'
|
||||
|
|
@ -82,6 +81,7 @@
|
|||
<stun xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The XMPP server SHOULD return the list of STUN servers, but MAY instead return an appropriate error, such as &unavailable; if the server does not support the STUN Server Discovery protocol or &forbidden; if the requesting entity does not have permission to receive the list of STUN servers.</p>
|
||||
<example caption='XMPP Server Returns List'><![CDATA[
|
||||
<iq type='result'
|
||||
from='shakespeare.lit'
|
||||
|
|
@ -93,9 +93,14 @@
|
|||
</stun>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>(Naturally, the XMPP MAY instead return an appropriate error, such as &unavailable; if the server does not support the STUN Server Discovery protocol or &forbidden; if the requesting entity does not have permission to receive the server list.)</p>
|
||||
<p>The 'host' attribute is REQUIRED and specifies either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6). The 'port' attribute is REQUIRED and specifies the communications port to be used at the host. <note>The port is necessary since this specification assumes that DNS SRV lookups are not possible.</note></p>
|
||||
<p>A STUN server may require a username and password in order to accept STUN binding requests and/or STUN allocate requests. In this case, the XMPP server would typically generate a short-term authentication credential based on a private key shared with the STUN server (naturally, other implementations are possible, and long-term credentials could be used instead; see <cite>RFC 3489</cite> and <cite>rfc3489bis</cite> for details).</p>
|
||||
<p>The syntax of the <server/> element is as follows:</p>
|
||||
<ul>
|
||||
<li>The <server/> element SHOULD be empty.</li>
|
||||
<li>The 'host' attribute is REQUIRED and specifies either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6).</li>
|
||||
<li>The 'port' attribute is REQUIRED and specifies the communications port to be used at the host. <note>The port is necessary since this specification assumes that DNS SRV lookups are not possible.</note></li>
|
||||
<li>The 'username' and 'password' attributes are OPTIONAL and are used as described below.</li>
|
||||
</ul>
|
||||
<p>A STUN server may require a username and password in order to accept STUN binding requests and/or STUN allocate requests. In this case, the XMPP server would typically generate a short-term authentication credential based on a private key shared with the STUN server. <note>Other implementations are possible, and long-term credentials could be used instead; see <cite>RFC 3489</cite> and <cite>rfc3489bis</cite> for details).</note></p>
|
||||
<example caption='XMPP Server Returns List With Credentials'><![CDATA[
|
||||
<iq type='result'
|
||||
from='shakespeare.lit'
|
||||
|
|
@ -113,7 +118,6 @@
|
|||
</stun>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The 'username' and 'password' attributes are OPTIONAL.</p>
|
||||
<p>An XMPP server MAY send an updated list of STUN servers by "pushing" the list to a client that has previously requested the list:</p>
|
||||
<example caption='List Push'><![CDATA[
|
||||
<iq type='set'
|
||||
|
|
@ -138,16 +142,16 @@
|
|||
<p>If an entity supports the STUN Server Discovery protocol, it MUST report that fact by including a service discovery feature of "http://www.xmpp.org/extensions/xep-0215.html#ns" &NSNOTE; in response to a &xep0030; information request:</p>
|
||||
<example caption="Service Discovery Information Request"><![CDATA[
|
||||
<iq type='get'
|
||||
from='romeo@montague.net/orchard'
|
||||
to='juliet@capulet.com/balcony'
|
||||
from='romeo@montague.lit/orchard'
|
||||
to='montague.lit'
|
||||
id='disco1'>
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<example caption="Service Discovery Information Response"><![CDATA[
|
||||
<iq type='result'
|
||||
from='juliet@capulet.com/balcony'
|
||||
to='romeo@montague.net/orchard'
|
||||
from='montague.lit'
|
||||
to='romeo@montague.lit/orchard'
|
||||
id='disco1'>
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||||
...
|
||||
|
|
|
|||
Loading…
Reference in New Issue