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
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.
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
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.
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
Extensions
The
extensions
allow
construction
of
an
RTCIceTransport
without
offer/answer.
RTCIceTransport
RTCIceGatherOptions
Dictionary
RTCIceGatherOptions
provides
options
relating
to
the
gathering
of
ICE
candidates.
WebIDLdictionaryRTCIceGatherOptions{RTCIceTransportPolicygatherPolicy;sequence<RTCIceServer>iceServers; sequence<DOMString>?networkIds; };
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.
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{attribute attributevoidgather(RTCIceGatherOptionsoptions); voidstart(RTCIceParameters remoteParameters, optionalRTCIceRolerole = "controlled"); voidstop(); voidaddRemoteCandidate(RTCIceCandidateremoteCandidate); voidretainLocalCandidate(RTCIceCandidatelocalCandidate); voidremoveLocalCandidate(RTCIceCandidatelocalCandidate); sequence<RTCIceCandidatePair>getCandidatePairs();RTCIceTransportfork(); attribute EventHandleronerror; attribute EventHandleronlocalcandidate; attribute EventHandleronchecksent; };
RTCIceTransport
onerror
of
type
EventHandler
This
event
handler,
of
event
handler
event
type
,
MUST
be
fired
if
an
error
occurs
in
the
gathering
of
ICE
candidates
(such
as
if
TURN
credentials
are
invalid).
icecandidateerror
onicecandidate
onlocalcandidate
of
type
EventHandler
This
event
handler
utilizes
the
event
handler
event
type
.
icecandidate
onchecksent
of
type
EventHandler
This
event
handler
utilizes
the
event
handler
event
type
icecheck
.
gather
Gather
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
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
object
can
respond
to
incoming
connectivity
checks
based
on
its
configured
role.
Since
RTCIceTransport
start()
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
stop
Irreversibly
stops
the
.
When
RTCIceTransport
stop
is
called,
the
following
steps
MUST
be
run:
RTCIceTransport
object
on
which
the
stop
method
is
invoked.
iceTransport
.state
is
closed
,
abort
these
steps.
iceTransport
.state
to
closed
.
statechange
at
iceTransport
.
void
addRemoteCandidate
Add
a
remote
candidate
associated
with
the
remote
.
If
RTCIceTransport
state
is
closed
,
throw
an
InvalidStateError
.
When
the
remote
RTCIceGatherer
emits
its
final
candidate,
should
be
called
with
an
addRemoteCandidate
()
RTCIceCandidateComplete
dictionary
as
an
argument,
so
that
the
local
can
know
there
are
no
more
remote
candidates
expected,
and
can
enter
the
RTCIceTransport
completed
state.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| remoteCandidate |
| ✘ | ✘ |
void
removeLocalCandidate
Removes 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
retainLocalCandidate
Cause 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
DOMString
networkInfo
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);
};
setMinCheckInterval
Causes 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
setFrozen
Freezes or unfreezes the candidate pair. When frozen, no ICE checks will be sent over it.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| frozen |
boolean
| ✘ | ✘ |
void
select
Selects 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
nominate
Nominates 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>
waitForReceiveTimeout
Wait 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
boolean
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 ].
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
objects:
RTCIceTransport
| Event name | Interface | Fired when... |
|---|---|---|
icecandidateerror
|
|
The
object
has
experienced
an
ICE
gathering
failure
(such
as
an
authentication
failure
with
TURN
credentials).
|
icecandidate
|
|
A
new
is
made
available
to
the
script.
|
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
object
was
initially
described
in
the
W3C
ORTC
CG
,
and
has
been
adapted
for
use
in
this
specification.
RTCIceTransport