From 2a71e1626e48b5f6890a55f8b70ed6ddbdf08b31 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Thu, 18 Dec 2008 23:00:03 +0000 Subject: [PATCH] bandwidth, encryption, etc. git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2580 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0167.xml | 266 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 178 insertions(+), 88 deletions(-) diff --git a/xep-0167.xml b/xep-0167.xml index 45499c32..926fcea3 100644 --- a/xep-0167.xml +++ b/xep-0167.xml @@ -17,10 +17,12 @@ XMPP Core XEP-0166 + RFC 3550 - NOT_YET_ASSIGNED + N/A + jingle &scottlu; &stpeter; &seanegan; @@ -28,11 +30,13 @@ &diana; 0.25 - 2008-12-16 + 2008-12-18 psa
    -
  • Added optional bandwidth attribute.
    • +
  • Refactored encryption syntax.
    • +
  • Added optional bandwidth element.
    • +
  • Added example of description-info action for modifying application parameters.
 @@ -258,7 +262,7 @@ ]]>

The &DESCRIPTION; element is intended to be a child of a Jingle &CONTENT; element as specified in XEP-0166.

The &DESCRIPTION; element MUST possess a 'media' attribute that specifies the media type, such as "audio" or "video", where the media type SHOULD be as registered at &ianamedia;.

-

The &DESCRIPTION; element MAY possess a 'bandwidth' attribute that specifies the "session bandwidth" as described in Section 6.2 of RFC 3550, measured in kilobits per second as described in Section 5.2 of RFC 4566.

+

After inclusion of one or more &PAYLOADTYPE; child elements, the &DESCRIPTION; element MAY also contain a <bandwidth/> element that specifies the allowable or preferred bandwidth for use by this application type. The 'type' attribute of the <bandwidth/> element SHOULD be a value for the SDP "bwtype" parameter as listed in the &ianasdp;. For RTP sessions, often the <bandwidth/> element will specify the "session bandwidth" as described in Section 6.2 of RFC 3550, measured in kilobits per second as described in Section 5.2 of RFC 4566.

The encodings SHOULD be provided in order of preference by placing the most-preferred payload type as the first &PAYLOADTYPE; child of the &DESCRIPTION; element and the least-preferred payload type as the last child.

The allowable attributes of the &PAYLOADTYPE; element are as follows:

@@ -335,20 +339,20 @@ Initiator Responder ]]>

When the initiator sends a session-initiate stanza to the responder, the &DESCRIPTION; element includes all of the payload types that the initiator can send and/or receive for Jingle RTP, each one encapsulated in a separate &PAYLOADTYPE; element (the rules specified in &rfc3264; SHOULD be followed regarding inclusion of payload types).

- + - + @@ -358,24 +362,24 @@ Initiator Responder ]]>

Upon receiving the session-initiate stanza, the responder determines whether it can proceed with the negotiation. The general Jingle error cases are specified in XEP-0166 and illustrated in the Scenarios section of this document.

-

If there is no error, the responder acknowledges the session initiation request.

+

If there is no immediate error, the responder acknowledges the session initiation request.

]]>

After successful transport negotiation (not shown here), the responder accepts the session by sending a session-accept action to the initiator. The session-accept SHOULD include a subset of the payload types sent by the initiator, i.e., a list of the offered payload types that the responder can send and/or receive. The list that the responder sends SHOULD retain the ID numbers specified by the initiator. The order of the &PAYLOADTYPE; elements indicates the responder's preferences, with the most-preferred types first.

In the following example, we imagine that the responder supports Speex at clockrate of 8000 but not 16000, G729, and PCMA but not PMCU. Therefore the responder returns only two payload types (since PMCA was not offered).

@@ -401,9 +405,9 @@ Initiator Responder ]]>

And the initiator acknowledges session acceptance:

]]>

The initiator and responder would then exchange media using any of the codecs that meet the following criteria:

@@ -464,8 +468,8 @@ a=fmtp:96 vbr=on;cng=on - - + + @@ -476,7 +480,7 @@ a=fmtp:96 vbr=on;cng=on @@ -498,8 +502,8 @@ delivery-method=inline; configuration=somebase16string;

&rfc3711; defines the Secure Real-time Transport Protocol, and &rfc4568; defines the SDP "crypto" attribute for signalling and negotiating the use of SRTP in the context of offer-answer protocols such as SIP. To enable the use of SRTP and gatewaying to non-XMPP technologies that make use of the "crypto" SDP attribute, we define a corresponding <crypto/> element qualified by the 'urn:xmpp:jingle:apps:rtp:0' namespace.

-

If the initiator wishes to use SRTP, the session-initiate MUST include at least one <crypto/> element and MAY include multiple instances of the element. The <crypto/> element MUST be a child of the <description/> element.

-

The XML attributes of the <crypto/> element are as follows:

+

If the initiator wishes to use SRTP, the session-initiate stanza MUST include an <encryption/> element, which MUST contain at least one <crypto/> element and MAY include multiple instances of the <crypto/> element. The <encryption/> element MUST be a child of the <description/> element. If the initiator requires the session to be encrypted, the <encryption/> element MUST include a 'required' attribute whose logical value is TRUE and whose lexical value is "true" or "1" &BOOLEANNOTE;, where this attribute defaults to a logical value of FALSE (i.e., a lexical value of "false" or "0").

+

The <crypto/> element is defined as empty (i.e., not containing any child elements); the XML attributes of the <crypto/> element are as follows:

  • crypto-suite -- this maps to the SDP "crypto-suite" parameter and has the same semantics (i.e., it is an identifier that describes the encryption and authentication algorithms).
  • key-params -- this maps to the SDP "key-params" parameter and has the same semantics (i.e., it provides one or more sets of keying material for the crypto-suite in question).
    • @@ -508,18 +512,22 @@ delivery-method=inline; configuration=somebase16string;

An example follows.

+ + + ]]> -

The mapping to SDP is as follows.

+

The mapping of to SDP is as follows.

-

When the responder receives a session-initiate action containing one or more instances of the <crypto/> element, it MUST either accept one of the <crypto/> elements or reject the offer by sending a session-terminate action with a Jingle reason of <general-error/> and an RTP-specific condition of <invalid-crypto/>; see the Scenarios section of this document for examples.

+

When the responder receives a session-initiate action containing an <encryption/> element, the responder MUST either (1) accept the offer by denoting one of the <crypto/> elements as acceptable (it does this by mirroring that <crypto/> element in its session acceptance) or (2) reject the offer by sending a session-terminate action with a Jingle reason of <security-error/> and an RTP-specific condition of <invalid-crypto/>.

+

If the responder requires encryption but the initiator did not include an <encryption/> element in its offer, the responder MUST reject the offer by sending a session-terminate action with a Jingle reason of <security-error/> and an RTP-specific condition of <crypto-required/>.

+

If the initiator requires encryption but the responder does not include an <encryption/> element in its session acceptance, the initiator MUST terminate the session with a Jingle reason of <security-error/> and an RTP-specific condition of <crypto-required/>.

 @@ -551,13 +559,13 @@ delivery-method=inline; configuration=somebase16string; - + @@ -565,26 +573,26 @@ delivery-method=inline; configuration=somebase16string; ]]> ]]> @@ -592,13 +600,13 @@ delivery-method=inline; configuration=somebase16string; ]]> @@ -607,20 +615,45 @@ delivery-method=inline; configuration=somebase16string; + +

Before or during an RTP session, either party can share suggested application parameters with the other party by sending a Jingle stanza with an action of "description-info". The stanza shall contain only a &DESCRIPTION; element, which specifies suggested parameters for a given application type (e.g., a change to the height and width for display of a video stream). An example follows.

+ + + + + + + + + + + + + ]]> +

The description-info stanza SHOULD include only the suggested or modified information, not the complete set of application parameters (if those parameters have not changed). Furthermore, the data provided is purely advisory; the session SHOULD NOT fail if the receving party cannot adjust its parameters accordingly.

+ +

If an entity supports Jingle RTP session, it MUST advertise that fact by returning a feature of "urn:xmpp:jingle:apps:rtp:0" &VNOTE; in response to &xep0030; information requests.

]]> ... @@ -688,13 +721,13 @@ Romeo Juliet type='result'/> ]]> @@ -792,13 +825,13 @@ Romeo Juliet type='result'/> ]]> @@ -931,18 +964,20 @@ Romeo Juliet - + + + ]]> -

To signal that the initiator wishes to use SRTP, the initiator's client includes keying material.

+

To signal that the initiator wishes to use SRTP, the initiator's client includes keying material via the <encryption/> element (with one set of keying material per <crypto/> element). Here the initiator signals that encryption is mandatory via the 'required' attribute.

The responder immediately acknowledges the session initiation request.

@@ -968,13 +1003,13 @@ Romeo Juliet ]]> @@ -1001,11 +1036,13 @@ Romeo Juliet - + + + - - + + @@ -1362,6 +1399,7 @@ Romeo Juliet + 768000 @@ -1375,13 +1413,13 @@ Romeo Juliet type='result'/> ]]> @@ -1461,13 +1499,13 @@ Romeo Juliet

The parties now begin to exchange media. In this case they would exchange audio using the Speex codec at a clockrate of 8000 since that is the highest-priority codec for the responder (as determined by the XML order of the &PAYLOADTYPE; children).

The parties chat for a while. Eventually Juliet wants to get her hair in order so she puts Romeo on hold.

@@ -1481,13 +1519,13 @@ Romeo Juliet ]]>

Juliet returns so she informs Romeo that she is actively engaged in the call again.

@@ -1513,14 +1551,15 @@ Romeo Juliet - - + + + 768000 @@ -1546,13 +1585,14 @@ Romeo Juliet - - + + + 768000 @@ -1566,8 +1606,35 @@ Romeo Juliet to='romeo@montague.lit/orchard' type='result'/> ]]> -

The media session proceeds. Now they would exchange both audio and video, where the audio is exchanged via the Speex codec at a clockrate of 8000 and the video is exchanged using the Theora codec with a height of 720 pixels, a width of 1280 pixels, and so on.

+

The media session proceeds. Now they would exchange both audio and video, where the audio is exchanged via the Speex codec at a clockrate of 8000 and the video is exchanged using the Theora codec with a height of 600 pixels, a width of 800 pixels, and so on.

The parties can continue the session as long as desired.

+

Other events might occur throughout the life of the session. For example, one of the parties might want to tweak the video parameters using a description-info action.

+ + + + + + + + + + + + 768000 + + + + + ]]> +

Eventually, one of the parties terminates the session.

- + maxOccurs='1'/> + + + + + + + + + @@ -1708,6 +1789,15 @@ Romeo Juliet + + + + + + -

Thanks to Milton Chen, Olivier Crête, Tim Julien, Steffen Larsen, Jeff Muller, Mike Ruprecht, and Paul Witty for their feedback.

+

Thanks to Milton Chen, Paul Chitescu, Olivier Crête, Tim Julien, Steffen Larsen, Jeff Muller, Mike Ruprecht, Justin Uberti, and Paul Witty for their feedback.