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 {{RTCDtlsTransport}} is defined in [[WEBRTC]]. The {{RTCIceTransport}} interface, the {{RTCIceTransport/getLocalParameters()}} method, the icecandidate, icecandidateerror, {{RTCPeerConnectionIceEvent}} and {{RTCPeerConnectionIceErrorEvent}} events, the {{RTCIceCandidate}} interface, {{RTCIceCandidateInit}} and {{RTCIceServer}} dictionaries, the {{RTCIceTransportPolicy}}, {{RTCIceTransportState}} and {{RTCIceRole}} enums and the [[\IceRole]], [[\IceTransportState]], [[\IceGathererState]] and [[\SelectedCandidatePair]] internal slots are defined in [[!WEBRTC]] Section 5.6.

{{RTCIceTransport}} Extensions

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.

{{RTCIceParameters}} Extensions

The {{RTCIceParameters}} dictionary is extended with an {{RTCIceParameters/iceLite}} member.

partial dictionary RTCIceParameters {
             boolean   iceLite;

Dictionary {{RTCIceParameters}} Members

iceLite of type boolean

If only ICE-lite is supported (true) or not (false or unset). Since [[RTCWEB-TRANSPORT]] 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 Dictionary

{{RTCIceGatherOptions}} provides options relating to the gathering of ICE candidates.

dictionary RTCIceGatherOptions {
             RTCIceTransportPolicy     gatherPolicy = "all";
             sequence<RTCIceServer> iceServers;

Dictionary {{RTCIceGatherOptions}} Members

gatherPolicy of type {{RTCIceTransportPolicy}}

The 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.

Interface Definition

partial interface RTCIceTransport {
    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:

  1. Create an {{RTCIceTransport}} transport.
  2. Initialize transport's [[\IceTransportState]], [[\IceGathererState]], [[\SelectedCandidatePair]] and [[\IceRole]] internal slots as specified in [[!WEBRTC]] Section 5.6.
  3. Initialize transport's local ICE parameters.
  4. Return transport.
No parameters.


onerror of type {{EventHandler}}

This event handler, of event handler event type {{icecandidateerror}}, MUST be fired if an error occurs in the gathering of ICE candidates (such as if TURN credentials are invalid).

onicecandidate of type {{EventHandler}}

This event handler utilizes the event handler event type {{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:

  1. Let options be the first argument.

  2. Let servers be the value of options.{{RTCIceGatherOptions/iceServers}}.

  3. Let validatedServers be an empty list.

  4. Run the following steps for each element in servers:

    1. Let server be the current list element.

    2. If server.{{RTCIceServer/urls}} is a string, let server.urls be a list consisting of just that string.

    3. For each url in server.urls run the following steps:

      1. 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 [[RFC7064]] fails, [=exception/throw=] a {{SyntaxError}}. If scheme name is stun or stuns, and parsing the url using the syntax defined in [[RFC7065]] fails, [=exception/throw=] a {{SyntaxError}}.

      2. If scheme name is turn or turns, and either of server.{{RTCIceServer/username}} or server.credential are omitted, then [=exception/throw=] an {{InvalidAccessError}}.

      3. If scheme name is turn or turns, and server.{{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"password"}}, and server.credential is not a {{DOMString}}, then [=exception/throw=] an {{InvalidAccessError}} and abort these steps.

    4. Append server to validatedServers.

  5. Let validatedServers be the ICE servers list.


As noted in [[RFC5245]] Section, 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:

  1. If {{RTCIceTransport/state}} is {{RTCIceTransportState/"closed"}}, [=exception/throw=] an {{InvalidStateError}}.
  2. If remoteParameters.{{RTCIceParameters/usernameFragment}} or remoteParameters.{{RTCIceParameters/password}} is unset, [=exception/throw=] an {{TypeError}}.
  3. If remoteParameters.{{RTCIceParameters/usernameFragment}} or remoteParameters.{{RTCIceParameters/password}} does not conform to the syntax described in [[RFC8839]] Section 5.4, [=exception/throw=] a {{SyntaxError}}.
  4. If {{start()}} is called again and {{RTCIceTransport/role}} is changed, [=exception/throw=] an {{InvalidStateError}}.
  5. If {{start()}} is called again with the same value of remoteParameters, this has no effect.
  6. If {{start()}} is called for the first time, if there are remote candidates, set {{RTCIceTransport/state}} to {{RTCIceTransportState/"checking"}} and start connectivity checks. If there are no remote candidates, {{RTCIceTransport/state}} remains {{RTCIceTransportState/"new"}}.
  7. If {{start()}} is called again but the value of remoteParameters has changed, local candidates are kept, remote candidates are flushed, candidate pairs are flushed and {{RTCIceTransport/state}} transitions to {{RTCIceTransportState/"new"}}.
  8. If {{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 {{RTCIceTransport/state}} transitions to {{RTCIceTransportState/"checking"}}.
  9. If {{start()}} is called again with new values of remoteParameters, local candidates are flushed, remote candidates are flushed, candidate pairs are flushed and {{RTCIceTransport/state}} transitions to {{RTCIceTransportState/"new"}}.

Irreversibly stops the {{RTCIceTransport}}. When {{stop}} is called, the following steps MUST be run:

  1. Let iceTransport be the {{RTCIceTransport}} object on which the {{stop}} method is invoked.
  2. If iceTransport.{{RTCIceTransport/state}} is {{RTCIceTransportState/"closed"}}, abort these steps.
  3. Set iceTransport.{{RTCIceTransport/state}} to {{RTCIceTransportState/"closed"}}.
  4. Fire a simple event 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.

Privacy and Security Considerations

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]].

Impact on same origin policy

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.

Impact on local network

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.

Confidentiality of Communications

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.

Event summary

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.