RTCIceCandidate.usernameFragment

在此页

句法
用法注意事项
范例
规范
浏览器兼容性
相关话题

只读 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() . Note that 24 bits of the username fragment are required to be randomized by the browser. See Randomization below for details.

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.

句法

var ufrag = RTCIceCandidate.usernameFragment;

值

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, including for any communication with the STUN server. The string may be up to 256 characters long, and has no default value.

Randomization

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.

用法注意事项

ICE uses the usernameFragment 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.

注意： There is no API to obtain the ICE password, for what should be fairly obvious security reasons.

usernameFragment and password both change every time an ICE restart 出现。

范例

Although the WebRTC infrastructure will filter out obsolete candidates for you after an ICE restart, you can do it yourself if you're trying to absolutely minimize the number of messages going back and forth.

To do so, you can compare the value of usernameFragment to the current usernameFragment being used for the connection after receiving the candidate from the signaling server and before caling addIceCandidate() to add it to the set of possible candidates.

When the web app receives a message from the signaling server that includes a candidate to be added to the RTCPeerConnection , you can (and generally should ) simply call addIceCandidate() . There's not typically a need to manually worry about filtering the candidates.

However, let's imagine that we do need to minimize traffic. The function below, ssNewCandidate() , is called when a message, signalMsg , arrives from the signaling server that contains an ICE candidate to be added to the RTCPeerConnection . To avoid including candidates obsoleted by an ICE restart, we can use code like this:

const ssNewCandidate = signalMsg => {
  let candidate = new RTCIceCandidate(signalMsg.candidate);
  let receivers = pc.getReceivers();
  receivers.forEach(receiver => {
    let parameters = receiver.transport.getParameters();
    if (parameters.usernameFragment === candidate.usernameFragment) {
      return;
    }
  });
  pc.addIceCandidate(candidate)
    .catch(reportError);
}

This walks through the list of the RTCRtpReceiver objects being used to receive ICE data, and looks to see if the usernameFragment indicated in the candidate matches any of them. If it does, ssNewCandidate() aborts. Otherwise, after checking every receiver, it adds the new candidate to the connection.

规范

规范	状态	注释
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'RTCIceCandidate.usernameFragment' in that specification.	候选推荐	初始定义。

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`usernameFragment`	Chrome 74	Edge ≤79	Firefox 67	IE 不支持 No	Opera ?	Safari ?	WebView Android 74	Chrome Android 74	Firefox Android 67	Opera Android ?	Safari iOS ?	Samsung Internet Android 11.0

图例

完整支持
不支持
兼容性未知 ?

元数据

最后修改： May 7, 2019

WebRTC API
RTCIceCandidate
构造函数
1. RTCIceCandidate()
特性
1. address
2. candidate
3. component
4. foundation
5. port
6. priority
7. 协议
8. relatedAddress
9. relatedPort
10. sdpMid
11. sdpMLineIndex
12. usernameFragment
方法
1. toJSON()
Related pages for WebRTC

在此页

句法

值

Randomization

用法注意事项

范例

规范

浏览器兼容性

图例

相关话题