TUN Interfaces and Routing

After this lesson your program reads raw IP packets the way a TUN device hands them over, finds each packet's destination address, and picks the peer whose route covers it, with the most specific route winning.

What a TUN device gives you

A TUN device is a virtual network interface that lives in a program instead of on a network card. On Linux you open the file /dev/net/tun, ask the kernel for an interface with the flags IFF_TUN (layer 3) and IFF_NO_PI (no extra header), and then:

• every read returns exactly one IP packet that the kernel wanted to send out of the interface, and
• every write injects exactly one IP packet as if it had arrived from the network.

A TAP device does the same one layer lower, with whole Ethernet frames. WireGuard uses TUN. Administrators then point routes at the interface (ip route add 10.0.0.0/24 dev wg0), and from that moment the kernel does the rest: anything addressed to 10.0.0.x shows up in your program's read. This lesson is the program's side of that: deciding which peer a packet belongs to.

The IPv4 header

The first 20 bytes of every IPv4 packet (RFC 791, section 3.1):

IHL is the header length in 32 bit words: 5 means 20 bytes, more means IP options are present. A worked packet, bytes in hex:

45 00 00 73 00 00 40 00 40 11 b8 61 c0 a8 00 01 c0 a8 00 c7

45 is version 4, IHL 5. 0073 is a total length of 115. 40 is TTL 64 and 11 is protocol 17 (UDP). The checksum b861 is not needed for routing. The source is c0 a8 00 01, which is 192.168.0.1, and the destination at offsets 16 to 19 is c0 a8 00 c7, which is 192.168.0.199. The destination is always at offset 16, whatever IHL says; IHL only tells you where the payload starts.

A TUN device also delivers IPv6 packets (version 6, a 40 byte header) and sometimes garbage. This stage routes IPv4 only: drop anything whose version is not 4, whose IHL is below 5, or that is shorter than its own header.

Longest-prefix match

A route is a CIDR block such as 10.0.0.0/24: the network address and a prefix length. An address matches when its first 24 bits equal the route's first 24 bits. Several routes can match one address, and the rule is that the longest prefix wins.

A /0 route matches every address and loses to anything more specific: that is a full-tunnel VPN. A /24 on its own is a split tunnel. Two details decide whether tables behave:

• Bits after the prefix are ignored. 10.0.0.77/24 means 10.0.0.0/24, so mask the network address when you store it.
• Registering the same block for a second peer moves the block to that peer, like wg set does. The later PEER line wins; the table never holds two peers for one exact block.

Common mistakes

• Routing on the source address (offset 12) instead of the destination (offset 16). A reply packet looks fine in one direction and goes to the wrong peer in the other.
• First match wins. With the default route listed first, every packet goes to it. Order of registration must not matter between different prefix lengths.
• Comparing without masking. 10.0.0.77/24 stored as is never equals the masked destination.
• Shifting by 32. A mask for /0 built as "all ones shifted left by 32" is undefined in some languages and a no-op in others. Treat /0 as its own case.
• Trusting the packet. A 12 byte buffer or a version 6 packet has no IPv4 destination; answer DROP.

Your exercise

The starter reads the input, decodes the hex for you and has a dotted-quad parser. You build the table and the lookup. The most likely mistake is returning the first matching route instead of the longest.