ICE, STUN and TURN

candidate:1470850663 1 udp 2113937151 2ac62b8c-6ece-479f-803a-5becef4db60c.local 61731 typ host generation 0 ufrag uXsD network-cost 999
candidate:2221953911 1 udp 1677729535 198.51.100.4 58144 typ srflx raddr 0.0.0.0 rport 0 generation 0 ufrag uXsD network-cost 999
candidate:102955130 1 udp 50339839 203.0.113.10 40533 typ relay raddr 198.51.100.4 rport 58144 generation 0 ufrag uXsD network-cost 999

peer.onicecandidate = ({ candidate }) => signalling.send({ type: 'candidate', to: remoteId, candidate });
signalling.on('candidate', ({ candidate }) => peer.addIceCandidate(candidate).catch(ignoreIfStale));

turn:turn.example.test:3478?transport=udp       lowest latency, blocked by some corporate firewalls
turn:turn.example.test:3478?transport=tcp       works through UDP-blocking firewalls, head-of-line blocking
turns:turn.example.test:443?transport=tcp       TLS on 443, passes inspecting proxies that allow HTTPS

# Huddle TURN lab: coturn, eturnal and the ephemeral-credentials endpoint.
# Start:  TURN_HOST=<your LAN IP> docker compose up -d   (see the page: Chrome binds UDP sockets to LAN addresses)
# Stop:   docker compose down -v
name: huddle-turn

services:
  coturn:
    image: coturn/coturn:4.18.0
    # The image's entrypoint is turnserver; every option comes from the mounted file.
    command: ["-c", "/etc/coturn/turnserver.conf"]
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro
    networks:
      huddle:
        ipv4_address: 172.29.185.10
    ports:
      - "40500:3478/udp"
      - "40500:3478/tcp"
      - "40510-40540:40510-40540/udp"
    restart: unless-stopped

  eturnal:
    image: ghcr.io/processone/eturnal:1.12.3
    volumes:
      - ./eturnal.yml:/opt/eturnal/etc/eturnal.yml:ro
    networks:
      huddle:
        ipv4_address: 172.29.185.11
    ports:
      - "40501:3478/udp"
      - "40545-40575:40545-40575/udp"
    restart: unless-stopped

  credentials:
    image: node:24-alpine
    working_dir: /app
    command: ["node", "server.mjs"]
    environment:
      PORT: "8080"
      TURN_SHARED_SECRET: example-shared-secret-change-me
      HUDDLE_API_TOKEN: example-session-token
      TURN_HOST: ${TURN_HOST:-127.0.0.1}
      TURN_PORT: "40500"
      TURN_TTL_SECONDS: "3600"
    volumes:
      - ./creds-server/server.mjs:/app/server.mjs:ro
      - ./public:/app/public:ro
    networks: [huddle]
    ports:
      - "40502:8080"
    restart: unless-stopped

networks:
  huddle:
    ipam:
      config:
        - subnet: 172.29.185.0/24

# coturn 4.18.0 configuration for the Huddle lab
listening-port=3478
min-port=40510
max-port=40540

# Ephemeral credentials (TURN REST API): username is "<expiry>:<user>",
# password is base64(HMAC-SHA1(static-auth-secret, username)).
use-auth-secret
static-auth-secret=example-shared-secret-change-me
realm=huddle.example.test

# Behind NAT or in a cloud VM, advertise the public address of the relay:
#external-ip=203.0.113.10/172.29.185.10

# Never let a client use the relay to reach internal services (SSRF protection).
no-multicast-peers
denied-peer-ip=0.0.0.0-0.255.255.255
denied-peer-ip=127.0.0.0-127.255.255.255
denied-peer-ip=169.254.0.0-169.254.255.255
denied-peer-ip=100.64.0.0-100.127.255.255
denied-peer-ip=192.168.0.0-192.168.255.255
denied-peer-ip=10.0.0.0-10.255.255.255
# 172.16.0.0/12 is deliberately NOT denied in this lab: both browser peers are
# relayed through the same server and their relay addresses live in the Docker
# network. In production add: denied-peer-ip=172.16.0.0-172.31.255.255

# Limits
user-quota=12
total-quota=1200
max-bps=3000000
bps-capacity=0
stale-nonce=600

# Hygiene
fingerprint
no-tls
log-file=stdout
simple-log

# eturnal 1.12.3 configuration for the Huddle lab
eturnal:
  # A list of secrets is accepted too: credentials derived from any entry are valid, which allows rotation.
  secret: "example-shared-secret-change-me"
  realm: "huddle.example.test"
  listen:
    - ip: "::"
      port: 3478
      transport: udp
    - ip: "::"
      port: 3478
      transport: tcp
  # The address clients must reach the relay on: the server's public IPv4 address.
  relay_ipv4_addr: "172.29.185.11"
  relay_min_port: 40545
  relay_max_port: 40575
  strict_expiry: true        # reject expired credentials when sessions are refreshed
  max_permissions: 10
  # blacklist_peers defaults to "recommended"; the lab whitelists the Docker network.
  whitelist_peers:
    - "172.16.0.0/12"
  log_level: info
  log_dir: stdout
  modules:
    mod_log_stun: {}

// server.mjs: ephemeral TURN credentials for Huddle (Node.js 24, no dependencies)
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';
import { readFile } from 'node:fs/promises';

const {
  PORT = '8080',
  TURN_SHARED_SECRET,
  HUDDLE_API_TOKEN,
  TURN_HOST = 'turn.example.test',
  TURN_PORT = '3478',
  TURN_TTL_SECONDS = '3600',
} = process.env;

if (!TURN_SHARED_SECRET || !HUDDLE_API_TOKEN) {
  throw new Error('TURN_SHARED_SECRET and HUDDLE_API_TOKEN are required');
}

/** username = "<unix expiry>:<user id>", credential = base64(HMAC-SHA1(secret, username)) */
export function turnCredentials(userId, secret, ttlSeconds, now = Date.now()) {
  const expiry = Math.floor(now / 1000) + ttlSeconds;
  const username = `${expiry}:${userId}`;
  const credential = createHmac('sha1', secret).update(username).digest('base64');
  return { username, credential, ttl: ttlSeconds };
}

function authorised(header = '') {
  const given = Buffer.from(header.replace(/^Bearer /, ''));
  const wanted = Buffer.from(HUDDLE_API_TOKEN);
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

const server = createServer(async (req, res) => {
  const url = new URL(req.url, 'http://localhost');
  if (url.pathname === '/turn-credentials' && req.method === 'GET') {
    if (!authorised(req.headers.authorization)) {
      res.writeHead(401, { 'WWW-Authenticate': 'Bearer' }).end();
      return;
    }
    // In Huddle the user id comes from the verified session, not from the query string.
    const userId = url.searchParams.get('user') ?? 'anonymous';
    const { username, credential, ttl } = turnCredentials(userId, TURN_SHARED_SECRET, Number(TURN_TTL_SECONDS));
    const body = {
      username,
      credential,
      ttl,
      iceServers: [
        { urls: `stun:${TURN_HOST}:${TURN_PORT}` },
        {
          urls: [`turn:${TURN_HOST}:${TURN_PORT}?transport=udp`, `turn:${TURN_HOST}:${TURN_PORT}?transport=tcp`],
          username,
          credential,
        },
      ],
    };
    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
    res.end(JSON.stringify(body));
    return;
  }
  if (url.pathname === '/ice-check.html') {
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
    res.end(await readFile(new URL('./public/ice-check.html', import.meta.url)));
    return;
  }
  res.writeHead(404).end();
});

server.listen(Number(PORT), () => console.log(`credentials endpoint on :${PORT}`));

// huddle-ice.mjs: create peer connections with fresh TURN credentials
let iceServers = [];
let refreshTimer;

async function refreshIceServers(sessionToken) {
  const response = await fetch('/turn-credentials', { headers: { Authorization: `Bearer ${sessionToken}` } });
  if (!response.ok) throw new Error(`credentials request failed: ${response.status}`);
  const { iceServers: servers, ttl } = await response.json();
  iceServers = servers;
  clearTimeout(refreshTimer);
  // Ask for new credentials when 80 percent of the lifetime has passed.
  refreshTimer = setTimeout(() => refreshIceServers(sessionToken), ttl * 800);
}

export async function createPeer(sessionToken, { relayOnly = false } = {}) {
  if (iceServers.length === 0) await refreshIceServers(sessionToken);
  const peer = new RTCPeerConnection({ iceServers, iceTransportPolicy: relayOnly ? 'relay' : 'all' });
  peer.addEventListener('icecandidateerror', (event) => {
    // 701 means the server could not be reached; 300-699 are STUN/TURN error codes (401: bad credentials).
    console.warn('ICE server error', event.errorCode, event.errorText, event.url);
  });
  peer.addEventListener('connectionstatechange', () => {
    if (peer.connectionState === 'failed') {
      peer.setConfiguration({ ...peer.getConfiguration(), iceServers });
      peer.restartIce();
    }
  });
  return peer;
}

<!doctype html>
<meta charset="utf-8">
<title>Huddle ICE check</title>
<pre id="out">idle</pre>
<script type="module">
// Two peer connections in one page, forced through the TURN relay.
async function fetchServers(turnPort, tamper, transport) {
  const res = await fetch('/turn-credentials?user=alice', { headers: { Authorization: 'Bearer example-session-token' } });
  const { iceServers } = await res.json();
  return iceServers.map((s) => {
    const urls = [].concat(s.urls).filter((u) => !transport || !u.includes('transport=') || u.includes(`transport=${transport}`)).map((u) => (turnPort ? u.replace(/:\d+(\?|$)/, `:${turnPort}$1`) : u));
    return { ...s, urls, ...(s.credential && tamper ? { credential: s.credential.replace(/.$/, 'A') } : {}) };
  });
}

window.runCheck = async function runCheck({ policy = 'relay', turnPort = null, tamper = false, transport = null, timeoutMs = 15000 } = {}) {
  const iceServers = await fetchServers(turnPort, tamper, transport);
  const a = new RTCPeerConnection({ iceServers, iceTransportPolicy: policy });
  const b = new RTCPeerConnection({ iceServers, iceTransportPolicy: policy });
  const seen = { a: [], b: [] };
  const errors = [];
  for (const [name, pc, other] of [['a', a, b], ['b', b, a]]) {
    pc.onicecandidate = (e) => {
      if (!e.candidate) return;
      seen[name].push({ type: e.candidate.type, protocol: e.candidate.protocol, address: e.candidate.address, relayProtocol: e.candidate.relayProtocol });
      other.addIceCandidate(e.candidate);
    };
    pc.onicecandidateerror = (e) => errors.push({ code: e.errorCode, text: e.errorText, url: e.url });
  }
  const channel = a.createDataChannel('ping');
  const echoed = new Promise((resolve) => {
    b.ondatachannel = (e) => { e.channel.onmessage = (m) => e.channel.send(`echo:${m.data}`); };
    channel.onmessage = (m) => resolve(m.data);
    channel.onopen = () => channel.send('hello-from-alice');
  });
  const offer = await a.createOffer();
  await a.setLocalDescription(offer);
  await b.setRemoteDescription(offer);
  const answer = await b.createAnswer();
  await b.setLocalDescription(answer);
  await a.setRemoteDescription(answer);

  const result = await Promise.race([
    echoed.then((reply) => ({ connected: true, reply })),
    new Promise((r) => setTimeout(() => r({ connected: false }), timeoutMs)),
  ]);
  let selected = null;
  if (result.connected) {
    const stats = await a.getStats();
    stats.forEach((s) => {
      if (s.type === 'transport' && s.selectedCandidatePairId) {
        const pair = stats.get(s.selectedCandidatePairId);
        const local = stats.get(pair.localCandidateId);
        const remote = stats.get(pair.remoteCandidateId);
        selected = { local: local.candidateType, remote: remote.candidateType, relayProtocol: local.relayProtocol, rttMs: pair.currentRoundTripTime * 1000 };
      }
    });
  }
  const types = (list) => [...new Set(list.map((c) => c.type))];
  const out = { policy, transport, connected: result.connected, reply: result.reply, aTypes: types(seen.a), bTypes: types(seen.b), selected, errors };
  a.close(); b.close();
  document.getElementById('out').textContent = JSON.stringify(out, null, 2);
  return out;
};
document.getElementById('out').textContent = 'ready';
</script>

{ "name": "huddle-ice-driver", "private": true, "type": "module", "dependencies": { "puppeteer-core": "25.16.0" } }

import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  headless: true,
  args: ['--use-fake-device-for-media-stream', '--use-fake-ui-for-media-stream', '--no-first-run'],
});
const page = await browser.newPage();
await page.goto('http://localhost:40502/ice-check.html');
await page.waitForFunction(() => typeof window.runCheck === 'function');
const cases = [
  ['relay via coturn', { policy: 'relay', transport: 'udp' }],
  ['relay via coturn over TCP', { policy: 'relay', transport: 'tcp' }],
  ['relay via eturnal', { policy: 'relay', turnPort: 40501, transport: 'udp' }],
  ['relay with tampered credential', { policy: 'relay', tamper: true, transport: 'udp', timeoutMs: 8000 }],
  ['all policy', { policy: 'all' }],
];
for (const [name, opts] of cases) {
  const r = await page.evaluate((o) => window.runCheck(o), opts);
  console.log(name, JSON.stringify(r));
}
await browser.close();

export TURN_HOST=$(ipconfig getifaddr en0)      # macOS; on Linux: hostname -I | cut -d' ' -f1
docker compose up -d
cd driver && npm install && node run.mjs
docker compose down -v

relay via coturn            connected, local relay, remote relay, relayProtocol udp
relay via coturn over TCP   connected, local relay, remote relay, relayProtocol tcp
relay via eturnal           connected, local relay, remote relay, relayProtocol udp
tampered credential         not connected, no candidates, errors: 401, 401
all policy                  connected, local host, remote host (srflx also gathered)

curl -s -H 'Authorization: Bearer example-session-token' 'http://localhost:40502/turn-credentials?user=alice'