idnits 2.17.1
draft-li-rtcweb-jsep-xmpp-mapping-02.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The abstract seems to contain references ([XEP-0166]), which it
shouldn't. Please replace those with straight textual mentions of the
documents in question.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document doesn't use any RFC 2119 keywords, yet seems to have RFC
2119 boilerplate text.
-- The document date (January 29, 2013) is 4077 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: 'RFC3264' is defined on line 707, but no explicit
reference was found in the text
== Outdated reference: A later version (-26) exists of
draft-ietf-rtcweb-jsep-02
-- Possible downref: Non-RFC (?) normative reference: ref. 'XEP-0166'
-- Possible downref: Non-RFC (?) normative reference: ref. 'XEP-0167'
Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 3 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 rtcweb K. Li
3 Internet-Draft Huawei Technologies
4 Intended status: Standards Track January 29, 2013
5 Expires: August 2, 2013
7 RTCWeb JSEP XMPP/Jingle Mapping
8 draft-li-rtcweb-jsep-xmpp-mapping-02
10 Abstract
12 This document proposes mapping message representations between RTCWeb
13 Javascript Session Establishment Protocol(JSEP) scheme and XMPP/
14 Jingle [XEP-0166] messaging scheme. Such a signaling mapping is
15 intended to enable Javascript to use XMPP/Jingle to establish a
16 session between two RTCWeb enabled browsers.
18 Status of this Memo
20 This Internet-Draft is submitted in full conformance with the
21 provisions of BCP 78 and BCP 79.
23 Internet-Drafts are working documents of the Internet Engineering
24 Task Force (IETF). Note that other groups may also distribute
25 working documents as Internet-Drafts. The list of current Internet-
26 Drafts is at http://datatracker.ietf.org/drafts/current/.
28 Internet-Drafts are draft documents valid for a maximum of six months
29 and may be updated, replaced, or obsoleted by other documents at any
30 time. It is inappropriate to use Internet-Drafts as reference
31 material or to cite them other than as "work in progress."
33 This Internet-Draft will expire on August 2, 2013.
35 Copyright Notice
37 Copyright (c) 2013 IETF Trust and the persons identified as the
38 document authors. All rights reserved.
40 This document is subject to BCP 78 and the IETF Trust's Legal
41 Provisions Relating to IETF Documents
42 (http://trustee.ietf.org/license-info) in effect on the date of
43 publication of this document. Please review these documents
44 carefully, as they describe your rights and restrictions with respect
45 to this document. Code Components extracted from this document must
46 include Simplified BSD License text as described in Section 4.e of
47 the Trust Legal Provisions and are provided without warranty as
48 described in the Simplified BSD License.
50 Table of Contents
52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
53 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
54 2. Architecture Overview . . . . . . . . . . . . . . . . . . . . 3
55 2.1. Architecture Model . . . . . . . . . . . . . . . . . . . . 3
56 2.2. Basic Session Flow . . . . . . . . . . . . . . . . . . . . 4
57 2.3. Overall Session Management . . . . . . . . . . . . . . . . 5
58 3. Media Setup . . . . . . . . . . . . . . . . . . . . . . . . . 7
59 3.1. Session Management . . . . . . . . . . . . . . . . . . . . 7
60 3.1.1. Initiate the Session . . . . . . . . . . . . . . . . . 7
61 3.1.2. Accept the Session . . . . . . . . . . . . . . . . . . 7
62 3.1.3. Terminate the Session . . . . . . . . . . . . . . . . 8
63 3.2. Media Management . . . . . . . . . . . . . . . . . . . . . 8
64 3.2.1. Add Media . . . . . . . . . . . . . . . . . . . . . . 8
65 3.2.2. Modify Media . . . . . . . . . . . . . . . . . . . . . 9
66 3.2.3. Remove Media . . . . . . . . . . . . . . . . . . . . . 9
67 3.2.4. Accept Media . . . . . . . . . . . . . . . . . . . . . 10
68 3.2.5. Reject Media . . . . . . . . . . . . . . . . . . . . . 10
69 3.3. Information Exchange . . . . . . . . . . . . . . . . . . . 11
70 3.3.1. Exchange the ICE . . . . . . . . . . . . . . . . . . . 11
71 3.3.2. Description Information . . . . . . . . . . . . . . . 11
72 3.3.3. Result . . . . . . . . . . . . . . . . . . . . . . . . 12
73 3.3.4. Error . . . . . . . . . . . . . . . . . . . . . . . . 12
74 3.4. Other Actions . . . . . . . . . . . . . . . . . . . . . . 12
75 4. Mapping between Jingle Message and JSEP API . . . . . . . . . 13
76 4.1. Map JSEP API to Jingle Message . . . . . . . . . . . . . . 13
77 4.2. Map Jingle Message to JSEP API . . . . . . . . . . . . . . 13
78 5. Mapping to SDP . . . . . . . . . . . . . . . . . . . . . . . . 14
79 6. Example Message Flows . . . . . . . . . . . . . . . . . . . . 15
80 6.1. Exchange Candidates . . . . . . . . . . . . . . . . . . . 15
81 6.2. Add Contents . . . . . . . . . . . . . . . . . . . . . . . 15
82 6.3. Exchange Description Information . . . . . . . . . . . . . 16
83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17
84 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
85 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
86 10. Normative References . . . . . . . . . . . . . . . . . . . . . 17
87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18
89 1. Introduction
91 In draft [I-D.ietf-rtcweb-jsep], it is mentioned that there are
92 several options for the signalling mechanisms: ROAP (see
93 [I-D.jennings-rtcweb-signaling]), SIP or XMPP/Jingle.
95 This document focuses on XMPP/Jingle and tries to explain how to use
96 JSEP and XMPP/Jingle to exchange session descriptions.
98 1.1. Terminology
100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
102 document are to be interpreted as described in [RFC2119].
104 2. Architecture Overview
106 2.1. Architecture Model
108 In Figure 1, it shows the overall architecture. In the figure,
109 "Browser" is synonymous with "User Agent", and "Web Application" is
110 synonymous with "JavaScript".
112 +----------------------+
113 | Web |
114 | |
115 | Server |
116 +----------------------+
117 / \
118 / \
119 Jingle / \ Jingle
120 / \
121 / \
122 / \
123 +-------------+ +--------------+
124 | Web | | Web |
125 | Application | | Application |
126 + ----------- + + ------------ +
127 ^ ^
128 | SDP | SDP
129 | |
130 V (JSEP) V (JSEP)
131 +-------------+ +--------------+
132 | Offerer | | Answerer |
133 | | <====== Media =======> | |
134 | Browser | | Browser |
135 +-------------+ +--------------+
137 Figure 1: JSEP-XMPP/Jingle Mapping Architecture
139 2.2. Basic Session Flow
141 In Figure 2, it shows the basic Jingle session flow.
143 Offerer Answerer
144 | |
145 | session-initiate |
146 |---------------------------->|
147 | ack |
148 |<----------------------------|
149 | session-accept |
150 |<----------------------------|
151 | ack |
152 |---------------------------->|
153 | RTCWeb Media Session |
154 |<===========================>|
155 | session-terminate |
156 |<----------------------------|
157 | ack |
158 |---------------------------->|
159 | |
161 Figure 2: Jingle Session Flow
163 2.3. Overall Session Management
165 In Figure 3, it shows the overall Jingle session management.
167 o
168 |
169 | session-initiate
170 |
171 | +---------->--------------+
172 |/ |
173 PENDING o-----------------------+ |
174 | | content-accept, | |
175 | | content-add, | |
176 | | content-modify, | |
177 | | content-reject, | |
178 | | content-remove, | |
179 | | description-info, | |
180 \|/ | session-info, | |
181 | | transport-accept, | |
182 | | transport-info, | |
183 | | transport-reject, | |
184 | | transport-replace | |
185 | +-------------------+ |
186 | |
187 | session-accept \|/
188 | |
189 ACTIVE o-----------------------+ |
190 | | content-accept, | |
191 | | content-add, | |
192 | | content-modify, | |
193 | | content-reject, | |
194 | | content-remove, | |
195 | | description-info, | |
196 \|/ | session-info, | |
197 | | transport-accept, | |
198 | | transport-info, | |
199 | | transport-reject, | |
200 | | transport-replace | |
201 | +-------------------+ |
202 | |
203 +------------>--------------+
204 | | session-terminate
205 |
206 o ENDED
208 Figure 3: Jingle Overall Session Management
210 In Section 3, it introduces how JS clients could use the Jingle
211 actions to manage a session. The detailed descriptions of the Jingle
212 actions are defined in [XEP-0166].
214 3. Media Setup
216 3.1. Session Management
218 3.1.1. Initiate the Session
220 To initiate a session, the initiator can create an offer, and send
221 the offer to the recipient by using Jingle "session-initiate" action.
223 The JSEP APIs are defined in [webrtc-api] and [I-D.ietf-rtcweb-jsep].
225 JSEP API:
227 OffererJS->OffererUA: pc = new PeerConnection();
229 OffererJS->OffererUA: pc.addStream(localStream, null);
231 OffererJS->OffererUA: offer = pc.createOffer(null);
233 Jingle message:
235 OffererJS->AnswererJS: .
237 After receiving the Jingle "session-initiate" action, the recipient
238 can parse the session information, and apply the supplied offer as
239 the remote description.
241 JSEP API:
243 AnswererJS->AnswererUA: pc.setRemoteDescription("offer",offer);
245 3.1.2. Accept the Session
247 If the recipient accepts a session, it can create an answer and send
248 back the answer by using Jingle "session-accept" action.
250 JSEP API:
252 AnswererJS->AnswererUA: peer.addStream(localStream, null);
254 AnswererJS->AnswererUA: answer = peer.createAnswer(offer, null);
256 Jingle message:
258 AnswererJS->OffererJS: .
260 After receiving the Jingle "session-accept" action, the initiator can
261 parse the received answer and apply the supplied answer to the remote
262 description.
264 JSEP API:
266 OffererJS->OffererUA: pc.setRemoteDescription("answer", answer);
268 3.1.3. Terminate the Session
270 To terminate a session, the initiator can close the peer connection
271 with the recipient by using Jingle "session-terminate" action.
273 JSEP API:
275 OffererJS->OffererUA: pc.close();
277 Jingle message:
279 OffererJS->AnswererJS: .
281 After receiving the Jingle "session-terminate" action, the recipient
282 can close the peer connection.
284 JSEP API:
286 AnswererJS->AnswererUA: peer.close();
288 3.2. Media Management
290 3.2.1. Add Media
292 To add media (e.g.video) to an existing session, the initiator can
293 use Jingle "content-add" action.
295 JSEP API:
297 OffererJS->OffererUA: pc.addStream(videoStream);
299 OffererJS->OffererUA: offer = pc.createOffer(null);
301 Jingle message:
303 OffererJS->AnswererJS: .
305 After receiving the Jingle "content-add" action, the recipient can
306 parse the received offer and set the remote description.
308 JSEP API:
310 AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);
312 3.2.2. Modify Media
314 To modify media (e.g.change audio to video) to an existing session,
315 the initiator can either use Jingle "content-modify" action, or use
316 combined Jingle "content-remove" action and "content-add" action.
318 JSEP API:
320 OffererJS->OffererUA: pc.removeStream(audioStream);
322 OffererJS->OffererUA: pc.addStream(videoStream);
324 Jingle message:
326 OffererJS->AnswererJS: .
328 After receiving the Jingle "content-modify" action, the recipient can
329 parse the received offer and set the remote description.
331 JSEP API:
333 AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);
335 3.2.3. Remove Media
337 To remove media (e.g.video) to an existing session, the initiator can
338 use Jingle "content-remove" action.
340 JSEP API:
342 OffererJS->OffererUA: pc.removeStream(audioStream);
344 Jingle message:
346 OffererJS->AnswererJS: .
348 After receiving the Jingle "content-remove" action, the recipient can
349 parse the received offer and set the remote description.
351 JSEP API:
353 AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);
355 3.2.4. Accept Media
357 If the recipient accepts the "content-add" action to an existing
358 session from the initiator, recipient can create an answer and send
359 back the answer by using Jingle "content-accept" action.
361 JSEP API:
363 AnswererJS: offer = parseContentAdd(xmpp);
365 AnswererJS->AnswererUA: peer.createAnswer(offer,null);
367 Jingle message:
369 AnswererJS->OffererJS: .
371 After receiving the Jingle "content-accept" action, the initiator can
372 parse the received answer and apply the received answer to the remote
373 description.
375 JSEP API:
377 OffererJS->OffererUA: peer.setRemoteDescription("answer", answer);
379 3.2.5. Reject Media
381 If the recipient rejects the "content-add" action to an existing
382 session from the initiator, recipient can send back answer by using
383 Jingle "content-reject" action.
385 JSEP API:
387 AnswererJS: offer = parseContentAdd(xmpp);
389 AnswererJS->AnswererUA: peer.createAnswer(offer,null);
391 Jingle message:
393 AnswererJS->OffererJS: .
395 After receiving the Jingle "content-reject" action, the initiator can
396 parse the received answer and apply the received answer to the remote
397 description.
399 JSEP API:
401 OffererJS->OffererUA: peer.setRemoteDescription("answer", answer);
403 3.3. Information Exchange
405 3.3.1. Exchange the ICE
407 To perform the ICE process, the initiator can start gathering or
408 update ICE address, and exchange the ICE candidates with the
409 recipient by using Jingle "transport-info" action.
411 JSEP API:
413 OffererJS->OffererUA: pc.startIce();
415 OffererJS->OffererUA: pc.updateIce();
417 Jingle message:
419 OffererJS->AnswererJS: .
421 AnswererJS->OffererJS: .
423 After receiving the Jingle "transport-info" action, the recipient can
424 parse the received ICE candidates and add remote candidate to the ICE
425 Agent.
427 JSEP API:
429 AnswererJS->AnswererUA: pc.addIceCandidate(candidate);
431 3.3.2. Description Information
433 To send informational hints about parameters related to an existing
434 session, for example, add new video sources to a call that already
435 has video, the initiator can indicate that by using Jingle
436 "description-info" action.
438 JSEP API:
440 OffererJS->OffererUA: pc.addStream(offererVideoStream2);
442 OffererJS->OffererUA: offer = pc.createOffer(null);
444 Jingle message:
446 OffererJS->AnswererJS: .
448 After receiving the Jingle "description-info" action, the recipient
449 parses the description information and sends back the acknowledgement
450 by using IQ stanza of "result" type. There is no mapped JSEP API for
451 Jingle "description-info" action.
453 3.3.3. Result
455 To acknowledge the description information to an existing session
456 from the initiator, recipient can send back answer by using IQ stanza
457 of "result" type. See [RFC6120].
459 Jingle message:
461 AnswererJS->OffererJS: .
463 After receiving the Jingle IQ stanza of "result" type, the recipient
464 can use the remote offer as an answer in the remote description.
466 JSEP API:
468 AnswererJS->AnswererUA: peer.setRemoteDescription("answer", offer);
470 3.3.4. Error
472 If there are errors occurred during an existing session, the
473 recipient can send back answer by using IQ stanza of "error" type.
474 See [RFC6120].
476 JSEP API:
478 AnswererJS->AnswererUA: peer.RTCPeerConnectionErrorCallback;
480 Jingle message:
482 AnswererJS->OffererJS: .
484 After receiving the Jingle IQ stanza of "error" type, the initiate
485 can choose to close the peer connection due to the errors.
487 JSEP API:
489 OffererJS->OffererUA: pc.close();
491 3.4. Other Actions
493 TBD 1: do we have usage for the following actions: "security-info",
494 "session-info"?
496 TBD 2: do we need to redefine a transport method? If yes, we can use
497 "transport-replace", "transport-accept", "transport-reject".
499 4. Mapping between Jingle Message and JSEP API
501 4.1. Map JSEP API to Jingle Message
503 When Offerer Javascript uses JSEP API to interact with Offerer User
504 Agent, it needs to map the JSEP API to Jingle message, to send it
505 Answerer JavaScript. In Figure 4, it shows the mapping table from
506 JSEP APIs to Jingle messages.
508 +--------------------------------+---------------------+
509 | JSEP API | Jingle Message |
510 +--------------------------------+---------------------+
511 | createOffer() | session-initiate |
512 +--------------------------------+---------------------+
513 | startIce() | transport-info |
514 +--------------------------------+---------------------+
515 | updateIce() | transport-info |
516 +--------------------------------+---------------------+
517 | createAnswer() | session-accept |
518 +--------------------------------+---------------------+
519 | close() | session-terminate |
520 +--------------------------------+---------------------+
521 | addStream() | content-add |
522 +--------------------------------+---------------------+
523 | removeStream(), addStream() | content-modify |
524 +--------------------------------+---------------------+
525 | removeStream() | content-remove |
526 +--------------------------------+---------------------+
527 | createAnswer() | content-accept |
528 +--------------------------------+---------------------+
529 | createOffer() | description-info |
530 +--------------------------------+---------------------+
531 | RTCPeerConnectionErrorCallback | iq "error" |
532 +--------------------------------+---------------------+
534 Figure 4: Map JSEP API to Jingle Message
536 4.2. Map Jingle Message to JSEP API
538 When Answerer Javascript receives Jingle message, it needs to map it
539 to JSEP API, and interacts with ANswerer User Agent. In Figure 5, it
540 shows the mapping table from JSEP APIs to Jingle messages.
542 +---------------------+--------------------------+
543 | Jingle Message | JSEP API |
544 +---------------------+--------------------------+
545 | session-initiate | setRemoteDescription() |
546 +---------------------+--------------------------+
547 | transport-info | addIceCandidate() |
548 +---------------------+--------------------------+
549 | session-accept | setRemoteDescription() |
550 +---------------------+--------------------------+
551 | session-terminate | close() |
552 +---------------------+--------------------------+
553 | content-add | setRemoteDescription() |
554 +---------------------+--------------------------+
555 | content-modify | setRemoteDescription() |
556 +---------------------+--------------------------+
557 | content-remove | setRemoteDescription() |
558 +---------------------+--------------------------+
559 | content-accept | setRemoteDescription() |
560 +---------------------+--------------------------+
561 | description-info | setRemoteDescription() |
562 +---------------------+--------------------------+
563 | iq "error" | close() |
564 +---------------------+--------------------------+
566 Figure 5: Map Jingle Message to JSEP API
568 5. Mapping to SDP
570 In order to perform the media negotiation, PeerConnection SDP
571 Messages need to be converted into Jingle message and vice-versa.
573 The session description information included in Jingle message can be
574 mapped to SDP as defined in section 6 of [XEP-0167].
576 For example, consider a payload of 16-bit linear-encoded stereo audio
577 sampled at 16KHz associated with dynamic payload-type 96:
579
580
582 That Jingle-formatted information would be mapped to SDP as follows:
584 m=audio 9999 RTP/AVP 96a=rtpmap:96 speex/16000
586 6. Example Message Flows
588 6.1. Exchange Candidates
590 In Figure 6, OffererJS uses Jingle "session-initiate" action to
591 initiate a session with AnswererJS, and uses Jingle "transport-info"
592 to exchange ICE candidates with AnswererJS. Then AnswererJS accepts
593 the session using Jingle "session-accept" action. After the media
594 session, OffererJS uses "session-terminate" action to terminate the
595 session, and AnswererJS acknowledges with IQ stanza of "result" type.
597 Offerer JS Answerer JS
598 | |
599 | |
600 |-------------------------------------->|
601 | |
602 | |
603 |-------------------------------------->|
604 | |
605 | |
606 |<--------------------------------------|
607 | |
608 | |
609 |<--------------------------------------|
610 | |
611 | Media Session |
612 |<=====================================>|
613 | |
614 | |
615 |-------------------------------------->|
616 | |
617 | |
618 |<--------------------------------------|
619 | |
621 Figure 6: Exchange Candidates
623 Message details go here...
625 6.2. Add Contents
627 In Figure 7, OffererJS uses Jingle "content-add" action to add video
628 media to an existing session. AnswererJS accepts that by using
629 Jingle "content-accept" action. For simplicity, candidate exchange
630 is not shown.
632 Offerer JS Answerer JS
633 | |
634 | |
635 |-------------------------------------->|
636 | |
637 | |
638 |<--------------------------------------|
639 | |
640 | Media Session |
641 |<=====================================>|
642 | |
644 Figure 7: Add Contents
646 Message details go here...
648 6.3. Exchange Description Information
650 In Figure 8, OffererJS uses Jingle "description-info" action to add
651 new video sources at the same time to a call that already has video.
652 AnswererJS also uses Jingle "description-info" action to indicate the
653 new sources to the remote side. After that, they uses IQ stanza of
654 "result" type to acknowledge each other.
656 Offerer JS Answerer JS
657 | |
658 | |
659 |-------------------------------------->|
660 | |
661 | |
662 |<--------------------------------------|
663 | |
664 | |
665 |-------------------------------------->|
666 | |
667 | |
668 |<--------------------------------------|
669 | |
670 | Media Session |
671 |<=====================================>|
672 | |
674 Figure 8: Exchange Description Information
676 Message details go here...
678 7. Security Considerations
680 TBD.
682 8. IANA Considerations
684 This document requires no actions from IANA.
686 9. Acknowledgements
688 The author would like to thank Kiran Kumar, Bert greevenbosch, Justin
689 Uberti for the reviews and feedbacks.
691 10. Normative References
693 [I-D.ietf-rtcweb-jsep]
694 Uberti, J. and C. Jennings, "Javascript Session
695 Establishment Protocol", draft-ietf-rtcweb-jsep-02 (work
696 in progress), October 2012.
698 [I-D.jennings-rtcweb-signaling]
699 Jennings, C., Rosenberg, J., and R. Jesup, "RTCWeb Offer/
700 Answer Protocol (ROAP)",
701 draft-jennings-rtcweb-signaling-01 (work in progress),
702 October 2011.
704 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
705 Requirement Levels", BCP 14, RFC 2119, March 1997.
707 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model
708 with Session Description Protocol (SDP)", RFC 3264,
709 June 2002.
711 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence
712 Protocol (XMPP): Core", RFC 6120, March 2011.
714 [XEP-0166]
715 XMPP Standards Foundation, "Jingle", Dec 2009.
717 [XEP-0167]
718 XMPP Standards Foundation, "Jingle RTP Sessions",
719 Dec 2009.
721 [webrtc-api]
722 W3C, "WebRTC 1.0: Real-time Communication Between
723 Browsers", Jul 2012.
725 Author's Address
727 Kepeng Li
728 Huawei Technologies
729 Huawei Base, Bantian, Longgang, Shenzhen
730 P. R. China
732 Phone: +86-755-28971807
733 Email: likepeng@huawei.com