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