Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document defines a set of ECMAScript APIs in WebIDL to allow construction
of an RTCIceTransport
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
The API is based on preliminary work done in the W3C ORTC Community Group.
This document was published by the Web Real-Time Communications Working Group as an Editor's Draft.
Comments regarding this document are welcome. Please send them to public-webrtc@w3.org (archives).
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 W3C Process Document.
This section is non-normative.
This specification extends the WebRTC specification [WEBRTC] to
allow construction of an RTCIceTransport
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY and MUST in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL-1], as this specification uses that specification and terminology.
The EventHandler
interface, representing a callback used for event handlers, and the ErrorEvent
interface are defined in [HTML51].
The concepts queue a task, fires a simple event and networking task source are defined in [HTML51].
The terms event, event handlers and event handler event types are defined in [HTML51].
When referring to exceptions, the terms throw and create are defined in [WEBIDL-1].
The terms fulfilled, rejected, resolved, pending and settled used in the context of Promises are defined in [ECMASCRIPT-6.0].
The RTCDtlsTransport and RTCIceTransport interfaces,
the icecandidate, icecandidateerror, RTCPeerConnectionIceEvent and
RTCPeerConnectionIceErrorEvent events,
the RTCIceCandidate, RTCIceCandidatePair and RTCIceServer dictionaries
and the RTCIceTransportPolicy, RTCIceTransportState and
RTCIceRole enums are defined in [WEBRTC].
RTCIceTransport ExtensionsThe RTCIceTransportRTCIceTransport
RTCIceGatherOptions DictionaryRTCIceGatherOptions provides options relating to the
gathering of ICE candidates.
WebIDLdictionaryRTCIceGatherOptions{RTCIceTransportPolicygatherPolicy; sequence<RTCIceServer>iceServers; sequence<DOMString>?networkIds; };
RTCIceGatherOptions MembersgatherPolicy of type RTCIceTransportPolicyThe ICE gather policy.
iceServers of type sequence<RTCIceServer>Additional ICE servers to be configured. Since implementations MAY provide default ICE servers, and applications can desire to restrict communications to the local LAN, iceServers need not be set.
networkIds of type sequence<DOMString>If set and non-null, ICE gathering will be limited to the network interfaces specfied by the network IDs (obtained by calling getLocalCandidates().
WebIDL[ Constructor (), Exposed=Window] partial interfaceRTCIceTransport{ voidgather(RTCIceGatherOptionsoptions); voidstart(RTCIceParameters remoteParameters, optionalRTCIceRolerole = "controlled"); voidstop(); voidaddRemoteCandidate(RTCIceCandidateremoteCandidate); voidretainLocalCandidate(RTCIceCandidatelocalCandidate); voidremoveLocalCandidate(RTCIceCandidatelocalCandidate); sequence<RTCIceCandidatePair>getCandidatePairs();RTCIceTransportfork(); attribute EventHandleronerror; attribute EventHandleronlocalcandidate; attribute EventHandleronchecksent; };
RTCIceTransportonerror of type EventHandlerThis event handler, of event handler event type
icecandidateerror
onlocalcandidate of type EventHandlerThis event handler utilizes the event handler event type
icecandidate
onchecksent of type EventHandlerThis event handler utilizes the event handler event type
icecheck.
gatherGather ICE candidates. If
state is closed, throw an
InvalidStateError.
To validate the options argument,
implementations MUST run the following steps:
Let options be the first argument.
Let servers be the value of options.iceServers.
Let validatedServers be an empty list.
Run the following steps for each element in servers:
Let server be the current list element.
If server.urls is a string,
let server.urls be a list
consisting of just that string.
For each url in
server.urls run the following steps:
Parse the url using the generic URI syntax
defined in [RFC3986] and obtain the
scheme name. If the parsing based
on the syntax defined in [RFC3986] fails,
throw a SyntaxError. If
the scheme name is not implemented
by the browser throw a
NotSupportedError. If
scheme name is turn or
turns, and parsing the
url using the syntax defined in
[RFC7064] fails, throw a
SyntaxError. If scheme
name is stun or
stuns, and parsing the
url using the syntax defined in
[RFC7065] fails, throw a
SyntaxError.
If scheme name is turn or
turns, and either of
server.username or
server.credential are omitted,
then throw an InvalidAccessError.
If scheme name is turn or
turns, and
server.credentialType is
"password", and
server.credential is not a
DOMString, then
throw an InvalidAccessError and abort these
steps.
If scheme name is turn or
turns, and
server.credentialType is
"oauth", and
server.credential is not an
RTCOAuthCredential, then throw an
InvalidAccessError and abort these steps.
Append server to validatedServers.
Let validatedServers be the ICE servers list.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| options | |
✘ | ✔ |
void
startAs noted in [RFC5245] Section 7.1.2.3, an incoming connectivity check
utilizes the local/remote username fragment and the local password, whereas
an outgoing connectivity check utilizes the local/remote username fragment
and the remote password. Since start() provides role
information, as well as the remote username fragment and password, once
start() is called an RTCIceTransportstart() enables candidate pairs
to be formed, it also enables initiating connectivity checks.
When start() is called, the following
steps MUST be run:
state is closed, throw an InvalidStateError.
remoteParameters.usernameFragment
or remoteParameters.password is unset,
throw an TypeError.
start() is called again and
role is changed, throw an
InvalidStateError.
start() is called again with the same
value of remoteParameters, this has
no effect.
start() is called for the first time, if
there are remote candidates, set state
to checking and start connectivity checks.
If there are no remote candidates, state
remains new.
start() is called for the first time
and the value of gatherer
passed as an argument is different from that passed
in the constructor, flush local candidates. If there
are remote candidates, set state to
checking and start connectivity checks.
If there are no remote candidates, state
remains new.
start() is called again but the value
of remoteParameters has changed,
local candidates are kept, remote candidates are flushed,
candidate pairs are flushed and state
transitions to new.
start() is called again but the value of
remoteParameters is unchanged,
local candidates are flushed, candidate pairs are flushed,
new candidate pairs are formed with existing remote candidates,
and state transitions to checking.
start() is called again with new values of
remoteParameters, local
candidates are flushed, remote candidates are flushed,
candidate pairs are flushed and state transitions
to new.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| remoteParameters | RTCIceParameters |
✘ | ✘ | |
| role | controlled |
✘ | ✔ |
void
stopIrreversibly stops the
RTCIceTransportstop is called, the following
steps MUST be run:
RTCIceTransportstop method is invoked.
iceTransport.state is
closed, abort these steps.
iceTransport.state to
closed.
statechange
at iceTransport.
void
addRemoteCandidateAdd a remote candidate associated with the remote
RTCIceTransportstate is
closed, throw an InvalidStateError.
When the remote RTCIceGatherer emits its final
candidate, addRemoteCandidate()RTCIceCandidateComplete dictionary as an argument,
so that the local RTCIceTransportcompleted
state.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| remoteCandidate | |
✘ | ✘ |
void
removeLocalCandidateRemoves the given local candidate. This will trigger the removal of all candidate pairs with the given local candidate, the prevention of pairing with the given local candidate, and prevention of any network activity using the given local candidate.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| localCandidate | |
✘ | ✘ |
void
retainLocalCandidateCause the RTCIceTransport to not automatically remove the local candidate due to ICE pruning (such as when a candidate pair with a different local candidate is selected). But the local candidate may be removed if it completely fails (such as a network interface going away).
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| localCandidate | |
✘ | ✘ |
void
getCandidatePairs()Return all the candidate pairs.
sequence<RTCIceCandidatePair>
fork()Create a new RTCIceTransport that is the same as if constructor with a constructor except that the local ICE candidates already in the existing RTCIceTransport are shared with the new RTCIceTransport. Future calls to gather() for either of the transports does not affect the other (only the local candidates from before the fork are shared).
RTCIceTransport
WebIDL[Exposed=Window] partial interfaceRTCIceCandidate{ readonly attribute DOMString?networkId; // TODO: Add reference to https://wicg.github.io/netinfo/#dom-networkinformation readonly attribute NetworkInformation?networkInfo; };
networkId of type DOMStringnetworkInfo of type NetworkInformation[Exposed=Window]
// TODO: Change RTCIceCandidatePair to an interface in WebRTC 1.0, or rename this.
partial interface RTCIceCandidatePair {
void setMinCheckInterval(double seconds);
void setFrozen(bool frozen);
void select();
Promise nominate();
Promise waitForReceiveTimeout(double seconds);
};
setMinCheckIntervalCauses the RTCIceTransport to send ICE checks using this candidate pair no more frequently than indicated by the given interval (given in seconds). The RTCIceTransport may always send less frequently than specified.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| seconds | double |
✘ | ✘ |
void
setFrozenFreezes or unfreezes the candidate pair. When frozen, no ICE checks will be sent over it.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| frozen | boolean |
✘ | ✘ |
void
selectSelects the candidate pair. Once this is called once, the RTCIceTransport will no longer automatically select candidate pairs and the only way to change the selected candidate pair will be calling select() again will change the selected candidate pair again.
void
nominateNominates the candidate pair by sending a nomination to the remote side. Resolves the returned promise once the nomination has been sent or once it has been determined that it is impossible to nominate (for example, if aggressive nomination and renomination are both unavailable due to the ICE options and a nomination has already been sent.
Promise<boolean>
waitForReceiveTimeoutWait until no network pacekts have been received for more than the given timeout. This allows the detection of network outage. If called a second time on the same RTCIceTransport, the previous call's promise is rejected immediately. Thus, only one pending wait per IceTransport is allowed at a time.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| seconds | double |
✘ | ✘ |
void
[Exposed=Window]
interface RTCIceCheck {
readonly attribute Promise response;
};
response of type booleanThis section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the APIs and protocols used in WebRTC are described in [RTCWEB-SECURITY-ARCH].
This API, along with the QUIC API enables data to be communicated between browsers and other devices, including other browsers.
This means that data can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser. This is an extension to the Web model which has had barriers against sending data between entities with different origins.
This specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access data, it is free to share that data with other entities as it chooses. Peer-to-peer exchanges of data can therefore occur without any user explicit consent or involvement.
Since the browser is an active platform executing in a trusted network environment (inside the firewall), it is important to limit the damage that the browser can do to other elements on the local network, and it is important to protect data from interception, manipulation and modification by untrusted participants.
Mitigations include:
These measures are specified in the relevant IETF documents.
The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.
Since the SRTP, DTLS and QUIC protocols utilize a cryptographic negotiation in order to encrypt communications, confidentiality is provided.
This section is non-normative.
The following events fire on RTCIceTransport
| Event name | Interface | Fired when... |
|---|---|---|
icecandidateerror |
|
The |
icecandidate |
|
A new |
icehceck |
RTCIceCheckEvent |
A new RTCIceChecke is made available to the
script. |
This section is non-normative.
This section will be removed before publication.
The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson, Bernard Aboba and Dominique Hazaël-Massieux, for their support. Contributions to this specification were provided by Robin Raymond.
The RTCIceTransport