§ 3.3  Module 3 — The Broken Internet: NAT and the Art of Hole Punching

TURN: The Relay of Last Resort

In these situations, it is necessary for the host to use the services of an intermediate node that acts as a communication relay.— RFC 5766, April 2010

3.3.1When relay is mandatory, not optional

Lesson 3.2 ended with a taxonomy: RFC 4787 classifies a NAT by its mapping behavior (does the same internal socket get the same public mapping for every destination?) and its filtering behavior (which remote sources may send inbound through that mapping?). Hole punching, which ICE will systematize in the next lesson, relies on each side learning a public address for the other that will still be valid when packets actually fly.

Run the grid and one cell fails absolutely. If peer A’s NAT is endpoint-independent in its mapping, the server-reflexive address A learned from STUN is exactly the address A will present to B, and B’s first packets toward it open B’s own filter on the way out. This holds even if B’s NAT is “symmetric” — address-and-port-dependent mapping: B’s outbound checks toward A’s stable address create a fresh mapping, A sees the new source port, and ICE simply promotes it as a peer-reflexive candidate. One-sided symmetric NATs usually connect. But when both sides have address-and-port-dependent mapping, neither side can tell the other an address that will be valid for the real conversation: every prediction is stale on arrival. No cleverness fixes this — the information needed does not exist outside the two NATs. The only escape is a third party with a genuinely public address that both sides can reach outbound: a relay. That is the computation behind the phrase relay of last resort, and it is why any production deployment that omits TURN is quietly dropping the double-symmetric cell of the grid, plus every network that blocks UDP altogether.

3.3.2Allocations, permissions, and channels

TURN is an extension of STUN: same 20-byte header, same attribute encoding, same transaction model, new methods. A client begins by sending an Allocate request to the server (default port 3478, like STUN). The first attempt fails by design: the server answers 401 with a REALM and a NONCE, the client computes a message-integrity key from its credentials, and retries. On success the server reserves a relayed transport address — a public UDP socket on the server itself, say 203.0.113.15:49152 — that will forward traffic on the client’s behalf. That reservation is the allocation. It is soft state: the response carries a LIFETIME (600 seconds by default), and the client must send Refresh requests before expiry or the server reclaims the port. A Refresh with lifetime 0 deletes it politely.

An allocation alone relays nothing, because an open public socket that forwarded packets from anyone would be a reflection-attack machine. The client must install a permission for each peer it expects: a CreatePermission request naming the peer’s IP address. Permissions live 300 seconds and must likewise be refreshed; once a permission expires, the server silently discards that peer’s packets. With a permission in place there are two ways to move data. The simple way is a pair of STUN messages: the client wraps outgoing payloads in Send indications naming the peer (XOR-PEER-ADDRESS) and carrying the payload (DATA); the server unwraps them onto the wire and wraps inbound packets in Data indications going back. Indications need no acknowledgment, but each one costs roughly 36 bytes of framing — a 20-byte STUN header plus the two attributes — on every single packet, forever.

The efficient way is a channel. A ChannelBind request associates a 16-bit channel number (0x4000–0x4FFF, RFC 8656 §12) with one peer address; the binding lasts 600 seconds and installs or refreshes the matching permission as a side effect. Thereafter both directions use ChannelData messages: 2 bytes of channel number, 2 bytes of length, then the raw payload — 4 bytes of overhead instead of 36. For media flowing 50 packets a second in each direction, that difference is real money, which is a theme we will return to. Note one asymmetry that surprises people: whatever transport the client uses to reach the TURN server, the relayed leg from server to peer is always plain UDP under RFC 8656 (TCP allocations exist separately, in RFC 6062, and are rare in WebRTC practice).

A quick mid-lesson check before we climb the transport ladder.

3.3.3The transport ladder: UDP, TCP, then TLS on 443

Everything above assumed the client can reach the TURN server at all. Hostile networks defeat this in layers, and the configuration answer is a ladder of URIs, standardized in RFC 7065 (November 2013 — Petit-Huguenin, Nandakumar, Salgueiro, Jones). turn:host:3478?transport=udp is the happy path. Networks that drop all outbound UDP — a common corporate posture — fall through to turn:host:3478?transport=tcp. Networks fronted by a proxy that permits outbound TCP only to port 443, and often only when it looks like TLS, leave exactly one rung: turns:host:443?transport=tcp, TURN inside a TLS session on the HTTPS port. (Absent an explicit port, turn: defaults to 3478 and turns: to 5349.) That last rung is what saved the enterprise deployment in the opening note: from the proxy’s point of view the call became one more long-lived HTTPS connection. The rungs are ordered by quality as well as reachability — a TCP or TLS leg to the relay reintroduces head-of-line blocking for the media riding it, so you take the highest rung the network allows.

In the browser this ladder is just the iceServers list handed to RTCPeerConnection. Listing every rung is standard practice; ICE gathers relay candidates from each and its priority rules keep them at the bottom of the pile unless nothing else survives.

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.example.com:3478' },
    {
      urls: [
        'turn:relay.example.com:3478?transport=udp',
        'turn:relay.example.com:3478?transport=tcp',
        'turns:relay.example.com:443?transport=tcp',
      ],
      username: '1760812345:alice',      // ephemeral, see § 3.3.4
      credential: 'nGh2k…base64…',
    },
  ],
  // Drill mode: force relay to prove TURN works BEFORE a customer needs it.
  // iceTransportPolicy: 'relay',
});

Listing 3.3.1 — The canonical hostile-network configuration: every rung of the ladder, plus the relay-only test switch.

iceTransportPolicy: 'relay' deserves respect as a testing tool. With it set, ICE discards host and server-reflexive candidates and will use relayed candidates only; with no working TURN server configured, gathering completes with zero candidates and the connection can never form. Running your integration tests with relay-only policy is the cheapest way to discover a broken TURN fleet before the 10–20% of users who genuinely need it do. It is also a deliberate product feature: “hide my IP address from the far end” in privacy-sensitive applications is implemented as exactly this policy.

3.3.4Credentials: long-term, ephemeral, and hygienic

Because relayed bytes cost the operator money, every allocation is authenticated. The base mechanism is STUN’s long-term credential scheme (RFC 8489 §9.2): username, realm, and password combine into a key — classically MD5 of username:realm:password — that HMACs each request’s MESSAGE-INTEGRITY attribute, with the server’s NONCE preventing replay. The name “long-term” is the problem. A WebRTC application must place the username and credential into JavaScript running in the user’s browser, where “view source” defeats it; a static TURN password shipped to every client is best understood as public, and strangers will happily relay their traffic on your bill.

Production systems therefore mint ephemeral credentials, following a convention published by Justin Uberti in 2013 (draft-uberti-behave-turn-rest, “A REST API for Access to TURN Services”) and implemented by coturn — Oleg Moskalenko’s open-source server, itself descended from the rfc5766-turn-server project — as use-auth-secret. The trick requires no protocol change: your application server and the TURN server share one secret; the username is an expiry timestamp (optionally timestamp:userid), and the password is base64(HMAC-SHA1(secret, username)). The TURN server can verify any such pair statelessly, and a leaked credential dies at its timestamp. Hygiene follows directly: issue credentials from an authenticated endpoint at call-join time, scope lifetimes to hours not months, never commit the shared secret to client code or version control, and rotate it like any other key. When a browser shows you a prompt-free way to test a relay — the well-known Trickle ICE sample page — remember that anything you paste there stays as public as you made it.

3.3.5Relay economics — and what TURN cannot see

How often does the last resort actually fire? Consistently, across published operator measurements, on the order of 10–20% of production sessions: the double-symmetric grid cell, plus UDP-hostile corporate and hotel networks, plus carrier-grade NAT on mobile. That number turns TURN from a protocol detail into a line item. A relayed call routes its media — both directions — through your server: at a typical 1 Mbps-per-direction video call, every 100 concurrent relayed calls demand roughly 200 Mbps of sustained relay throughput, and cloud egress at that rate is often the single largest infrastructure cost of a calling product. This is why mature teams put TURN percentage on a dashboard next to revenue: a sudden rise means a network path regressed (or a big customer deployed a stricter proxy); a sudden fall to zero usually means your relay fleet is down and the 10–20% are failing silently. The measurement comes from getStats: find the succeeded, nominated candidate-pair, look up its localCandidateId, and check whether that candidate’s candidateType is 'relay' (the relayProtocol field even tells you which rung of the ladder — udp, tcp, or tls — carried it).

async function callUsedRelay(pc) {
  const stats = await pc.getStats();
  for (const s of stats.values()) {
    if (s.type === 'candidate-pair' && s.state === 'succeeded' && s.nominated) {
      const local = stats.get(s.localCandidateId);
      return !!local && local.candidateType === 'relay';
    }
  }
  return false;
}

Listing 3.3.2 — The one-liner behind every TURN-percentage dashboard.

The economics make people nervous about a different question: if all my media flows through a rented middlebox, can its operator watch my calls? No — and it is worth being precise about why. The keys that protect WebRTC media are negotiated end-to-end by DTLS-SRTP: the DTLS handshake runs between the two peers, through the relay, and TURN sits entirely below it in the stack. What the relay forwards is SRTP ciphertext (and DTLS records) it has no keys for. A compromised TURN server is not harmless — it sees metadata: both parties’ transport addresses, session timing, and traffic volume — but the media itself is opaque. This is also why lesson 7 will need a different tool (SFrame and insertable streams) for the SFU case, where the server, unlike TURN, deliberately terminates the encryption.

Problems for § 3.3Check your understanding

One coding drill against the corporate-firewall war story, and one scenario matrix on when the last resort actually fires.

¶Field quirks

What the specifications say, and what the browsers actually do, are two different documents. These are the divergences that cost production teams their weekends.