How it Works
Client-to-Server and Server-to-Server connections are established using a "Relay" Wireguard tunnel (wiretap_relay.conf). These UDP connections occur over real-world TCP/IP network infrastructure. Each Relay tunnel connects one Wiretap instance (Server or Client) directly to one other instance. They become Wireguard peers, able to pass encrypted messages back and forth between each other. When a new Server or Client is added to the Wiretap network, it is attached to an existing Server by creating a new Relay tunnel between them. These Relay tunnels function very similar to a traditional Wireguard VPN, except that the internal "relay" network resides in a user-space networking stack. By default, Relay interfaces receive internal Wireguard IPs: 172.16.X.X for IPv4, and fd:16::X for IPv6.
Inside the Relay user-space network, Wiretap establishes a second virtual End-to-End Encrypted (E2EE) network (wiretap.conf). Each Server and Client gets its own unique internal IP addresses inside this network, assigned to a separate E2EE interface: 172.19.X.X for IPv4, and fd:19::X for IPv6. As the E2EE name suggests, each Client-Server pair within this virtual network become Wireguard peers, able to generate encrypted messages that only the other can decrypt. For security, Servers only receive E2EE configuration data needed to communicate with Clients, NOT other Servers.
Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the Relay network. When a Client machine generates a packet destined for a known Wiretap route, Wireguard encrypts it using the E2EE configuration associated with the Server assigned to that route. The encrypted packet (now a UDP datagram) gets marked with the Relay IP address of the assigned server as its destination.
At this point, the Client may not have a direct relay connection to the destination Server, so the chain of Servers within the Relay network act much like standard TCP/IP routers. The Client passes the datagram to the first Server through their Relay tunnel, adding a layer of Relay encryption that only that Server's Relay interface can decrypt. The Server receives the datagram, decrypts the Relay payload, identifies which of its peer Servers in the Relay network the E2EE datagram should be sent to next, and sends it off via the associated relay tunnel. The datagram receives a new layer of Relay encryption as it leaves the Server.
The process repeats until the packet reaches the intended Wiretap Server. That Server is finally able to decrypt the E2EE encryption (using its E2EE peer configuration for the Client), revealing the original packet data. It copies this packet to the host's real network stack so it can be sent off to the real-world IP address indicated in the packet header. Any response packets received are sent back to the Client using the same process.
Within the E2EE network (i.e., accessible only to legitimate Clients), Wiretap Servers expose an API to enable real-time configuration changes and to monitor the health of the Wiretap network. When its configurations are generated, each Server is dynamically assigned an additional unique internal IP (usually an IPv6 address, such as ::2) inside the E2EE network to enable the secure usage of this API. This IP is referred to as the "API address."
Accessing the API address works very similar to accessing any other host in the Server's assigned route, and this IP is in fact automatically added to the Client's route list for the Server (the last AllowedIPs value in wiretap.conf) when the Server is first configured. But instead of copying packets with this destination back to the host's real network stack to send to a remote destination host, the Wiretap Server directs those packets to its internal API handler. You can see this behavior for yourself by sending a standard HTTP GET request to an API path on this API address, from a Client, once the Wiretap network is properly connected. For example:
curl -6 [::2]/serverinfo
- This will return a JSON array with (sensitive) info about the Server's configuration.
- This API needs no authentication because they only way to access it is to already be a valid Wiretap Client in the Wiretap network.
Warning
Unlike the other AllowedIP values assigned with the --routes argument, the API address is actually assigned to the Server in its configuration (wiretap_server.conf). You should not try to manually change it or remove it.
API addresses can be seen either in the client E2EE config files (wiretap.conf) or in the output of Wiretap's status command. Servers added with the add server command will also have their API address stored in their wiretap_server.conf file.