RTCIceCandidate.usernameFragment

The read-only usernameFragment property on the RTCIceCandidate interface is a string indicating the username fragment ("ufrag") that uniquely identifies a single ICE interaction session.

This value is specified when creating the RTCIceCandidate by setting the corresponding usernameFragment value in the RTCIceCandidateInit object when creating a new candidate with new RTCIceCandidate().

If you instead call RTCIceCandidate() with a string parameter containing the candidate m-line text, the value of usernameFragment is extracted from the m-line.

Syntax

var ufrag = RTCIceCandidate.usernameFragment;

Value

A DOMString containing the username fragment (usually referred to in shorthand as "ufrag" or "ice-ufrag") that, along with the ICE password ("ice-pwd"), uniquely identifies a single ongoing ICE interaction. The string may be up to 256 characters long, and has no default value.

At least 24 bits of the text in the ufrag are required to be randomly selected by the ICE layer at the beginning of the ICE session. The specifics for which bits are random and what the remainder of the ufrag text are are left up to the browser implementation to decide. For example, a browser might choose to always use a 24-character ufrag in which bit 4 of each character is randomly selected between 0 and 1. Another example: it might take a user-defined string and append three 8-bit random bytes to the end. Or perhaps every character is entirely random.

Usage notes

ICE uses the ufrag and password to ensure message integrity. This avoids crosstalk among multiple ongoing ICE sessions, but, more importantly, helps secure ICE transactions (and all of WebRTC by extension) against attacks that might try to inject themselves into an ICE exchange.

Note: There is no API to obtain the ICE password, for what should be fairly obvious security reasons.

The ufrag string remains consistent across multiple generations of the same ICE process, even across ICE restarts.

Example

...

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCIceCandidate.usernameFragment' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support ? ? No ? ? ?
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support ? ? ? No ? ? ?

Document Tags and Contributors

Contributors to this page: Sheppy
Last updated by: Sheppy,