rtcweb K. Li
Internet-Draft Huawei Technologies
Intended status: Standards Track January 29, 2013
Expires: August 2, 2013
RTCWeb JSEP XMPP/Jingle Mapping
draft-li-rtcweb-jsep-xmpp-mapping-02
Abstract
This document proposes mapping message representations between RTCWeb
Javascript Session Establishment Protocol(JSEP) scheme and XMPP/
Jingle [XEP-0166] messaging scheme. Such a signaling mapping is
intended to enable Javascript to use XMPP/Jingle to establish a
session between two RTCWeb enabled browsers.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 2, 2013.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Li Expires August 2, 2013 [Page 1]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Architecture Overview . . . . . . . . . . . . . . . . . . . . 3
2.1. Architecture Model . . . . . . . . . . . . . . . . . . . . 3
2.2. Basic Session Flow . . . . . . . . . . . . . . . . . . . . 4
2.3. Overall Session Management . . . . . . . . . . . . . . . . 5
3. Media Setup . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Session Management . . . . . . . . . . . . . . . . . . . . 7
3.1.1. Initiate the Session . . . . . . . . . . . . . . . . . 7
3.1.2. Accept the Session . . . . . . . . . . . . . . . . . . 7
3.1.3. Terminate the Session . . . . . . . . . . . . . . . . 8
3.2. Media Management . . . . . . . . . . . . . . . . . . . . . 8
3.2.1. Add Media . . . . . . . . . . . . . . . . . . . . . . 8
3.2.2. Modify Media . . . . . . . . . . . . . . . . . . . . . 9
3.2.3. Remove Media . . . . . . . . . . . . . . . . . . . . . 9
3.2.4. Accept Media . . . . . . . . . . . . . . . . . . . . . 10
3.2.5. Reject Media . . . . . . . . . . . . . . . . . . . . . 10
3.3. Information Exchange . . . . . . . . . . . . . . . . . . . 11
3.3.1. Exchange the ICE . . . . . . . . . . . . . . . . . . . 11
3.3.2. Description Information . . . . . . . . . . . . . . . 11
3.3.3. Result . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3.4. Error . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4. Other Actions . . . . . . . . . . . . . . . . . . . . . . 12
4. Mapping between Jingle Message and JSEP API . . . . . . . . . 13
4.1. Map JSEP API to Jingle Message . . . . . . . . . . . . . . 13
4.2. Map Jingle Message to JSEP API . . . . . . . . . . . . . . 13
5. Mapping to SDP . . . . . . . . . . . . . . . . . . . . . . . . 14
6. Example Message Flows . . . . . . . . . . . . . . . . . . . . 15
6.1. Exchange Candidates . . . . . . . . . . . . . . . . . . . 15
6.2. Add Contents . . . . . . . . . . . . . . . . . . . . . . . 15
6.3. Exchange Description Information . . . . . . . . . . . . . 16
7. Security Considerations . . . . . . . . . . . . . . . . . . . 17
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
10. Normative References . . . . . . . . . . . . . . . . . . . . . 17
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18
Li Expires August 2, 2013 [Page 2]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
1. Introduction
In draft [I-D.ietf-rtcweb-jsep], it is mentioned that there are
several options for the signalling mechanisms: ROAP (see
[I-D.jennings-rtcweb-signaling]), SIP or XMPP/Jingle.
This document focuses on XMPP/Jingle and tries to explain how to use
JSEP and XMPP/Jingle to exchange session descriptions.
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. Architecture Overview
2.1. Architecture Model
In Figure 1, it shows the overall architecture. In the figure,
"Browser" is synonymous with "User Agent", and "Web Application" is
synonymous with "JavaScript".
Li Expires August 2, 2013 [Page 3]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
+----------------------+
| Web |
| |
| Server |
+----------------------+
/ \
/ \
Jingle / \ Jingle
/ \
/ \
/ \
+-------------+ +--------------+
| Web | | Web |
| Application | | Application |
+ ----------- + + ------------ +
^ ^
| SDP | SDP
| |
V (JSEP) V (JSEP)
+-------------+ +--------------+
| Offerer | | Answerer |
| | <====== Media =======> | |
| Browser | | Browser |
+-------------+ +--------------+
Figure 1: JSEP-XMPP/Jingle Mapping Architecture
2.2. Basic Session Flow
In Figure 2, it shows the basic Jingle session flow.
Li Expires August 2, 2013 [Page 4]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
Offerer Answerer
| |
| session-initiate |
|---------------------------->|
| ack |
|<----------------------------|
| session-accept |
|<----------------------------|
| ack |
|---------------------------->|
| RTCWeb Media Session |
|<===========================>|
| session-terminate |
|<----------------------------|
| ack |
|---------------------------->|
| |
Figure 2: Jingle Session Flow
2.3. Overall Session Management
In Figure 3, it shows the overall Jingle session management.
Li Expires August 2, 2013 [Page 5]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
o
|
| session-initiate
|
| +---------->--------------+
|/ |
PENDING o-----------------------+ |
| | content-accept, | |
| | content-add, | |
| | content-modify, | |
| | content-reject, | |
| | content-remove, | |
| | description-info, | |
\|/ | session-info, | |
| | transport-accept, | |
| | transport-info, | |
| | transport-reject, | |
| | transport-replace | |
| +-------------------+ |
| |
| session-accept \|/
| |
ACTIVE o-----------------------+ |
| | content-accept, | |
| | content-add, | |
| | content-modify, | |
| | content-reject, | |
| | content-remove, | |
| | description-info, | |
\|/ | session-info, | |
| | transport-accept, | |
| | transport-info, | |
| | transport-reject, | |
| | transport-replace | |
| +-------------------+ |
| |
+------------>--------------+
| | session-terminate
|
o ENDED
Figure 3: Jingle Overall Session Management
In Section 3, it introduces how JS clients could use the Jingle
actions to manage a session. The detailed descriptions of the Jingle
actions are defined in [XEP-0166].
Li Expires August 2, 2013 [Page 6]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
3. Media Setup
3.1. Session Management
3.1.1. Initiate the Session
To initiate a session, the initiator can create an offer, and send
the offer to the recipient by using Jingle "session-initiate" action.
The JSEP APIs are defined in [webrtc-api] and [I-D.ietf-rtcweb-jsep].
JSEP API:
OffererJS->OffererUA: pc = new PeerConnection();
OffererJS->OffererUA: pc.addStream(localStream, null);
OffererJS->OffererUA: offer = pc.createOffer(null);
Jingle message:
OffererJS->AnswererJS: <jingle action="session-initiate"/> .
After receiving the Jingle "session-initiate" action, the recipient
can parse the session information, and apply the supplied offer as
the remote description.
JSEP API:
AnswererJS->AnswererUA: pc.setRemoteDescription("offer",offer);
3.1.2. Accept the Session
If the recipient accepts a session, it can create an answer and send
back the answer by using Jingle "session-accept" action.
JSEP API:
AnswererJS->AnswererUA: peer.addStream(localStream, null);
AnswererJS->AnswererUA: answer = peer.createAnswer(offer, null);
Jingle message:
AnswererJS->OffererJS: <jingle action="session-accept"/>.
After receiving the Jingle "session-accept" action, the initiator can
parse the received answer and apply the supplied answer to the remote
Li Expires August 2, 2013 [Page 7]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
description.
JSEP API:
OffererJS->OffererUA: pc.setRemoteDescription("answer", answer);
3.1.3. Terminate the Session
To terminate a session, the initiator can close the peer connection
with the recipient by using Jingle "session-terminate" action.
JSEP API:
OffererJS->OffererUA: pc.close();
Jingle message:
OffererJS->AnswererJS: <jingle action="session-terminate"/>.
After receiving the Jingle "session-terminate" action, the recipient
can close the peer connection.
JSEP API:
AnswererJS->AnswererUA: peer.close();
3.2. Media Management
3.2.1. Add Media
To add media (e.g.video) to an existing session, the initiator can
use Jingle "content-add" action.
JSEP API:
OffererJS->OffererUA: pc.addStream(videoStream);
OffererJS->OffererUA: offer = pc.createOffer(null);
Jingle message:
OffererJS->AnswererJS: <jingle action="content-add"/>.
After receiving the Jingle "content-add" action, the recipient can
parse the received offer and set the remote description.
JSEP API:
Li Expires August 2, 2013 [Page 8]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);
3.2.2. Modify Media
To modify media (e.g.change audio to video) to an existing session,
the initiator can either use Jingle "content-modify" action, or use
combined Jingle "content-remove" action and "content-add" action.
JSEP API:
OffererJS->OffererUA: pc.removeStream(audioStream);
OffererJS->OffererUA: pc.addStream(videoStream);
Jingle message:
OffererJS->AnswererJS: <jingle action="content-modify"/>.
After receiving the Jingle "content-modify" action, the recipient can
parse the received offer and set the remote description.
JSEP API:
AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);
3.2.3. Remove Media
To remove media (e.g.video) to an existing session, the initiator can
use Jingle "content-remove" action.
JSEP API:
OffererJS->OffererUA: pc.removeStream(audioStream);
Jingle message:
OffererJS->AnswererJS: <jingle action="content-remove"/>.
After receiving the Jingle "content-remove" action, the recipient can
parse the received offer and set the remote description.
JSEP API:
AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);
Li Expires August 2, 2013 [Page 9]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
3.2.4. Accept Media
If the recipient accepts the "content-add" action to an existing
session from the initiator, recipient can create an answer and send
back the answer by using Jingle "content-accept" action.
JSEP API:
AnswererJS: offer = parseContentAdd(xmpp);
AnswererJS->AnswererUA: peer.createAnswer(offer,null);
Jingle message:
AnswererJS->OffererJS: <jingle action="content-accept"/>.
After receiving the Jingle "content-accept" action, the initiator can
parse the received answer and apply the received answer to the remote
description.
JSEP API:
OffererJS->OffererUA: peer.setRemoteDescription("answer", answer);
3.2.5. Reject Media
If the recipient rejects the "content-add" action to an existing
session from the initiator, recipient can send back answer by using
Jingle "content-reject" action.
JSEP API:
AnswererJS: offer = parseContentAdd(xmpp);
AnswererJS->AnswererUA: peer.createAnswer(offer,null);
Jingle message:
AnswererJS->OffererJS: <jingle action="content-reject"/>.
After receiving the Jingle "content-reject" action, the initiator can
parse the received answer and apply the received answer to the remote
description.
JSEP API:
OffererJS->OffererUA: peer.setRemoteDescription("answer", answer);
Li Expires August 2, 2013 [Page 10]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
3.3. Information Exchange
3.3.1. Exchange the ICE
To perform the ICE process, the initiator can start gathering or
update ICE address, and exchange the ICE candidates with the
recipient by using Jingle "transport-info" action.
JSEP API:
OffererJS->OffererUA: pc.startIce();
OffererJS->OffererUA: pc.updateIce();
Jingle message:
OffererJS->AnswererJS: <jingle action="transport-info"/>.
AnswererJS->OffererJS: <jingle action="transport-info"/>.
After receiving the Jingle "transport-info" action, the recipient can
parse the received ICE candidates and add remote candidate to the ICE
Agent.
JSEP API:
AnswererJS->AnswererUA: pc.addIceCandidate(candidate);
3.3.2. Description Information
To send informational hints about parameters related to an existing
session, for example, add new video sources to a call that already
has video, the initiator can indicate that by using Jingle
"description-info" action.
JSEP API:
OffererJS->OffererUA: pc.addStream(offererVideoStream2);
OffererJS->OffererUA: offer = pc.createOffer(null);
Jingle message:
OffererJS->AnswererJS: <jingle action="description-info"/>.
After receiving the Jingle "description-info" action, the recipient
parses the description information and sends back the acknowledgement
by using IQ stanza of "result" type. There is no mapped JSEP API for
Li Expires August 2, 2013 [Page 11]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
Jingle "description-info" action.
3.3.3. Result
To acknowledge the description information to an existing session
from the initiator, recipient can send back answer by using IQ stanza
of "result" type. See [RFC6120].
Jingle message:
AnswererJS->OffererJS: <iq type="result"/>.
After receiving the Jingle IQ stanza of "result" type, the recipient
can use the remote offer as an answer in the remote description.
JSEP API:
AnswererJS->AnswererUA: peer.setRemoteDescription("answer", offer);
3.3.4. Error
If there are errors occurred during an existing session, the
recipient can send back answer by using IQ stanza of "error" type.
See [RFC6120].
JSEP API:
AnswererJS->AnswererUA: peer.RTCPeerConnectionErrorCallback;
Jingle message:
AnswererJS->OffererJS: <iq type="error"/>.
After receiving the Jingle IQ stanza of "error" type, the initiate
can choose to close the peer connection due to the errors.
JSEP API:
OffererJS->OffererUA: pc.close();
3.4. Other Actions
TBD 1: do we have usage for the following actions: "security-info",
"session-info"?
TBD 2: do we need to redefine a transport method? If yes, we can use
"transport-replace", "transport-accept", "transport-reject".
Li Expires August 2, 2013 [Page 12]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
4. Mapping between Jingle Message and JSEP API
4.1. Map JSEP API to Jingle Message
When Offerer Javascript uses JSEP API to interact with Offerer User
Agent, it needs to map the JSEP API to Jingle message, to send it
Answerer JavaScript. In Figure 4, it shows the mapping table from
JSEP APIs to Jingle messages.
+--------------------------------+---------------------+
| JSEP API | Jingle Message |
+--------------------------------+---------------------+
| createOffer() | session-initiate |
+--------------------------------+---------------------+
| startIce() | transport-info |
+--------------------------------+---------------------+
| updateIce() | transport-info |
+--------------------------------+---------------------+
| createAnswer() | session-accept |
+--------------------------------+---------------------+
| close() | session-terminate |
+--------------------------------+---------------------+
| addStream() | content-add |
+--------------------------------+---------------------+
| removeStream(), addStream() | content-modify |
+--------------------------------+---------------------+
| removeStream() | content-remove |
+--------------------------------+---------------------+
| createAnswer() | content-accept |
+--------------------------------+---------------------+
| createOffer() | description-info |
+--------------------------------+---------------------+
| RTCPeerConnectionErrorCallback | iq "error" |
+--------------------------------+---------------------+
Figure 4: Map JSEP API to Jingle Message
4.2. Map Jingle Message to JSEP API
When Answerer Javascript receives Jingle message, it needs to map it
to JSEP API, and interacts with ANswerer User Agent. In Figure 5, it
shows the mapping table from JSEP APIs to Jingle messages.
Li Expires August 2, 2013 [Page 13]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
+---------------------+--------------------------+
| Jingle Message | JSEP API |
+---------------------+--------------------------+
| session-initiate | setRemoteDescription() |
+---------------------+--------------------------+
| transport-info | addIceCandidate() |
+---------------------+--------------------------+
| session-accept | setRemoteDescription() |
+---------------------+--------------------------+
| session-terminate | close() |
+---------------------+--------------------------+
| content-add | setRemoteDescription() |
+---------------------+--------------------------+
| content-modify | setRemoteDescription() |
+---------------------+--------------------------+
| content-remove | setRemoteDescription() |
+---------------------+--------------------------+
| content-accept | setRemoteDescription() |
+---------------------+--------------------------+
| description-info | setRemoteDescription() |
+---------------------+--------------------------+
| iq "error" | close() |
+---------------------+--------------------------+
Figure 5: Map Jingle Message to JSEP API
5. Mapping to SDP
In order to perform the media negotiation, PeerConnection SDP
Messages need to be converted into Jingle message and vice-versa.
The session description information included in Jingle message can be
mapped to SDP as defined in section 6 of [XEP-0167].
For example, consider a payload of 16-bit linear-encoded stereo audio
sampled at 16KHz associated with dynamic payload-type 96:
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
<payload-type id='96' name='speex' clockrate='16000'/> </description>
That Jingle-formatted information would be mapped to SDP as follows:
m=audio 9999 RTP/AVP 96a=rtpmap:96 speex/16000
Li Expires August 2, 2013 [Page 14]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
6. Example Message Flows
6.1. Exchange Candidates
In Figure 6, OffererJS uses Jingle "session-initiate" action to
initiate a session with AnswererJS, and uses Jingle "transport-info"
to exchange ICE candidates with AnswererJS. Then AnswererJS accepts
the session using Jingle "session-accept" action. After the media
session, OffererJS uses "session-terminate" action to terminate the
session, and AnswererJS acknowledges with IQ stanza of "result" type.
Offerer JS Answerer JS
| |
| <jingle action="session-initiate"/> |
|-------------------------------------->|
| |
| <jingle action="transport-info"/> |
|-------------------------------------->|
| |
| <jingle action="transport-info"/> |
|<--------------------------------------|
| |
| <jingle action="session-accept"/> |
|<--------------------------------------|
| |
| Media Session |
|<=====================================>|
| |
| <jingle action="session-terminate"/> |
|-------------------------------------->|
| |
| <iq type="result"/> |
|<--------------------------------------|
| |
Figure 6: Exchange Candidates
Message details go here...
6.2. Add Contents
In Figure 7, OffererJS uses Jingle "content-add" action to add video
media to an existing session. AnswererJS accepts that by using
Jingle "content-accept" action. For simplicity, candidate exchange
is not shown.
Li Expires August 2, 2013 [Page 15]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
Offerer JS Answerer JS
| |
| <jingle action="content-add"/> |
|-------------------------------------->|
| |
| <jingle action="content-accept"/> |
|<--------------------------------------|
| |
| Media Session |
|<=====================================>|
| |
Figure 7: Add Contents
Message details go here...
6.3. Exchange Description Information
In Figure 8, OffererJS uses Jingle "description-info" action to add
new video sources at the same time to a call that already has video.
AnswererJS also uses Jingle "description-info" action to indicate the
new sources to the remote side. After that, they uses IQ stanza of
"result" type to acknowledge each other.
Offerer JS Answerer JS
| |
| <jingle action="description-info"/> |
|-------------------------------------->|
| |
| <jingle action="description-info"/> |
|<--------------------------------------|
| |
| <iq type="result"/> |
|-------------------------------------->|
| |
| <iq type="result"/> |
|<--------------------------------------|
| |
| Media Session |
|<=====================================>|
| |
Figure 8: Exchange Description Information
Message details go here...
Li Expires August 2, 2013 [Page 16]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
7. Security Considerations
TBD.
8. IANA Considerations
This document requires no actions from IANA.
9. Acknowledgements
The author would like to thank Kiran Kumar, Bert greevenbosch, Justin
Uberti for the reviews and feedbacks.
10. Normative References
[I-D.ietf-rtcweb-jsep]
Uberti, J. and C. Jennings, "Javascript Session
Establishment Protocol", draft-ietf-rtcweb-jsep-02 (work
in progress), October 2012.
[I-D.jennings-rtcweb-signaling]
Jennings, C., Rosenberg, J., and R. Jesup, "RTCWeb Offer/
Answer Protocol (ROAP)",
draft-jennings-rtcweb-signaling-01 (work in progress),
October 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model
with Session Description Protocol (SDP)", RFC 3264,
June 2002.
[RFC6120] Saint-Andre, P., "Extensible Messaging and Presence
Protocol (XMPP): Core", RFC 6120, March 2011.
[XEP-0166]
XMPP Standards Foundation, "Jingle", Dec 2009.
[XEP-0167]
XMPP Standards Foundation, "Jingle RTP Sessions",
Dec 2009.
[webrtc-api]
W3C, "WebRTC 1.0: Real-time Communication Between
Li Expires August 2, 2013 [Page 17]
Internet-Draft RTCWeb-JSEP-XMPP-Mapping January 2013
Browsers", Jul 2012.
Author's Address
Kepeng Li
Huawei Technologies
Huawei Base, Bantian, Longgang, Shenzhen
P. R. China
Phone: +86-755-28971807
Email: likepeng@huawei.com
Li Expires August 2, 2013 [Page 18]