This document defines a set of ECMAScript APIs in WebIDL to allow construction of an RTCIceTransport interface in situations where such an interface would not be created in the WebRTC 1.0 API (such as when data is exchanged using QUIC). 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.

Introduction

This specification extends the WebRTC specification [[!WEBRTC]] to allow construction of an RTCIceTransport interface in situations where such an interface would not created in the WebRTC 1.0 API, such as when the WebRTC-QUIC extension [[WEBRTC-QUIC]] is used in a scenario involving QUIC data exchange, but not use of audio, video or the SCTP data channel.

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.

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 Extensions

The RTCIceTransport extensions allow construction of an RTCIceTransport without offer/answer.

RTCIceGatherOptions Dictionary

RTCIceGatherOptions provides options relating to the gathering of ICE candidates.

dictionary RTCIceGatherOptions {
             RTCIceTransportPolicy     gatherPolicy;
             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

[ Constructor (), Exposed=Window]
partial interface RTCIceTransport {
    void                      gather (RTCIceGatherOptions options);
    void                      start (RTCIceParameters remoteParameters, optional RTCIceRole role = "controlled");
    void                      stop ();
    void                      addRemoteCandidate (RTCIceCandidate remoteCandidate);
                    attribute EventHandler        onerror;
                    attribute EventHandler        onicecandidate;
};

Constructors

RTCIceTransport
No parameters.

Attributes

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.

Methods

gather

Gather ICE candidates. If state is closed, 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.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.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, 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.

      2. If scheme name is turn or turns, and either of server.username or server.credential are omitted, then throw an InvalidAccessError.

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

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

    4. Append server to validatedServers.

  5. Let validatedServers be the ICE servers list.

Parameter Type Nullable Optional Description
options RTCIceGatherOptions
Return type: void
start

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:

  1. If state is closed, throw an InvalidStateError.
  2. If remoteParameters.usernameFragment or remoteParameters.password is unset, throw an TypeError.
  3. If start() is called again and role is changed, throw an InvalidStateError.
  4. If start() is called again with the same value of remoteParameters, this has no effect.
  5. If 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.
  6. If 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.
  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 state transitions to 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 state transitions to 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 state transitions to new.
Parameter Type Nullable Optional Description
remoteParameters RTCIceParameters
role RTCIceRole = controlled
Return type: void
stop

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.state is closed, abort these steps.
  3. Set iceTransport.state to closed.
  4. Fire a simple event statechange at iceTransport.
No parameters.
Return type: void
addRemoteCandidate

Add a remote candidate associated with the remote RTCIceTransport. If state is closed, throw an InvalidStateError. When the remote RTCIceGatherer emits its final candidate, addRemoteCandidate() should be called with an RTCIceCandidateComplete dictionary as an argument, so that the local RTCIceTransport can know there are no more remote candidates expected, and can enter the completed state.

Parameter Type Nullable Optional Description
remoteCandidate RTCIceCandidate
Return type: void

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 [[RTCWEB-SECURITY-ARCH]].

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.

Examples

      

Change Log

This section will be removed before publication.

Acknowledgements

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.