TURN client (RFC 8656)

View Source

This page lists the client-side TURN requirements implemented by webrtc_turn_client (UDP, TCP or TLS to the server) and its use by the ICE agent for relayed candidates. Read it before relying on a relay feature. There is no TURN server in the stack; tests run against the test-only server test/webrtc_test_turn_server.erl.

Client

IDSectionRequirementModuleTestStatus
TURN-15STUN-formatted messages over UDP with FINGERPRINT; SOFTWARE in Allocate and Refreshwebrtc_turn_clientwebrtc_turn_client_tests:allocate_md5_testUnit tested
TURN-25, RFC 8489 6.2.1Request retransmission over UDP, RTO cached per serverwebrtc_turn_client, webrtc_stun_txwebrtc_turn_client_tests:allocate_timeout_testUnit tested
TURN-37.1REQUESTED-TRANSPORT UDP on Allocate; LIFETIME and REQUESTED-ADDRESS-FAMILY when configuredwebrtc_turn_clientwebrtc_turn_client_tests:allocate_md5_testUnit tested (the family option is implemented, untested)
TURN-4RFC 8489 9.2.3.1First Allocate sent without credentialswebrtc_turn_clientwebrtc_turn_client_tests:allocate_md5_testUnit tested
TURN-5RFC 8489 9.2.5401 with REALM and NONCE retried once with USERNAME, REALM, NONCE and MESSAGE-INTEGRITY (MD5 key); a second 401 failswebrtc_turn_client, webrtc_turn_authwebrtc_turn_client_tests:allocate_md5_test, wrong_password_testUnit tested
TURN-6RFC 8489 9.2.5PASSWORD-ALGORITHMS echoed, first supported algorithm in PASSWORD-ALGORITHM, MESSAGE-INTEGRITY-SHA256 only afterwardswebrtc_turn_authwebrtcturn_client_tests:allocate_sha256_test, auth_algorithm_testUnit tested
TURN-7RFC 8489 9.2.1Nonce cookie: "password algorithms" bit without PASSWORD-ALGORITHMS stops the retrywebrtc_turn_authwebrtc_turn_client_tests:challenge_with_cookie_without_algorithms_testUnit tested
TURN-8RFC 8489 9.2.4USERHASH (username anonymity)webrtc_turn_authwebrtcturn_client_tests:auth_algorithm_testNot implemented: a nonce cookie asking for it fails the allocation with {unsupported, userhash}
TURN-9RFC 8489 9.2.5438 retried with the new nonce, at most 3 times in a row, for every requestwebrtc_turn_clientwebrtc_turn_client_tests:stale_nonce_test, refresh_stale_nonce_testUnit tested
TURN-10RFC 8489 9.2.5Responses to authenticated requests discarded unless integrity verifies (401 and 438 excepted); unprotected 400 discardedwebrtc_turn_authwebrtc_turn_client_tests:unauthenticated_success_discarded_testUnit tested
TURN-117.3Relayed address, mapped address and the lifetime granted by the server keptwebrtc_turn_clientwebrtc_turn_client_tests:allocate_md5_testUnit tested
TURN-127.4403, 440, 441, 442, 486, 508 fail the allocation and are reported; no automatic retrywebrtc_turn_clientwebrtcturn_client_tests:allocate_errors_testUnit tested
TURN-137.4300 Try Alternate: the allocation is retried against the ALTERNATE-SERVER with the same credentials, at most three redirections and never back to a server already triedwebrtc_turn_client, webrtc_ice_relaywebrtc_turn_client_tests:try_alternate_test, webrtc_ice_agent_tests:turn_try_alternate_test, turn_alternate_loop_testUnit tested
TURN-147.4437 on Allocate over UDP: the agent asks its owner for a new local port ({open_udp, Ref, #{local := IP}}) and allocates from it, once per serverwebrtc_ice_relay, webrtc_ice_agent, webrtc_transport_netwebrtc_ice_agent_tests:turn_allocation_mismatch_testUnit tested
TURN-157.4Allocate timeout reportedwebrtc_turn_clientwebrtc_turn_client_tests:allocate_timeout_testUnit tested
TURN-168Refresh one minute before expiry (half the lifetime when shorter than two minutes)webrtc_turn_clientwebrtc_turn_client_tests:refresh_test, short_lifetime_refresh_testUnit tested
TURN-178.3437 to a Refresh: allocation lost; to a deletion: successwebrtc_turn_clientwebrtc_turn_client_tests:unauthenticated_success_discarded_test, deallocate_testUnit tested
TURN-188Allocation lost when it expires without a successful Refreshwebrtc_turn_clientwebrtc_turn_client_tests:expiry_without_refresh_testUnit tested
TURN-198.1Deallocation with a Refresh of LIFETIME 0webrtc_turn_clientwebrtc_turn_client_tests:deallocate_testUnit tested
TURN-209, 10.1CreatePermission per peer IP (XOR-PEER-ADDRESS, port ignored), refreshed every 240 s (lifetime 300 s)webrtc_turn_clientwebrtc_turn_client_tests:send_creates_permission_test, permission_refresh_testUnit tested
TURN-2110.3Permission errors reported, data queued for the peer droppedwebrtc_turn_clientwebrtc_turn_client_tests:forbidden_permission_testUnit tested
TURN-2211.1Send indication (XOR-PEER-ADDRESS, DATA) only once the permission is installed; data queued meanwhile (bounded)webrtc_turn_clientwebrtc_turn_client_tests:send_creates_permission_testUnit tested
TURN-2311.4Data indication needs XOR-PEER-ADDRESS, a permission for the peer IP and DATAwebrtc_turn_clientwebrtc_turn_client_tests:data_indication_checks_test, send_creates_permission_testUnit tested
TURN-2411.6ICMP attribute in Data indicationsNot implemented: such indications are ignored
TURN-2512Channel numbers 0x4000 to 0x4FFF, one per peerwebrtc_turn_clientwebrtc_turn_client_tests:channel_testUnit tested
TURN-2612.1, 12.3ChannelBind installs the channel and refreshes the permission; rebound every 540 s (lifetime 600 s)webrtc_turn_clientwebrtc_turn_client_tests:channel_test, channel_refresh_testUnit tested
TURN-27125 minutes before reusing a channel number or peer after expirywebrtc_turn_clientwebrtc_turn_client_tests:lost_channel_bind_testUnit tested: bindings in use are refreshed and never expire while the allocation lives; a number whose ChannelBind failed (possibly installed on the server) and its peer are kept apart for 15 minutes (lifetime plus 5), the same peer getting the number back
TURN-2812.3ChannelBind failure out of sync (400): delete the allocationwebrtc_turn_clientwebrtc_turn_client_tests:channel_out_of_sync_testUnit tested: the allocation is deleted (Refresh with LIFETIME 0) and reported as {allocation_lost, channel_out_of_sync}; the ICE agent removes the relayed candidate
TURN-2912.4, 12.5ChannelData framing, padded to 4 bytes over UDP; Send indications until the binding is confirmedwebrtc_turn_channel, webrtc_turn_clientwebrtcturn_client_tests:channel_test, channel_codec_testUnit tested
TURN-3012.6ChannelData discarded on reserved numbers, short datagrams, unbound channels or without permissionwebrtc_turn_channel, webrtc_turn_clientwebrtcturn_client_tests:channel_codec_test, channel_data_unknown_channel_testUnit tested
TURN-3121Truncated or bit-flipped server messages never crash the clientwebrtc_turn_clientwebrtc_turn_client_tests:malformed_input_testUnit tested
TURN-323.1TCP and TLS-over-TCP to the server (transport of turn_servers): STUN and ChannelData framed on the stream, ChannelData padded to 4 bytes, bytes out of step close the connection; no request retransmission on the stream (RFC 8489 §6.2.2, 39.5 s timeout); TLS server certificate verified against the system CA store and the host name or IP addresswebrtc_turn_stream, webrtc_ice_relay, webrtc_transport_netwebrtc_turn_stream_tests, webrtc_ice_agent_tests:stream_turn_test, stream_turn_connect_failure_test, webrtc_turn_interop_SUITE:relayed_over_tcp, relayed_over_tls, untrusted_tls_no_relayInteroperability tested (pion/turn)
TURN-363.1DTLS-over-UDP to the serverNot implemented: not used by browsers
TURN-337.1ADDITIONAL-ADDRESS-FAMILY, EVEN-PORT, RESERVATION-TOKEN, DONT-FRAGMENTNot implemented (optional)
TURN-344, RFC 5928Server discovery through DNS: see URI-1 to URI-8webrtc_ice_resolvewebrtc_ice_uri_testsUnit and interoperability tested
TURN-35RFC 8489 9.2.2OpaqueString processing of the realm and passwordNon-compliant / known limitation: used as given, see STUN-16

ICE integration

The ICE agent owns one webrtc_turn_client per (host socket, TURN server) and allocates from every host candidate whose family matches the server. For a server reached over TCP or TLS the agent asks its owner to open a connection from the host address ({connect, {stream, N}, Params}), which then plays the role of the host socket; the owner reports it with stream_up/3 and stream_down/4. A relayed candidate is reached through the path {relay, Socket, ServerAddr}: checks, consent requests and data sent from it are wrapped by the client and sent to the server over the host socket; datagrams from the server are unwrapped and fed back to the check processing, or emitted as {data, Via, Peer, Data} when they are not STUN.

IDSectionRequirementModuleTestStatus
TURN-I1RFC 8445 5.1.1.2Relayed and server-reflexive candidates from a successful Allocate; relay identical to a host candidate discardedwebrtc_ice_relaywebrtc_ice_net_tests:srflx_candidate_testUnit tested
TURN-I2RFC 8445 7.2.1Permissions for every remote candidate of the relay's familywebrtc_ice_relaywebrtc_ice_net_tests:symmetric_needs_relay_testUnit tested
TURN-I3RFC 8445 7.3.1.2Requests relayed by the server answered with the peer address the server sawwebrtc_ice_relaywebrtc_ice_net_tests:symmetric_needs_relay_testUnit tested
TURN-I4Channel bound to the peer of a selected relayed pairwebrtc_ice_relaywebrtc_ice_net_tests:symmetric_needs_relay_testUnit tested
TURN-I5Lost allocation removes the relayed candidate and its pairs ({local_candidate_removed, C}, {turn_error, Server, Reason})webrtc_ice_relaywebrtc_ice_net_tests:turn_allocation_lost_testUnit tested
TURN-I6Allocations deleted when the agent closeswebrtc_ice_relaywebrtc_ice_net_tests:close_deletes_allocations_testUnit tested
TURN-I7RFC 8445 5.1.2.1A relay reached over TCP or TLS has a lower local preference than one reached over UDP, and its own foundationwebrtc_ice_relaywebrtc_ice_agent_tests:stream_turn_testUnit tested
TURN-I8A stream that fails to open ends its gathering job; one that closes loses the allocation and its candidate ({turn_error, Server, {stream, Reason}}, {allocation_lost, {stream, Reason}})webrtc_ice_relaywebrtc_ice_agent_tests:stream_turn_test, stream_turn_connect_failure_testUnit tested

Server URIs and discovery

The ice_servers option takes the W3C RTCIceServer list; its URIs are resolved when the peer connection starts (webrtc_pc), and the servers join stun_servers and turn_servers.

IDSpecRequirementModuleTestStatus
URI-1RFC 7064 §3.1stun and stuns URIs: host (IPv4, IPv6 in brackets, registered name with percent-encoding), optional port, default 3478 and 5349; no querywebrtc_ice_urirfcexamples_test, hoststest, refusedtestUnit tested
URI-2RFC 7065 §3.1turn and turns URIs with ?transport=udp or tcp; a transport-ext is refused as unsupported; default ports 3478 and 5349webrtc_ice_urirfcexamples_test, unsupportedtransport_testUnit tested
URI-3RFC 7065 §3, RFC 5928 §3A URI without transport: UDP for turn, TLS over TCP for turnswebrtc_ice_urirfcexamples_testNon-compliant / known limitation: the NAPTR lookup (RFC 5928 step 1, S-NAPTR) is not done, as in browsers
URI-4RFC 5928 §3 steps 1 to 3, RFC 8489 §8.1An IP address is used as is; a name with a port is looked up for A and AAAA (step 2); without a port, SRV _turn._udp, _turn._tcp, _turns._tcp or _stun._udp first (targets by priority, then weight), A and AAAA with the default port when there is none (step 3)webrtc_ice_resolveliteraltest, explicit_port_test, srv_test, srv_names_testUnit tested
URI-5RFC 8489 §8.1, RFC 5928 §3, RFC 8445 §5.1.1.2Both A and AAAA queried; per family the first address of the URI is the server and the others, SRV targets in order, are tried in turn when it does not answer (STUN transaction timeout, TURN allocation timeout, a TCP or TLS connection that fails); a server that answers, even with an error, is not failed over (RFC 8656 §7.3); every address silent gives {ice_server_error, Url, unreachable} oncewebrtc_ice_resolve, webrtc_pc, webrtc_ice_gather, webrtc_ice_relayexplicit_port_test, srv_test, stun_fallback_test, stun_all_unreachable_test, stream_turn_fallback_test, turn_udp_fallback_test, webrtc_turn_interop_SUITE:srv_fallback_tcp, srv_fallback_tlsInteroperability tested (pion/turn)
URI-6RFC 8656 §3.1, RFC 6125turns: TLS to the server, the certificate checked against the name in the URIwebrtc_ice_resolve, webrtc_transport_netwebrtc_turn_interop_SUITE:relayed_by_uri_tlsInteroperability tested (pion/turn)
URI-7W3C webrtc-pc RTCIceServerurls (one or several), username and credential required for TURN; a malformed list refuses the peer connection ({badarg, ice_servers}); a URI that cannot be used is reported as {ice_server_error, Url, Reason} and the others kept; eight servers in all at mostwebrtc, webrtc_pc, webrtc_ice_uriserverstest, peerconnection_testUnit tested
URI-8RFC 7064 §3.1, RFC 8489 §6.2.3stuns (STUN over TLS)serverstestNot implemented: reported as unsupported; binding requests go over UDP

Names resolve in parallel within ice_server_timeout (default 2 s), so starting a peer connection waits at most that long. Fallback addresses do not count toward the eight servers. A server given in stun_servers or turn_servers must be an IP address ({badarg, {server_address, A}} otherwise).

Notes

  • Specification status checked on 2026-11-14 at rfc-editor.org: RFC 8656 and RFC 8489 have no update or obsoleting document.
  • Per-allocation state is bounded: data queued while a permission is pending (64 datagrams per peer IP), permissions and channels follow the remote candidates the ICE agent keeps (max_remote).
IDSpecRequirementModuleTestStatus
TURN-INTEROP-17, 9, 11Allocate with the 401 retry, permissions for remote candidates and relayed connectivity checks and data, against an independent server (pion/turn v5)webrtc_turn_client, webrtc_ice_relaywebrtc_turn_interop_SUITE (relay/relay, relay/host, wrong password)Interoperability tested
TURN-INTEROP-28Allocations deleted with a zero lifetime Refresh when the peer connection closeswebrtc_transport, webrtc_ice_relaywebrtc_security_SUITE:turn_allocation_deleted_on_closeE2E tested