--- 1/draft-ietf-rtcweb-jsep-04.txt 2013-10-21 17:16:19.552901828 -0700 +++ 2/draft-ietf-rtcweb-jsep-05.txt 2013-10-21 17:16:19.644904205 -0700 @@ -1,19 +1,19 @@ Network Working Group J. Uberti Internet-Draft Google Intended status: Standards Track C. Jennings -Expires: March 22, 2014 Cisco - September 18, 2013 +Expires: April 25, 2014 Cisco + October 22, 2013 Javascript Session Establishment Protocol - draft-ietf-rtcweb-jsep-04 + draft-ietf-rtcweb-jsep-05 Abstract This document describes the mechanisms for allowing a Javascript application to control the signaling plane of a multimedia session via the interface specified in the W3C RTCPeerConnection API, and discusses how this relates to existing signaling protocols. Status of This Memo @@ -23,21 +23,21 @@ 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 March 22, 2014. + This Internet-Draft will expire on April 25, 2014. 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 @@ -61,68 +61,70 @@ 3.4.1. ICE Candidate Trickling . . . . . . . . . . . . . . . 10 3.4.1.1. ICE Candidate Format . . . . . . . . . . . . . . 10 3.5. Interactions With Forking . . . . . . . . . . . . . . . . 11 3.5.1. Sequential Forking . . . . . . . . . . . . . . . . . 11 3.5.2. Parallel Forking . . . . . . . . . . . . . . . . . . 12 3.6. Session Rehydration . . . . . . . . . . . . . . . . . . . 13 4. Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1. Methods . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1.1. createOffer . . . . . . . . . . . . . . . . . . . . . 14 4.1.2. createAnswer . . . . . . . . . . . . . . . . . . . . 15 - 4.1.3. SessionDescriptionType . . . . . . . . . . . . . . . 15 + 4.1.3. SessionDescriptionType . . . . . . . . . . . . . . . 16 4.1.3.1. Use of Provisional Answers . . . . . . . . . . . 16 4.1.3.2. Rollback . . . . . . . . . . . . . . . . . . . . 17 - 4.1.4. setLocalDescription . . . . . . . . . . . . . . . . . 17 + 4.1.4. setLocalDescription . . . . . . . . . . . . . . . . . 18 4.1.5. setRemoteDescription . . . . . . . . . . . . . . . . 18 - 4.1.6. localDescription . . . . . . . . . . . . . . . . . . 18 - 4.1.7. remoteDescription . . . . . . . . . . . . . . . . . . 18 + 4.1.6. localDescription . . . . . . . . . . . . . . . . . . 19 + 4.1.7. remoteDescription . . . . . . . . . . . . . . . . . . 19 4.1.8. updateIce . . . . . . . . . . . . . . . . . . . . . . 19 4.1.9. addIceCandidate . . . . . . . . . . . . . . . . . . . 19 - 5. SDP Interaction Procedures . . . . . . . . . . . . . . . . . 19 - 5.1. SDP Requirements Overview . . . . . . . . . . . . . . . . 19 - 5.2. Constructing an Offer . . . . . . . . . . . . . . . . . . 21 - 5.2.1. Initial Offers . . . . . . . . . . . . . . . . . . . 21 - 5.2.2. Subsequent Offers . . . . . . . . . . . . . . . . . . 25 - 5.2.3. Constraints Handling . . . . . . . . . . . . . . . . 26 - 5.2.3.1. OfferToReceiveAudio . . . . . . . . . . . . . . . 26 - 5.2.3.2. OfferToReceiveVideo . . . . . . . . . . . . . . . 27 - 5.2.3.3. VoiceActivityDetection . . . . . . . . . . . . . 27 - 5.2.3.4. IceRestart . . . . . . . . . . . . . . . . . . . 27 - 5.3. Generating an Answer . . . . . . . . . . . . . . . . . . 27 - 5.3.1. Initial Answers . . . . . . . . . . . . . . . . . . . 27 - 5.3.2. Subsequent Answers . . . . . . . . . . . . . . . . . 31 - 5.3.3. Constraints Handling . . . . . . . . . . . . . . . . 31 - 5.4. Parsing an Offer . . . . . . . . . . . . . . . . . . . . 31 - 5.5. Parsing an Answer . . . . . . . . . . . . . . . . . . . . 31 - 5.6. Applying a Local Description . . . . . . . . . . . . . . 31 - 5.7. Applying a Remote Description . . . . . . . . . . . . . . 31 - - 6. Configurable SDP Parameters . . . . . . . . . . . . . . . . . 31 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 33 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 - 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 33 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 33 - 10.2. Informative References . . . . . . . . . . . . . . . . . 35 - Appendix A. JSEP Implementation Examples . . . . . . . . . . . . 36 - A.1. Example API Flows . . . . . . . . . . . . . . . . . . . . 36 - A.1.1. Call using ROAP . . . . . . . . . . . . . . . . . . . 36 - A.1.2. Call using XMPP . . . . . . . . . . . . . . . . . . . 37 - A.1.3. Adding video to a call, using XMPP . . . . . . . . . 38 - A.1.4. Simultaneous add of video streams, using XMPP . . . . 39 - A.1.5. Call using SIP . . . . . . . . . . . . . . . . . . . 40 - A.1.6. Handling early media (e.g. 1-800-GO FEDEX), using SIP 40 - A.2. Example Session Descriptions . . . . . . . . . . . . . . 41 - A.2.1. createOffer . . . . . . . . . . . . . . . . . . . . . 41 - A.2.2. createAnswer . . . . . . . . . . . . . . . . . . . . 43 - Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 44 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 + 5. SDP Interaction Procedures . . . . . . . . . . . . . . . . . 20 + 5.1. Requirements Overview . . . . . . . . . . . . . . . . . . 20 + 5.1.1. Implementation Requirements . . . . . . . . . . . . . 20 + 5.1.2. Usage Requirements . . . . . . . . . . . . . . . . . 21 + 5.2. Constructing an Offer . . . . . . . . . . . . . . . . . . 22 + 5.2.1. Initial Offers . . . . . . . . . . . . . . . . . . . 22 + 5.2.2. Subsequent Offers . . . . . . . . . . . . . . . . . . 26 + 5.2.3. Constraints Handling . . . . . . . . . . . . . . . . 28 + 5.2.3.1. OfferToReceiveAudio . . . . . . . . . . . . . . . 28 + 5.2.3.2. OfferToReceiveVideo . . . . . . . . . . . . . . . 28 + 5.2.3.3. VoiceActivityDetection . . . . . . . . . . . . . 28 + 5.2.3.4. IceRestart . . . . . . . . . . . . . . . . . . . 29 + 5.3. Generating an Answer . . . . . . . . . . . . . . . . . . 29 + 5.3.1. Initial Answers . . . . . . . . . . . . . . . . . . . 29 + 5.3.2. Subsequent Answers . . . . . . . . . . . . . . . . . 33 + 5.3.3. Constraints Handling . . . . . . . . . . . . . . . . 33 + 5.4. Parsing an Offer . . . . . . . . . . . . . . . . . . . . 33 + 5.5. Parsing an Answer . . . . . . . . . . . . . . . . . . . . 33 + 5.6. Applying a Local Description . . . . . . . . . . . . . . 33 + 5.7. Applying a Remote Description . . . . . . . . . . . . . . 33 + 6. Configurable SDP Parameters . . . . . . . . . . . . . . . . . 33 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 34 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 34 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 35 + 10.2. Informative References . . . . . . . . . . . . . . . . . 37 + Appendix A. JSEP Implementation Examples . . . . . . . . . . . . 38 + A.1. Example API Flows . . . . . . . . . . . . . . . . . . . . 38 + A.1.1. Call using ROAP . . . . . . . . . . . . . . . . . . . 38 + A.1.2. Call using XMPP . . . . . . . . . . . . . . . . . . . 39 + A.1.3. Adding video to a call, using XMPP . . . . . . . . . 40 + A.1.4. Simultaneous add of video streams, using XMPP . . . . 41 + A.1.5. Call using SIP . . . . . . . . . . . . . . . . . . . 41 + A.1.6. Handling early media (e.g. 1-800-GO FEDEX), using SIP 42 + A.2. Example Session Descriptions . . . . . . . . . . . . . . 43 + A.2.1. createOffer . . . . . . . . . . . . . . . . . . . . . 43 + A.2.2. createAnswer . . . . . . . . . . . . . . . . . . . . 45 + A.2.3. Call Flows . . . . . . . . . . . . . . . . . . . . . 46 + Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 46 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 1. Introduction This document describes how the W3C WEBRTC RTCPeerConnection interface[W3C.WD-webrtc-20111027] is used to control the setup, management and teardown of a multimedia session. 1.1. General Design of JSEP The thinking behind WebRTC call setup has been to fully specify and @@ -444,21 +446,21 @@ application via a callback; these candidates will automatically be added to the local session description. When all candidates have been gathered, the callback will also be invoked to signal that the gathering process is complete. 3.4.1. ICE Candidate Trickling Candidate trickling is a technique through which a caller may incrementally provide candidates to the callee after the initial offer has been dispatched; the semantics of "Trickle ICE" are defined - in [I-D.ivov-mmusic-trickle-ice]. This process allows the callee to + in [I-D.ietf-mmusic-trickle-ice]. This process allows the callee to begin acting upon the call and setting up the ICE (and perhaps DTLS) connections immediately, without having to wait for the caller to gather all possible candidates. This results in faster call startup in cases where gathering is not performed prior to initiating the call. JSEP supports optional candidate trickling by providing APIs that provide control and feedback on the ICE candidate gathering process. Applications that support candidate trickling can send the initial offer immediately and send individual candidates when they get the @@ -894,79 +894,104 @@ This call will result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity being established. 5. SDP Interaction Procedures This section describes the specific procedures to be followed when creating and parsing SDP objects. -5.1. SDP Requirements Overview - The key specifications that govern creation and processing of offers - and answers are listed below. This list is derived from - [I-D.ietf-rtcweb-rtp-usage]. +5.1. Requirements Overview + + JSEP implementations must comply with the specifications listed below + that govern the creation and processing of offers and answers. + + The first set of specifications is the "mandatory-to-implement" set. + All implementations must support these behaviors, but may not use all + of them if the remote side, which may not be a JSEP endpoint, does + not support them. + + The second set of specifications is the "mandatory-to-use" set. The + local JSEP endpoint and any remote endpoint must indicate support for + these specifications in their session descriptions. + +5.1.1. Implementation Requirements + + This list of mandatory-to-implement specifications is derived from + the requirements outlined in [I-D.ietf-rtcweb-rtp-usage]. R-1 [RFC4566] is the base SDP specification and MUST be implemented. - R-2 The [RFC5888] grouping framework MUST be implemented for - signaling grouping information, and MUST be used to identify m= - lines via the a=mid attribute. + R-2 [RFC5764] MUST be supported for signaling the UDP/TLS/RTP/SAVPF + RTP profile. - R-3 [RFC5124] MUST be supported for signaling RTP/SAVPF RTP - profile. + R-3 [RFC5245] MUST be implemented for signaling the ICE credentials + and candidate lines corresponding to each media stream. The ICE + implementation MUST be a Full implementation, not a Lite + implementation. - R-4 [RFC4585] MUST be implemented to signal RTCP based feedback. + R-4 [RFC5763] MUST be implemented to signal DTLS certificate + fingerprints. - R-5 [RFC5245] MUST be implemented for signaling the ICE candidate - lines corresponding to each media stream. + R-5 [RFC4568] MUST NOT be implemented to signal SDES SRTP keying + information. - R-6 [RFC5761] MUST be implemented to signal multiplexing of RTP and - RTCP. + R-6 The [RFC5888] grouping framework MUST be implemented for + signaling grouping information, and MUST be used to identify m= + lines via the a=mid attribute. - R-7 The SDP atributes of "sendonly", "recvonly", "inactive", and + R-7 [I-D.ietf-mmusic-msid] MUST be supported, in order to signal + associations between RTP objects and W3C MediaStreams and + MediaStreamTracks in a standard way. + + R-8 The bundle mechanism in + [I-D.ietf-mmusic-sdp-bundle-negotiation] MUST be supported to + signal the ability to multiplex RTP streams on a single UDP port, + in order to avoid excessive use of port number resources. + + R-9 The SDP attributes of "sendonly", "recvonly", "inactive", and "sendrecv" from [RFC4566] MUST be implemented to signal information about media direction. - R-8 [RFC5576] MUST be implemented to signal RTP SSRC values. + R-10 [RFC5576] MUST be implemented to signal RTP SSRC values. - R-9 [RFC5763] MUST be implemented to signal DTLS certificate - fingerprints. + R-11 [RFC4585] MUST be implemented to signal RTCP based feedback. - R-10 [RFC5506] MAY be implemented to signal Reduced-Size RTCP + R-12 [RFC5761] MUST be implemented to signal multiplexing of RTP and + RTCP. + + R-13 [RFC5506] MUST be implemented to signal reduced-size RTCP messages. - R-11 [RFC3556] with bandwidth modifiers MAY be supported for + R-14 [RFC3556] with bandwidth modifiers MAY be supported for specifying RTCP bandwidth as a fraction of the media bandwidth, RTCP fraction allocated to the senders and setting maximum media bit-rate boundaries. - R-12 [RFC4568] MUST NOT be implemented to signal SDES SRTP keying - information. + As required by [RFC4566], Section 5.13, JSEP implementations MUST + ignore unknown attribute (a=) lines. - R-13 A [I-D.ietf-mmusic-msid] MUST be supported, in order to signal - associations between RTP objects and W3C MediaStreams and - MediaStreamTracks in a standard way. +5.1.2. Usage Requirements - R-14 The bundle mechanism in - [I-D.ietf-mmusic-sdp-bundle-negotiation] MUST be supported to - signal the use or multiplexing RTP somethings on a single UDP - port, in order to avoid excessive use of port number resources. + All session descriptions handled by JSEP endpoints, both local and + remote, MUST indicate support for the following specifications. If + any of these are absent, this omission MUST be treated as an error. - As required by [RFC4566] Section 5.13 JSEP implementations MUST - ignore unknown attributes (a=) lines. + R-1 Either the UDP/TLS/RTP/SAVP or the UDP/TLS/RTP/SAVPF RTP + profile, as specified in [RFC5764], MUST be used. - Example SDP for RTCWeb call flows can be found in - [I-D.nandakumar-rtcweb-sdp]. [TODO: since we are starting to specify - how to handle SDP in this document, should these call flows be merged - into this document, or this link moved to the examples section?] + R-2 ICE, as specified in [RFC5245], MUST be used. Note that the + remote endpoint MAY use a Lite implementation. + + R-3 DTLS-SRTP, as specified in [RFC5763], MUST be used. 5.2. Constructing an Offer When createOffer is called, a new SDP description must be created that includes the functionality specified in [I-D.ietf-rtcweb-rtp-usage]. The exact details of this process are explained below. 5.2.1. Initial Offers @@ -986,60 +1011,82 @@ cryptographically random number. To ensure uniqueness, this number SHOULD be at least 64 bits long. The value of the field SHOULD be zero. The value of the tuple SHOULD be set to a non- meaningful address, such as IN IP4 0.0.0.0, to prevent leaking the local address in this field. As mentioned in [RFC4566], the entire o= line needs to be unique, but selecting a random number for is sufficient to accomplish this. o The third SDP line MUST be a "s=" line, as specified in [RFC4566], - Section 5.3; a single space SHOULD be used as the session name, - e.g. "s= " + Section 5.3; to match the "o=" line, a single dash SHOULD be used + as the session name, e.g. "s=-". o Session Information ("i="), URI ("u="), Email Address ("e="), Phone Number ("p="), Bandwidth ("b="), Repeat Times ("r="), and Time Zones ("z=") lines are not useful in this context and SHOULD NOT be included. o Encryption Keys ("k=") lines do not provide sufficient security and MUST NOT be included. o A "t=" line MUST be added, as specified in [RFC4566], Section 5.9; both and SHOULD be set to zero, e.g. "t=0 0". + o An "a=msid-semantic:WMS" line MUST be added, as specified in + [I-D.ietf-mmusic-msid], Section 4. + The next step is to generate m= sections for each MediaStreamTrack that has been added to the PeerConnection via the addStream method. - Note that this method takes a MediaStream, which can contain multiple - MediaStreamTracks, and therefore multiple m= sections can be - generated even if addStream is only called once. + (Note that this method takes a MediaStream, which can contain + multiple MediaStreamTracks, and therefore multiple m= sections can be + generated even if addStream is only called once.) When generating m= + sections, the ordering is based on (1) the order in which the + MediaStreams were added to the PeerConnection, and (2) the + alphabetical ordering of the media type for the MediaStreamTrack. + For example, if a MediaStream containing both an audio and a video + MediaStreamTrack is added to a PeerConnection, the resultant m=audio + section will precede the m=video section. + + Each m= section, provided it is not being bundled into another m= + section, MUST generate a unique set of ICE credentials and gather its + own unique set of ICE candidates. Otherwise, it MUST use the same + ICE credentials and candidates that were used in the m= section that + it is being bundled into. + + For DTLS, all m= sections MUST use the certificate for the identity + that has been specified for the PeerConnection; as a result, they + MUST all have the same [RFC4572]fingerprint value. Each m= section should be generated as specified in [RFC4566], - Section 5.14. The field MUST be set to "RTP/SAVPF". If a m= - section is not being bundled into another m= section, it MUST - generate a unique set of ICE credentials and gather its own set of - candidates. Otherwise, it MUST use the same ICE credentials and - candidates that were used in the m= section that it is being bundled - into. For DTLS, all m= sections MUST use the same certificate [OPEN - ISSUE: how this is configured] and will therefore have the same - fingerprint values. + Section 5.14. For the m= line itself, the following rules MUST be + followed: - Each m= section MUST include the following: + o The port value is set to the port of the default ICE candidate for + this m= section; if this m= section is not being bundled into + another m= section, the port value MUST be unique. If no + candidates have yet been gathered, and a 'null' port value is + being used, as indicated in [I-D.ietf-mmusic-trickle-ice], + Section 5.1., this port MUST still be unique. + + o To properly indicate use of DTLS, the field MUST be set to + "UDP/TLS/RTP/SAVPF", as specified in [RFC5764], Section 8. + + Each m= section MUST include the following attribute lines: o An "a=mid" line, as specified in [RFC5888], Section 4. o An "a=msid" line, as specified in [I-D.ietf-mmusic-msid], Section 2. o [OPEN ISSUE: Use of App Token versus stream-correlator ] - o An "a=sendrecv" line, as specified in [RFC3264], Section 5.1. o For each supported codec, "a=rtpmap" and "a=fmtp" lines, as specified in [RFC4566], Section 6. For audio, the codecs specified in [I-D.ietf-rtcweb-audio], Section 3, MUST be be supported. o For each primary codec where RTP retransmission should be used, a corresponding "a=rtpmap" line indicating "rtx" with the clock rate of the primary codec and an "a=fmtp" line that references the @@ -1046,36 +1093,34 @@ payload type fo the primary codec, as specified in [RFC4588], Section 8.1. o For each supported FEC mechanism, a corresponding "a=rtpmap" line indicating the desired FEC codec. o "a=ice-ufrag" and "a=ice-passwd" lines, as specified in [RFC5245], Section 15.4. o An "a=ice-options" line, with the "trickle" option, as specified - in [I-D.ivov-mmusic-trickle-ice], Section 4. + in [I-D.ietf-mmusic-trickle-ice], Section 4. o For each candidate that has been gathered during the most recent gathering phase, an "a=candidate" line, as specified in [RFC5245], Section 4.3., paragraph 3. o For the current default candidate, a "c=" line, as specific in - [RFC5245], Section 4.3., paragraph 6. [OPEN ISSUE, pending - resolution in mmusic: If no candidates have yet been gathered yet, - the default candidate should be set to the null value defined in - [I-D.ivov-mmusic-trickle-ice], Section 5.1.] + [RFC5245], Section 4.3., paragraph 6. If no candidates have been + gathered yet, the default candidate should be set to the 'null' + value defined in [I-D.ietf-mmusic-trickle-ice], Section 5.1. - o An "a=fingerprint" line, as specified in [RFC4572], Section 5. - Use of the SHA-256 algorithm for the fingerprint is REQUIRED; if - the browser also supports stronger hashes, additional - "a=fingerprint" lines with these hashes MAY also be added. + o An "a=fingerprint" line, as specified in [RFC4572], Section 5; the + algorithm used for the fingerprint MUST match that used in the + certificate signature. o An "a=setup" line, as specified in [RFC4145], Section 4, and clarified for use in DTLS-SRTP scenarios in [RFC5763], Section 5. The role value in the offer MUST be "actpass". o An "a=rtcp-mux" line, as specified in [RFC5761], Section 5.1.1. o An "a=rtcp-rsize" line, as specified in [RFC5506], Section 5. o For each supported RTP header extension, an "a=extmap" line, as @@ -1084,45 +1129,53 @@ [I-D.ietf-rtcweb-rtp-usage], Section 5.2. Any header extensions that require encryption MUST be specified as indicated in [RFC6904], Section 4. o For each supported RTCP feedback mechanism, an "a=rtcp-fb" mechanism, as specified in [RFC4585], Section 4.2. The list of RTCP feedback mechanisms that SHOULD/MUST be supported is specified in [I-D.ietf-rtcweb-rtp-usage], Section 5.1. o An "a=ssrc" line, as specified in [RFC5576], Section 4.1, - indicating the SSRC to be used for sending media. + indicating the SSRC to be used for sending media, along with the + mandatory "cname" source attribute, as specified in Section 6.1, + indicating the CNAME for the source. The CNAME must be generated + in accordance with draft-rescorla-random-cname-00. [OPEN ISSUE: + How are CNAMEs specified for MSTs? Are they randomly generated + for each MediaStream? If so, can two MediaStreams be synced?] o If RTX is supported for this media type, another "a=ssrc" line with the RTX SSRC, and an "a=ssrc-group" line, as specified in [RFC5576], section 4.2, with semantics set to "FID" and including the primary and RTX SSRCs. o If FEC is supported for this media type, another "a=ssrc" line with the FEC SSRC, and an "a=ssrc-group" line, as specified in [RFC5576], section 4.2, with semantics set to "FEC" and including the primary and FEC SSRCs. o [OPEN ISSUE: Handling of a=imageattr] o [TODO: bundle-only] Lastly, if a data channel has been created, a m= section MUST be generated for data. The field MUST be set to "application" and the field MUST be set to "DTLS/SCTP", as specified in - [I-D.ietf-mmusic-sctp-sdp], Section 3. The "a=mid", "a=ice-ufrag", - "a=ice-passwd", "a=ice-options", "a=candidate", "a=fingerprint", and - "a=setup" lines MUST be included as mentioned above. [OPEN ISSUE: - additional SCTP-specific stuff to be included, as indicated in - [I-D.jesup-rtcweb-data-protocol] (currently none)] + [I-D.ietf-mmusic-sctp-sdp], Section 3; the "fmt" value MUST be set to + the SCTP port number, as specified in Section 4.1. + Within the data m= section, the "a=mid", "a=ice-ufrag", "a=ice- + passwd", "a=ice-options", "a=candidate", "a=fingerprint", and + "a=setup" lines MUST be included as mentioned above, along with an + "a=sctpmap" line referencing the SCTP port number and specifying the + application protocol indicated in [I-D.ietf-rtcweb-data-protocol]. + [OPEN ISSUE: the -00 of this document is missing this information.] Once all m= sections have been generated, a session-level "a=group" attribute MUST be added as specified in [RFC5888]. This attribute MUST have semantics "BUNDLE", and identify the m= sections to be bundled. [OPEN ISSUE: Need to determine exactly how this decision is made.] Attributes that are common between all m= sections MAY be moved to session-level, if desired. Attributes other than the ones specified above MAY be included, @@ -1136,39 +1189,39 @@ o "a=ice-lite" Note that when BUNDLE is used, any additional attributes that are added MUST follow the advice in [I-D.nandakumar-mmusic-sdp-mux-attributes] on how those attributes interact with BUNDLE. 5.2.2. Subsequent Offers - When createOffer is called a second (or later) time, the processing - is different, depending on the current signaling state. + When createOffer is called a second (or later) time, or is called + after a local description has already been installed, the processing + is somewhat different than for an initial offer. If the initial offer was not applied using setLocalDescription, meaning the PeerConnection is still in the "stable" state, the steps - for generating an initial offer should be followed, with this - exception: + for generating an initial offer should be followed, subject to the + following restriction: - o The "o=" line MUST stay the same. + o The fields of the "o=" line MUST stay the same except for the + field, which MUST increment if the session + description changes in any way, including the addition of ICE + candidates. If the initial offer was applied using setLocalDescription, but an answer from the remote side has not yet been applied, meaning the - PeerConnection is still in the "local-offer" state, the steps for - generating an initial offer should be followed, with these - exceptions: - - o The "o=" line MUST stay the same, except for the - field, which MUST increase by 1 from the previously applied local - description. + PeerConnection is still in the "local-offer" state, an offer is + generated by following the steps in the "stable" state above, along + with these exceptions: o The "s=" and "t=" lines MUST stay the same. o Each "a=mid" line MUST stay the same. o Each "a=ice-ufrag" and "a=ice-pwd" line MUST stay the same. o For MediaStreamTracks that are still present, the "a=msid", "a=ssrc", and "a=ssrc-group" lines MUST stay the same. @@ -1251,27 +1304,24 @@ "true", the offer MUST include a m= section with media type "video", even if no video MediaStreamTrack has been added to the PeerConnection. This allows the offerer to receive video even when not sending it; accordingly, the directional attribute on the video m= section MUST be set to recvonly. If this constraint is specified when an video MediaStreamTrack has already been added to the PeerConnection, or a non-rejected m= section with media type "video" previously existed, it has no effect. 5.2.3.3. VoiceActivityDetection - If the "VoiceActivityDetection" constraint is specified, with a value of "true", the offer MUST indicate support for silence suppression by including comfort noise ("CN") codecs for each supported clock rate, - as specified in [RFC3389], Section 5.1. [OPEN issue: should this do - anything in signaling, or should it just control built-in DTX modes - in audio codecs? Opus has built-in DTX, but G.711 does not.] + as specified in [RFC3389], Section 5.1. 5.2.3.4. IceRestart If the "IceRestart" constraint is specified, with a value of "true", the offer MUST indicate an ICE restart by generating new ICE ufrag and pwd attributes, as specified in RFC5245, Section 9.1.1.1. If this constraint is specified on an initial offer, it has no effect (since a new ICE ufrag and pwd are already generated). 5.3. Generating an Answer @@ -1282,31 +1332,30 @@ details of this process are explained below. 5.3.1. Initial Answers When createAnswer is called for the first time after a remote description has been provided, the result is known as the initial answer. If no remote description has been installed, an answer cannot be generated, and an error MUST be returned. Note that the remote description SDP may not have been created by a - WebRTC endpoint and may not conform to all the requirements listed in + JSEP endpoint and may not conform to all the requirements listed in Section 5.2. For many cases, this is not a problem. However, if any mandatory SDP attributes are missing, or functionality listed as - mandatory-to-use is not present (e.g. ICE, DTLS) [TODO: find - reference for this], this MUST be treated as an error. [OPEN ISSUE: - Should this cause setRemoteDescription to fail, or should this cause - createAnswer to reject those particular m= sections?] + mandatory-to-use above is not present, this MUST be treated as an + error, and MUST cause the affected m= sections to be marked as + rejected. The first step in generating an initial answer is to generate session-level attributes. The process here is identical to that - indicated in the Initial Offers section above, with the addition that + indicated in the Initial Offers section above. The next step is to generate m= sections for each m= section that is present in the remote offer, as specified in [RFC3264], Section 6. For the purposes of this discussion, any session-level attributes in the offer that are also valid as media-level attributes SHALL be considered to be present in each m= section. If any of the offered m= sections have been rejected, by stopping the associated remote MediaStreamTrack, the corresponding m= section in the answer MUST be marked as rejected by setting the port in the m= @@ -1318,25 +1367,26 @@ the PeerConnection via addStream and not yet associated with a m= section, the MediaStreamTrack is associated with the m= section at this time. If there are more m= sections of a certain type than MediaStreamTracks, some m= sections will not have an associated MediaStreamTrack. If there are more MediaStreamTracks of a certain type than m= sections, only the first N MediaStreamTracks will be able to be associated in the constructed answer. The remainder will need to be associated in a subsequent offer. Each m= section should then generated as specified in [RFC3264], - Section 6.1. The field MUST be set to "RTP/SAVPF". If the - offer supports BUNDLE, all m= sections to be BUNDLEd must use the - same ICE credentials and candidates; all m= sections not being - BUNDLEd must use unique ICE credentials and candidates. Each m= - section MUST include the following: + Section 6.1. Because use of DTLS is mandatory, the field + MUST be set to "UDP/TLS/RTP/SAVPF". If the offer supports BUNDLE, + all m= sections to be BUNDLEd must use the same ICE credentials and + candidates; all m= sections not being BUNDLEd must use unique ICE + credentials and candidates. Each m= section MUST include the + following: o If present in the offer, an "a=mid" line, as specified in [RFC5888], Section 9.1. The "mid" value MUST match that specified in the offer. o If a local MediaStreamTrack has been associated, an "a=msid" line, as specified in [I-D.ietf-mmusic-msid], Section 2. o [OPEN ISSUE: Use of App Token versus stream-correlator ] @@ -1360,36 +1410,34 @@ codec, as specified in [RFC4588], Section 8.1. o For each supported FEC mechanism that is present in the offer, a corresponding "a=rtpmap" line indicating the desired FEC codec. o "a=ice-ufrag" and "a=ice-passwd" lines, as specified in [RFC5245], Section 15.4. o If the "trickle" ICE option is present in the offer, an "a=ice- options" line, with the "trickle" option, as specified in - [I-D.ivov-mmusic-trickle-ice], Section 4. + [I-D.ietf-mmusic-trickle-ice], Section 4. o For each candidate that has been gathered during the most recent gathering phase, an "a=candidate" line, as specified in [RFC5245], Section 4.3., paragraph 3. o For the current default candidate, a "c=" line, as specific in - [RFC5245], Section 4.3., paragraph 6. [OPEN ISSUE, pending - resolution in mmusic: If no candidates have yet been gathered yet, - the default candidate should be set to the null value defined in - [I-D.ivov-mmusic-trickle-ice], Section 5.1.] + [RFC5245], Section 4.3., paragraph 6. If no candidates have been + gathered yet, the default candidate should be set to the 'null' + value defined in [I-D.ietf-mmusic-trickle-ice], Section 5.1. - o An "a=fingerprint" line, as specified in [RFC4572], Section 5. - Use of the SHA-256 algorithm for the fingerprint is REQUIRED; if - the browser also supports stronger hashes, additional - "a=fingerprint" lines with these hashes MAY also be added. + o An "a=fingerprint" line, as specified in [RFC4572], Section 5; the + algorithm used for the fingerprint MUST match that used in the + certificate signature. o An "a=setup" line, as specified in [RFC4145], Section 4, and clarified for use in DTLS-SRTP scenarios in [RFC5763], Section 5. The role value in the answer MUST be "active" or "passive"; the "active" role is RECOMMENDED. o If present in the offer, an "a=rtcp-mux" line, as specified in [RFC5761], Section 5.1.1. o If present in the offer, an "a=rtcp-rsize" line, as specified in @@ -1420,36 +1468,41 @@ o If a local MediaStreamTrack has been associated, and FEC has been negotiated for this m= section, another "a=ssrc" line with the FEC SSRC, and an "a=ssrc-group" line, as specified in [RFC5576], section 4.2, with semantics set to "FEC" and including the primary and FEC SSRCs. o [OPEN ISSUE: Handling of a=imageattr] o [TODO: bundle-only] + If a data channel m= section has been offered, a m= section MUST also be generated for data. The field MUST be set to "application" and the field MUST be set to "DTLS/SCTP", as - specified in [I-D.ietf-mmusic-sctp-sdp], Section 3. The "a=mid", "a - =ice-ufrag", "a=ice-passwd", "a=ice-options", "a=candidate", - "a=fingerprint", and "a=setup" lines MUST be included as mentioned - above. [OPEN ISSUE: additional SCTP-specific stuff to be included, - as indicated in [I-D.jesup-rtcweb-data-protocol] (currently none)] + specified in [I-D.ietf-mmusic-sctp-sdp], Section 3; the "fmt" value + MUST be set to the SCTP port number, as specified in Section 4.1. + + Within the data m= section, the "a=mid", "a=ice-ufrag", "a=ice- + passwd", "a=ice-options", "a=candidate", "a=fingerprint", and + "a=setup" lines MUST be included as mentioned above, along with an + "a=sctpmap" line referencing the SCTP port number and specifying the + application protocol indicated in [I-D.ietf-rtcweb-data-protocol]. + [OPEN ISSUE: the -00 of this document is missing this information.] [TODO: processing of BUNDLE group] Attributes that are common between all m= sections MAY be moved to session-level, if desired. - The attributes prohibited in creation of offers are also prohibited - in the creation of answers. + The attributes prohibited in the creation of offers are also + prohibited in the creation of answers. 5.3.2. Subsequent Answers 5.3.3. Constraints Handling 5.4. Parsing an Offer 5.5. Parsing an Answer 5.6. Applying a Local Description @@ -1625,36 +1676,36 @@ [RFC5888] Camarillo, G. and H. Schulzrinne, "The Session Description Protocol (SDP) Grouping Framework", RFC 5888, June 2010. [RFC6904] Lennox, J., "Encryption of Header Extensions in the Secure Real-time Transport Protocol (SRTP)", RFC 6904, April 2013. 10.2. Informative References - [I-D.ivov-mmusic-trickle-ice] + [I-D.ietf-mmusic-trickle-ice] Ivov, E., Rescorla, E., and J. Uberti, "Trickle ICE: Incremental Provisioning of Candidates for the Interactive - Connectivity Establishment (ICE) Protocol", draft-ivov- - mmusic-trickle-ice-01 (work in progress), March 2013. + Connectivity Establishment (ICE) Protocol", draft-ietf- + mmusic-trickle-ice-00 (work in progress), March 2013. + + [I-D.ietf-rtcweb-data-protocol] + Jesup, R., Loreto, S., and M. Tuexen, "WebRTC Data Channel + Protocol", draft-ietf-rtcweb-data-protocol-04 (work in + progress), February 2013. [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. - [I-D.jesup-rtcweb-data-protocol] - Jesup, R., Loreto, S., and M. Tuexen, "WebRTC Data Channel - Protocol", draft-jesup-rtcweb-data-protocol-04 (work in - progress), February 2013. - [I-D.nandakumar-rtcweb-sdp] Nandakumar, S. and C. Jennings, "SDP for the WebRTC", draft-nandakumar-rtcweb-sdp-02 (work in progress), July 2013. [RFC3389] Zopf, R., "Real-time Transport Protocol (RTP) Payload for Comfort Noise (CN)", RFC 3389, September 2002. [RFC3556] Casner, S., "Session Description Protocol (SDP) Bandwidth Modifiers for RTP Control Protocol (RTCP) Bandwidth", RFC @@ -1678,20 +1729,24 @@ [RFC5576] Lennox, J., Ott, J., and T. Schierl, "Source-Specific Media Attributes in the Session Description Protocol (SDP)", RFC 5576, June 2009. [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework for Establishing a Secure Real-time Transport Protocol (SRTP) Security Context Using Datagram Transport Layer Security (DTLS) ", RFC 5763, May 2010. + [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer + Security (DTLS) Extension to Establish Keys for the Secure + Real-time Transport Protocol (SRTP)", RFC 5764, May 2010. + [W3C.WD-webrtc-20111027] Bergkvist, A., Burnett, D., Narayanan, A., and C. Jennings, "WebRTC 1.0: Real-time Communication Between Browsers", World Wide Web Consortium WD WD- webrtc-20111027, October 2011, . Appendix A. JSEP Implementation Examples A.1. Example API Flows @@ -1927,22 +1981,23 @@ This SDP shows a typical initial offer, created by createOffer for a PeerConnection with a single audio MediaStreamTrack, a single video MediaStreamTrack, and a single data channel. Host candidates have also already been gathered. Note some lines have been broken into two lines for formatting reasons. v=0 o=- 4962303333179871722 1 IN IP4 0.0.0.0 s=- t=0 0 + a=msid-semantic:WMS a=group:BUNDLE audio video data - m=audio 56500 RTP/SAVPF 111 0 8 126 + m=audio 56500 UDP/TLS/RTP/SAVPF 111 0 8 126 c=IN IP4 192.0.2.1 a=rtcp:56501 IN IP4 192.0.2.1 a=candidate:3348148302 1 udp 2113937151 192.0.2.1 56500 typ host generation 0 a=candidate:3348148302 2 udp 2113937151 192.0.2.1 56501 typ host generation 0 a=ice-ufrag:ETEn1v9DoTMB9J4r a=ice-pwd:OtSK0WpNtpUjkY4+86js7ZQl a=ice-options:trickle a=mid:audio @@ -1956,21 +2011,21 @@ a=setup:actpass a=rtpmap:111 opus/48000/2 a=fmtp:111 minptime=10 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 a=rtpmap:126 telephone-event/8000 a=maxptime:60 a=ssrc:1732846380 cname:EocUG1f0fcg/yvY7 a=msid:47017fee-b6c1-4162-929c-a25110252400 f83006c5-a0ff-4e0a-9ed9-d3e6747be7d9 - m=video 56502 RTP/SAVPF 100 115 116 117 + m=video 56502 UDP/TLS/RTP/SAVPF 100 115 116 117 c=IN IP4 192.0.2.1 a=rtcp:56503 IN IP4 192.0.2.1 a=candidate:3348148302 1 udp 2113937151 192.0.2.1 56502 typ host generation 0 a=candidate:3348148302 2 udp 2113937151 192.0.2.1 56503 typ host generation 0 a=ice-ufrag:BGKkWnG5GmiUpdIV a=ice-pwd:mqyWsAjvtKwTGnvhPztQ9mIf a=ice-options:trickle a=mid:video @@ -1995,43 +2050,45 @@ a=ssrc:1366781084 cname:EocUG1f0fcg/yvY7 a=ssrc:1366781085 cname:EocUG1f0fcg/yvY7 a=ssrc-group:FID 1366781083 1366781084 a=ssrc-group:FEC 1366781083 1366781085 a=msid:61317484-2ed4-49d7-9eb7-1414322a7aae f30bdb4a-5db8-49b5-bcdc-e0c9a23172e0 m=application 56504 DTLS/SCTP 5000 c=IN IP4 192.0.2.1 a=candidate:3348148302 1 udp 2113937151 192.0.2.1 56504 typ host generation 0 + a=ice-ufrag:VD5v2BnbZm3mgP3d a=ice-pwd:+Jlkuox+VVIUDqxcfIDuTZMH a=ice-options:trickle a=mid:data a=fingerprint:sha-256 19:E2:1C:3B:4B:9F:81:E6:B8:5C:F4:A5:A8:D8:73:04 :BB:05:2F:70:9F:04:A9:0E:05:E9:26:33:E8:70:88:A2 a=setup:actpass - a=fmtp:5000 protocol=webrtc-datachannel; streams=10 + a=sctpmap:5000 webrtc-datachannel 16 A.2.2. createAnswer This SDP shows a typical initial answer to the above offer, created by createAnswer for a PeerConnection with a single audio MediaStreamTrack, a single video MediaStreamTrack, and a single data channel. Host candidates have also already been gathered. Note some lines have been broken into two lines for formatting reasons. v=0 o=- 6729291447651054566 1 IN IP4 0.0.0.0 s=- t=0 0 + a=msid-semantic:WMS a=group:BUNDLE audio video data - m=audio 20000 RTP/SAVPF 111 0 8 126 + m=audio 20000 UDP/TLS/RTP/SAVPF 111 0 8 126 c=IN IP4 192.0.2.2 a=candidate:2299743422 1 udp 2113937151 192.0.2.2 20000 typ host generation 0 a=ice-ufrag:6sFvz2gdLkEwjZEr a=ice-pwd:cOTZKZNVlO9RSGsEGM63JXT2 a=fingerprint:sha-256 6B:8B:F0:65:5F:78:E2:51:3B:AC:6F:F3:3F:46:1B:35 :DC:B8:5F:64:1A:24:C2:43:F0:A1:58:D0:A1:2C:19:08 a=setup:active a=mid:audio a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level @@ -2039,21 +2096,21 @@ a=rtcp-mux a=rtpmap:111 opus/48000/2 a=fmtp:111 minptime=10 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 a=rtpmap:126 telephone-event/8000 a=maxptime:60 a=ssrc:3429951804 cname:Q/NWs1ao1HmN4Xa5 a=msid:PI39StLS8W7ZbQl1sJsWUXkr3Zf12fJUvzQ1 PI39StLS8W7ZbQl1sJsWUXkr3Zf12fJUvzQ1a0 - m=video 20000 RTP/SAVPF 100 115 116 117 + m=video 20000 UDP/TLS/RTP/SAVPF 100 115 116 117 c=IN IP4 192.0.2.2 a=candidate:2299743422 1 udp 2113937151 192.0.2.2 20000 typ host generation 0 a=ice-ufrag:6sFvz2gdLkEwjZEr a=ice-pwd:cOTZKZNVlO9RSGsEGM63JXT2 a=fingerprint:sha-256 6B:8B:F0:65:5F:78:E2:51:3B:AC:6F:F3:3F:46:1B:35 :DC:B8:5F:64:1A:24:C2:43:F0:A1:58:D0:A1:2C:19:08 a=setup:active a=mid:video a=extmap:2 urn:ietf:params:rtp-hdrext:toffset @@ -2078,23 +2135,36 @@ m=application 20000 DTLS/SCTP 5000 c=IN IP4 192.0.2.2 a=candidate:2299743422 1 udp 2113937151 192.0.2.2 20000 typ host generation 0 a=ice-ufrag:6sFvz2gdLkEwjZEr a=ice-pwd:cOTZKZNVlO9RSGsEGM63JXT2 a=fingerprint:sha-256 6B:8B:F0:65:5F:78:E2:51:3B:AC:6F:F3:3F:46:1B:35 :DC:B8:5F:64:1A:24:C2:43:F0:A1:58:D0:A1:2C:19:08 a=setup:active a=mid:data - a=fmtp:5000 protocol=webrtc-datachannel; streams=10 + a=sctpmap:5000 webrtc-datachannel 16 + +A.2.3. Call Flows + + Example SDP for WebRTC call flows can be found in + [I-D.nandakumar-rtcweb-sdp]. [TODO: should these call flows be + merged into this section?] Appendix B. Change log + Changes in draft-05: + + o Fixed several issues identified in the createOffer/Answer sections + during document review. + + o Updated references. + Changes in draft-04: o Filled in sections on createOffer and createAnswer. o Added SDP examples. o Fixed references. Changes in draft-03: