Articles / Networking

  • nat
  • stun
  • turn
  • hole-punching
  • p2p
  • go

Why a Peer-to-Peer Node Behind NAT Still Needs Someone Else's Server

Two peers behind home routers cannot connect to each other without help from a third machine that is not behind NAT. That is true even for protocols sold as "serverless". The third machine does not carry your data (usually), but it has to exist, be reachable, and be run by somebody.

This post walks through why, what the helper actually does, and how to find out which kind of NAT you have with about sixty lines of Go.

The router only lets in what you first sent out

A NAT router keeps a table of outbound flows. When your laptop sends a UDP packet from 192.168.1.20:5000 to some server, the router rewrites the source to its own public address and a port it picks, say 203.0.113.7:61234, and remembers the pairing.

Replies to that public address and port get translated back. Anything arriving with no matching table entry is dropped, because the router has no idea which inside machine it is for. Nothing can connect in until something has gone out.

Now put a NAT on both sides. Peer A does not know B's public address and port, and even if it did, B's router has no entry for A, so the packet dies. Both peers are waiting for the other to speak first.

Step one: learn your own public address

You cannot read your public mapping off your own network interface; it only exists inside the router. So you ask someone outside. STUN (RFC 8489) is exactly that: you send a tiny UDP packet to a public server, and it replies with the source address and port it saw.

That reply is your server-reflexive address, which is a long way of saying "what the internet sees". The STUN server stores nothing and does almost no work, but it is still a server you did not run.

Step two: someone has to introduce the peers

Knowing your own address is useless until the other peer learns it too. That needs a channel both can already reach, usually called signalling or a rendezvous server. It can be a bootstrap node, a DHT entry, a chat room, anything that is publicly reachable.

Once each side has the other's address, both send a packet to each other at roughly the same moment. Each outbound packet creates a table entry on its own router, so the other side's packet now matches and gets in. That is UDP hole punching.

  1. A and B each ask a STUN server for their public address and port.
  2. They swap those through the rendezvous channel.
  3. Both fire UDP packets at each other's address, repeatedly, for a second or two.
  4. Each router sees "return" traffic for a flow it opened, and lets it through.

Quick detour, because it is neat: the timing works because neither router can tell the difference between "reply to my packet" and "a stranger's packet from the same address and port". Plain NAT filtering checks addresses and ports, not intent.

Where it breaks: the mapping depends on the destination

Everything above assumes the router uses the same public port for a given inside socket no matter who it is talking to. That is called endpoint-independent mapping, and it is what makes the address STUN reported valid for the other peer too.

Some routers, and nearly all carrier-grade NAT, pick a fresh public port per destination. The port STUN saw was allocated for the STUN server only. When B sends to it, it is the wrong port and the packet is dropped. This is the "symmetric" NAT of the old classification.

If one side is symmetric and the other is friendly, punching can sometimes work by guessing. If both are symmetric, it generally does not. At that point the only way through is to relay the traffic.

Check your own NAT in Go

The test is simple: use one local UDP socket, ask two different STUN servers what they see, and compare. Same public port both times means endpoint-independent mapping. Different ports means per-destination mapping, and hole punching with that router is going to be miserable.

package main

import (
	"crypto/rand"
	"encoding/binary"
	"errors"
	"fmt"
	"net"
	"net/netip"
	"time"
)

var cookie = [4]byte{0x21, 0x12, 0xA4, 0x42}

func mapped(conn *net.UDPConn, server string) (netip.AddrPort, error) {
	dst, err := net.ResolveUDPAddr("udp4", server)
	if err != nil {
		return netip.AddrPort{}, err
	}
	// Binding request: type 0x0001, length 0, magic cookie, 12-byte ID.
	req := make([]byte, 20)
	binary.BigEndian.PutUint16(req[0:], 0x0001)
	copy(req[4:], cookie[:])
	if _, err := rand.Read(req[8:]); err != nil {
		return netip.AddrPort{}, err
	}
	if _, err := conn.WriteToUDP(req, dst); err != nil {
		return netip.AddrPort{}, err
	}
	conn.SetReadDeadline(time.Now().Add(3 * time.Second))
	buf := make([]byte, 1500)
	n, _, err := conn.ReadFromUDP(buf)
	if err != nil {
		return netip.AddrPort{}, err
	}
	msg := buf[:n]
	if n < 20 || string(msg[8:20]) != string(req[8:20]) {
		return netip.AddrPort{}, errors.New("unexpected reply")
	}
	for off := 20; off+4 <= n; {
		typ := binary.BigEndian.Uint16(msg[off:])
		l := int(binary.BigEndian.Uint16(msg[off+2:]))
		if off+4+l > n {
			break
		}
		v := msg[off+4 : off+4+l]
		// 0x0020 is XOR-MAPPED-ADDRESS; family 0x01 is IPv4.
		if typ == 0x0020 && l >= 8 && v[1] == 0x01 {
			port := binary.BigEndian.Uint16(v[2:]) ^ 0x2112
			ip := [4]byte{v[4] ^ cookie[0], v[5] ^ cookie[1], v[6] ^ cookie[2], v[7] ^ cookie[3]}
			return netip.AddrPortFrom(netip.AddrFrom4(ip), port), nil
		}
		off += 4 + (l+3)&^3 // attributes are padded to 4 bytes
	}
	return netip.AddrPort{}, errors.New("no mapped address")
}

func main() {
	conn, err := net.ListenUDP("udp4", nil)
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	a, err := mapped(conn, "stun.l.google.com:19302")
	if err != nil {
		panic(err)
	}
	b, err := mapped(conn, "stun1.l.google.com:19302")
	if err != nil {
		panic(err)
	}
	fmt.Println("server 1 sees", a)
	fmt.Println("server 2 sees", b)
	if a == b {
		fmt.Println("same mapping: hole punching should work")
	} else {
		fmt.Println("mapping depends on destination: expect to need a relay")
	}
}

The address is XORed with the magic cookie so that helpful middleboxes that rewrite IP addresses inside payloads do not "fix" it. Hang on, why would they? Old application-layer gateways scanned packets for anything that looked like an IP address and rewrote it. XORing hides the address from them.

Run it from a normal home connection and you will most likely see the same address twice. Run it from a phone on mobile data, or from a line behind CGNAT, and you may well see two ports. I have not hard-coded those two server names as a recommendation; they are public test servers that could change, so swap in whichever you trust.

The fallback is a relay, and it is a server

When punching fails, peers send their traffic through a relay on a public address. The standard form is TURN (RFC 8656): the relay allocates a public port on your behalf and forwards packets in both directions. Both peers make outbound connections to it, which every NAT allows.

ICE (RFC 8445) ties it together. It gathers every candidate address (local, STUN-reflexive, relayed), tests pairs, and picks the best one that works. Direct is preferred; relay is the last resort. WebRTC does exactly this, and several libp2p and mesh VPN systems use the same shape with different names.

A relay can be end-to-end encrypted, so it sees only who talks to whom and how much. That is a real privacy cost, though, and a real operating cost for whoever pays for the bandwidth.

What this means if you are building one

  • Ship with a bootstrap or rendezvous node, and say plainly who runs it.
  • Expect a meaningful fraction of connections to need a relay; carrier-grade NAT makes it common on mobile and some rural links.
  • Encrypt end to end so the relay is a dumb pipe, and think about what its logs reveal.
  • Let users point at their own STUN and relay servers, so "decentralised" is not quietly decided by one vendor's defaults.

IPv6 removes most of the problem in principle, since there is no address shortage to justify NAT, but a stateful firewall still drops unsolicited inbound packets, so a form of punching is still needed. The helper just gets a lot less to do.