webrtc_ice_candidate (webrtc v0.1.0)

View Source

ICE candidates: priorities, foundations, pair priorities, redundancy elimination and the RFC 8839 candidate-attribute syntax.

Candidates are #ice_cand{} records (include/webrtc_ice.hrl).

  • priority/3 is the RFC 8445 §5.1.2.1 formula with the recommended type preferences of §5.1.2.2.
  • local_preferences/1 orders the host addresses of a multihomed or dual-stack agent as RFC 8421 recommends (IPv6 first, then IPv4 and IPv6 intermingled) and gives each one a unique local preference. Derived candidates (server-reflexive, relayed) use local_preference/2 so that different servers keep unique values.
  • foundation/4 implements §5.1.1.3: equal type, base IP, server IP and transport give equal foundations.
  • pair_priority/2 is the 64-bit §6.1.2.3 formula.
  • to_sdp/1 and from_sdp/1 encode and parse the value of an a=candidate attribute (RFC 8839 §5.1), as used by trickle ICE signaling.

Summary

Functions

RFC 8445 §6.1.2.2: same component, same address family, same transport, and IPv6 link-local only with link-local. A relayed local candidate is never paired with a remote candidate resolved from an mDNS name, which would reveal the peer's host address to the TURN server (draft-ietf-mmusic-mdns-ice-candidates-03 §3.3.2).

A candidate is redundant if its transport address and base equal those of another candidate; the one with the lower priority goes.

RFC 8445 §5.1.1.3 foundation. ServerIP is the IP address used to reach the STUN or TURN server, undefined for host and peer-reflexive candidates.

Parse a candidate attribute value. Accepts an optional a= and candidate: prefix. Connection addresses must be IP literals; FQDN (including mDNS) candidates are reported as {error, {fqdn, Name}} because resolving them is the owner's job.

True when Cand has the same transport address, base and component as one of Others.

Local preference for the host candidate of rank Rank (0 is the most preferred) and the server of index ServerIdx (0 for the host candidate itself).

Order host IP addresses as recommended by RFC 8421 §4 and give each one a unique local preference. IPv6 addresses get a head start of (N4 + N6) div N4 positions, then the families alternate. The relative order within a family is kept, so callers list their preferred interface first.

RFC 8445 §6.1.2.3: 2^32*MIN(G,D) + 2*MAX(G,D) + (G>D?1:0) where G is the priority of the controlling agent's candidate.

RFC 8445 §5.1.2.1: (2^24)*type pref + (2^8)*local pref + (256 - component).

Random 24 character password (144 bits, RFC 8445 §5.3 asks >= 128).

Random 8 character ufrag (48 bits, RFC 8445 §5.3 asks >= 24).

RFC 6544 §4.2: local preference of a TCP candidate, 2^13 * direction-pref + other-pref, with the direction preference of host candidates (active 6, passive 4, simultaneous-open 2) and the other preference 0..8191 from the host rank. It stays below the local preference of UDP host candidates, so UDP paths are preferred.

Encode the value of an a=candidate attribute, prefixed with candidate:.

ice-pwd: 22 to 256 ice-chars.

ice-ufrag: 4 to 256 ice-chars.

Types

address/0

-type address() :: {inet:ip_address(), inet:port_number()}.

role/0

-type role() :: controlling | controlled.

type/0

-type type() :: host | srflx | prflx | relay.

Functions

can_pair(Ice_cand, Ice_cand)

-spec can_pair(#ice_cand{foundation :: binary(),
                         component :: 1..256,
                         transport :: udp | tcp,
                         priority :: 1..2147483647,
                         address :: inet:ip_address(),
                         port :: inet:port_number(),
                         type :: host | srflx | prflx | relay,
                         related_address :: inet:ip_address() | undefined,
                         related_port :: inet:port_number() | undefined,
                         tcptype :: active | passive | so | undefined,
                         extensions :: [{binary(), binary()}],
                         base :: {inet:ip_address(), inet:port_number()} | undefined,
                         socket :: term(),
                         server :: {inet:ip_address(), inet:port_number()} | undefined},
               #ice_cand{foundation :: binary(),
                         component :: 1..256,
                         transport :: udp | tcp,
                         priority :: 1..2147483647,
                         address :: inet:ip_address(),
                         port :: inet:port_number(),
                         type :: host | srflx | prflx | relay,
                         related_address :: inet:ip_address() | undefined,
                         related_port :: inet:port_number() | undefined,
                         tcptype :: active | passive | so | undefined,
                         extensions :: [{binary(), binary()}],
                         base :: {inet:ip_address(), inet:port_number()} | undefined,
                         socket :: term(),
                         server :: {inet:ip_address(), inet:port_number()} | undefined}) ->
                  boolean().

RFC 8445 §6.1.2.2: same component, same address family, same transport, and IPv6 link-local only with link-local. A relayed local candidate is never paired with a remote candidate resolved from an mDNS name, which would reveal the peer's host address to the TURN server (draft-ietf-mmusic-mdns-ice-candidates-03 §3.3.2).

eliminate_redundant(Cands)

-spec eliminate_redundant([#ice_cand{foundation :: binary(),
                                     component :: 1..256,
                                     transport :: udp | tcp,
                                     priority :: 1..2147483647,
                                     address :: inet:ip_address(),
                                     port :: inet:port_number(),
                                     type :: host | srflx | prflx | relay,
                                     related_address :: inet:ip_address() | undefined,
                                     related_port :: inet:port_number() | undefined,
                                     tcptype :: active | passive | so | undefined,
                                     extensions :: [{binary(), binary()}],
                                     base :: {inet:ip_address(), inet:port_number()} | undefined,
                                     socket :: term(),
                                     server :: {inet:ip_address(), inet:port_number()} | undefined}]) ->
                             [#ice_cand{foundation :: binary(),
                                        component :: 1..256,
                                        transport :: udp | tcp,
                                        priority :: 1..2147483647,
                                        address :: inet:ip_address(),
                                        port :: inet:port_number(),
                                        type :: host | srflx | prflx | relay,
                                        related_address :: inet:ip_address() | undefined,
                                        related_port :: inet:port_number() | undefined,
                                        tcptype :: active | passive | so | undefined,
                                        extensions :: [{binary(), binary()}],
                                        base :: {inet:ip_address(), inet:port_number()} | undefined,
                                        socket :: term(),
                                        server :: {inet:ip_address(), inet:port_number()} | undefined}].

A candidate is redundant if its transport address and base equal those of another candidate; the one with the lower priority goes.

family(_)

-spec family(inet:ip_address()) -> ipv4 | ipv6.

foundation(Type, BaseIP, ServerIP, Transport)

-spec foundation(type(), inet:ip_address(), inet:ip_address() | undefined, udp | tcp) -> binary().

RFC 8445 §5.1.1.3 foundation. ServerIP is the IP address used to reach the STUN or TURN server, undefined for host and peer-reflexive candidates.

from_sdp(Str)

-spec from_sdp(binary() | string()) ->
                  {ok,
                   #ice_cand{foundation :: binary(),
                             component :: 1..256,
                             transport :: udp | tcp,
                             priority :: 1..2147483647,
                             address :: inet:ip_address(),
                             port :: inet:port_number(),
                             type :: host | srflx | prflx | relay,
                             related_address :: inet:ip_address() | undefined,
                             related_port :: inet:port_number() | undefined,
                             tcptype :: active | passive | so | undefined,
                             extensions :: [{binary(), binary()}],
                             base :: {inet:ip_address(), inet:port_number()} | undefined,
                             socket :: term(),
                             server :: {inet:ip_address(), inet:port_number()} | undefined}} |
                  {error, term()}.

Parse a candidate attribute value. Accepts an optional a= and candidate: prefix. Connection addresses must be IP literals; FQDN (including mDNS) candidates are reported as {error, {fqdn, Name}} because resolving them is the owner's job.

is_redundant(Ice_cand, Others)

-spec is_redundant(#ice_cand{foundation :: binary(),
                             component :: 1..256,
                             transport :: udp | tcp,
                             priority :: 1..2147483647,
                             address :: inet:ip_address(),
                             port :: inet:port_number(),
                             type :: host | srflx | prflx | relay,
                             related_address :: inet:ip_address() | undefined,
                             related_port :: inet:port_number() | undefined,
                             tcptype :: active | passive | so | undefined,
                             extensions :: [{binary(), binary()}],
                             base :: {inet:ip_address(), inet:port_number()} | undefined,
                             socket :: term(),
                             server :: {inet:ip_address(), inet:port_number()} | undefined},
                   [#ice_cand{foundation :: binary(),
                              component :: 1..256,
                              transport :: udp | tcp,
                              priority :: 1..2147483647,
                              address :: inet:ip_address(),
                              port :: inet:port_number(),
                              type :: host | srflx | prflx | relay,
                              related_address :: inet:ip_address() | undefined,
                              related_port :: inet:port_number() | undefined,
                              tcptype :: active | passive | so | undefined,
                              extensions :: [{binary(), binary()}],
                              base :: {inet:ip_address(), inet:port_number()} | undefined,
                              socket :: term(),
                              server :: {inet:ip_address(), inet:port_number()} | undefined}]) ->
                      boolean().

True when Cand has the same transport address, base and component as one of Others.

local_preference(Rank, ServerIdx)

-spec local_preference(non_neg_integer(), 0..7) -> 0..65535.

Local preference for the host candidate of rank Rank (0 is the most preferred) and the server of index ServerIdx (0 for the host candidate itself).

local_preferences(IPs)

-spec local_preferences([inet:ip_address()]) -> [{inet:ip_address(), 0..65535}].

Order host IP addresses as recommended by RFC 8421 §4 and give each one a unique local preference. IPv6 addresses get a head start of (N4 + N6) div N4 positions, then the families alternate. The relative order within a family is kept, so callers list their preferred interface first.

pair_priority(G, D)

-spec pair_priority(non_neg_integer(), non_neg_integer()) -> non_neg_integer().

RFC 8445 §6.1.2.3: 2^32*MIN(G,D) + 2*MAX(G,D) + (G>D?1:0) where G is the priority of the controlling agent's candidate.

pair_priority(Local, Remote, _)

-spec pair_priority(non_neg_integer(), non_neg_integer(), role()) -> non_neg_integer().

priority(Type, LocalPref, Component)

-spec priority(type(), 0..65535, 1..256) -> 1..2147483647.

RFC 8445 §5.1.2.1: (2^24)*type pref + (2^8)*local pref + (256 - component).

random_pwd()

-spec random_pwd() -> binary().

Random 24 character password (144 bits, RFC 8445 §5.3 asks >= 128).

random_ufrag()

-spec random_ufrag() -> binary().

Random 8 character ufrag (48 bits, RFC 8445 §5.3 asks >= 24).

tcp_local_preference(TcpType, Rank)

-spec tcp_local_preference(active | passive | so, non_neg_integer()) -> 0..65535.

RFC 6544 §4.2: local preference of a TCP candidate, 2^13 * direction-pref + other-pref, with the direction preference of host candidates (active 6, passive 4, simultaneous-open 2) and the other preference 0..8191 from the host rank. It stays below the local preference of UDP host candidates, so UDP paths are preferred.

to_sdp(Ice_cand)

-spec to_sdp(#ice_cand{foundation :: binary(),
                       component :: 1..256,
                       transport :: udp | tcp,
                       priority :: 1..2147483647,
                       address :: inet:ip_address(),
                       port :: inet:port_number(),
                       type :: host | srflx | prflx | relay,
                       related_address :: inet:ip_address() | undefined,
                       related_port :: inet:port_number() | undefined,
                       tcptype :: active | passive | so | undefined,
                       extensions :: [{binary(), binary()}],
                       base :: {inet:ip_address(), inet:port_number()} | undefined,
                       socket :: term(),
                       server :: {inet:ip_address(), inet:port_number()} | undefined}) ->
                binary().

Encode the value of an a=candidate attribute, prefixed with candidate:.

transport_address(Ice_cand)

-spec transport_address(#ice_cand{foundation :: binary(),
                                  component :: 1..256,
                                  transport :: udp | tcp,
                                  priority :: 1..2147483647,
                                  address :: inet:ip_address(),
                                  port :: inet:port_number(),
                                  type :: host | srflx | prflx | relay,
                                  related_address :: inet:ip_address() | undefined,
                                  related_port :: inet:port_number() | undefined,
                                  tcptype :: active | passive | so | undefined,
                                  extensions :: [{binary(), binary()}],
                                  base :: {inet:ip_address(), inet:port_number()} | undefined,
                                  socket :: term(),
                                  server :: {inet:ip_address(), inet:port_number()} | undefined}) ->
                           address().

type_preference(_)

-spec type_preference(type()) -> 0..126.

valid_pwd(P)

-spec valid_pwd(term()) -> boolean().

ice-pwd: 22 to 256 ice-chars.

valid_ufrag(U)

-spec valid_ufrag(term()) -> boolean().

ice-ufrag: 4 to 256 ice-chars.