This document defines a set of ECMAScript APIs in WebIDL to allow construction of an {{RTCIceTransport}} object in situations where this would not otherwise be available, such as in a data exchange-only application. This specification is being developed in conjunction with protocol specifications developed by the IETF ICE Working Group.
The API is based on preliminary work done in the W3C ORTC Community Group.
This specification extends the WebRTC specification [[WEBRTC]] to
allow construction of an {{RTCIceTransport}} object
in situations where this would not otherwise be available, such as in a
data exchange-only application that does not construct an
RTCPeerConnection object (e.g. {{RTCDataChannel}}
in workers, WebRTC-QUIC, etc.).
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]], as this specification uses that specification and terminology.
The {{RTCIceTransport}} extensions allow construction of
an {{RTCIceTransport}} without offer/answer. This specification
differs from the approach taken in [[ORTC]] in that it does not define a distinct
RTCIceGatherer object, instead adding methods for control of ICE
candidate gathering to {{RTCIceTransport}}. As a result, an
application can test for support of this specification by checking for the
{{RTCIceTransport.start()}} method, and the absence of
an RTCIceGatherer object.
The {{RTCIceParameters}} dictionary is extended with an {{RTCIceParameters/iceLite}} member.
partial dictionary RTCIceParameters {
boolean iceLite;
};
If only ICE-lite is supported (true) or not
(false or unset). Since [[RFC8835]] Section 3.4
requires browser support for full ICE, {{iceLite}} will
only be true for a remote peer such as a gateway.
{{RTCIceTransport/getLocalParameters()}}.{{iceLite}} MUST NOT be set.
{{RTCIceGatherOptions}} provides options relating to the gathering of ICE candidates.
dictionary RTCIceGatherOptions {
RTCIceTransportPolicy gatherPolicy = "all";
sequence<RTCIceServer> iceServers;
};
The ICE gather policy.
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.
[Exposed=Window]
partial interface RTCIceTransport {
constructor();
undefined gather (optional RTCIceGatherOptions options = {});
undefined start (optional RTCIceParameters remoteParameters = {}, optional RTCIceRole role = "controlled");
undefined stop ();
undefined addRemoteCandidate (optional RTCIceCandidateInit remoteCandidate = {});
attribute EventHandler onerror;
attribute EventHandler onicecandidate;
};
When the constructor is invoked, the user agent MUST run the following steps:
This event handler, of event handler event type {{RTCIceTransport/icecandidateerror}}, MUST be fired if an error occurs in the gathering of ICE candidates (such as if TURN credentials are invalid).
This event handler utilizes the event handler event type {{RTCIceTransport/icecandidate}}.
Gather ICE candidates. If {{RTCIceTransport/state}} is {{RTCIceTransportState/"closed"}}, [=exception/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.{{RTCIceGatherOptions/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.{{RTCIceServer/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, [= exception/throw =]
a {{SyntaxError}}. If the scheme name is
not implemented by the browser [= exception/throw =]
a {{NotSupportedError}}. If scheme name is
turn or turns, and parsing the url
using the syntax defined in [[!RFC7065]] fails, [=
exception/throw =] a {{SyntaxError}}. If scheme
name is stun or
stuns, and parsing the
url using the syntax defined in
[[!RFC7064]] fails, [= exception/throw =] a
{{SyntaxError}}.
If scheme name is turn or turns, and either of
server.{{RTCIceServer/username}} or
server.{{RTCIceServer/credential}} are
omitted, then [= exception/throw =] an
{{InvalidAccessError}}.
If scheme name is turn or turns, and
server.{{RTCIceServer/credential}} is not
a DOMString, then
[= exception/throw =] an {{InvalidAccessError}}.
Append server to validatedServers.
Let validatedServers be the ICE servers list.
As 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 {{RTCIceTransport}} object can respond to incoming connectivity checks based on its configured role. Since {{start()}} enables candidate pairs to be formed, it also enables initiating connectivity checks. When {{start()}} is called, the following steps MUST be run:
remoteParameters.{{RTCIceParameters/usernameFragment}}
or remoteParameters.{{RTCIceParameters/password}} is unset,
[=exception/throw=] an {{TypeError}}.
remoteParameters.{{RTCIceParameters/usernameFragment}}
or remoteParameters.{{RTCIceParameters/password}} does not
conform to the syntax described in [[RFC8839]] Section 5.4,
[=exception/throw=] a {{SyntaxError}}.
remoteParameters is unchanged,
local candidates are flushed, candidate pairs are flushed,
new candidate pairs are formed with existing remote candidates,
and {{RTCIceTransport/state}} transitions to {{RTCIceTransportState/"checking"}}.
Irreversibly stops the {{RTCIceTransport}}. When {{stop}} is called, the following steps MUST be run:
iceTransport.{{RTCIceTransport/state}} is
{{RTCIceTransportState/"closed"}}, abort these steps.
iceTransport.{{RTCIceTransport/state}} to
{{RTCIceTransportState/"closed"}}.
statechange
at iceTransport.
Add a remote candidate associated with the remote {{RTCIceTransport}}. If {{RTCIceTransport/state}} is {{RTCIceTransportState/"closed"}}, [=exception/throw=] an {{InvalidStateError}}. If remoteCandidate is malformed, [=exception/throw=] an {{OperationError}}. When the remote {{RTCIceTransport}} emits its end-of-candidates indication (as described in [[WEBRTC]] Section 4.8.2), {{addRemoteCandidate()}} should be called with the end-of-candidates indication as an argument, so that the local {{RTCIceTransport}} can know there are no more remote candidates expected, and can enter the {{RTCIceTransportState/"completed"}} state.
This 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 [[RFC8827]].
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.
The following events fire on {{RTCIceTransport}} objects:
| Event name | Interface | Fired when... |
|---|---|---|
| icecandidateerror | {{RTCPeerConnectionIceErrorEvent}} | The {{RTCIceTransport}} object has experienced an ICE gathering failure (such as an authentication failure with TURN credentials). |
| icecandidate | {{RTCPeerConnectionIceEvent}} | A new {{RTCIceCandidate}} is made available to the script. |
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}} object was initially described in the W3C ORTC CG, and has been adapted for use in this specification.