TURN Server (rings-turn)
rings-turn is a standalone, stateless RFC 5766 TURN server for Rings Network that authenticates WebRTC relay allocations using Rings cryptographic signatures (“signature as password”) instead of a username/password database or shared HMAC secret.
When to Use rings-turn
WebRTC peers normally establish direct UDP datachannels via STUN hole-punching (typ host / typ srflx). You only need rings-turn when direct hole-punching cannot succeed or when you want zero-secret relay access control:
- Symmetric NAT & Carrier-Grade NAT (CGNAT):
When both peers are behind Symmetric NATs (common on 4G/5G mobile networks, residential CGNAT, or strict cloud NAT gateways) where external UDP port mappings change per destination, STUN cannot punch a direct path and a TURN relay (
typ relay) is required. - Strict Corporate / Enterprise Firewalls:
Environments that block arbitrary peer-to-peer UDP traffic and only allow UDP packets to known infrastructure IPs/ports (such as port
3478and a bounded relay port range--min-port/--max-port). - Zero-Database, Zero-Shared-Secret Operations:
Traditional TURN deployments (
coturn, etc.) require maintaining either a staticusername:passwordtable or a shared REST HMAC secret (use-auth-secret) synchronized across auth servers and TURN instances.rings-turnrequires no database, no user registration, and no shared secret—any node holding a valid RingsDelegateeKeyorDidprivate key self-signs its own TURN credentials locally, and anyrings-turninstance verifies them statelessly. - Private / Permissioned Overlay Relays:
Operators running private or consortium Rings overlays can pass
--allow-did <did1,did2,...>(RINGS_TURN_ALLOW_DIDS) so only authorized DIDs (or session delegations issued by those DIDs) may allocate TURN relay sockets.
How Signature + ECDH Authentication Works
Standard WebRTC clients (both browser RTCPeerConnection and native webrtc-rs) authenticate to TURN servers using the RFC 5389 / RFC 5766 long-term credential mechanism. Because STUN/TURN USERNAME attributes are transmitted in cleartext over UDP, rings-turn combines a public identity signature in USERNAME with a secp256k1 Diffie-Hellman (ECDH) derived password in credential:
Client (Native / Browser) rings-turn Server (server_sk, server_pk)
───────────────────────── ────────────────────────────────────────
1. Sign TURN transcript bound to server_pk & derive ECDH password:
- Direct DID: username = "<0x_did>.<base58(sig)>"
credential = base58(keccak256("rings-turn-credential-v1\n" || ECDH(did_sk, server_pk) || sig))
- Delegation: username = "<base58(delegation)>.<base58(sig)>"
credential = base58(keccak256("rings-turn-credential-v1\n" || ECDH(delegatee_sk, server_pk) || sig))
- Account: username = "<base58(codec(AccountSessionClaim))>.<base58(sig)>"
credential = base58(keccak256("rings-turn-credential-v1\n" || ECDH(session_sk, server_pk) || sig))
2. Send STUN/TURN Allocate Request ───────────────────────▶ 3. DelegationAuthHandler::auth_handle(username, realm):
- USERNAME = username (cleartext) - Decode identity & sig from USERNAME
- MESSAGE-INTEGRITY = - Verify DID/Account signature OR Delegation
HMAC-SHA1(MD5(username : realm : credential), pkt) (bound to server_pk) & recover client secp256k1 pubkey
- Check TurnAdmissionPolicy (AllowAny / Allowlist)
- Compute ECDH(server_sk, client_pk) -> credential
- Derive MD5(username : realm : credential)
- Verify MESSAGE-INTEGRITY & allocate relay
Because credential depends on the ECDH shared secret x(client_sk · server_pk) == x(server_sk · client_pk), passive on-path UDP observers who see USERNAME in cleartext cannot recover credential or impersonate the client on a new TURN allocation.
Two signing modes are supported via TurnCredentials:
- Direct DID / Account Signature (Non-Expiring):
- Secp256k1
SecretKey/Did:username:<0x_did>.<base58(did_sig)>credential:base58(keccak256("rings-turn-credential-v1\n" || shared_secret || did_sig))- Signed transcript:
"rings-turn-auth-v1\nsecp256k1\n<0x_did>\n<hex(server_pubkey)>"(pack_turn_did_auth)
- Any
Account(EIP191,BIP137,Secp256r1,Ed25519,Bls12381):username:<base58(codec(AccountSessionClaim))>.<base58(account_sig)>credential:base58(keccak256("rings-turn-credential-v1\n" || shared_secret || account_sig))- Signed transcript:
"rings-turn-auth-v1\n<algorithm>\n<did>\n<hex(session_pubkey)>\n<hex(server_pubkey)>"(pack_turn_account_auth)
- Carries no delegation TTL and never expires when a node’s session
DelegateeKeyrotates.
- Secp256k1
- Session
DelegateeKeySignature (Bounded by Delegation TTL):username:<base58(codec(delegation))>.<base58(delegatee_sig)>credential:base58(keccak256("rings-turn-credential-v1\n" || shared_secret || delegatee_sig))- Signed transcript:
"rings-turn-auth-v1\n<hex(delegation.digest())>\n<hex(server_pubkey)>"(pack_turn_auth) - Ideal for browser tabs and nodes that keep their root
delegator_keyoffline; when a running node renews itsDelegateeKey,SwarmTransportautomatically refreshes its TURN credentials and updates active peer connections whilerings-turnkeeps existing established 5-tuple allocations alive across renewal.
Running rings-turn
Build or install the rings-turn binary from the workspace:
cargo build --release -p rings-turn --bin rings-turn
# or
cargo install --path crates/turn
Command-line interface
Usage: rings-turn [OPTIONS]
Options:
--listen <LISTEN>
UDP socket address to listen on for STUN/TURN requests
[env: RINGS_TURN_LISTEN=] [default: 0.0.0.0:3478]
--realm <REALM>
TURN authentication realm advertised in 401/438 challenges
[env: RINGS_TURN_REALM=] [default: rings.network]
--public-ip <PUBLIC_IP>
Public IPv4/IPv6 address advertised in XOR-RELAYED-ADDRESS.
Defaults to the listener IP (or 127.0.0.1 when listening on 0.0.0.0)
[env: RINGS_TURN_PUBLIC_IP=]
--relay-bind-ip <RELAY_BIND_IP>
Local IPv4/IPv6 address bound when allocating relay UDP sockets.
Defaults to the listener IP
[env: RINGS_TURN_RELAY_BIND_IP=]
--min-port <MIN_PORT>
Inclusive lower bound for allocated relay UDP ports
[env: RINGS_TURN_MIN_PORT=]
--max-port <MAX_PORT>
Inclusive upper bound for allocated relay UDP ports
[env: RINGS_TURN_MAX_PORT=]
--channel-bind-timeout-secs <CHANNEL_BIND_TIMEOUT_SECS>
ChannelBind timeout in seconds (0 uses the RFC 5766 default of 600s)
[env: RINGS_TURN_CHANNEL_BIND_TIMEOUT_SECS=] [default: 0]
--server-key <SERVER_KEY>
Hex-encoded 32-byte secp256k1 secret key for TURN ECDH credential derivation.
When omitted, an ephemeral key is generated on startup and its public key is logged
[env: RINGS_TURN_SERVER_KEY=]
--allow-did <ALLOW_DIDS>
Optional comma-separated allowlist of DIDs allowed to allocate TURN relays.
When omitted, any cryptographically valid Rings signature is admitted
[env: RINGS_TURN_ALLOW_DIDS=]
--allow-private-peers
Allow relay sockets to exchange UDP packets with loopback, link-local, or private
peer addresses (disabled by default to prevent SSRF / local-network amplification)
[env: RINGS_TURN_ALLOW_PRIVATE_PEERS=]
--max-nonces <MAX_NONCES>
Maximum number of active nonce challenges tracked concurrently
[env: RINGS_TURN_MAX_NONCES=] [default: 4096]
-h, --help
Print help
-V, --version
Print version
Deployment examples
-
Public relay with bounded UDP port range (open UDP
3478and49152-65535in your firewall):rings-turn \ --listen 0.0.0.0:3478 \ --public-ip 203.0.113.10 \ --relay-bind-ip 0.0.0.0 \ --min-port 49152 \ --max-port 65535 \ --server-key 0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318 -
Private relay restricted to an allowlist of DIDs:
rings-turn \ --listen 0.0.0.0:3478 \ --public-ip 203.0.113.10 \ --server-key 0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318 \ --allow-did 0x1111111111111111111111111111111111111111,0x2222222222222222222222222222222222222222
Configuring nodes to use rings-turn
In a node’s config.yaml (or via rings run --ice-servers), list the turn:// server with its ?pubkey=<base58(server_pubkey)> query parameter (logged by rings-turn on startup) and without credentials:
ice_servers: stun://stun.l.google.com:19302;turn://203.0.113.10:3478?pubkey=249495738f7s7d8f7s8d7f8s7d8f7s8d7f8s7d8f7s8d
- When
delegator_keyis configured inconfig.yaml, the node signsturn://...?pubkey=<server_pubkey>entries directly with its DID key and ECDH shared secret, which never expires. - When only
delegatee_keyis configured, the node signsturn://...?pubkey=<server_pubkey>entries with itsDelegateeKeyand ECDH shared secret and refreshes them automatically wheneverDelegateeKeyis renewed. - Explicit
turn://user:pass@host:portentries are left untouched for third-party TURN servers.